wcgw

用途

wcgw 是一个 MCP（Model Context Protocol）服务器，为 Claude 等聊天应用提供 Shell 与编码智能体能力，使 AI 能够在本地机器上编写代码、构建项目并运行命令。

主要能力

创建、执行、迭代：可让 Claude 持续运行编译检查直到修复所有错误，或轮询长时间运行命令直至完成。
大型文件编辑：支持大型文件的增量编辑以避免令牌限制问题，根据所需更改百分比智能选择小编辑或大重写。
编辑语法检查：若编辑存在语法错误，向 LLM 反馈以便重做。
交互式命令处理：支持使用方向键、中断和 ANSI 转义序列的交互式命令。
文件保护：AI 必须先读取文件至少一次才能编辑或重写，避免意外覆盖；读取超大文件时分块处理，避免上下文溢出；初始化时返回工作区目录结构（基于 .gitignore 和统计方法选择重要文件）。文件编辑基于搜索替换，若存在多个匹配则根据先前搜索块寻找正确块，否则失败；支持空格容忍匹配，缩进不匹配时警告；无匹配时返回最接近的匹配供 AI 修正。采用类似 Aider 的搜索替换，性能优于基于工具调用的搜索替换。
Shell 优化：任何 shell 命令后始终返回当前工作目录，防止 AI 迷失；命令轮询在快速超时后退出，状态检查根据新输出流有等待容忍；支持多个并发后台命令。
上下文保存：ContextSave 工具将任务描述和文件内容保存在单个文件中，生成任务 ID，可在新对话中通过“Resume <id>”恢复任务，或用于知识转移。
模式切换：支持 architect（规划）、code-writer（代码编辑与项目构建）、wcgw（无限制完全授权）三种模式。code-writer 模式可提供通配符路径限制可编辑文件。
多路复用终端：可通过 VSCode 扩展或 screen -x 附加到 AI 运行的终端，查看历史、中断进程或交互。
自动加载 CLAUDE.md/AGENTS.md：初始化时自动加载项目根目录的 CLAUDE.md 或 AGENTS.md 文件作为指令；全局路径 ~/.wcgw/CLAUDE.md 或 ~/.wcgw/AGENTS.md 中的指令也会加载。文件名区分大小写，优先 CLAUDE.md。

使用方式

Claude 设置（使用 MCP）

使用 Homebrew 安装 uv：brew install uv（重要：使用 Homebrew 安装，确保 uv 位于全局位置如 /usr/bin/）。
创建或更新 claude_desktop_config.json（路径：~/Library/Application Support/Claude/claude_desktop_config.json）。
重启 Claude 应用。

可选：强制特定 shell（bash 或 zsh），添加 --shell 参数。

可选：可流式 HTTP 传输。wcgw_mcp 默认使用 stdio；对于更适合长连接 HTTP MCP 端点的客户端或网关，可运行相关命令，MCP 端点为 http://127.0.0.1:8765/mcp/ 。绑定到回环地址使服务器保持本地，同时允许支持 HTTP 的本地网关多路复用请求而无需共享一个 stdio 管道。

常见问题排查

若出现“uv ENOENT”错误，确保已安装 uv，在终端运行 which uv，用其输出替换配置中的“uv”。
若仍有问题，检查 uv tool run --python 3.12 wcgw 在终端中运行无输出且不退出。
尝试移除 ~/.cache/uv 文件夹。
尝试使用 uv 0.6.0 版本（该工具经测试的版本）。
使用 npx @modelcontextprotocol/inspector@0.1.7 uv tool run --python 3.12 wcgw 调试 MCP 服务器。

Windows 支持

该 MCP 服务器仅在 Windows 上通过 WSL 工作。安装 uv 后，更新配置文件 %APPDATA%\Claude\claude_desktop_config.json。在命令提示符中执行 wsl uv --python 3.12 wcgw，若提示 uv 未找到，需找到 uv 安装路径并替换配置中的完整路径。

使用流程

配置成功后，可要求 Claude 执行 shell 命令、读取文件、编辑文件、运行代码等。通过“Attach from MCP”按钮附加“KnowledgeTransfer”提示可进行任务检查点或知识转移，会调用 ContextSave 工具保存任务描述和所有文件内容至单个文件并生成任务 ID。新对话中可说“Resume '<id>'”，AI 会调用 Initialize 加载上下文。也可直接打开生成的文件分享给其他 AI。

附加到终端

若安装了 screen 命令，wcgw 自动在 screen 实例中运行。列出 screen 会话并记下 wcgw 屏幕名称（如 93358.wcgw.235521），使用 screen -x 93358.wcgw.235521 附加。可安全中断任何运行中的命令，与终端安全交互（如输入密码或文本；警告：运行新命令会中断任何新的 LLM 命令）。不要使用 exit 或 Ctrl-d 退出，应使用 ctrl+a+d 安全分离而不破坏 screen 会话。建议在 ~/.screenrc 中包含相关配置以获得更好的滚动体验。

VSCode 扩展（可选）

可从 Visual Studio Marketplace 获取（itemName=AmanRusia.wcgw）。选择文本并按 cmd+' 然后输入指令，将切换到 Claude 并粘贴包含指令、文件路径、工作区目录和选中文本的文本。

使用 Docker 运行 MCP 服务器

先构建 Docker 镜像：docker build -t wcgw https://github.com/rusiaaman/wcgw.git，然后更新配置文件。

提供的 MCP 工具

Shell 操作

Initialize：重置 shell 并设置工作区环境。参数：any_workspace_path (string)、initial_files_to_read (string[])、mode_name ("wcgw"|"architect"|"code_writer")、task_id_to_resume (string)、thread_id (string；仅第一次调用为空)。
BashCommand：执行 shell 命令并控制超时。参数：command (string)、wait_for_seconds (int, 可选)、thread_id (string)；或参数：send_text (string) 或 send_specials (["Enter"|"Key-up"|...]) 或 send_ascii (int[])、wait_for_seconds (int, 可选)。

文件操作

ReadFiles：读取一个或多个文件内容。参数：file_paths (string[])、thread_id (string)。
WriteIfEmpty：创建新文件或写入空文件。参数：file_path (string)、file_content (string)。
FileEdit：使用搜索/替换块编辑现有文件。参数：file_path (string)、file_edit_using_search_replace_blocks (string)。
ReadImage：读取图像文件以供显示/处理。参数：file_path (string)、thread_id (string)。

项目管理

ContextSave：保存项目上下文和文件，用于知识转移或任务检查点以便后续恢复。参数：id (string)、project_root_path (string)、description (string)、relevant_file_globs (string[])、thread_id (string)。

所有工具支持绝对路径，并内置针对常见错误的保护。

适用场景

希望让 Claude 等聊天应用在本地执行编码、构建、运行任务的开发者。
需要 AI 代理在本地机器上进行交互式 shell 操作和文件编辑的用户。
需要任务检查点或在不同 AI 之间进行知识转移的场景。

限制

该 MCP 服务器对机器 Shell 和文件提供无过滤访问，不限制 LLM 执行任意命令或进行意外修改，可能被攻击者滥用或由 AI 幻觉触发危险操作，仅在你完全理解并接受风险时运行。
该服务器仅在 Windows 上通过 WSL 工作。
code-writer 模式目前要么允许所有命令，要么不允许任何命令；若提供允许命令列表，Claude 会被指示仅运行这些命令，但无实际检查（WIP）。