Typesensekit

TypesenseKit

[](https://github.com/akshitkrnagpal/typesensekit/actions/workflows/ci.yml)

TypesenseKit is the developer toolkit for operating Typesense from terminals and AI agents. It gives you one typed operation registry, a human-friendly CLI, and an MCP stdio server over the same Typesense Admin API surface.

Use it when you want repeatable Typesense automation without rebuilding small scripts for every collection, import, search, schema update, or agent workflow.

What You Get

• @typesensekit/cli: a tsk command for profile-aware Typesense operations, raw API calls, and agent config snippets.
• @typesensekit/mcp: an MCP stdio server that exposes Typesense operations as tools for compatible agents.
• @typesensekit/core: the private shared client, operation registry, validation layer, and redaction utilities used by both public packages.

Quick Start

Install the CLI:

pnpm add -g @typesensekit/cli

Create and use a profile:

tsk profile add local --url http://localhost:8108 --api-key xyz
tsk profile use local
tsk collections.list --input '{}'

Or run without a saved profile:

TYPESENSE_URL=http://localhost:8108 TYPESENSE_API_KEY=xyz tsk health --input '{}'

List every supported operation:

tsk operations

Inspect an operation's input shape before running it:

tsk documents.search --schema
tsk documents.search --examples

Search parameters are passed inside the top-level params object:

tsk documents.search --input '{"collection":"production__products","params":{"q":"*","query_by":"q"}}' --json

MCP Server

Run the MCP stdio server directly. MCP tools are read-only by default, so the assistant surface includes search, document reads, collection metadata, and status checks without write/delete/admin operations.

TYPESENSE_URL=http://localhost:8108 TYPESENSE_API_KEY=xyz pnpm dlx @typesensekit/mcp

To expose the full operation registry, including writes, deletes, key management, and raw api.call, opt in explicitly:

TYPESENSEKIT_READ_ONLY=false TYPESENSE_URL=http://localhost:8108 TYPESENSE_API_KEY=xyz pnpm dlx @typesensekit/mcp

Claude Desktop example:

{
  "mcpServers": {
    "typesensekit": {
      "command": "npx",
      "args": ["-y", "@typesensekit/mcp"],
      "env": {
        "TYPESENSE_URL": "http://localhost:8108",
        "TYPESENSE_API_KEY": "xyz"
      }
    }
  }
}

Generate copy-ready integration snippets from the CLI:

tsk skills mcp
tsk skills claude-desktop
tsk skills claude-code
tsk skills hermes

For scoped key examples, production guidance, and the compatibility matrix, read [docs/mcp-security.md](./docs/mcp-security.md).

For Streamable HTTP, Docker, and deployment examples, read [docs/mcp-http-docker.md](./docs/mcp-http-docker.md). For an end-to-end assistant search flow with citations, read [examples/assistant-search-citations.md](./examples/assistant-search-citations.md).

The MCP server also exposes resources:

| Resource | Purpose | | --- | --- | | typesensekit://operations | JSON manifest of operations exposed by the current MCP mode | | typesensekit://read-only-tools | JSON list of tools included in default read-only mode | | typesense://collections/{collection}/schema | Collection schema lookup | | typesense://collections/{collection}/documents/{id} | Document lookup |

API Coverage

TypesenseKit covers the common Typesense administration and search surfaces, plus api.call for endpoints that are new, uncommon, or not yet wrapped.

| Area | Operations | | --- | --- | | Collections | list, get, create, update, delete, schema changes | | Documents | index, upsert, get, get many, update, delete, import, export, search | | Search | search, multi-search, facet exploration, suggestions | | Configuration | aliases, synonyms, overrides, stopwords, presets | | Access | API keys | | Analytics | rules and events | | Conversations | models and history | | System | health, metrics, stats, debug | | Escape hatch | raw HTTP calls through api.call |

Typesense v30 global synonym sets are available through synonym_sets.*:

tsk synonym_sets.list --input '{}' --json
tsk synonym_sets.items.list --input '{"name":"products-core"}' --json

Why It Exists

Typesense work often jumps between dashboards, one-off scripts, local curl commands, and agent experiments. TypesenseKit keeps those workflows on one command and one tool registry:

• Use the same operation names from the CLI and MCP server.
• Keep API keys out of command history with saved profiles or environment variables.
• Get structured input validation before requests hit Typesense.
• Redact secrets in error output.
• Fall back to raw API calls when Typesense ships faster than the wrappers.

Development

corepack enable
pnpm install
pnpm check

Run local Typesense:

docker run -p 8108:8108 \
  -e TYPESENSE_API_KEY=xyz \
  -e TYPESENSE_DATA_DIR=/data \
  typesense/typesense:27.1 --enable-cors

Useful scripts:

pnpm lint
pnpm typecheck
pnpm test
pnpm build
pnpm pack:dry

Repository Assets

• README banner: [assets/github-hero.png](./assets/github-hero.png)
• GitHub social preview image: [assets/github-og.png](./assets/github-og.png)

Use assets/github-og.png as the repository social preview in GitHub settings.

Releasing

pnpm changeset
pnpm changeset version
pnpm release

Contributing

Read [CONTRIBUTING.md](./CONTRIBUTING.md) for setup, development rules, and release notes.

License

MIT

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: akshitkrnagpal
• Source: akshitkrnagpal/typesensekit
• License: MIT

Install and usage instructions live in the source repository linked above.