Marionette MCP 服务器实现

使用说明（Markdown 格式）

• 项目简介

  • Marionette 是一个基于 MCP 的后端服务器实现，目标是向大型语言模型客户端提供结构化的上下文信息、可注册的工具以及可渲染的提示模板。通过 JSON-RPC 风格的请求/响应方式，支持资源、工具调用和提示渲染等核心能力，并且具备会话管理和多传输协议的支持能力（如 Stdio、WebSocket、SSE 等）。

• 主要功能点

  • MCP 服务器核心：实现对 MCP 请求（如读取工具、执行工具、获取提示等）的处理，返回符合 MCP 规范的 JSON-RPC 响应。
  • 工具注册与执行：工具注册中心根据服务器配置提供工具定义，并实现工具调用的执行逻辑（如 Set Task 等工具，与 Jira 等服务集成）。
  • 资源与会话管理：与 Claude Code 的 JSONL 会话结合，维持会话标识、任务名称、Jira 票据等元信息，支持历史会话的导入和实时监听。
  • 代理与扩展性：通过本地 API 代理与 WebSocket 服务，提供会话事件上报、状态同步、以及与前端 UI 的交互能力。
  • 配置与 CLI 集成：提供命令行脚本用于在 Claude Code 中注册 MCP 服务器，自动化把 MCP 服务器加入工作流中。
  • 传输与容错：提供 Stdio 传输作为 MCP 服务的默认实现，同时具备 WebSocket 等传输的扩展能力，具备重连与清理机制。

• 安装步骤

  • 克隆仓库并安装依赖（建议使用 Node.js 18+、pnpm）。
  • 构建 MCP 服务器包：
    • 进入仓库根目录，安装依赖并构建 packages/mcp-server。
  • 启动 MCP 服务器（示例路径以实际环境为准）：
    • 运行 dist/index.js（通过 npm/yarn/pnpm 脚本进行构建后的输出）。
  • 配置 Claude Code 使用 Marionette：
    • 通过 marionette-mcp 配置脚本，将 Marionette 服务器以 Node 进程形式作为 MCP 服务注册到 Claude Code。
  • 运行 Claude Code，确保 Marionette API 服务地址正确（默认 http://localhost:8787）。

• 服务器配置（MCP 客户端无需额外开发，只是供配置参考）

  • server_name: Marionette MCP Server
  • command: node
  • args: ["/path/to/仓库根目录/packages/mcp-server/dist/index.js"]
  • env: MARIONETTE_API_URL: "http://localhost:8787" // 后端 MCP API 的入口地址 注释说明：以上是 Claude Code 作为 MCP 客户端时需要在配置中填写的字段组合。MCP 客户端会使用这些信息来启动并连接到 MCP 服务器，后续的通讯采用 MCP 约定的 JSON-RPC 请求/响应格式。

• 基本使用方法

  • 启动 MCP 服务后，确保 Claude Code 已经安装并配置指向 Marionette 的 MCP 服务器（通过前述 CLI 配置步骤）。
  • Claude Code 将通过 MCP 通道向 Marionette 请求工具定义、执行工具、获取提示等。
  • 服务器端会管理会话身份、工具运行、以及与外部系统（如 Jira、WebSocket 通道）之间的交互。
  • 通过服务器日志与 API 代理的错误处理来排查问题，必要时可调整 MARIONETTE_API_URL 等环境变量。

• 额外信息

  • 本实现包含一个文件 watcher、一个 API 代理、以及若干服务组件（如 WebSocket 服务、Jira 服务、工具注册等），以支撑 MCP 服务器在真实场景中的持续运行、扩展性与可观测性。