内容
<p align="center">
<img src="./assets/readme-icon.png" alt="TypesenseKit 机器人图标" 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)
## 从终端或 AI 代理操作 Typesense
TypesenseKit 为人类和 AI 代理提供相同的 **95 种 Typesense 操作**，通过人性化的 CLI 和安全的 MCP 服务器。MCP 访问**默认只读**；写入、删除、密钥管理和原始 API 工具需要明确启用。
**[网站](https://typesensekit.vercel.app)** · **[Typesense CLI](https://typesensekit.vercel.app/typesense-cli/)** · **[Typesense MCP](https://typesensekit.vercel.app/typesense-mcp/)** · **[指南](https://typesensekit.vercel.app/guides/clients/)**
```sh
pnpm add -g @typesensekit/cli
# 安全地提示输入 API 密钥
tsk profile add local --url http://localhost:8108
tsk profile use local
# 发现输入，然后运行操作
tsk documents.search --examples
tsk documents.search --input '{"collection":"products","params":{"q":"oak chair","query_by":"title"}}' --json
```
## 为什么选择 TypesenseKit
Typesense 工作经常在仪表板、一次性脚本、本地 curl 命令和代理实验之间跳转。TypesenseKit 将这些工作流保持在同一个可预测的表面上：
- 在 CLI 和 MCP 服务器上使用相同的操作名称。
- 在请求到达 Typesense 之前验证结构化输入。
- 获取可读的终端输出或稳定的、编辑过的 JSON 用于脚本。
- 使用安全提示、标准输入或 macOS Keychain 配置文件将密钥排除在 shell 历史记录之外。
- 在运行破坏性 CLI 操作之前确认。
- 默认情况下为 AI 客户端提供只读工具，然后有意启用写入。
| | 一次性脚本 | Typesense 客户端 | 基本 MCP 包装 | TypesenseKit |
| --- | --- | --- | --- | --- |
| 以终端为中心的工作流 | 手动 | — | — | 内置 |
| MCP 工具 | — | — | 是 | 是 |
| 共享 CLI/MCP 操作 | — | — | 变化 | 是 |
| 安全的操作默认值 | 您构建它们 | 应用程序所有 | 变化 | 只读 + 确认 |
在应用程序代码中使用官方 Typesense 客户端。当人类、脚本和代理需要执行相同的操作工作时，使用 TypesenseKit。
## CLI
安装公共 CLI 包：
```sh
pnpm add -g @typesensekit/cli
```
交互式创建配置文件，通过标准输入管道密钥进行自动化，或使用 macOS Keychain：
```sh
# 交互式安全提示
tsk profile add local --url http://localhost:8108
# 脚本设置，无需将密钥放入 argv 或 shell 历史记录中
printf '%s' "$TYPESENSE_API_KEY" | tsk profile add ci \
--url https://search.example.com --api-key-stdin
# macOS 上基于 Keychain 的配置文件
tsk profile add production --url https://search.example.com --keychain
```
每个操作都支持生成的模式和示例。常见结果呈现为表格；传递 `--json` 以获取稳定的自动化输出。
```sh
tsk operations
tsk collections.list --input '{}'
tsk documents.search --schema
tsk documents.search --examples
tsk collections.list --input '{}' --json
```
启用 shell 补全：
```sh
source <(tsk completion zsh)
source <(tsk completion bash)
tsk completion fish | source
```
参见 **[Typesense CLI 概述](https://typesensekit.vercel.app/typesense-cli/)** 或阅读 **[完整的 CLI 指南](https://typesensekit.vercel.app/guides/cli/)**，了解配置文件、仅限环境使用、JSON 输入、补全和破坏性操作行为。
## MCP 服务器
直接运行 stdio 服务器。默认情况下，它公开搜索、读取、集合元数据、配置读取和系统状态操作。
```sh
TYPESENSE_URL=http://localhost:8108 \
TYPESENSE_API_KEY=xyz \
pnpm dlx @typesensekit/mcp
```
写入、删除、密钥管理和原始 API 工具在明确启用完全访问之前保持隐藏：
```sh
TYPESENSEKIT_READ_ONLY=false \
TYPESENSE_URL=http://localhost:8108 \
TYPESENSE_API_KEY=xyz \
pnpm dlx @typesensekit/mcp
```
从 CLI 生成客户端配置：
```sh
tsk skills mcp
tsk skills claude-desktop
tsk skills claude-code
tsk skills hermes
```
参见 **[Typesense MCP 概述](https://typesensekit.vercel.app/typesense-mcp/)**、 **[MCP 指南](https://typesensekit.vercel.app/guides/mcp/)** 和 **[客户端设置指南](https://typesensekit.vercel.app/guides/clients/)**，适用于 Claude Desktop、Claude Code、Codex、Cursor、通用 MCP 客户端、Streamable HTTP 和 Docker。
### MCP 资源
| 资源 | 目的 |
| --- | --- |
| `typesensekit://operations` | 当前 MCP 模式下公开的操作 |
| `typesensekit://read-only-tools` | 默认只读模式下包含的工具 |
| `typesense://collections/{collection}/schema` | 集合模式查找 |
| `typesense://collections/{collection}/documents/{id}` | 文档查找 |
## 您可以使用 TypesenseKit 操作的内容
TypesenseKit 针对 Typesense v30.2 API 以实现当前一流的操作：
- 集合、模式更改、文档、导入、导出、搜索、多搜索、方面和建议
- 别名、预设、全局同义词和策划集、停用词、词干字典和旧集合配置
- API 密钥、分析规则和事件、自然语言搜索模型、对话和对话历史
- 健康状况、指标、统计信息、调试信息、快照、慢速请求日志、数据库维护和其他系统操作
生成的 **[API 覆盖范围清单](./docs/api-coverage.md)** 是操作名称和兼容性说明的真实来源。使用 `api.call` 来访问新的、不常见的或尚未封装的端点。
## 安全
Typesense 管理涉及数据和凭证。对于面向助手的部署，请保持 MCP 服务器只读，使用狭义范围的 Typesense 密钥，并使用身份验证和网络控制保护任何 Streamable HTTP 部署。
- [MCP 安全性和生产指南](./docs/mcp-security.md)
- [Streamable HTTP 和 Docker](./docs/mcp-http-docker.md)
- [带有引用的助手搜索](./examples/assistant-search-citations.md)
## 开发
```sh
corepack enable
pnpm install
pnpm check
```
运行本地 Typesense 服务器：
```sh
docker run -p 8108:8108 \
-e TYPESENSE_API_KEY=xyz \
-e TYPESENSE_DATA_DIR=/data \
typesense/typesense:30.2 --enable-cors
```
在本地运行登陆页面：
```sh
pnpm dev:web
```
参见 [CONTRIBUTING.md](./CONTRIBUTING.md) 了解开发和发布规则。
## 许可证
[MIT](./LICENSE)
