使用说明

项目简介

wcgw (Shell and Coding agent for Claude and Chatgpt) 项目提供了一个 MCP (Model Context Protocol) 服务器实现，旨在增强聊天应用程序（如 Claude）的功能，使其能够与用户的本地机器进行代码编写、构建和运行等操作。通过 MCP 协议，wcgw 服务器作为 Claude 等 LLM 客户端的后端，提供上下文信息和工具调用能力，实现更强大的本地机器交互。

主要功能点

Shell 命令执行: 允许 Claude 通过 'BashCommand' 工具在本地机器上执行 Shell 命令，并返回命令输出和状态。支持交互式命令、超时控制和后台运行。
文件操作: 提供 'ReadFiles', 'WriteIfEmpty', 'FileEdit' 等工具，使 Claude 能够读取、创建和编辑本地文件。具备文件保护机制，防止意外覆盖和处理大文件编辑。
项目上下文管理: 通过 'Initialize' 工具设置工作区环境，并返回项目目录结构和重要文件信息，为 Claude 提供项目上下文。
任务Checkpoint和知识转移: 使用 'ContextSave' 工具保存项目上下文和文件，支持任务checkpoint和知识转移，方便后续任务恢复或与其他AI共享。
多种运行模式: 支持 'architect', 'code-writer', 'wcgw' 三种模式，分别限制或开放文件编辑和命令执行权限，以适应不同的使用场景。
可附加终端: 允许用户通过 'screen' 命令附加到 AI 运行命令的终端会话，方便查看历史命令、中断进程或进行交互。

安装步骤

安装 'uv': 使用 Homebrew 安装 'uv' 包管理器 (推荐):
```
brew install uv
```
注意: 如果使用其他方式安装 'uv'，请确保 'uv' 可全局访问，例如位于 '/usr/bin/' 目录下。
配置 Claude Desktop:
- 打开 Claude Desktop 应用程序。
- 找到或创建 'claude_desktop_config.json' 文件，该文件通常位于 '~/Library/Application Support/Claude/' 目录下。
- 将以下 JSON 配置添加到 'claude_desktop_config.json' 文件的 '"mcpServers"' 字段中。如果 'mcpServers' 字段不存在，则创建它。
```
{
  "mcpServers": {
    "wcgw": {
      "command": "uv",
      "args": [
        "tool",
        "run",
        "--from",
        "wcgw@latest",
        "--python",
        "3.12",
        "wcgw_mcp"
      ]
    }
  }
}
```
配置参数说明:
- '"server name"': 'wcgw' - 服务器名称，在 Claude 客户端中用于选择和连接。
- '"command"': 'uv' - 用于启动 wcgw MCP 服务器的命令。
- '"args"': '[...]' - 传递给 'uv' 命令的参数，用于运行 'wcgw_mcp' 入口点。
- 如果 'uv' 命令无法找到: 请先确认 'uv' 是否已正确安装。在终端中运行 'which uv' 命令，查找 'uv' 的安装路径。如果 'uv' 未安装或不在默认路径中，请根据 'which uv' 的输出结果，将 '"command"' 字段的值更新为 'uv' 的实际安装路径。
重启 Claude 应用程序: 配置完成后，重启 Claude Desktop 应用程序使配置生效。

服务器配置

wcgw MCP 服务器的配置主要通过 'claude_desktop_config.json' 文件中的 JSON 对象进行设置。关键配置参数已在 安装步骤 中说明。

基本使用方法

启动 Claude 应用程序: 确保 Claude Desktop 应用程序已启动并已加载 wcgw MCP 服务器配置。
检查 MCP 连接状态: 在 Claude 应用程序界面中，如果配置正确，您应该能看到一个火箭🚀图标，表示 wcgw MCP 服务器已成功连接。
与 Claude 交互: 现在您可以指示 Claude 执行 Shell 命令、读取/编辑文件、运行代码等任务。例如，您可以向 Claude 发送指令:
- "执行 'ls -l' 命令查看当前目录文件"
- "读取文件 '~/Desktop/my_project/README.md' 的内容"
- "在 '~/Desktop/my_project/main.py' 文件中添加 'print('Hello, World!')'"
- "使用 'architect' 模式来分析代码库"

任务Checkpoint和知识转移

您可以使用 "KnowledgeTransfer" Prompt 来进行任务 checkpoint 或知识转移。
在 Claude 中点击 "Attach from MCP" 按钮，选择 "KnowledgeTransfer" Prompt 并运行。
运行 "KnowledgeTransfer" Prompt 后，wcgw 服务器会调用 "ContextSave" 工具，将任务描述和相关文件内容保存到一个文件中，并生成一个任务 ID。
在新的 Claude 对话中，您可以使用 "Resume '<task id>'" 指令来恢复之前的任务上下文。
或者，您可以直接打开生成的文件，与其他 AI 工具或人员共享任务上下文。

切换运行模式

您可以通过在 Claude 中发送指令来切换 wcgw 的运行模式，例如:

"使用 'architect' 模式"
"Run in code writer mode, only 'tests/**' allowed, only uv command allowed"
"Run in wcgw mode"

不同的模式会限制或开放不同的功能，例如 "architect" 模式主要用于代码库分析，禁止文件编辑和写入操作。

附加到工作终端

如果您安装了 'screen' 命令，wcgw MCP 服务器会自动在 'screen' 会话中运行。您可以使用以下步骤附加到 AI 的工作终端:

运行 'screen -ls' 命令列出当前 'screen' 会话。
找到名称类似于 '93358.wcgw.235521' 的 'screen' 会话，其中 'wcgw' 是会话名称，最后的数字是时间戳。
使用 'screen -x <session_name>' 命令附加到该会话，例如 'screen -x 93358.wcgw.235521'。
在终端中，您可以查看命令历史、中断进程或与终端进行交互。
使用 'Ctrl+a+d' 安全地分离会话，避免使用 'exit' 或 'Ctrl-d' 退出。

关键词

使用说明

信息