Readonly Typesense MCP

只读Typesense MCP服务器

一种模型上下文协议（MCP）服务器，提供对Typesense Cloud的只读访问。与官方合作建造 @modelcontextprotocol/sdk 和 typesense 包装。

特性

• 🔍 搜索操作：使用过滤器、方面、排序和多搜索的全文搜索
• 📚 集合：列出并检查集合架构
• 📄 文件：检索、搜索和导出文档
• 🎯 策展：访问搜索覆盖
• 🔤 同义词：查看同义词配置
• 🏷️ 别名：管理集合别名
• 📊 分析：访问分析规则
• ⚕️ 集群信息：健康检查、指标和统计
• 🔒 只读：所有操作都是只读的（没有写/删除操作）

安装

npm install
npm run build

配置

服务器按以下顺序查找配置：

1. TYPESENSE_CONFIG_PATH 环境变量
2. typesense.json 在当前工作目录中
3. config/typesense.json 在当前工作目录中
4. 捆绑的 config/typesense.json （相对于模块）

这允许您简单地放下 typesense.json 任何项目目录中的文件，MCP都会自动使用它。

配置文件格式

创建 typesense.json:

{
  "nodes": [
    {
      "host": "xxx.a1.typesense.net",
      "port": 443,
      "protocol": "https"
    }
  ],
  "nearestNode": {
    "host": "xxx.a1.typesense.net",
    "port": 443,
    "protocol": "https"
  },
  "apiKey": "your-admin-api-key",
  "connectionTimeoutSeconds": 10
}

环境变量

• TYPESENSE_CONFIG_PATH：配置文件的显式路径（覆盖自动发现）
• TYPESENSE_API_KEY：从配置文件重写API密钥

API关键要求

虽然此服务器仅实现只读操作，但它需要 管理员API密钥 访问某些端点，如列表集合、覆盖、同义词等。仅搜索API密钥的权限有限，无法访问集合元数据。

服务器与管理员密钥一起使用是安全的，因为：

• 未执行任何写入操作
• 未执行删除操作
• 所有操作都是严格只读的
• 非常适合生产监控和搜索集成

可用工具（20）

集合

• typesense_list_collections -列出所有具有架构的集合
• typesense_get_collection -获取特定的集合架构

文件

• typesense_search -带过滤器、方面、排序的全文搜索
• typesense_get_document -按ID获取文档
• typesense_export_documents -将文档导出为JSONL
• typesense_multi_search -跨集合的联合搜索

策展/覆盖

• typesense_list_overrides -集合的列表覆盖
• typesense_get_override -获取特定覆盖

同义词

• typesense_list_synonyms -列出集合的同义词
• typesense_get_synonym -获取特定同义词

别名

• typesense_list_aliases -列出所有别名
• typesense_get_alias -获取特定别名

分析

• typesense_list_analytics_rules -列出分析规则
• typesense_get_analytics_rule -获取特定规则

NL搜索模型

• typesense_list_nl_models -列出所有NL搜索模型（已编辑凭据）
• typesense_get_nl_model -通过ID获取特定的NL模型（已编辑凭据）

簇

• typesense_health -节点健康状态
• typesense_metrics -RAM/CPU/磁盘指标
• typesense_stats -API请求统计信息
• typesense_debug -版本和状态信息

MCP资源

• typesense://collections/{name}/schema -集合架构
• typesense://cluster/health -群集运行状况

测试

使用MCP检查员进行测试：

npm run inspect

Claude代码集成

MCP自动发现 typesense.json 在当前工作目录中，使其非常适合调试不同的Typesense集群。

设置

创建 .mcp.json 在您的项目根目录中（或从该仓库复制）：

{
  "mcpServers": {
    "typesense": {
      "command": "node",
      "args": ["/home/alanm/dev/readonly-typesense-mcp/build/index.js"]
    }
  }
}

用法

1. 复制 .mcp.json 到您的项目（或将其符号链接）
2. 创建 typesense.json 使用您的群集凭据
3. 启动克劳德代码-它将检测MCP并提示启用它

cd /path/to/your/project

# Copy MCP config
cp /home/alanm/dev/readonly-typesense-mcp/.mcp.json .

# Create typesense.json with your cluster credentials
cat > typesense.json << 'EOF'
{
  "nodes": [{"host": "xxx.a1.typesense.net", "port": 443, "protocol": "https"}],
  "apiKey": "your-admin-api-key",
  "connectionTimeoutSeconds": 10
}
EOF

# Start Claude Code
claude

Claude Code将检测 .mcp.json 并请求启用Typesense MCP服务器。

Claude桌面集成

添加到您的Claude桌面配置(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS或 ~/.config/Claude/claude_desktop_config.json 在Linux上）：

{
  "mcpServers": {
    "typesense": {
      "command": "node",
      "args": ["/home/alanm/dev/readonly-typesense-mcp/build/index.js"]
    }
  }
}

示例用法

一旦与Claude Desktop集成，您可以提出以下问题：

• “Typesense提供哪些系列？”
• “搜索价格大于100的产品”
• “显示用户集合的架构”
• “Typesense集群的运行状况如何？”
• “导出产品集合中的所有文档”

发展

# Watch mode for development
npm run watch

# Build
npm run build

# Test with inspector
npm run inspect

许可证

麻省理工学院