Voyage AI MCP 服务器

使用说明

• 项目简介

  • 该仓库实现了一个 MCP 服务器，用于向 AI 客户端（如 Claude、Cursor、Windsurf、VS Code 等工具）暴露 Voyage AI 的资源、工具和提示模板。服务器核心职责包括：托管资源以提供数据访问、注册并执行工具、定义和渲染 Prompt 模板，并通过 JSON-RPC 与客户端通信。服务器端负责会话管理、能力声明，并支持多种传输协议以实现灵活的集成场景。

• 主要功能点

  • 资源管理：提供对嵌入向量、数据源等资源的访问能力。
  • 工具注册与执行：将 Voyage AI 的查询、检索、嵌入、相似度、聚合等工具注册为可被远程调用的接口。
  • Prompt 模板渲染：定义并渲染用于与 LLM 交互的提示模板，支持自定义上下文与工作流。
  • JSON-RPC 标准通信：通过 JSON-RPC 请求与响应实现客户端调用与服务端能力暴露。
  • 多传输协议支持：默认 stdio，亦可通过 HTTP/SSE/WebSocket 等方式对外暴露服务。
  • 会话与能力声明：提供会话管理、能力表述以及对外暴露的服务器能力信息。
  • 安全与扩展性：集中管理工具、资源与 Prompts 以实现安全、可扩展的后端上下文服务。

• 安装与运行

  • 本仓库包含完整的 MCP 服务实现代码，建议在 Node.js 18+ 环境下运行。先安装依赖、编译/构建（若有构建步骤），再启动 MCP 服务。仓库内提供多种传输模式的示例与文档。

• 服务器配置（给 MCP 客户端的配置信息说明）

  • 配置用途：MCP 客户端需要知道如何启动并连接到 MCP 服务器。本描述仅供参考，实际客户端配置按自身工具要求进行；下列信息为与本仓库实现对应的示意描述，用于帮助理解哪些字段需要包含。
  • serverName: vai-mcp-server
  • command: vai
  • args: [ "mcp", "--transport", "stdio" // 默认为 stdio，若使用远程客户端可切换为 http、sse、websocket 等 // 其他必要参数如端口、认证等按需要添加 ]
  • 注：该配置用于 MCP 客户端在启动时知道服务器进程及启动参数的组合。客户端本身不需要依赖此处的实现细节，只需按照服务器的启动方式进行连接即可。

• 基本使用方法

  1. 启动方式
     • 使用标准输入输出（stdio）模式直接在同一进程中启动并与 MCP 客户端进行通信。
     • 或者通过 HTTP/WS/SSE 端口对外暴露，在远程客户端中使用相应传输协议进行连接。
  2. 组件协作方式
     • 客户端通过 JSON-RPC 调用服务器的资源读取、工具执行、Prompts 渲染等能力。
     • 服务器维持会话状态、能力声明，并对外暴露可用的工具集和资源集合。
  3. 集成要点
     • MCP 客户端在使用前应将服务器地址、传输模式等信息配置到连接配置中。
     • 若使用 HTTP/SSE/WebSocket，请确保网络可访问且认证（如需要）配置正确。
  4. 运行示例（非代码块说明）
     • 通过 CLI 启动（示例命令，具体环境请参考仓库文档）："vai mcp --transport http --port 3100"
     • 客户端通过 JSON-RPC 请求向服务器发起读取资源、调用工具、获取 Prompt 等操作，服务器返回标准的 JSON-RPC 响应。
  5. 安全与运维
     • 使用 API 密钥、访问控制和日志审计等机制保护 MCP 服务的访问。
     • 结合监控、健康检查等工具对服务进行运行状态与性能监控。

• 运行与调试建议

  • 首先遵循仓库内的文档（docs/mcp-server.md）了解服务器端实现细节、API 约定与传输模态。
  • 通过已有的测试用例对 MCP 功能进行本地化验证，确保资源、工具、Prompts 的注册与执行路径正常工作。
  • 根据实际需求选择合适的传输模式（stdio、http、sse、websocket 等），并据此调整客户端连接配置。