Runner MCP

Runner MCP

已确认的跨产品角色（2026-10-20）：Runner-MCP 是有边界的认证执行与 MCP 访问边界，不是公司驾驶舱，也不是第二个技术协调器。AIfordable 负责公司范围的业务驾驶舱，以及客户、产品、注册和期望状态数据；Runner-Fabric 负责技术 F10/F17 驾驶舱，并且是唯一的技术协调器。现有的 Agent Bus 中继代码作为传输层保留，不会成为重复的调度器。Runner-MCP 可选的 Fabric 桥接仍保持狭窄范围，不会自动扩大权限。跨产品角色约定。

让 AI 在你自己的服务器上运行测试和受控的预发布环境操作，而无需向它提供通用远程 Shell。

Runner MCP 是一款以安全为先、可自托管的模型上下文协议服务。你可以配置可用的项目和操作；AI 从这些受限能力中进行选择，而不是提供任意 Shell 命令、可执行文件、文件系统路径或服务名称。

一个 AIfordable 项目——安全软件。以 AI 构建。定价公平。

Runner MCP 目前处于 alpha 阶段并进入维护模式。规范的公开版本为 v0.1.3，可通过 PyPI、官方 MCP Registry 和 GitHub Releases 获取。核心 alpha 范围已完成；后续工作仅限于安全修复、缺陷修复、兼容性和具体运维需求，不会进行推测性的功能扩展。

从这里开始：5 分钟演示 · 快速入门 · 安全模型 · 威胁模型

新主机的一次性预发布环境配置（仅限本地操作员）：固定源的主机引导配置。此操作不会激活服务，也不会授予远程权限。

一张表看懂区别

方式	AI 可以检查／运行已配置的工作	通用 Shell 是常规接口	明确的审计／安全边界
SSH／广泛的远程控制工具	是	是	取决于周边配置
Runner MCP	是	否	是——允许列表、受限输出、紧急停止和审批关卡

Runner MCP 并非用于运行不可信代码的沙箱，也不声称能取代所有操作员维护工具。它的目标更为有限：常规的 AI 辅助开发和预发布环境操作不应要求向 AI 提供不受限制的 Shell。

Runner MCP 存在的意义

当助手能够根据真实项目验证更改时，AI 辅助开发会更有用。但读取安全文件、运行已知测试套件或检查暂存服务等日常任务，并不需要通用远程 Shell 的权限。

Runner MCP 将这些日常操作转化为明确的能力。操作者在本地配置项目和具名操作；AI 客户端从这些能力中进行选择，而不是提供任意命令、可执行文件路径或私有基础设施值。

最初的动机很实际：在保留实用的开发和暂存自动化的同时，减少日常工作对宽泛远程控制工具的依赖。

工作原理

flowchart LR
    A[AI client] -->|private MCP transport| R[Runner MCP]
    A -->|optional bounded requests| G[GitHub mailbox]
    G -->|strict allow-listed bridge| R
    H[Human operator] -->|approval / emergency stop| R
    R --> P[Configured projects]
    R --> T[Predefined test profiles]
    R --> O[Controlled staging operations]

Runner MCP 是本地安全边界。GitHub 可用于协作处理源代码，也可选择用作受限的邮箱传输机制；它不会被变成发送任意 Shell 命令的手段。

正常的权限模型刻意采用不对称设计：只读检查更容易执行；会修改暂存环境的操作范围更窄；风险更高的操作需要短时本地审批；生产环境中的修改则始终禁用。

可选的 Runner Fabric 工作单元桥接

Runner Fabric 仍是独立产品，并负责其自身的编排与控制平面。当两款产品运行在同一主机上时，Runner MCP 可选择启用仅限环回地址的传输桥接，并提供三个粗粒度工具——运行、检查和取消受限的 Fabric 工作单元。这样，AI 无需获得通用的 GitHub/Git/Shell 基元，也能交接整个代码仓库更改工作流。

该桥接默认禁用，且不会改变 Runner MCP 的权限模型。请参阅可选的 Runner Fabric 桥接。

对于 ChatGPT/Codex 客户端，Runner MCP 还可以生成私有的第一方插件包，复用现有 MCP 边界，而无需嵌入持有者令牌值或增加另一个控制平面。请参阅第一方 ChatGPT/Codex 控制路径。

我只想使用它

对于基本工作流，你无需理解 Python 源代码。

从 v0.1.1 开始，最简的持久安装方式是：

uv tool install aifordable-runner-mcp
runner-mcp setup
runner-mcp doctor
runner-mcp guide
runner-mcp status

uvx aifordable-runner-mcp ... 也适合发现软件包和短期评估，但对于带有私有配置且可自动启动的自托管服务，持久安装工具是更清晰的选择。

如需直接从源代码安装：

git clone https://github.com/Blacksp1d3r/runner-mcp.git
cd runner-mcp
./install.sh

请从 QUICKSTART.md 开始，按照指南进行安装。

连接仍优先采用环回方式。runner-mcp setup 在 public 模式下只会记录外部 HTTPS 资源／身份验证信息；它不会公开绑定地址、安装 TLS、编辑 DNS／防火墙、配置反向代理或创建隧道。runner-mcp guide 只会报告通用的连接类别，不会打印已配置的主机名或私有 URL。对于受支持的 OpenAI 产品，私有访问可以使用 Secure MCP Tunnel；由运维人员管理的外部 HTTPS 反向代理也是一种替代方案。

如果 Runner MCP 在专用服务帐户下运行，而你使用另一个运维帐户登录，请安装本地运维包装器。如果 Runner MCP 在你交互使用的同一帐户下运行，则跳过此步骤：

./install-operator.sh SERVICE_USER
runner-mcp guide

该包装器会将私有配置保留在服务帐户下，并通过 sudo 执行操作；它不会将凭据复制到运维帐户。

如需了解从用户到开发者的进阶路径，请参阅 docs/USING_AND_EXTENDING.md。贡献者可以从 CONTRIBUTING.md 开始。

如需了解零额外服务费用的 GitHub 邮箱模式，请参阅 docs/GITHUB_MAILBOX_BRIDGE.md。公共软件包现在同时包含与传输方式无关的处理器和固定主机的 GitHub 传输；完成反馈和监视器韧性说明见 docs/COMPLETION_FEEDBACK.md 和 docs/WATCHER_RESILIENCE.md。有界多项目调度和容量控制说明见 docs/CONCURRENCY.md。

自更新会有意拒绝依赖项／构建／解释器契约变更，此类变更需要通过本地引导或手动升级；请参阅自更新兼容性。

Runner MCP 是作为 AIfordable 项目开发的。公开发布准备情况在 docs/LAUNCH_READINESS.md 中跟踪。另请参阅变更日志、发布检查清单和已准备好的发布文案。

常用命令：

runner-mcp setup
runner-mcp doctor
runner-mcp guide
runner-mcp status
runner-mcp emergency-stop on
runner-mcp emergency-stop status
runner-mcp emergency-stop off
runner-mcp autostart preflight
runner-mcp autostart status
runner-mcp project list
runner-mcp project add ...
runner-mcp test-profile list PROJECT
runner-mcp test-profile add PROJECT NAME --preset pytest
runner-mcp service-config list PROJECT
runner-mcp service-config add PROJECT ALIAS --unit UNIT
runner-mcp database-config list
runner-mcp database-config add PROJECT
runner-mcp retention preview PROJECT
runner-mcp database restore-plan PROJECT BACKUP_ID
runner-mcp migration-config add PROJECT --preset alembic
runner-mcp deployment-config list
runner-mcp deployment-config add PROJECT --release-root PATH --service ALIAS
runner-mcp github-mailbox status
runner-mcp github-watcher once
runner-mcp plugin-package registered-app --app-id APP_ID --output PRIVATE_DIR
runner-mcp plugin-package http --url MCP_URL --output PRIVATE_DIR
runner-mcp serve

# MCP/mailbox clients can also use:
# runtime_status
# runtime_doctor
# self_update <full-main-commit>
# self_update_status <job-id>

紧急停止机制有意设计为易于启用、难以解除。

目前已实现的功能

目前已实现的基础功能包括：

• 通过 Streamable HTTP 提供经过身份验证的 MCP；
• 项目允许列表；
• 安全的项目文件列表、元数据和分页读取；
• 路径遍历、符号链接和机密文件保护；
• 请求 ID、速率限制和审计日志；
• DNS 重绑定保护；
• 外部操作员紧急停止；
• 同时使用最小数量和最短保留时间的回滚保留策略；
• 本地只读保留预览，包含严格的版本发布／备份验证，且无删除权限；
• 明确区分代码回滚和数据库还原；
• 受控的异步测试任务；
• 对规范 Runner MCP 项目进行固定到提交的自更新；更新以未变更的 Python／构建／依赖兼容性约定为门槛，执行固定的 lint／单元测试验证，并在内部重新执行自身；
• 有界且公平的多项目测试调度，每个项目可选择启用并行执行；
• 安全地查看队列、工作进程和任务状态，不泄露基础设施信息；
• 允许列表中的 systemd-user 暂存服务状态查看／启动／停止／重启；
• 可选的私有服务运行状况检查；
• 私有 PostgreSQL 备份及安全的元数据列表；
• 本地只读 PostgreSQL 还原预检，不会修改数据库；
• 受控的迁移状态查看／执行，并强制要求迁移前备份；
• 仅用于暂存环境的版本发布规划和异步部署任务；
• 基于干净 Git 状态的版本发布归档、原子激活和由运行状况检查决定的回滚；
• 安全的版本发布历史，以及一步式异步暂存环境回滚；
• 内置的允许列表项目适配器，可安全地检查功能；
• 严格的 MCP 工具参数：拒绝未知字段，而非忽略它们；
• 用于迁移、部署和回滚的短时人工审批门槛；
• 仅允许在暂存环境中执行变更；生产环境仍为只读；
• 私有 ChatGPT 连接可使用 OpenAI Secure MCP Tunnel，无需开放公网入站端口；
• 仅使用预定义的测试配置；
• 测试超时、取消和进程组清理；
• 已脱敏且有界的测试日志；
• 重启后可恢复中断测试任务的元数据；
• 交互式设置、状态和诊断命令；
• 无需手动编辑 YAML 即可通过 CLI 管理项目；
• 通过 CLI 管理测试配置，支持 pytest、Ruff 和自定义预设；
• 非 root 本地安装程序和引导式 Quickstart。

Runner MCP 刻意不提供的功能

Runner MCP 不提供以下功能：

• 通用远程 shell；
• 由 AI 客户端提供的任意命令；
• 自动还原生产数据库；
• 当前实现中的数据库还原执行；
• 自动执行多个版本发布的级联回滚；
• 不受限制的服务控制；
• 在具有特权且持久运行的 Runner 上执行不可信的公共 fork。

在实现更强的审批和隔离控制之前，生产环境操作仍不在支持范围内。

安全模型

Runner MCP 基于以下原则构建：

• 默认拒绝；
• 明确列出允许的项目、服务和测试配置；
• 不提供任意 shell 作为常规接口；
• MCP 工具输出中不包含机密信息；
• 严格的路径验证；
• 可审计的操作；
• 最小权限运行时权限；
• 为运维工具明确划分风险等级；
• 外部操作员紧急停止；
• 操作员执行操作前确认保留策略；
• 每次获批操作仅执行一步代码回滚；
• 数据库还原始终需要明确的人工审批；
• DNS 重绑定保护与配置的 MCP 资源 URL 绑定。

请参阅：

• security/SECURITY_BASELINE.md
• security/THREAT_MODEL.md
• security/OPERATOR_SAFETY.md
• security/TEST_EXECUTION.md

公共仓库规则

本仓库绝不能包含真实基础设施信息。

请勿提交：

• 真实 IP 地址或主机名；
• 内部域名；
• 私有服务端点或端口；
• 用户名；
• 来自真实安装环境的绝对部署路径；
• 数据库端点；
• 凭据或令牌；
• 私钥；
• 数据库转储或备份。

公共示例只能使用占位符。真实值应存放在私有本地配置或适当的密钥存储中。

受控测试执行

MCP 客户端只能选择已配置的项目和具名测试配置。

测试配置会定义确切的可执行文件、确切的参数数组、相对于项目的工作目录、超时时间、日志限制，以及明确允许的环境变量。

命令会通过 shell=False 启动。

运行测试仍会执行项目代码。在具备更强的沙箱机制之前，只应测试受信任的仓库修订版本。

回滚原则

代码回滚和数据库恢复是分开的操作。

代码发布版本通过以下两项要求保留：

• 最少发布版本数；
• 最短保留时间。

只有在两项条件都允许时，发布版本才符合清理条件。

单次获批的回滚操作最多只能回退一个代码发布版本。Runner MCP 必须停止、进行健康检查并重新评估，然后才能再次回滚。

数据库恢复绝不是代码回滚的自动副作用，且始终需要获得人工明确批准。

开发

目标运行时：Python 3.12+。

核心技术：

• 官方 MCP Python SDK；
• Pydantic；
• PyYAML；
• Starlette；
• Uvicorn；
• pytest；
• Ruff。

该实现通过 Streamable HTTP 使用 MCP。

请勿将拥有特权的持久化自托管 Runner 连接到不受信任的公共拉取请求代码。

项目状态

当前实现状态记录在：

• handover/CURRENT_STATE.md
• roadmap/ROADMAP.md
• FUTURE_LAB.md — 实验性研究、基准测试和远大目标，与稳定核心分开维护

Runner MCP v0.1.3 是当前规范的跨注册表 Alpha 版本。技术 Alpha/MVP 核心已完成，项目现处于维护模式。运行时、自我更新/恢复、受限的一方控制、GitHub 邮箱/Agent Bus 支持，以及可选的粗粒度 Runner Fabric 桥接均已取得实际验收证据。未来对 Runner MCP 的更改应由安全性、缺陷、兼容性或具体运维需求驱动；更广泛的编排和新自动化应由 Runner Fabric 承载，而不是将 Runner MCP 扩展为通用远程控制层。