XPouch MCP 服务器

使用说明（Markdown 格式）

• 项目简介 XPouch MCP 服务器基于 Model Context Protocol（MCP），实现了资源管理、工具注册/执行、以及 Prompt 模板的定义与渲染等核心能力。服务器通过 SSE/HTTP 等传输协议为 LLM 客户端提供结构化的上下文服务，支持多服务器工具集成、HITL 人机回环、以及可扩展的工具生态。前端的库页面可用于注册并管理 MCP 服务器，后端则处理服务器发现、连接测试、以及工具元数据的缓存与注入。

• 主要功能点

  • MCP 服务器注册与管理
    • 注册新的 MCP 服务器，测试连接并注入运行时
    • 支持多种传输协议（SSE 为主，后续可扩展）
  • 工具与资源托管
    • 动态加载并缓存 MCP 服务器的工具集合
    • 支持 TTL 缓存、并发单飞保护（single-flight）
  • Prompts 与模板
    • 定义和渲染 Prompts，用于 LLM 的上下文注入与交互模式
  • 安全与会话管理
    • 会话状态、用户认证、速率限制、以及 HITL 回放能力
  • 与 LangGraph 和 MCP 生态集成
    • 通过 mcp_tools_service 加载Server Tool
    • 通过 Streamable HTTP / SSE 提供高吞吐的上下文流

• 安装步骤（简化）

  1. 获取代码：将仓库克隆到本地或服务器。
  2. 配置环境变量：按后端配置要求提供 PostgreSQL、LangChain/LangGraph、以及 LLM 提供商的 API Key 等。
  3. 启动后端服务：可使用 Docker Compose 进行一键部署，或在本地直接运行后端 FastAPI 应用。
  4. 启动 MCP 服务端：确保后端应用以可对外暴露的端口运行，默认的 SSE 入口地址用于 MCP 客户端连接（示例：http://0.0.0.0:3001/sse）。
  5. 在前端 Library 页面添加 MCP Server：填写名称、描述、SSE URL（如 http://localhost:3001/sse），系统会自动测试连通性并注入到 LangGraph 运行时。
  6. MCP 客户端配置（JSON，示例仅示意，具体字段请参考客户端文档） { "server_name": "xpouch-fetch-server", "command": "uvicorn", "args": ["backend.main:app", "--host", "0.0.0.0", "--port", "3001"] }

• 服务器配置（MCP 客户端需要的最小信息）

  • server name（服务器名称，唯一标识）
  • command（启动服务器所用命令的主程序，例如 uvicorn）
  • args（启动参数，包含主模块、HOST、PORT 等） 注：MCP 客户端通常需要的其实是 SSE 端点地址（如 /sse），以及服务器的名称与连接信息。上述 JSON 提供了启动指令的注释性示例，帮助理解与集成。

• 基本使用方法

  1. 在 Library 页面新增 MCP Server，并确保服务器上线且可通过 SSE 端点访问。
  2. MCP 客户端通过服务器的名称与地址建立连接，读取工具并在 LangGraph 运行时注入。
  3. 使用 MCP 提供的工具接口进行 Web/SSE 交互，LLM 客户端在获得上下文后即可调用外部工具。
  4. 通过 HITL 面板进行任务审核、暂停、继续执行等人机回环操作。