WCWG MCP Server (Shell与编码代理)

你是否曾希望 AI 助手不仅能“聊”代码，更能像一位真正的同事那样，直接在你的终端里执行命令、编辑文件、迭代构建，直到任务完成？WCWG——全称“Work-Capable Generalist”——正是为此而生。这是一个集成了 Shell 终端与文件编辑能力的 MCP 服务器，将你的 AI 助手升级为一个能在本地机器上完整“编码-构建-运行”循环的自主代理。无论是修复错误、创建项目、还是管理仓库，WCWG 让 AI 拥有了真正的执行能力。

项目基本信息

一、项目介绍

WCWG 可能是我见过最接近“AI 同事”的 MCP 服务器。它不再是简单地提供几个工具，而是将整个本地开发环境的能力——Shell 终端、文件系统、编辑能力——系统性地暴露给了 AI。

核心理念：让 AI 拥有完整的执行循环

传统 AI 助手能生成代码，但无法执行；能提出建议，但无法验证。WCWG 打破了这个局限。它让 AI 能够：

1. 执行命令：运行编译、测试、安装包等任何 Shell 命令。
2. 读取与编辑文件：像开发者一样读代码、定位问题、修改文件。
3. 迭代修复：运行编译 → 发现错误 → 修改代码 → 再次运行，直到成功。
4. 保存与恢复上下文：将当前工作状态保存为检查点，在新会话中恢复。

核心工具集

WCWG 将能力封装为 5 个核心 MCP 工具：

三种工作模式

WCWG 借鉴了软件工程的最佳实践，内置了三种角色模式：

• 架构师模式 (architect)：仅允许只读命令和文件读取，禁止任何编辑。适合前期调研和方案设计阶段，防止 AI 过早动手修改。
• 代码编写者模式 (code-writer)：允许在指定路径和命令范围内进行编辑和执行。适合实现阶段，通过通配符限制 AI 的修改范围。
• wcgw 模式（默认，全能力）：所有工具全部开放，AI 拥有完全的 Shell 和文件编辑权限。

二、核心优势

极致的 Shell 交互优化

WCWG 的 Shell 工具不是简单的“执行并返回输出”。它实现了多项精细优化：

• 单实例管理：同一时间只有一个 Shell 实例运行，避免失控的并行进程。
• 自动回显工作目录：每条命令执行后都会返回当前工作目录，防止 AI “迷失”在文件系统中。
• 命令轮询与状态等待：快速超时退出以避免缓慢反馈，但对长时间运行的命令有等待容忍度，平衡了响应速度和实用性。
• 交互式命令支持：支持方向键、中断和 ANSI 转义序列，能处理需要用户交互的 CLI 工具。

安全且精确的文件编辑

• 语法检查：文件编辑后会进行语法检查，如果存在错误会反馈给 AI 让其修正。
• 间距容忍匹配：搜索替换时会容忍缩进差异，对不匹配的情况发出警告，并返回最接近的匹配项。
• 强制先读后编辑：AI 必须至少读取一次文件后才能编辑或重写，避免基于错误假设的修改。
• 大文件智能处理：文件会根据 token 长度分块，支持增量编辑以避免 token 限制。

跨会话的任务延续

ContextSave 工具允许将当前状态——包括文件内容、任务描述、项目路径——保存为单个文件。你可以生成一个任务 ID，在新会话中说“恢复任务 XXX”，AI 就能继续之前的工作。这解决了长期 AI 任务中会话超时或中断的问题。

多路复用终端

WCWG 自动在 screen 会话中运行。你可以通过 screen -x 附加到 AI 正在使用的终端，查看执行历史、中断进程，或与 AI 交互同一终端。这为调试和监控提供了极大的透明度。

三、适用场景

全自动构建与错误修复

“在我的仓库中运行 mypy 检查，修复所有类型错误，然后重新运行检查直到全部通过。”

AI 会持续迭代：运行检查 → 读取报错文件 → 编辑修复 → 再次运行，形成闭环。

从零搭建项目

“创建一个 Go + HTMX + Tailwind 的 Web 应用，然后打开浏览器查看效果（配合 Puppeteer MCP）。”

AI 会初始化项目、安装依赖、编写代码、启动服务，并（通过浏览器 MCP）验证结果。

代码审查与知识转移

“理解 /src/api 目录下的代码，然后在一个新文件中创建该模块的架构文档。”

AI 会读取所有相关文件，分析结构，并生成文档。

复杂工作流编排

“在后台运行服务器，然后运行 API 测试，同时监视日志中是否有错误。”

AI 会使用 shell 的 & 或 screen 管理多个并发进程。

四、安装教程

环境要求

macOS 和 Linux 安装

# 1. 安装 uv
brew install uv

# 2. 编辑 Claude Desktop 配置文件
# macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

添加以下配置：

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

重启 Claude Desktop 即可。

Windows (WSL) 安装

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

如果遇到 uv: command not found，找到 uv 的完整路径并替换：

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

排错提示

• 在终端运行 uv tool run --python 3.12 wcgw@latest，没有输出且不退出表示正常。
• 出现 uv ENOENT 等错误，使用 which uv 找到 uv 的完整路径并替换配置文件中的 "uv"。
• 可以尝试删除 ~/.cache/uv 缓存。
• 使用 npx @modelcontextprotocol/inspector uv tool run --python 3.12 wcgw@latest 进行调试。

五、使用示例

示例一：修复 mypy 类型错误

用户：在 /path/to/project 目录下运行 mypy，修复所有类型错误，重新运行直到没有错误。

AI 使用 BashCommand 运行 mypy，获取错误输出，用 ReadFiles 读取报错文件，用 FileEdit 修改代码，再次运行检查——循环直到通过。

示例二：创建新功能分支并提交 PR

用户：在 /repo 中创建一个分支 feat/new-api，在 api.py 中添加一个新的接口，提交代码，然后用 GitHub CLI 创建 PR。

AI 依次执行：git checkout -b、修改文件、git commit、git push、gh pr create。

示例三：使用架构师模式调研代码

用户：用架构师模式运行，理解 /src/modules 目录下的代码结构，给我生成一份模块依赖关系图。

AI 在只读模式下遍历文件，分析 import 关系，生成依赖说明。

示例四：跨会话的任务恢复

在第一个会话中：AI 使用 ContextSave 保存当前状态，生成任务 ID “abc123”。

在新会话中：

用户：恢复任务 abc123，继续之前的工作。

AI 调用 Initialize 加载保存的上下文，继续之前的任务。

六、常见问题

问：AI 执行的命令会不会删除我的重要文件？

答：这是一个合理的安全担忧。WCWG 提供了多层保护：所有编辑必须先读取文件，Shell 命令以非 root 权限运行，代码编写者模式可以限制 AI 的编辑范围。但强烈建议在生产环境中使用模式限制，在重要项目上先备份，或先在测试目录中试用。

问：如何查看 AI 正在执行的命令？

答：如果安装了 screen，WCWG 自动在 screen 会话中运行。你可以用 screen -ls 查看会话列表，用 screen -x 附加查看 AI 的实时执行过程。这为监控和调试提供了很好的透明度。

问：为什么限制为 Python 3.12？

答：这是项目当前所依赖的特定版本。uv 会自动为你管理 Python 3.12 环境，你不需要手动安装该版本。

问：Docker 模式下如何访问本地文件？

答：启动 Docker 容器时需要显式挂载目录，如示例中挂载了 ~/Desktop。只有挂载的目录对 AI 才是可见和可操作的。

问：代码编写者模式的限制有效吗？

答：目前命令限制部分仍在完善中——文件路径限制已生效，但命令限制目前仅是提示性的，底层没有硬性拦截。对于安全要求极高的场景，建议额外配置系统级权限限制。

七、总结

WCWG 是“AI 同事”这一愿景最接近现实的实现之一。它不像传统的 MCP 工具那样零散地提供几个功能，而是将整个本地开发环境的控制权系统性地交给了 AI——从 Shell 终端到文件编辑，从单次执行到迭代修复，从会话内协作到跨会话的任务延续。

对于开发者来说，WCWG 既是一个强大的自动化引擎，也是一个需要谨慎对待的利器。在正确使用模式和安全措施的前提下，它能显著加速开发流程，让你真正拥有一个可以“动手”而不仅仅是“动口”的 AI 助手。