Skip to main content
Glama

MCP ToolHub

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

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

功能特性

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

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

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

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

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

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

  • 支持 Windows 和 POSIX

Related MCP server: agent-bridge-mcp

环境要求

  • 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、公共网络、认证服务器、容器编排或云托管接口。

Available Tools

14 tools
filesystem.apply_patchApply workspace file patch (approval required)A
Destructive

Create a PENDING approval request for a narrowly-scoped patch.

The patch may modify only the requested file, and is applied only after out-of-band approval via filesystem.apply_patch_approved.

Inputs: path (required), patch (required), expected_hash. Returns: path, error, changed, message, +12 more

filesystem.apply_patch_approvedExecute an approved file patchA
Destructive

Execute exactly the patch stored in an APPROVED request.

Takes only a request_id; the stored snapshot is used. Single-use.

Inputs: request_id (required). Returns: path, error, changed, message, +12 more

filesystem.list_directoryList workspace directoryB
Read-only

List files and directories inside the ToolHub workspace.

Inputs: path. Returns: path, entries

filesystem.read_fileRead workspace fileB
Read-only

Read a UTF-8 text file inside the ToolHub workspace.

Inputs: path (required). Returns: path, size, sha256, content

filesystem.write_fileWrite workspace file (approval required)A
Destructive

Create a PENDING approval request for writing a UTF-8 text file.

The write happens only after a trusted administrator approves the request out-of-band and filesystem.write_file_approved executes the stored snapshot.

Inputs: path (required), content (required), expected_hash, create_parents. Returns: path, error, created, message, +9 more

filesystem.write_file_approvedExecute an approved file writeA
Destructive

Execute exactly the file write stored in an APPROVED request.

Takes only a request_id; the path/content/hash snapshot captured at request time is used. Single-use.

Inputs: request_id (required). Returns: path, error, created, message, +9 more

git.diffShow git diffA
Read-only

Read-only git diff. Never modifies repository state.

Args: path: Optional repository-relative path to filter the diff. staged: Show staged changes (git diff --cached) instead of unstaged ones.

Inputs: path, staged. Returns: raw, path, binary, staged, +2 more

git.statusShow git working tree statusA
Read-only

Read-only git status of the ToolHub workspace repository.

Inputs: no named parameters. Returns: raw, path, clean, branch, +1 more

shell.runRun workspace commandA
Destructive

Run a structured subprocess inside the ToolHub workspace.

Only LOW-risk commands execute automatically. MEDIUM/HIGH commands create a PENDING approval request that a trusted administrator must approve out-of-band before it can be run via shell.run_approved.

Inputs: program (required), cwd, args, timeout_seconds. Returns: cwd, args, risk, error, +13 more

shell.run_approvedRun an approved commandA
Destructive

Execute a previously-APPROVED command exactly as stored.

Takes only a request_id; the program, args, and cwd are always the originals captured when the request was created. Approvals are single-use, so a request cannot be replayed.

Inputs: request_id (required). Returns: cwd, args, risk, error, +13 more

toolhub.audit_recentRecent audit eventsA
Read-only

Return the most recent sanitized audit events (max 100).

Read-only: returns bounded metadata summaries. Event contents are already sanitized at write time; no raw stdout/stderr or secrets are included.

Inputs: limit. Returns: count, events

toolhub.capabilitiesShow ToolHub capabilitiesC
Read-only

Return the versioned public ToolHub execution contract.

Inputs: no named parameters. Returns: limits, transport, approval_model, package_version, +2 more

toolhub.pingB

Check whether MCP ToolHub is running correctly.

Inputs: message. Returns: object

toolhub.request_statusShow approval request statusA
Read-only

Observe an approval request without approving, rejecting, or consuming it.

Inputs: request_id (required). Returns: error, outcome, approval, trace_id, +1 more

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 14 tools

    Disambiguation5/5

    Tools are cleanly partitioned into namespaces (filesystem, shell, git, toolhub) and actions. The approval-request tools and their _approved counterparts have clearly distinct purposes, and descriptions explicitly explain the two-step approval flow, so an agent can reliably choose the right tool.

    Naming Consistency5/5

    All tool names follow a consistent namespace.action pattern using dot separators and snake_case actions. The _approved suffix is applied uniformly to the three post-approval execution tools, making the naming predictable throughout.

    Tool Count5/5

    The 14 tools are well-scoped for a secured execution hub: read/list, write/patch requests, shell requests, their approved counterparts, read-only git, and lightweight diagnostics/audit. No tool appears redundant, and the count stays within a reasonable range.

    Completeness4/5

    Core lifecycle operations for workspace inspection, file reading, controlled writes/patches, shell execution, git status/diff, and audit/request observation are covered. Minor gaps exist—no filesystem delete/move, no direct git history/log tools, and no pending-request listing—but agents can largely work around these via shell.run or request_status.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables controlled AI-agent access to enterprise-shaped tools with a deny-by-default gated write path, human approval, dry-run execution, and append-only audit logging.
      1
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI clients to safely read, search, understand, and edit local project code and files, with Git inspection, code indexing, and controlled command execution within permissioned workspaces.
      8 npm
      6
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables coding agents to safely inspect and modify project files within explicitly allowed workspace roots, with controls for file operations, git status/diff, and optionally allowlisted command execution.
      11
      Apache 2.0