使用说明

• 项目简介

  • 该仓库实现了一个 MCP 服务器，按照 MCP 协议规范处理请求与响应，通过 SSE 进行通信，提供以下核心能力：托管资源与资源模板、注册并执行工具、以及提供可渲染的 Prompt/Widget 内容。服务器对外提供 SSE 流端点、消息请求端点和健康检查，便于与 ChatGPT 的 MCP 客户端对接。

• 主要功能点

  • MCP 服务器核心：实现基于 MCP 协议的请求处理、工具调用、资源查询与读取等能力，提供标准化的 JSON-RPC 风格响应。
  • 资源与模板管理：暴露资源和资源模板信息，支持读取 Widget HTML 内容作为输出模板。
  • 工具注册与执行：定义并注册工具（如 get_items、create_item 等），对输入进行校验，并返回文本内容、结构化内容和元数据，支持后续在模型中渲染与使用。
  • Widget 构建与嵌入：包含 Widget 代码、打包脚本和嵌入 HTML，支持将打包后的 Widget 注入到 MCP 的资源中，以实现 UI 渲染。
  • 安全与稳定性考虑：实现了跨域资源共享（CORS）支持、SSE 会话管理、工具输入校验、以及基础的错误处理与日志输出。

• 安装步骤

  • 安装依赖：在项目根目录执行依赖安装（如 npm install / yarn install）。
  • 构建 Widget：执行打包脚本将前端 Widget 打包为 dist/widget/bundle.js 与 bundle.css。
  • 构建并启动服务器：按照项目的构建与启动流程，将 TypeScript 代码编译为可执行的 JS（dist/server/index.js），然后启动 Node.js 进程运行 MCP 服务器。
  • 运行前置条件：确保环境变量或配置文件中设置了 APP 名称、版本、以及后端 API 的基础地址等信息（如 APP_NAME、APP_VERSION、API_BASE_URL 等）。

• 服务器配置（MCP 客户端所需，MCP 客户端不需要额外信息，但用于连接示例）

  • 服务器名称（server_name）：ChatGPT-App-{{APP_NAME}}，用于唯一标识你的 MCP 服务器实例。
  • 启动命令（command）：node
  • 启动参数（args）：["dist/server/index.js"]
  • 其他可选参数（环境变量示例，客户端可参考）：{ "APP_NAME": "{{APP_NAME}}", "APP_VERSION": "1.0.0", "API_BASE_URL": "https://api.{{APP_DOMAIN}}" }
  • 客户端需要的连接端点（供参考，具体由客户端实现时确定）：
    • SSE 流：GET http://<host>:<port>/mcp
    • 消息处理：POST http://<host>:<port>/mcp/messages?sessionId=...
    • 健康检查：GET http://<host>:<port>/health

• 基本使用方法

  • 启动后，MCP 客户端通过 SSE 连接到 /mcp，建立会话并交互读取资源、调用工具、获取提示模板等。
  • 调用工具时，客户端会提供工具名与参数，服务器返回文本内容、结构化内容以及元数据，供 LLM 解析和应用。
  • 客户端可通过读取 Widget 资源来渲染前端界面，Widget 已打包并可以嵌入到对话上下文中以提升交互体验。