MCP ToolHub

MCP ToolHub 是一个本地、仅 stdio 的 Model Context Protocol 服务器，提供限定于工作区的文件系统操作、只读的 Git 检视、结构化命令执行以及审计追踪。变更文件系统的操作和所有由智能体选择的外部 shell 命令均使用现有的带外人工审批模型。

ToolHub 不暴露 HTTP、SSE 或其他网络监听器。

功能特性

• 限定于工作区的文件读取、目录列举、写入和补丁操作

• 只读的 Git 状态和差异操作

• 结构化 shell 命令，采用默认拒绝的风险分类

• 原子性、可过期、一次性使用的审批请求

• 独立的可信管理员 CLI；无 MCP 自审批工具

• 有界、脱敏的 JSON Lines 审计事件

• 支持 Windows 和 POSIX

Related MCP server: enterprise-agent-lab

环境要求

• Python 3.12 或更高版本（CI 目前验证 3.12 和 3.13）

• 支持 stdio 服务器的 MCP 客户端

• 使用 Git 工具及需要审批的 Git shell 请求时需要 git

安装

使用 uv 从源代码检出目录安装：

uv tool install .

或者构建并安装 wheel：

uv build
uv tool install dist/mcp_toolhub-0.1.0-py3-none-any.whl

安装后提供两个可执行文件：

• mcp-toolhub — stdio MCP 服务器

• mcp-toolhub-admin — 可信人工审批 CLI

运行时配置

工作区根目录

mcp-toolhub serve 和管理员 CLI 都需要 TOOLHUB_WORKSPACE_ROOT。该变量必须包含指向现有目录的绝对路径。ToolHub 会规范化该路径一次，并在进程的整个生命周期内将其固定。

ToolHub 有意不默认使用当前目录、源代码检出目录或安装目录。

可信状态根目录

TOOLHUB_STATE_ROOT 可选地选择包含 workspace-binding.json、approvals.json 和 audit.jsonl 的目录。设置时必须为绝对路径。该目录在首次有效使用时永久绑定到恰好一个规范化工作区；将其用于另一个工作区将失败即关闭。

当未设置 TOOLHUB_STATE_ROOT 时，ToolHub 使用 platformdirs 提供的平台适应用户状态目录作为基础。每个规范化工作区在 workspaces/ 下获得一个独立命名空间，命名使用由平台规范化工作区路径派生出的确定性 SHA-256 标识符。该标识符避免将工作区路径放入目录名，但它只是命名空间隔离而非身份验证机密。移动或重命名工作区通常会创建新的默认命名空间。

状态目录会按需创建、规范化，并与工作区配置一起固定。如果状态根目录位于工作区内部，则启动失败。服务器和管理员 CLI 必须以同一用户身份运行，并使用相同的工作区和状态配置，以便共享此状态。

POSIX 示例

export TOOLHUB_WORKSPACE_ROOT=/home/alice/projects/example
export TOOLHUB_STATE_ROOT=/home/alice/.local/state/mcp-toolhub
mcp-toolhub serve

Windows PowerShell 示例

$env:TOOLHUB_WORKSPACE_ROOT = "D:\work\example"
$env:TOOLHUB_STATE_ROOT = "$env:LOCALAPPDATA\mcp-toolhub"
mcp-toolhub serve

服务器不会向 stdout 输出横幅或人类可读的日志文本。stdout 专用于 MCP 协议消息。预期的配置错误会简洁地报告到 stderr，并以非零状态退出。

命令

mcp-toolhub --version
mcp-toolhub serve
python -m mcp_toolhub serve

mcp-toolhub-admin --help
mcp-toolhub-admin list
mcp-toolhub-admin approve REQUEST_ID
mcp-toolhub-admin reject REQUEST_ID

管理员命令面向人类用户，可以向 stdout 输出普通内容。它不是 MCP 传输进程。

MCP 客户端配置

确切的外层配置键因客户端而异。典型的 POSIX stdio 配置项如下：

{
  "mcpServers": {
    "toolhub": {
      "command": "mcp-toolhub",
      "args": ["serve"],
      "env": {
        "TOOLHUB_WORKSPACE_ROOT": "/home/alice/projects/example",
        "TOOLHUB_STATE_ROOT": "/home/alice/.local/state/mcp-toolhub"
      }
    }
  }
}

Windows 路径需要对 JSON 进行转义：

{
  "mcpServers": {
    "toolhub": {
      "command": "mcp-toolhub",
      "args": ["serve"],
      "env": {
        "TOOLHUB_WORKSPACE_ROOT": "D:\\work\\example",
        "TOOLHUB_STATE_ROOT": "C:\\Users\\alice\\AppData\\Local\\mcp-toolhub"
      }
    }
  }
}

如果 MCP 客户端不继承 shell 的 PATH，请使用绝对可执行文件路径。

工具清单

生产服务器恰好暴露以下 12 个 MCP 工具：

• toolhub.ping

• toolhub.audit_recent

• filesystem.list_directory

• filesystem.read_file

• filesystem.write_file

• filesystem.write_file_approved

• filesystem.apply_patch

• filesystem.apply_patch_approved

• git.status

• git.diff

• shell.run

• shell.run_approved

不存在 MCP 管理、批准或拒绝工具。

人工审批工作流

1. MCP 变更请求或外部 shell 请求会返回一个待处理的请求 ID。

2. 管理员在与服务器相同的工作区和状态环境下运行 mcp-toolhub-admin list。

3. 要批准时，管理员运行 mcp-toolhub-admin approve REQUEST_ID。

4. CLI 显示受保护的请求，并要求操作员准确输入 APPROVE。

5. MCP 调用方使用请求 ID 调用对应的 _approved 工具。成功消费是原子性且一次性的。

对于 shell 请求，审批显示内容包括原始程序、解析并规范化后的可执行文件、SHA-256、字节大小、cwd，以及分别进行 JSON 转义的参数值。它不会将参数表示为含糊不清的 shell 命令字符串。

安全模型与限制

结构化 shell 命令

shell.run 使用默认拒绝的命令策略。LOW 仅限于 ToolHub 内建功能本身，目前是查询正在运行的 Python 版本。LOW 从不搜索 PATH，也从不创建外部子进程。通用 Git、shell 解释器、Windows 批处理脚本、py 启动器和未知程序绝不会被评为 LOW。

每个外部 shell 命令都属于 MEDIUM 或 HIGH，并且必须经过带外管理员审批。审批捕获不可变的程序、参数、cwd、超时、工作区和主可执行文件快照。已批准的 shell 请求会在快照验证前以原子方式被消费；此后的任何失败都会永久消耗该请求，因此重试需要重新审批。

在 subprocess 启动之前，ToolHub 会立即验证主可执行文件的规范化路径、大小和 SHA-256。执行使用该绝对路径并设置 shell=False。这是在启动前立即经过验证的主可执行文件身份，而非对操作系统最终映射的确切字节提供密码学保证。

ToolHub 保证：

• LOW 从不创建外部子进程。

• 每次外部 shell 执行都需要 MEDIUM 或 HIGH 审批。

• 智能体无法替换已批准的程序、参数、cwd 或超时。

• 审批是原子性、可过期且一次性使用的。

• 工作区和主可执行文件快照是必需的，且失败即关闭。

• 主可执行文件的规范化身份和哈希在启动前立即重新验证。

• 文件系统路径保持在固定的工作区边界内。

• 变更路径拒绝符号链接遍历，并在适用处强制 expected_hash 并发检查。

ToolHub 不保证：

• 在从最终检查到执行的狭窄竞态窗口内，对抗并发本地文件系统攻击者的确切字节身份。

• DLL、解释器、辅助程序、插件、配置文件、环境选定的依赖项或子进程的身份。

• 已批准的可执行文件字节为良性、已签名或来自信誉良好的发布者。

管理员审批显示暴露受保护的规范化路径、哈希、大小、cwd 和精确的 JSON 转义参数边界。智能体可读的审计事件会省略外部可执行文件目录，保留基本文件名、哈希、大小、范围和请求 ID 关联。

审计行为

审计事件追加到可信状态根目录下的 audit.jsonl。它们包含有界元数据，对可识别的机密参数进行脱敏，并且只存储 stdout/stderr 字符计数而非原始进程输出。审计写入失败对工具执行不构成致命影响。

开发

安装所有锁定的运行时和开发依赖：

uv sync --all-groups

运行必需的检查：

uv run ruff check .
uv run ruff format --check .
uv run python -m compileall -q src/mcp_toolhub
uv run pytest -q
uv build
git diff --check

如需实际应用格式化：

uv run ruff format .

构建产物冒烟测试

在 uv build 之后，使用检出目录之外的虚拟环境运行跨平台冒烟驱动。

POSIX：

uv run python scripts/artifact_smoke.py --dist-dir dist --venv /tmp/mcp-toolhub-wheel-env --repository .

Windows PowerShell：

uv run python scripts/artifact_smoke.py --dist-dir dist --venv "$env:TEMP\mcp-toolhub-wheel-env" --repository .

该驱动检查 wheel 内容，仅将 wheel 安装到隔离环境中，验证控制台/版本行为，并从仓库外部运行 initialize、list_tools、ping、已配置工作区访问、无效配置，以及服务器/管理员共享状态测试。

故障排查

• TOOLHUB_WORKSPACE_ROOT is required：在 MCP 客户端环境中添加指向现有目录的绝对工作区路径。

• Workspace is not a directory：创建该目录或修正路径。

• State root must be outside the workspace：将 TOOLHUB_STATE_ROOT 移动到 MCP 文件系统工具无法访问的可信目录。

• State namespace belongs to a different workspace：选择不同的显式 TOOLHUB_STATE_ROOT；绑定绝不会被静默重新分配。

• Client reports invalid stdio JSON：验证包装器和启动脚本不会向 stdout 打印横幅或日志。

• Admin cannot see a request：确认服务器和管理员以同一用户身份运行，并具有相同的工作区和状态根目录设置。

• Executable changed after approval：请求新的审批；已消费或失效的审批绝不会被重放。

生产环境中的 ToolHub 有意不暴露 HTTP、SSE、公共网络、认证服务器、容器编排或云托管接口。