只读Typesense MCP服务器
一种模型上下文协议（MCP）服务器，提供对Typesense Cloud的只读访问。与官方合作建造 @modelcontextprotocol/sdk 和 typesense 包装。
特性
- 🔍 搜索操作：使用过滤器、方面、排序和多搜索的全文搜索
- 📚 集合：列出并检查集合架构
- 📄 文件：检索、搜索和导出文档
- 🎯 策展：访问搜索覆盖
- 🔤 同义词：查看同义词配置
- 🏷️ 别名：管理集合别名
- 📊 分析：访问分析规则
- ⚕️ 集群信息：健康检查、指标和统计
- 🔒 只读：所有操作都是只读的（没有写/删除操作）
安装
npm install
npm run build配置
服务器按以下顺序查找配置：
TYPESENSE_CONFIG_PATH环境变量typesense.json在当前工作目录中config/typesense.json在当前工作目录中- 捆绑的
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-将文档导出为JSONLtypesense_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 inspectClaude代码集成
MCP自动发现 typesense.json 在当前工作目录中，使其非常适合调试不同的Typesense集群。
设置
创建 .mcp.json 在您的项目根目录中（或从该仓库复制）：
{
"mcpServers": {
"typesense": {
"command": "node",
"args": ["/home/alanm/dev/readonly-typesense-mcp/build/index.js"]
}
}
}用法
- 复制
.mcp.json到您的项目（或将其符号链接） - 创建
typesense.json使用您的群集凭据 - 启动克劳德代码-它将检测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
claudeClaude 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许可证
麻省理工学院