关键词

代码执行文件操作Git操作自动化LLM工具集成

项目简介

这是一个增强版的 Model Context Protocol (MCP) 服务器，它基于 Anthropic 的 Claude Code CLI 工具构建。该服务器允许大型语言模型 (LLM) 客户端（如 Claude Desktop, Cursor 等）通过标准化的 MCP 协议与 Claude Code 进行交互，执行代码、文件系统、Git、终端命令等复杂任务。

项目特点包括绕过权限提示、强大的任务编排能力（如“回旋镖模式”）、鲁棒的错误处理、自动重试、配置热加载以及通过 '.roomodes' 文件进行模式集成等。

主要功能点

  • 安全执行 Claude Code: 通过 MCP 协议，LLM 可以调用服务器托管的 'claude_code' 工具，执行代码、文件、Git 等操作，并自动处理 '--dangerously-skip-permissions' 权限。
  • 任务编排与自动化: 支持将复杂任务分解为子任务，并通过父任务 ID 和返回模式（summary/full）进行管理。内置 Markdown 任务转换工具，可将结构化的 Markdown 任务列表自动转换为可执行的 MCP 命令序列。
  • 增强的可靠性: 实现心跳机制防止客户端超时、对瞬时错误进行自动重试、请求跟踪和优雅关机。
  • 文件系统及 Git 操作: LLM 可以直接访问文件编辑、目录列表、文件移动/复制/删除以及 Git 版本控制等功能。
  • 终端命令执行: LLM 可以请求服务器执行任意终端命令或打开 URL。
  • 健康检查: 提供 'health' 工具用于检查服务器状态、版本和配置。
  • Roo 模式集成: 如果启用并通过 '.roomodes' 文件配置，可以为 'claude_code' 工具指定特定的模式（如 'coder', 'designer'）以影响 Claude 的行为。

安装步骤

  1. 安装 Node.js: 需要 Node.js v20 或更新版本。推荐使用 fnm 或 nvm 进行安装管理。
  2. 安装 Claude CLI: 在本地安装 Claude CLI ('@anthropic-ai/claude-code')。
  3. 接受 Claude CLI 权限: 重要步骤！ 首次使用前，必须手动运行一次 'claude --dangerously-skip-permissions' 命令，登录并接受权限提示。 macOS 可能还会要求文件访问权限，首次运行可能失败，之后正常。
  4. 安装并启动 MCP 服务器:
    • 推荐方式（使用 npx）: 在 MCP 客户端的配置文件（如 '.mcp.json' 或 'mcp_config.json'）中直接配置，客户端将使用 'npx' 启动服务器。
    • 手动方式: 克隆仓库，运行 'npm install' 安装依赖，然后运行 'npm run build' 构建项目。之后在 MCP 配置文件中指向构建好的 'dist/server.js' 文件。

服务器配置

该 MCP 服务器需要通过 MCP 客户端的配置文件（通常是 '.mcp.json' 或 'mcp_config.json'）进行设置。以下是配置一个使用 Stdio 传输协议连接到此服务器的示例结构：

在您的 MCP 配置文件中，找到 'mcpServers' 部分，添加一个新的服务器条目。条目名称（例如 "Local Claude Code Server"）是您在客户端中看到的服务器名称。

{
  "mcpServers": {
    "Local Claude Code Server": {
      // 服务器类型，通常使用 "stdio"
      // 更多信息请参考 MCP 客户端或 SDK 文档
      "type": "stdio",

      // 启动服务器进程的命令
      // 如果使用手动方式安装，这里指向您构建好的 server.js 文件
      "command": "node",

      // 传递给 command 的参数列表
      // 如果使用手动方式，参数为 ["dist/server.js"]
      // 如果使用 npx 方式，参数为 ["-y", "@steipete/claude-code-mcp@latest"]
      "args": ["dist/server.js"], // 示例：手动方式配置

      // 可选的环境变量配置，用于定制服务器行为
      "env": {
        // 设置为 "true" 启用调试日志
        "MCP_CLAUDE_DEBUG": "false",
        // 心跳间隔（毫秒），防止客户端超时，默认 15000 (15秒)
        "MCP_HEARTBEAT_INTERVAL_MS": "15000",
        // CLI 执行超时时间（毫秒），默认 1800000 (30分钟)
        "MCP_EXECUTION_TIMEOUT_MS": "1800000",
        // 设置为 "true" 启用 .roomodes 集成
        "MCP_USE_ROOMODES": "true",
        // 设置为 "true" 监听 .roomodes 文件变化并热加载
        "MCP_WATCH_ROOMODES": "true",
        // 瞬时错误的重试次数，默认 3
        "MCP_MAX_RETRIES": "3",
        // 重试之间的延迟（毫秒），默认 1000 (1秒)
        "MCP_RETRY_DELAY_MS": "1000"
      }
    }
    // ... 您可能配置的其他 MCP 服务
  }
}

请根据您的安装方式（npx 或手动）修改 'command' 和 'args' 参数。

基本使用方法

配置完成后，您的 MCP 客户端（如 LLM 助手界面）将能够通过这个服务器调用 Claude Code 的能力。您通常不需要直接与服务器进程交互，而是通过 LLM 客户端的界面或指令来利用它。

例如，当您在支持 MCP 的 LLM 客户端中向 LLM 发起请求时，LLM 可以根据您的需求和自身逻辑，决定调用此服务器提供的工具：

  • 调用 'claude_code' 执行任务: LLM 会向服务器发送一个工具调用请求，指定工具名称（如 'claude_code:claude_code'）和参数（包含 'prompt' 和可选的 'workFolder', 'parentTaskId', 'returnMode', 'taskDescription', 'mode'）。
    • 例如，要求 LLM 编辑文件：您可以告诉 LLM：“使用 'claude_code' 工具，工作目录设置为 '/path/to/project'，编辑文件 'src/main.py'，将变量 'DEBUG = True' 修改为 'DEBUG = False'。” LLM 会构建相应的 MCP 工具调用请求发送给服务器。
    • 例如，要求 LLM 执行 Git 命令：您可以告诉 LLM：“使用 'claude_code' 工具，工作目录设置为 '/path/to/project'，提交暂存的修改，提交信息为 'fix: resolved issue #123'。”
  • 调用 'health' 检查状态: LLM 会向服务器发送一个 'claude_code:health' 工具调用请求，服务器返回包含状态、版本、配置等的 JSON 响应。
  • 调用 'convert_task_markdown' 转换任务: 如果您编写了结构化的 Markdown 任务文件，LLM 可以调用 'claude_code:convert_task_markdown' 工具，提供 Markdown 文件路径，服务器将转换后的 MCP 任务列表返回给 LLM 或保存到文件。

请注意，具体的交互方式取决于您的 MCP 客户端如何暴露和利用这些 MCP 工具。

信息

分类

开发者工具

访问项目