TypesenseKit
95 typed Typesense operations for AI agents through an MCP server that is read-only by default.
Open source Open in the app JSON README (API)
About
95 typed Typesense operations for AI agents through an MCP server that is read-only by default.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- typesensekit
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.4.4
- Stars
- 2
- Last push
- 2026-07-17T00:52:30Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 04:01:36
- Updated
- 2026-08-29 04:01:36
- Origin id
io.github.typesensekit/typesensekit
README
<p align="center">
<img src="./assets/readme-icon.png" alt="TypesenseKit robot icon" width="160">
</p>
<h1 align="center">TypesenseKit</h1>
[](https://github.com/typesensekit/typesensekit/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/@typesensekit/cli)
[](https://www.npmjs.com/package/@typesensekit/mcp)
[](./LICENSE)
## Operate Typesense from your terminal or AI agent
TypesenseKit gives humans and AI agents the same **95 typed Typesense operations** through a human-friendly CLI and secure MCP server. MCP access is **read-only by default**; write, delete, key-management, and raw API tools require explicit opt-in.
**[Website](https://typesensekit.vercel.app)** · **[Typesense CLI](https://typesensekit.vercel.app/typesense-cli/)** · **[Typesense MCP](https://typesensekit.vercel.app/typesense-mcp/)** · **[Guides](https://typesensekit.vercel.app/guides/clients/)**
```sh
pnpm add -g @typesensekit/cli
# Securely prompts for the API key
tsk profile add local --url http://localhost:8108
tsk profile use local
# Discover the input, then run the operation
tsk documents.search --examples
tsk documents.search --input '{"collection":"products","params":{"q":"oak chair","query_by":"title"}}' --json
```
## Why TypesenseKit
Typesense work often jumps between dashboards, one-off scripts, local curl commands, and agent experiments. TypesenseKit keeps those workflows on one predictable surface:
- Use the same operation names from the CLI and MCP server.
- Validate structured inputs before requests reach Typesense.
- Get readable terminal output or stable, redacted JSON for scripts.
- Keep secrets out of shell history with secure prompts, stdin, or macOS Keychain profiles.
- Confirm destructive CLI operations before they run.
- Give AI clients read-only tools by default, then opt in to writes deliberately.
- Reach newer or uncommon endpoints through the raw `api.call` escape hatch.
| | One-off scripts | Typesense client | Basic MCP wrapper | TypesenseKit |
| --- | --- | --- | --- | --- |
| Terminal-first workflow | Manual | — | — | Built in |
| MCP tools | — | — | Yes | Yes |
| Shared CLI/MCP operations | — | — | Varies | Yes |
| Safe operational defaults | You build them | Application-owned | Varies | Read-only + confirmations |
Use the official Typesense client in application code. Use TypesenseKit when humans, scripts, and agents need to perform the same operational work.
## CLI
Install the public CLI package:
```sh
pnpm add -g @typesensekit/cli
```
Create a profile interactively, pipe a key over stdin for automation, or use macOS Keychain:
```sh
# Interactive secure prompt
tsk profile add local --url http://localhost:8108
# Scripted setup without putting the key in argv or shell history
printf '%s' "$TYPESENSE_API_KEY" | tsk profile add ci \
--url https://search.example.com --api-key-stdin
# Keychain-backed profile on macOS
tsk profile add production --url https://search.example.com --keychain
```
Every operation supports generated schemas and examples. Common results render as tables; pass `--json` for stable automation output.
```sh
tsk operations
tsk collections.list --input '{}'
tsk documents.search --schema
tsk documents.search --examples
tsk collections.list --input '{}' --json
```
Enable shell completion:
```sh
source <(tsk completion zsh)
source <(tsk completion bash)
tsk completion fish | source
```
See the **[Typesense CLI overview](https://typesensekit.vercel.app/typesense-cli/)** or read the **[complete CLI guide](https://typesensekit.vercel.app/guides/cli/)** for profiles, environment-only use, JSON input, completion, and destructive-operation behavior.
## MCP Server
Run the stdio server directly. It exposes search, reads, collection metadata, configuration reads, and system status operations by default.
```sh
TYPESENSE_URL=http://localhost:8108 \
TYPESENSE_API_KEY=xyz \
pnpm dlx @typesensekit/mcp
```
Write, delete, key-management, and raw API tools stay hidden unless full access is explicitly enabled:
```sh
TYPESENSEKIT_READ_ONLY=false \
TYPESENSE_URL=http://localhost:8108 \
TYPESENSE_API_KEY=xyz \
pnpm dlx @typesensekit/mcp
```
Generate client configuration from the CLI:
```sh
tsk skills mcp
tsk skills claude-desktop
tsk skills claude-code
tsk skills hermes
```
See the **[Typesense MCP overview](https://typesensekit.vercel.app/typesense-mcp/)**, **[MCP guide](https://typesensekit.vercel.app/guides/mcp/)**, and **[client setup guide](https://typesensekit.vercel.app/guides/clients/)** for Claude Desktop, Claude Code, Codex, Cursor, generic MCP clients, Streamable HTTP, and Docker.
### MCP resources
| Resource | Purpose |
| --- | --- |
| `typesensekit://operations` | Operations exposed by the current MCP mode |
| `typesensekit://read-only-tools` | Tools included in the default read-only mode |
| `typesense://collections/{collection}/schema` | Collection schema lookup |
| `typesense://collections/{collection}/documents/{id}` | Document lookup |
## What You Can Operate
TypesenseKit targets the Typesense v30.2 API for current first-class operations:
- Collections, schema changes, documents, imports, exports, search, multi-search, facets, and suggestions
- Aliases, presets, global synonym and curation sets, stopwords, stemming dictionaries, and legacy collection configuration
- API keys, analytics rules and events, natural-language search models, conversations, and conversation history
- Health, metrics, stats, debug information, snapshots, slow-request logging, database maintenance, and other system operations
The generated **[API coverage inventory](./docs/api-coverage.md)** is the source of truth for operation names and compatibility notes. Use `api.call` for endpoints that are new, uncommon, or not yet wrapped.
## Security
Typesense administration touches data and credentials. Keep the MCP server read-only for assistant-facing deployments, use narrowly scoped Typesense keys, and protect any Streamable HTTP deployment with authentication and network controls.
- [MCP security and production guidance](./docs/mcp-security.md)
- [Streamable HTTP and Docker](./docs/mcp-http-docker.md)
- [Assistant search with citations](./examples/assistant-search-citations.md)
## Development
```sh
corepack enable
pnpm install
pnpm check
```
Run a local Typesense server:
```sh
docker run -p 8108:8108 \
-e TYPESENSE_API_KEY=xyz \
-e TYPESENSE_DATA_DIR=/data \
typesense/typesense:30.2 --enable-cors
```
Run the landing page locally:
```sh
pnpm dev:web
```
See [CONTRIBUTING.md](./CONTRIBUTING.md) for development and release rules.
## License
[MIT](./LICENSE)