Claude及其他MCP客户端的Shell与编码代理工具

为聊天应用赋予在本地机器上编码、构建和运行的能力。

wcgw是一个集成了Shell和代码编辑工具的MCP服务器。

⚠️ 警告：未经审查不得使用BashCommand工具，可能导致数据丢失。

演示

更新日志

• [2025年4月27日] 移除了通过中继服务器支持GPTs的功能。版本>=5仅支持MCP服务器。

• [2025年3月24日] 改进了sonnet 3.7的写作和编辑体验，CLAUDE.md会自动加载。

• [2025年2月16日] 现在可以连接到AI使用的工作终端。详见下文的"attach-to-terminal"部分。

• [2025年1月15日] 新增模式：架构师模式、代码编写模式和全能的wcgw模式。

• [2025年1月8日] 上下文保存工具：可将相关文件路径与描述保存在单个文件中，可用作任务检查点或知识转移。

• [2024年12月29日] 文件写入和编辑的语法检查现已稳定。优化了initialize工具调用；如果引用任何仓库，会向claude发送智能仓库结构。大文件处理也得到了改进。

• [2024年12月9日] VSCode扩展：将上下文粘贴到Claude应用

🚀 核心功能

• ⚡ 创建、执行、迭代：让claude持续运行编译检查直到所有错误修复，或让其持续检查长时间运行命令的状态直到完成。

• ⚡ 大文件编辑：支持大文件增量编辑以避免令牌限制问题。根据所需更改百分比智能选择小编辑或大重写。

• ⚡ 编辑时语法检查：如果LLM的编辑存在语法错误，会报告反馈以便其重做。

• ⚡ 交互式命令处理：支持使用方向键、中断和ANSI转义序列的交互式命令。

• ⚡ 文件保护：

  • AI必须至少读取一次文件后才能编辑或重写，避免意外覆盖。
  • 避免读取超大文件时上下文填满。文件会根据令牌长度分块。
  • 初始化时返回工作区目录结构（基于.gitignore和统计方法选择重要文件）。
  • 基于搜索替换的文件编辑会尝试找到正确的搜索块（如果有多个匹配项），否则失败（确保正确性）。
  • 文件编辑具有间距容忍匹配，对缩进不匹配等问题发出警告。如果没有匹配项，返回最接近的匹配项供AI修正错误。
  • 使用类似Aider的搜索替换，性能优于基于工具调用的搜索替换。

• ⚡ Shell优化：

  • 一次只允许运行一个命令，简化管理并避免失控进程。任何时候只有一个Shell实例。
  • 任何Shell命令后总是返回当前工作目录，防止AI迷失方向。
  • 命令轮询在快速超时后退出以避免缓慢反馈。但状态检查对命令的新鲜输出流具有等待容忍度。这两种方法结合提供了良好的Shell交互体验。

• ⚡ 在单个文件中保存仓库上下文：使用"ContextSave"工具的任务检查点将详细上下文保存在单个文件中。任务可以在新聊天中通过"Resume task id"恢复。保存的文件可用于其他类型的知识转移，例如向另一个AI寻求帮助。

• ⚡ 轻松切换各种模式：

  • 让其以"architect"模式运行进行规划。受adier的架构师模式启发，与Claude一起先制定计划。提高准确性并防止过早编辑文件。
  • 让其以"code-writer"模式运行进行代码编辑和项目构建。可以提供带有通配符支持的特定路径以防止编辑其他文件。
  • 默认以"wcgw"模式运行，无限制且完全授权。
  • 更多详情见模式部分

• ⚡ 在多路复用终端中运行：运行screen -x附加到AI运行命令的终端。查看历史记录、中断进程或与AI使用的同一终端交互。

主要使用场景示例

• 使用Python解决问题X，创建并运行测试用例并修复任何问题。在临时目录中完成。
• 在我的仓库中查找具有X行为的代码实例。
• 在我的主目录中Git克隆https://github.com/my/repo，然后理解项目、设置环境并构建。
• 创建一个golang htmx tailwind Web应用，然后打开浏览器查看是否正常工作（与puppeteer MCP一起使用）。
• 编辑或更新大文件。
• 在单独的分支中创建功能Y，然后使用github CLI向原始分支创建PR。
• 命令X在Y目录中失败，请运行并修复问题。
• 使用X虚拟环境运行Y命令。
• 使用CLI工具创建、构建和测试Android应用。最后使用模拟器运行供我使用。
• 修复我的仓库中X路径的所有mypy问题。
• 使用'screen'在后台运行我的服务器，然后在后台运行另一个API服务器，最后运行前端构建。持续检查所有三个的日志是否有问题。
• 创建仓库范围的单元测试用例。持续迭代文件并创建测试用例。每次更新后持续运行测试。不要修改原始代码。

Claude设置（使用MCP）

Mac和Linux

首先使用Homebrew安装uv：brew install uv

（重要：使用Homebrew安装uv。否则确保uv位于全局位置，如/usr/bin/）

然后创建或更新claude_desktop_config.json（~/Library/Application Support/Claude/claude_desktop_config.json）为以下JSON：

{
  "mcpServers": {
    "wcgw": {
      "command": "uv",
      "args": ["tool", "run", "--python", "3.12", "wcgw@latest"]
    }
  }
}

然后重启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服务器

Windows上的WSL

此MCP服务器仅在Windows上的WSL中工作。

要设置它，请安装uv

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

{
  "mcpServers": {
    "wcgw": {
      "command": "wsl.exe",
      "args": ["uv", "tool", "run", "--python", "3.12", "wcgw@latest"]
    }
  }
}

遇到错误时，在命令提示符中执行命令wsl uv --python 3.12 wcgw@latest。如果得到error /bin/bash: line 1: uv: command not found，意味着uv未全局安装，需要指向uv的正确路径。

1. 查找uv的安装位置：

whereis uv

示例输出： uv: /home/mywsl/.local/bin/uv

2. 测试完整路径是否有效：

wsl /home/mywsl/.local/bin/uv tool run --python 3.12 wcgw@latest

3. 使用完整路径更新配置：

{
  "mcpServers": {
    "wcgw": {
      "command": "wsl.exe",
      "args": ["/home/mywsl/.local/bin/uv", "tool", "run", "--python", "3.12", "wcgw@latest"]
    }
  }
}

将/home/mywsl/.local/bin/uv替换为步骤1中的实际uv路径。

使用方法

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

在这里

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

任务检查点或知识转移

• 可以通过使用"Attach from MCP"按钮附加"KnowledgeTransfer"提示来进行任务检查点或知识转移。
• 运行"KnowledgeTransfer"提示时，将调用"ContextSave"工具，将任务描述和所有文件内容一起保存在单个文件中。将生成一个任务ID。
• 在新聊天中可以说"Resume ''"，AI应该会调用"Initialize"并使用该任务ID加载上下文。
• 或者你可以直接打开生成的文件并与另一个AI共享以寻求帮助。

模式

有三个内置模式。你可以让Claude以其中一种模式运行，例如"Use 'architect' mode"

模式	描述	允许	禁止	调用提示
架构师	旨在让你与Claude一起调查和理解你的仓库。	只读命令	FileEdit和Write工具	Run in mode='architect'
代码编写者	用于代码编写和开发	指定路径通配符进行编辑或写入，指定命令	不匹配指定通配符的路径的FileEdit，不匹配指定通配符的路径的Write	Run in code writer mode, only 'tests/**' allowed, only uv command allowed
wcgw	默认模式，允许一切	一切	无	无提示，或"Run in wcgw mode"

注意：在代码编写者模式下，目前要么允许所有命令，要么不允许任何命令。如果你提供允许的命令列表，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安全分离而不销毁screen会话。

[可选] VSCode扩展

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为：

{
  "mcpServers": {
    "wcgw": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--mount",
        "type=bind,src=/Users/username/Desktop,dst=/workspace/Desktop",
        "wcgw"
      ]
    }
  }
}

[可选] 使用OpenAI API密钥或Anthropic API密钥的本地Shell访问

OpenAI

添加OPENAI_API_KEY和OPENAI_ORG_ID环境变量。

然后运行：

uvx wcgw@latest wcgw_local --limit 0.1 # 成本限制$0.1

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

Anthropic

添加ANTHROPIC_API_KEY环境变量。

然后运行：

uvx wcgw@latest wcgw_local --claude

现在可以直接编写消息或按Enter键打开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（整数，可选）
  • 参数：send_text（字符串）或send_specials（["Enter"|"Key-up"|...]）或send_ascii（整数数组），wait_for_seconds（整数，可选）

文件操作：

• ReadFiles：从单个或多个文件读取内容

  • 参数：file_paths（字符串数组）

• 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规范。