使用说明（Markdown）

• 项目简介

  • 该仓库实现了一个 MCP 服务器，用作将 Angel OS 平台的数据与功能暴露给基于 MCP 的 LLM 客户端（如 Claude Code）进行对话式交互。服务器通过 JSON-RPC 风格的请求/响应和多种传输通道（此实现采用 stdio）实现与客户端的通信，并暴露若干“工具（Tools）”，便于 LLM 调用外部功能、查询资源和获取 Prompt 模板。

• 主要功能点

  • MCP 核心暴露
    • 指定名称、版本号等元信息，提供对外的 JSON-RPC 2.0 风格接口。
  • 资源、工具、提示模板管理
    • 通过 MCP 服务器暴露多组工具（如 list_products、get_product、list_spaces、list_events、create_event 等共多达 23 种工具），可由 LLM 调用以完成资源访问、外部功能执行与数据渲染。
  • JWT/SOAP 风险与自我认证
    • 服务器实现了基于 PAYLOAD_SECRET 的自动化 JWT 生成与 Bearer 令牌使用，支持零配置的认证机制。
  • 与 Payload 的集成
    • MCP 调用通过 /api/mcp 与 Payload CMS 的端点进行数据查询和变更（如查找产品、事件、订单、 tenant 等），并通过统一的 api 调用封装。
  • 传输与协议
    • 传输采用标准的 stdio（命令行/脚本管道式通信）作为 MCP 的基础传输层；后续也可扩展为 SSE/WebSocket 等传输。
  • 会话与能力声明
    • 服务器含有会话上下文、能力声明以及工具的暴露，确保 LLM 客户端在运行时能获得一致、可审计的上下文与能力边界。

• 安装步骤

  • 克隆仓库并安装依赖
  • 运行 MCP 服务器（本实现基于 Node.js/TypeScript，使用 tsx 直接执行入口）
  • 若需要日志与调试，请确保环境变量正确配置（如 PAYLOAD_SECRET、ANGEL_OS_API_KEY 等）

• 服务器配置（MCP 客户端需要）

  • MCP 客户端需要提供一个配置，包含服务器名称、启动命令及参数，以便与 MCP 服务器建立连接，示例仅供理解，实际客户端无需此处显示代码。
  • 配置示例（JSON）说明性文本：
  • serverName: "angel-os"
  • command: "npx tsx mcp-server/index.ts"
  • args: []
  • 注释：serverName 指 MCP 服务在客户端的标识名称；command 指用于启动 MCP 服务器的命令；args 为启动命令的参数，视具体运行环境调整。该配置用于 MCP 客户端在初始化阶段知道如何启动并连接到 MCP 服务器。MCP 客户端本身不需要包含对后端实现细节的依赖。

• 基本使用方法

  • 启动与连接：在具备运行环境的前提下，按照配置启动 MCP 服务器，MCP 客户端将通过 JSON-RPC 调用向服务器请求资源、执行 Tools、渲染 Prompts。
  • 调用方式：客户端通过发送标准化的 JSON-RPC 请求（如“method: list_products”、“method: talk_to_merlin”等）来读取资源、执行工具、获取 Prompt 模板等。
  • 安全性：鉴权依赖于 PAYLOAD_SECRET/ANGEL_OS_API_KEY，并在请求头中携带 Bearer token 进行认证，确保跨租户调用的安全性。
  • 扩展性：服务端暴露的工具数量较多（23 工具），可通过向 MCP Server 注册新工具进行扩展，并通过 Payload CMS 的数据结构进行资源治理。

• 维护与扩展

  • 如需新增工具，遵循 MCP 标准为新工具定义名称、描述、参数（使用 zod 验证）和执行逻辑，统一暴露给 MCP 客户端。
  • 如需要新增资源类型或 Prompts，参照现有工具结构和资源查询模式进行实现。
  • 测试与本地调试：推荐在本地搭建 Payload CMS 数据库并执行 mv 或 migrate，确保工具调用可访问的端点。

• 备注

  • 本 MCP 实现的核心在 mcp-server/index.ts，基于 @modelcontextprotocol/sdk 的 MCP 服务实现，配合 stdio 传输、JWT 授权、以及对 Payload API 的集成，提供了较完整的 MCP 服务端能力与扩展性。