Typesense MCP Server 使用说明

项目简介

Typesense MCP Server 是一个基于 Model Context Protocol (MCP) 构建的服务器，它充当 LLM（大型语言模型）客户端和 Typesense 搜索引擎之间的桥梁。通过此服务器，LLM 可以安全、便捷地访问 Typesense 中存储的数据，并利用 Typesense 的搜索能力来增强其上下文理解和信息检索功能。

主要功能点

资源 (Resources) 管理:
- 列出和访问 Typesense 中的 Collection（集合），每个 Collection 被视为一个资源。
- 提供 Collection 的名称、描述和文档数量等基本信息。
- 支持通过 'typesense://' URI 格式访问 Collection 资源。
- 提供 Collection 的 Schema 信息，方便 LLM 理解数据结构。
工具 (Tools) 注册与执行:
- 提供以下预定义的工具，允许 LLM 调用 Typesense 的核心功能：
  - 'typesense_query': 在指定的 Collection 中执行强大的搜索查询，支持关键词搜索、过滤、排序和分页。
  - 'typesense_get_document': 根据 Document ID 从 Collection 中检索特定的文档。
  - 'typesense_collection_stats': 获取 Collection 的统计信息，包括文档数量和 Schema 信息。
Prompt 模板 (Prompts) 定义:
- 提供预定义的 Prompt 模板，帮助 LLM 与 Typesense 数据进行更有效的交互：
  - 'analyze_collection': 分析 Collection 的结构和内容，为 LLM 提供理解数据上下文的 Prompt。
  - 'search_suggestions': 为指定的 Collection 提供搜索建议，帮助 LLM 构建更有效的搜索查询。

安装步骤

环境准备: 确保已安装 Node.js 和 npm (或 yarn)。

全局安装 (推荐):

npm install -g typesense-mcp-server

或者 本地安装:

npm install typesense-mcp-server

您也可以使用 'mcp-get' 工具进行安装:

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

服务器配置

MCP 客户端（例如 Claude Desktop）需要配置 MCP 服务器的启动命令和参数才能连接。以下是 Typesense MCP Server 的配置信息示例，请根据您的 Typesense 实际部署情况进行修改：

{
  "mcpServers": {
    "typesense": {
      "command": "npx",
      "args": [
        "-y",
        "typesense-mcp-server",
        "--host", "your-typesense-host",  // 替换为您的 Typesense 主机地址 (例如：localhost 或 IP 地址)
        "--port", "8108",                 // 替换为您的 Typesense 端口号 (通常为 8108)
        "--protocol", "http",              // 替换为您的 Typesense 协议 (http 或 https)
        "--api-key", "your-api-key"       // 替换为您的 Typesense API 密钥
      ]
    }
  }
}

参数说明:

'server name': 'typesense' - 服务器名称，客户端通过此名称引用该服务器。
'command': 'npx' - 用于执行 npm 包的命令。
'args': 启动服务器的参数列表，包括：
- '-y': 'npx' 参数，自动确认执行 npm 包。
- 'typesense-mcp-server': 要执行的 npm 包名称，即 Typesense MCP Server。
- '--host': Typesense 服务器的主机地址。
- '--port': Typesense 服务器的端口号。
- '--protocol': Typesense 服务器的协议 (http 或 https)。
- '--api-key': 用于访问 Typesense 服务器的 API 密钥。 请务必替换为您的真实 API 密钥。

配置方法: 将以上 JSON 配置添加到 MCP 客户端的配置文件中。例如，对于 Claude Desktop，配置文件路径为：

MacOS: '~/Library/Application Support/Claude/claude_desktop_config.json'
Windows: '%APPDATA%/Claude/claude_desktop_config.json'

基本使用方法

启动 MCP 客户端: 启动配置了 Typesense MCP Server 的 MCP 客户端 (如 Claude Desktop)。
客户端连接服务器: 客户端会自动根据配置信息连接到 Typesense MCP Server。
利用工具和 Prompt: 在客户端中，您可以指示 LLM 使用 'typesense_query' 等工具来搜索 Typesense 数据，或者使用 'analyze_collection' 等 Prompt 来分析 Collection。 LLM 将通过 MCP 服务器与 Typesense 交互，并将结果返回给您。

例如，在 Claude Desktop 中，您可以指示 Claude 执行以下操作：

"使用 typesense_query 工具在名为 'products' 的 collection 中搜索包含 '机器学习' 的产品，并返回标题和描述。"
"分析名为 'articles' 的 collection，告诉我这个 collection 主要包含哪些类型的信息。"

LLM 将会调用 Typesense MCP Server 提供的工具和 Prompt，从而实现对 Typesense 数据的访问和利用。

关键词