网关控制服务

Name: 网关控制服务
Author: rusiaaman

作者：rusiaaman619 星标更新：2025-10-09

安装使用来源：spider==github.com

项目介绍

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

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

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

⚠️ 警告：不要在未经审查命令的情况下允许 BashCommand 工具，这可能会导致数据丢失。

演示

工作流演示

更新

[2025年10月6日] 现在可以同时运行多个后台命令。ZSH 现在是一个支持的 shell。改进了多路复用功能。
[2025年4月27日] 移除了通过中继服务器支持 GPT 的功能。版本 >= 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 命令之后始终返回当前工作目录，以防止 AI 迷失方向。
- 命令轮询在快速超时后退出，以避免慢速反馈。然而，状态检查有等待容忍度，基于命令的新鲜输出流。这两种方法结合提供了良好的 shell 交互体验。
- 支持多个并发后台命令以及主要的交互式 shell。
⚡ 将仓库上下文保存在一个文件中：使用“ContextSave”工具的任务检查点将详细上下文保存在一个文件中。可以在新聊天中通过询问“恢复 任务ID”来恢复任务。保存的文件可用于其他类型的知识转移，例如从另一个 AI 获取帮助。
⚡ 轻松切换各种模式：
- 要求它以“架构师”模式运行以进行规划。灵感来自 adier 的架构师模式，与 Claude 一起制定计划。这提高了准确性并防止过早编辑文件。
- 要求它以“代码编写者”模式运行以进行代码编辑和项目构建。您可以提供具有通配符支持的具体路径以防止其他文件被编辑。
- 默认情况下，它以“wcgw”模式运行，该模式没有限制且完全授权。
- 更多详情请参见模式部分
⚡ 在多路复用终端中运行 使用 vscode 扩展或运行 screen -x 来连接到 AI 运行命令的终端。查看历史记录或中断进程或与 AI 使用的同一终端互动。
⚡ 自动加载 CLAUDE.md/AGENTS.md 加载项目根目录中的“CLAUDE.md”或“AGENTS.md”文件，并在初始化期间作为指令发送。全局“~~/.wcgw/CLAUDE.md”或“~~/.wcgw/AGENTS.md”文件中的指令会被加载并添加到项目特定的 CLAUDE.md 中。文件名区分大小写。如果存在 CLAUDE.md，则附加它，否则附加 AGENTS.md。

主要使用案例示例

使用 Python 解决问题 X，创建并运行测试用例并修复任何问题。在临时目录中进行操作。
在我的仓库中查找具有 X 行为的代码实例。
在我的主目录中 git 克隆 https://github.com/my/repo，然后理解项目，设置环境并构建。
创建一个 golang htmx tailwind 网站应用，然后打开浏览器查看是否正常工作（使用 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": "uvx",
      "args": ["wcgw@latest"]
    }
  }
}

然后重启 Claude 应用。

可选：强制指定 shell

要使用特定 shell（bash 或 zsh），添加 --shell 参数：

{
  "mcpServers": {
    "wcgw": {
      "command": "uvx",
      "args": ["wcgw@latest", "--shell", "/bin/bash"]
    }
  }
}

如果设置过程中出现错误

如果出现类似“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 上的 WSL

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

要设置它，请安装 uv

然后在 %APPDATA%\Claude\claude_desktop_config.json 中添加或更新 Claude 配置文件，如下所示

{
  "mcpServers": {
    "wcgw": {
      "command": "wsl.exe",
      "args": ["uvx", "wcgw@latest"]
    }
  }
}

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

查找 uv 的安装位置：

whereis uv

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

测试完整的路径是否有效：

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

使用完整的路径更新配置：

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

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

使用

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

mcp 图标在这里

mcp 图标

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

任务检查点或知识转移

您可以通过使用“Attach from MCP”按钮附加“KnowledgeTransfer”提示来进行任务检查点或知识转移。
运行“KnowledgeTransfer”提示时，“ContextSave”工具将被调用，保存任务描述和所有文件内容到一个文件中。将生成一个任务 ID。
您可以在新的聊天中说“恢复 '<任务ID>'”，AI 应该调用“Initialize”并使用任务 ID 加载上下文。
或者您可以直接打开生成的文件并与另一个 AI 分享以获取帮助。

模式

内置了三种模式。您可以要求 Claude 在其中一种模式下运行，例如“使用‘架构师’模式”

模式	描述	允许	拒绝	调用提示
架构师	设计让您与 Claude 一起调查和了解您的仓库。	读取命令	文件编辑和写入工具	在模式='架构师'中运行
代码编写者	用于代码编写和开发	指定路径通配符用于编辑或写入，指定命令	文件编辑对于不匹配指定通配符的路径，写入对于不匹配指定通配符的路径	在代码编写者模式中运行，仅允许 'tests/**'，仅允许 uv 命令
wcgw	默认模式，允许一切	一切	无	无需提示，或“在 wcgw 模式中运行”

注意：在代码编写者模式下，目前要么允许所有命令，要么不允许任何命令。如果您给出允许的命令列表，Claude 被指示只运行那些命令，但不会实际检查。（正在进行中）

连接到正在工作的终端以进行调查

新功能：vscode 扩展现在会自动连接到正在运行的终端，如果工作区路径匹配的话。

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

screen -ls

并记下 wcgw 屏幕名称，它看起来像 93358.wcgw.235521，最后一个数字是以小时-分钟-秒格式表示的。

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

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

您可以安全地与终端互动，例如输入密码或输入一些文本。（警告：如果您运行了一个新命令，任何新的 LLM 命令都会中断它。）

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

在 ~/.screenrc 中包含以下内容以获得更好的滚动体验

defscrollback 10000
termcapinfo xterm* ti@:te@

[可选] 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 以包含

{
  "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 wcgw_local --limit 0.1 # 成本限制 $0.1

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

Anthropic

添加 ANTHROPIC_API_KEY 环境变量。

然后运行

uvx wcgw 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（整数，可选）
- 参数：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 规范以获取详细的协议信息。