mcp-wcgw

Claude 和其他 mcp 客户端的 Shell 和编码代理

使聊天应用程序能够在本地机器上进行编码、构建和运行。

wcgw 是一个具有紧密集成的 shell 和代码编辑工具的 MCP 服务器。

⚠️ 警告：未经审查的命令请勿允许使用 BashCommand 工具，否则可能会导致数据丢失。

演示

更新

• [2025 年 4 月 27 日] 移除了对中继服务器上 GPT 的支持。5 及以上版本仅支持 MCP 服务器。
• [2025 年 3 月 24 日] 改进了 sonnet 3.7 的写作和编辑体验，CLAUDE.md 会自动加载。
• [2025年2月16日] 您现在可以连接到AI使用的工作终端。请参阅下面的“连接到终端”部分。
• [2025 年 1 月 15 日] 引入模式：架构师、代码编写者以及功能强大的 wcgw 模式。
• [2025 年 1 月 8 日] 上下文保存工具，用于将相关文件路径及其描述保存在单个文件中。可用作任务检查点或知识传递。
• [2024 年 12 月 29 日] 文件写入和编辑的语法检查现已稳定。 initialize工具调用更加实用；如果引用了任何仓库，则将智能仓库结构发送给 Claude。大文件处理也得到了改进。
• [2024 年 12 月 9 日] Vscode 扩展程序可在 Claude 应用上粘贴上下文

🚀 亮点

• ⚡创建、执行、迭代：要求 Claude 继续运行编译器检查，直到所有错误都得到修复，或者要求它继续检查长时间运行的命令的状态，直到完成。
• ⚡大文件编辑：支持大文件增量编辑，避免令牌限制问题。根据所需更改的百分比，智能地选择何时进行小幅编辑或大规模重写。
• ⚡编辑时的语法检查：如果编辑有任何语法错误，则向 LLM 报告反馈，以便其可以重做。
• ⚡交互式命令处理：支持使用箭头键、中断和 ansi 转义序列的交互式命令。
• ⚡文件保护：
  • 人工智能需要至少读取一次文件，然后才允许编辑或重写它。这可以避免意外覆盖。
  • 避免读取大文件时上下文被填满。文件会根据 token 长度进行分块。
  • 初始化时，选择重要文件后返回提供的工作区目录结构（基于.gitignore以及统计方法）
  • 基于搜索-替换的文件编辑，如果根据之前的搜索块有多个匹配项，则会尝试找到正确的搜索块。否则，将失败（为了确保正确性）。
  • 文件编辑支持间距匹配，并会对缩进不匹配等问题发出警告。如果匹配不成功，则会将最接近的匹配返回给 AI 以修复错误。
  • 使用类似Aider的查找替换，比基于工具调用的查找替换性能更好。
• ⚡ Shell 优化：
  • 每次只允许运行一个命令，简化管理并避免恶意进程。任何时间点都只有一个 shell 实例。
  • 任何 shell 命令之后总是返回当前工作目录，以防止 AI 丢失。
  • 命令轮询会在短暂超时后退出，以避免反馈缓慢。然而，状态检查会根据命令的最新输出流进行等待容忍。这两种方法相结合，提供了良好的 Shell 交互体验。
• ⚡将代码库上下文保存到单个文件中：使用“ContextSave”工具进行任务检查点操作，可将详细上下文保存到单个文件中。稍后可以在新的聊天中通过询问“恢复task id ”来恢复任务。保存的文件可用于其他类型的知识传递，例如从其他 AI 那里获取帮助。
• ⚡轻松切换各种模式：
  • 让它以“建筑师”模式运行进行规划。受 Adier 建筑师模式的启发，先与 Claude 合作制定计划。这样可以提高准确性，并防止过早编辑文件。
  • 要求它以“代码编写器”模式运行，以进行代码编辑和项目构建。您可以提供支持通配符的特定路径，以防止其他文件被编辑。
  • 默认情况下，它以没有限制和完全授权的“wcgw”模式运行。
  • 更多详情请参阅模式部分
• ⚡**在多路复用终端中运行。**运行screen -x连接到 AI 运行命令的终端。查看历史记录、中断进程，或与 AI 使用的同一终端交互。

热门用例示例

• 使用 Python 解决问题 X，创建并运行测试用例，并修复所有问题。请在临时目录中执行此操作
• 在我的存储库中查找具有 X 行为的代码实例
• 在我的主目录中 Git clone https://github.com/my/repo ，然后了解项目，设置环境并构建
• 创建一个 golang htmx tailwind webapp，然后打开浏览器查看它是否有效（与 puppeteer mcp 一起使用）
• 编辑或更新大文件
• 在单独的分支中创建功能 Y，然后使用 github cli 创建到原始分支的 PR
• 命令 X 在 Y 目录中失败，请运行并修复问题
• 使用X虚拟环境运行Y命令
• 使用命令行工具，创建并测试一个 Android 应用。最后用模拟器运行它供我使用。
• 修复 X 路径中我的 repo 中的所有 mypy 问题。
• 使用“screen”在后台运行我的服务器，然后在后台运行另一个 API 服务器，最后运行前端构建。请持续检查这三个步骤的日志，看看是否存在任何问题。
• 创建代码库范围内的单元测试用例。持续迭代文件并创建用例。每次更新后也请持续运行测试。请勿修改原始代码。

Claude 设置（使用 mcp）

Mac 和 Linux

首先使用 homebrew brew install uv install uv安装 uv

（**重要提示：**使用 homebrew 安装 uv。否则请确保uv位于全局位置，例如 /usr/bin/）

然后使用以下 json 创建或更新claude_desktop_config.json (~/Library/Application Support/Claude/claude_desktop_config.json)。

然后重新启动 claude 应用程序。

如果设置过程中出现错误

• 如果出现类似“uv ENOENT”的错误，请确保已安装uv 。然后在终端中运行“which uv”，并使用它的输出替换配置中的“uv”。
• 如果问题仍然存在，请检查uv tool run --python 3.12 wcgw@latest是否在终端中运行。它应该没有输出，并且不会退出。
• 尝试删除 ~/.cache/uv 文件夹
• 尝试使用已测试此工具的uv版本0.6.0 。
• 使用npx @modelcontextprotocol/inspector@0.1.7 uv tool run --python 3.12 wcgw@latest调试 mcp 服务器

wsl 上的 Windows

此 mcp 服务器仅适用于 Windows 上的 wsl。

要进行设置，请安装 uv

然后使用以下内容添加或更新 claude 配置文件%APPDATA%\Claude\claude_desktop_config.json

用法

等待几秒钟。如果一切顺利，你应该能够看到这个图标。

在这里

然后让 claude 执行 shell 命令、读取文件、编辑文件、运行代码等。

任务检查点或知识转移

• 您可以使用“从 MCP 附加”按钮附加“KnowledgeTransfer”提示来进行任务检查点或知识转移。
• 运行“KnowledgeTransfer”命令时，将调用“ContextSave”工具，将任务描述和所有文件内容保存到一个文件中。同时，系统将生成该任务的 ID。
• 您可以在新聊天中说“恢复”，然后 AI 应该使用任务 ID 调用“初始化”并从那里加载上下文。
• 或者您可以直接打开生成的文件并与另一个 AI 共享以获得帮助。

模式

内置三种模式。你可以让 Claude 在其中一种模式下运行，例如“使用‘建筑师’模式”。

注意：在代码编写器模式下，目前要么允许所有命令，要么全部不允许。如果您提供允许的命令列表，Claude 会按照指示只运行这些命令，但不会进行实际检查。（开发中）

连接到工作终端进行调查

如果你安装了screen命令，wcgw 会自动在 screen 实例上运行。如果你已经启动了 wcgw mcp 服务器，则可以列出 screen 会话：

screen -ls

并记下 wcgw 屏幕名称，类似于93358.wcgw.235521其中最后一个数字采用小时-分钟-秒格式。

然后您可以使用screen -x 93358.wcgw.235521连接到会话

您可以安全地中断任何正在运行的命令。

您可以与终端交互，但请注意，AI 可能正在并行运行，并且可能与您正在执行的操作发生冲突。建议您尽量减少交互。

您不应该使用exit或 Ctrl-d 退出会话，而应该使用ctrl+a+d来安全分离而不破坏屏幕会话。

[可选] VS Code 扩展

https://marketplace.visualstudio.com/items?itemName=AmanRusia.wcgw

命令：

• 选择一段文本，按下cmd+'键，然后输入说明。这会将应用程序切换到 Claude，并粘贴一段包含说明、文件路径、工作区目录和所选文本的文本。

示例

通过 docker 使用 mcp 服务器

首先构建docker镜像docker build -t wcgw https://github.com/rusiaaman/wcgw.git

然后你可以更新/Users/username/Library/Application Support/Claude/claude_desktop_config.json以

[可选] 使用 openai API 密钥或 anthropic API 密钥进行本地 shell 访问

Openai

添加OPENAI_API_KEY和OPENAI_ORG_ID环境变量。

然后运行

uvx wcgw@latest wcgw_local --limit 0.1 # 费用限制 $0.1

您现在可以直接写消息或按回车键打开 vim 进行多行消息和文本粘贴。

人择

添加ANTHROPIC_API_KEY环境变量。

然后运行

uvx wcgw@latest wcgw_local --claude

您现在可以直接写消息或按回车键打开 vim 进行多行消息和文本粘贴。

工具

该服务器提供以下 MCP 工具：

Shell 操作：

• Initialize ：重置 shell 并设置工作区环境
  • 参数： any_workspace_path （字符串）、 initial_files_to_read （字符串[]）、 mode_name （“wcgw”|“architect”|“code_writer”）、 task_id_to_resume （字符串）
• BashCommand ：执���具有超时控制的 shell 命令
  • 参数： command （字符串）、 wait_for_seconds （int，可选）
  • 参数： send_text （字符串）或send_specials （["Enter"|"Key-up"|...]）或send_ascii （int[]）， wait_for_seconds （int，可选）

文件操作：

• ReadFiles ：从一个或多个文件读取内容
  • 参数： file_paths （string[]）
• WriteIfEmpty ：创建新文件或写入空文件
  • 参数： file_path （字符串）、 file_content （字符串）
• FileEdit ：使用搜索/替换块编辑现有文件
  • 参数： file_path （字符串）、 file_edit_using_search_replace_blocks （字符串）
• ReadImage ：读取图像文件进行显示/处理
  • 参数： file_path （字符串）

项目管理：

• ContextSave ：保存项目上下文和文件，用于知识转移或保存任务检查点，以便稍后恢复
  • 参数： id （字符串）、 project_root_path （字符串）、 description （字符串）、 relevant_file_globs （字符串[]）

所有工具都支持绝对路径，并内置了针对常见错误的保护机制。有关详细的协议信息，请参阅MCP 规范。