Typesense MCP Server

Typesense MCP 服务

---

一个 Model Context Protocol (MCP) 服务实现，为 AI 模型提供对 Typesense 搜索功能的访问。此服务使大模型能够发现、搜索和分析存储在 Typesense 集合中的数据。

演示

功能

资源

• 通过 typesense:// URI 列出和访问集合
• 每个集合都有名称、描述和文档数
• 用于访问架构的 JSON MIME 类型

工具

• typesense_query

  • 使用强大的筛选功能搜索 Typesense 集合中的文档
  • 输入：查询文本、集合名称、搜索字段、筛选条件、排序选项、数量限制
  • 返回匹配的文档及相关性评分

• typesense_get_document

  • 根据 ID 从集合中检索特定文档
  • 输入：集合名称、文档 ID
  • 返回完整的文档数据

• typesense_collection_stats

  • 获取 Typesense 集合的统计信息
  • 输入：集合名称
  • 返回集合元数据、文档数和架构信息

提示词

• analyze_collection

  • 分析集合结构和内容
  • 输入：集合名称
  • 输出：关于架构、数据类型和统计信息的洞察

• search_suggestions

  • 获取针对某个集合的有效搜索查询建议
  • 输入：集合名称
  • 输出：基于集合架构推荐的搜索策略

安装

通过 npm

# Global installation
npm install -g typesense-mcp-server

# Local installation
npm install typesense-mcp-server

通过 mcp-get

npx @michaellatman/mcp-get@latest install typesense-mcp-server

开发

安装依赖项：

npm install

构建服务：

npm run build

用于自动重新构建的开发模式：

npm run watch

开发环境安装

使用 Claude Desktop

要与 Claude Desktop 配合使用，请添加服务配置：

MacOS：~/Library/Application Support/Claude/claude_desktop_config.json

Windows：%APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "typesense": {
      "command": "node",
      "args": [
        "~/typesense-mcp-server/dist/index.js",
        "--host", "your-typesense-host",
        "--port", "8108",
        "--protocol", "http",
        "--api-key", "your-api-key"
      ]
    },
  }
}

调试

由于 MCP 服务通过 stdio 通信，调试可能颇具挑战。我们建议使用 MCP Inspector，它可通过包脚本运行：

npm run inspector

Inspector 将提供一个 URL，供你在浏览器中访问调试工具。

组件

资源

该服务提供有关 Typesense 集合的信息：

• 集合架构（typesense://collections/<collection>）
  • 每个集合的 JSON 架构信息
  • 包含字段名称和数据类型
  • 用于理解数据结构的示例文档

工具

该服务提供以下用于与 Typesense 交互的工具：

• typesense_list_collections - 列出所有可用集合及其架构

  • 支持零配置发现和路由
  • 大模型可以在运行时枚举集合，并在搜索前选择合适的集合
  • 适用于集合因环境、租户或版本而异的情况
  • 返回用于推断架构的字段定义（可搜索、可分面、数值字段）
  • 支持使用 include_fields 参数控制详细程度

• typesense_query - 搜索集合中的文档

  • 支持自定义参数的全文搜索
  • 支持筛选、排序和分页

• typesense_get_document - 根据 ID 检索特定文档

• typesense_collection_stats - 获取特定集合的详细统计信息

资源模板

服务器提供以下模板：

• typesense_search - 用于构建 Typesense 搜索查询的模板
• typesense_collection - 用于查看 Typesense 集合详情的模板

在 Claude Desktop 中使用

要在 Claude Desktop 桌面应用中使用此服务器，请将以下配置添加到 claude_desktop_config.json 的 "mcpServers" 部分：

{
  "mcpServers": {
    "typesense": {
      "command": "npx",
      "args": [
        "-y",
        "typesense-mcp-server",
        "--host", "your-typesense-host",
        "--port", "8108",
        "--protocol", "http",
        "--api-key", "your-api-key"
      ]
    }
  }
}

日志记录

服务器会将日志信息写入以下位置的文件：

/tmp/typesense-mcp.log

此日志包含有关服务器操作、请求和发生的任何错误的详细信息。

许可证

此 MCP 服务采用 MIT 许可证。这意味着您可以自由使用、修改和分发该软件，但须遵守 MIT 许可证的条款和条件。有关详情，请参阅项目仓库中的 LICENSE 文件。