depoledna/toolbox

# MCP Toolbox 面向编码 Agent 的 MCP 工具箱：提供持久化 Python REPL、内核沙箱化的 Shell、浏览器自动化和 SSH。所有工具均在服务器运行时支持热重载。包含一个反馈循环机制，Agent 可针对自身使用的工具提交 Bug，并由受限的修复 Agent 自动解决这些问题。 ## 核心亮点 - **可热重载的工具** — 编辑任何工具文件；下一次 Agent 调用将直接使用新代码，无需客户端重新连接。 - **自我修复的反馈循环** — Agent 提交遇到的 Bug，受安全护栏约束的修复 Agent 会自动解决这些问题。 - **内核沙箱化的 Shell** — 通过 macOS 的 `sandbox-exec` 实现只读强制执行；文件系统写入在操作系统层面被阻止。用于无权限限制的读取操作。 - **并行浏览器会话** — 每个 Agent 使用指定的 `name=` 声明会话；获取一个带有独立配置文件副本的隐藏 Chrome 实例。当需要用户介入（登录、验证码等）时，可按需使用 `surface` 取消隐藏。 - **稳定的代理层** — 后端重启对客户端完全透明。无会话中断，无任务中途重连。 ## 快速开始 ``` git clone https://github.com/depoledna/toolbox.git mcp && cd mcp uv venv && uv pip install -r pyproject.toml cp .env.example .env # add your API keys ./scripts/run_server.sh ``` ## 客户端配置

Claude Code

配置文件：`~/.claude.json` (全局) 或 `.mcp.json` (按项目) ``` { "mcpServers": { "toolbox": { "type": "http", "url": "http://localhost:11000/mcp" } } } ```

VS Code — GitHub Copilot

配置文件：工作区中的 `.vscode/mcp.json` ``` { "servers": { "toolbox": { "type": "http", "url": "http://localhost:11000/mcp" } } } ```

Cline

配置文件：`~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` ``` { "mcpServers": { "toolbox": { "url": "http://localhost:11000/mcp" } } } ```

Gemini CLI (stdio — 尚不支持 HTTP)

配置文件：`~/.gemini/settings.json` ``` { "mcpServers": { "toolbox": { "command": "/path/to/mcp/.venv/bin/fastmcp", "args": ["run", "server.py:mcp"], "cwd": "/path/to/mcp" } } } ```

## 架构 工具箱服务器位于稳定的代理之后，因此后端重载永远不会暴露给客户端。 ``` Client ─SSE:11000─▶ proxy ─HTTP:8765─▶ fastmcp --reload ──► tools/*.py ``` **为什么需要代理？** 当工具文件发生更改时，`fastmcp --reload` 会重启后端工作进程。如果没有代理，客户端会将每次重载视为断开连接。代理负责维持客户端会话，并将其转发给当前处于运行状态的后端工作进程——这样你就可以在对话中途编辑工具文件，而不会中断 Agent 的会话。只有更改工具的*签名*时，才需要客户端重新加载 `/mcp`，因为大多数客户端会对其进行缓存。 **进程布局** - 服务器代码运行在 `.venv/` 中 - REPL 在一个独立的子进程中运行，使用 `repl_venv/`，因此用户的 `pip install` 操作永远不会污染服务器环境 - SSH、浏览器和 REPL 的状态在工具调用期间会持久保存；只有后端重启才会清除它们 - 每个后端包含两个进程属于正常现象：重载监控进程（约 37 MB）和工作进程（约 110 MB） ## 反馈管道 当 Agent 遇到损坏的工具或需要缺失的功能时，会提交反馈。一个监控器会轮询反馈文件，并生成一个受限的修复 Agent。 Bug 会被自动解决。新功能和改进则需要人工审批。 ``` Bug ──► feedback(action="create", type="bug") └── watcher ──► fixer agent ──► fix ──► test ──► resolved Feature ──► feedback(action="create", type="feature_request") └── user approves ──► watcher ──► same flow Improvement ──► feedback(action="create", type="improvement") └── user approves ──► watcher ──► same flow ``` **安全护栏** - 修复 Agent 只能修改 `tools/` 和 `library/` - 预算上限：每个 Bug 1 美元，每个功能 3 美元——尝试会在达到上限时停止 - 每次尝试都会记录其方法、测试结果和结果，以便重试时不会重复相同的失败修复 如需禁用此功能，请在 `settings.json` 中设置 `"feedback_agent": false`。有关完整规范，请参阅 [`docs/feedback_pipeline.md`](docs/feedback_pipeline.md)。 ## 工具参考 ### 工具箱 | 工具 | 描述 | |------|-------------| | **`repl`** | 带有操作路由的持久化 Python 环境。`run` 执行代码（变量持久保存，原生支持 `await`），`install` 通过 UV 添加包，`vars` 列出已定义的变量，`clear` 重置命名空间。可以访问 `library.*` 实用工具——运行 `library.man()` 来发现它们。 | | **`read_only_bash`** | 通过 macOS `sandbox-exec` 实现的内核强制只读 Shell。文件系统写入在操作系统层面被阻止。可安全用于探索：`ls`、`grep`、`git log` 等。 | | **`browser`** | 通过 Playwright 驱动 Chrome，每个 `name=`（每次调用时必须提供）对应一个独立的浏览器实例。操作包括：`go`、`click`、`type`、`select`、`scroll`、`press`、`back`、`forward`、`refresh`、`eval`、`screenshot`、`act`、`extract`、`surface`、`close`。返回带有 `[ref=eN]` 元素引用的 ARIA 快照。窗口启动时处于隐藏状态（通过 `NSRunningApplication` 在 macOS 上隐藏应用）；`surface` 会在用户的主显示器上取消隐藏，并显示“Done”覆盖层，完成后再次隐藏。通过 Stagehand 支持针对 iframe 和 shadow DOM 的 AI 驱动的 `act` / `extract`。 | | **`ssh`** | 远程服务器上的持久化交互式 Shell。操作包括：`servers`、`connect`、`exec`、`rsync`。可处理工作目录（CWD）跟踪、sudo 提示、命令挂起检测和自动重连。 | | **`docs`** | 通过 Context7 查询库文档。`resolve` 按名称查找库，`query` 获取文档。 | | **`feedback`** | 针对工具箱提交 Bug、功能请求和改进建议。Bug 会由修复 Agent 自动解决；新功能和改进则需要人工审批。请参阅 [反馈管道](#feedback-pipeline)。 | ### 库 不是 MCP 工具——可通过 `from library import ...` 在 REPL 中导入。运行 `library.man()` 获取完整参考。 | 函数 | 描述 | |----------|-------------| | `generate_image` / `edit_image` / `generate_icon` | 通过 OpenRouter 生成和编辑图像 | | `testflight` | 在一次调用中完成构建、归档和上传到 TestFlight | | `asc_api` | 经过身份验证的 App Store Connect API 调用 | | `apple_ads_keywords` | 带有竞品分析的关键词研究（无头 Chrome） | | `blob_list` / `blob_put` / `blob_get` / `blob_delete` | Vercel Blob 存储 | ## 配置 | 文件 | 用途 | |------|---------| | `.env` | API 密钥（`OPENROUTER_KEY`、`CONTEXT7_API_KEY` 等） | | `settings.json` | SSH 服务器、反馈 Agent 开关 | 这两个文件均已被 gitignore 忽略。有关所有可用变量，请参阅 [`.env.example`](.env.example)。 SSH 会话会被远程记录到 `~/mcp_output/session_*.log`——包括命令、输出和退出码。7 天后自动清理。 ## 许可证 MIT

标签：AI安全, AI开发工具, AI编程智能体, AutoGPT, Bug自动修复, Chat Copilot, Chrome隔离会话, Claude Code, Cline, Devin, GitHub Copilot, LLM Agent, macOS sandbox-exec, MCP工具箱, Python REPL, SSH, VS Code, 内存分配, 内核级沙箱, 反馈循环, 大模型工具调用, 开发环境自动化, 数字取证, 无头浏览器, 智能体框架, 浏览器自动化, 热重载, 特征检测, 稳定会话, 系统沙箱, 自动化编程, 自动化脚本, 自我修复, 逆向工具