Turbopuffer MCP 服务器（TypeScript 实现）

关键词

LLM context工具执行文档搜索向量检索API 服务端

使用说明（简要、易上手）

  • 项目简介

    • 此仓库实现了一个可运行的 MCP 服务器，核心功能包括：
      • 注册并执行“工具（Tools）”以调用外部功能
      • 管理“资源（Resources）”以提供数据访问
      • 定义和渲染“Prompt 模板”，支持可定制的 LLM 交互模式
      • 通过 JSON-RPC 与客户端通信，支持多种传输方式（如 STDIO、HTTP）
      • 会话管理、能力声明，以及对日志、重试、超时等行为的全面处理

  • 主要功能点

    • MCP 服务端实现：提供 ListTools、CallTool、SetLevel 等请求处理，绑定工具实现与客户端交互
    • 传输层支持：
      • STDIO 传输：直接在命令行环境中启动
      • HTTP 传输：通过 Express 服务器对外提供 REST 风格的入口
    • 工具集合：内置 execute 工具、文档搜索工具等，便于演示和扩展
    • 认证与授权：通过 Authorization 头和自定义头部进行简单鉴权
    • 配置与扩展：
      • 可以通过选项控制是否暴露文档工具、日志等级等
      • 提供工具执行流的包装，使其与 Turbopuffer 客户端无缝对接
    • 错误与日志：全面的错误分层（如 NotFoundError、APIError、APIConnectionError 等）及可定制日志输出

  • 安装步骤

    1. 克隆仓库并安装依赖
    2. 在项目根目录执行构建/安装流程（根据仓库的工作流，通常包含安装依赖、构建 MCP 服务包等）
    3. 安装并运行 MCP 服务器（参考下方配置示例）

  • 服务器配置（MCP 客户端需要的最小配置） 说明：MCP 客户端需要一个配置，指明服务器名称、启动命令及参数等，以便建立连接。本示例基于仓库中的实现信息给出准确且可执行的配置项描述。请将以下信息提供给你的 MCP 客户端配置系统： { "server": { "name": "turbopuffer_turbopuffer_api", "command": "npx", "args": ["@turbopuffer/turbopuffer-mcp", "--transport=http", "--port=5000"] } // 说明： // - server.name 对应 MCP 服务器在内部的标识，源自 newMcpServer 的名称字段 // - server.command 与 server.args 指定如何启动 MCP 服务器。此处使用 npx 调用 MCP 服务入口 // - transport 设置为 http 时，服务器将通过 HTTP 提供服务，端口为 5000，可以根据实际环境调整 }

  • 基本使用方法

    • 启动服务器
      • 在支持的环境中，使用上述配置启动服务器。若使用 STDIO 模式，默认会在标准输入输出流中与客户端通信；若使用 HTTP 模式，则通过指定端口提供 JSON-RPC 接口。
    • 连接与交互
      • MCP 客户端通过 JSON-RPC 调用服务器的工具列表、执行工具、查询、写入等能力。确保客户端配置正确指向服务器地址与端口。
    • 运行与调试
      • 关注服务启动日志，确保服务器成功输出启动提示（如“MCP Server running on stdio/streamable HTTP”等）
      • 如需要调试，可在代码中开启调试日志并按需调整日志等级

  • 运行与扩展要点

    • 服务器内置了 execute 工具和文档搜索工具，便于演示与测试，并可按需扩展新的工具实现
    • 支持来自环境变量的默认命名空间、区域、默认命名空间等设置，通过 MCP 客户端配置传入
    • 具备错误分层，便于定位问题与统一处理

  • 参考要点

    • 服务器端实现基于 @modelcontextprotocol/sdk 的 MCP 服务端组件，提供必要的路由/处理器来响应 MCP 协议的请求
    • 提供 StreamableHTTPServerTransport 与 StdioTransport 两种传输实现，确保可在多种运行环境中使用

服务器信息

访问项目