Runner MCP

Runner MCP

製品横断で確認された役割（2026-10-20）： Runner-MCP は、認証済みの実行と MCP アクセスを制限する境界であり、会社全体のコックピットでも第 2 の技術オーケストレーターでもありません。AIfordable は会社全体のビジネスコックピットと、顧客／製品／登録／望ましい状態に関するデータを担います。Runner-Fabric は技術向け F10/F17 コックピットを担い、唯一の技術コーディネーターです。既存の Agent Bus リレーコードは、重複するスケジューラーではなく、トランスポートとして維持されます。Runner-MCP のオプションの Fabric ブリッジは限定的なままで、権限が自動的に拡張されることはありません。製品横断の役割契約。

汎用のリモートシェルを使わせることなく、AI に自分のサーバー上でテストや制御されたステージング操作を実行させましょう。

Runner MCP は、セキュリティを最優先するセルフホスト型の Model Context Protocol サービスです。プロジェクトと操作を設定すると、AI は任意のシェルコマンド、実行ファイル、ファイルシステムパス、サービス名を指定するのではなく、制限された機能の中から選択します。

AIfordable のプロジェクト — セキュアなソフトウェアを AI で構築し、公正な価格で提供します。

Runner MCP は現在、アルファ版でメンテナンスモードです。正式な公開リリースは v0.1.3 で、PyPI、公式 MCP レジストリ、GitHub Releases から入手できます。アルファ版の中核的な範囲は完成しており、今後の作業は、推測的な機能拡張ではなく、セキュリティ修正、バグ、互換性、および具体的な運用上のニーズに限定されます。

まずはこちら： 5 分間のデモ · クイックスタート · セキュリティモデル · 脅威モデル

新しいホストの初回ステージング（ローカルのオペレーターのみ）： ソースを固定したホストのブートストラップ。これはサービスを有効化したり、リモート権限を付与したりするものではありません。

ひと目でわかる違い

アプローチ	AI が設定済みの作業を調査／実行できる	任意のシェルが通常のインターフェースである	明示的な監査／安全性の境界
SSH／広範なリモート制御ツール	はい	はい	周囲の設定によります
Runner MCP	はい	いいえ	はい — 許可リスト、出力制限、緊急停止、承認ゲート

Runner MCP は、信頼できないコードを実行するためのサンドボックスではなく、あらゆるオペレーター向け保守ツールを置き換えるものでもありません。目標はより限定的です。AI を活用した日常的な開発やステージング操作のために、AI に無制限のシェルを渡す必要がないようにすることです。

Runner MCP が存在する理由

AI 支援開発は、アシスタントが実際のプロジェクトに対して変更を検証できると、はるかに役立つようになります。しかし、安全なファイルの読み取り、既知のテストスイートの実行、ステージングサービスの確認といった日常的なタスクには、汎用リモートシェルの権限は必要ありません。

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 を使用でき、任意で範囲を限定したメールボックスの転送にも使用できますが、任意のシェルコマンドを送信する仕組みにはなりません。

通常の権限モデルは、意図的に非対称になっています。読み取り専用の調査は容易に行える一方、ステージング環境に変更を加えるアクションはより限定され、リスクの高いアクションには有効期間の短いローカル承認が必要です。また、本番環境への変更は無効のままです。

Runner Fabric の任意の作業単位ブリッジ

Runner Fabric は、独立した製品であり、オーケストレーション／コントロールプレーンの所有者であり続けます。両製品を同じホストで実行する場合、Runner MCP は任意で、ループバック限定の転送ブリッジを公開できます。このブリッジには、範囲を限定した Fabric の作業単位に対する「実行」、「調査」、「キャンセル」の3つの大まかなツールがあります。これにより、汎用の GitHub／Git／シェルのプリミティブを受け取ることなく、AI がリポジトリ変更のワークフロー全体を引き継げます。

このブリッジはデフォルトで無効になっており、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 をご覧ください。

接続は引き続きループバックを優先します。public モードで runner-mcp setup を実行すると、外部 HTTPS リソース／認証 ID のみが記録されます。バインドアドレスの公開、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 ツール引数。未知のフィールドは無視せず拒否します；
• 移行、デプロイ、ロールバックに対する短時間有効な人間による承認ゲート；
• ステージングのみの変更ポリシー。production は引き続き読み取り専用です；
• プライベートな ChatGPT 接続では、受信側のパブリックポートを開かずに OpenAI Secure MCP Tunnel を利用できます；
• 事前定義済みのテストプロファイルのみ；
• テストのタイムアウト、キャンセル、プロセスグループのクリーンアップ；
• サニタイズ済みで上限付きのテストログ；
• 再起動後の中断されたテストジョブのメタデータ復旧；
• 対話型のセットアップ、状態確認、doctor コマンド；
• YAML を手動編集せずに行える、CLI によるプロジェクト管理；
• pytest、Ruff、カスタムプリセットに対応した、CLI によるテストプロファイル管理；
• 非 root のローカルインストーラーと、ガイド付き Quickstart。

Runner MCP が意図的に行わないこと

Runner MCP は、次の機能を提供することを目的としていません。

• 汎用のリモートシェル；
• AI クライアントが指定する任意のコマンドの実行；
• 本番データベースの自動復元；
• 現在の実装でのデータベース復元の実行；
• 複数リリースにわたる自動ロールバック連鎖；
• 無制限のサービス制御；
• 特権を持つ永続的なランナー上での、信頼できないパブリックフォークの実行。

より強力な承認および分離制御が実装されるまでは、本番環境に対する操作は対象外です。

安全性モデル

Runner MCP は、次の原則に基づいて構築されています。

• デフォルトで拒否する；
• プロジェクト、サービス、テストプロファイルの明示的な許可リスト；
• 通常のインターフェースとして任意のシェルを提供しない；
• MCP ツールの出力にシークレットを含めない；
• 厳格なパス検証；
• 操作の監査可能性；
• 最小権限のランタイム権限；
• 運用ツールに対する明示的なリスク分類；
• 外部オペレーターによる緊急停止；
• オペレーター操作前の保持確認；
• 承認された操作ごとにコードのロールバックは一段階のみ；
• データベースの復元には常に明示的な人間の承認が必要；
• 設定済みの MCP リソース URL に関連付けられた DNS リバインディング保護。

以下を参照してください。

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

パブリックリポジトリのルール

このリポジトリに実際のインフラストラクチャ情報を含めてはいけません。

次の情報をコミットしないでください。

• 実際の IP アドレスやホスト名
• 内部ドメイン
• 非公開のサービスエンドポイントやポート
• ユーザー名
• 実際のインストール環境における絶対デプロイパス
• データベースのエンドポイント
• 認証情報やトークン
• 秘密鍵
• データベースのダンプやバックアップ

パブリックな例ではプレースホルダーのみを使用します。実際の値は、非公開のローカル設定または適切なシークレットストアに保存してください。

テスト実行の制御

MCP クライアントが選択できるのは、設定済みのプロジェクトと名前付きテストプロファイルに限られます。

テストプロファイルでは、実行ファイル、引数配列、プロジェクト相対の作業ディレクトリ、タイムアウト、ログ上限、明示的に許可された環境変数を正確に定義します。

コマンドは shell=False で起動します。

テストの実行では、引き続きプロジェクトコードが実行されます。より強固なサンドボックスが整うまでは、信頼できるリポジトリのリビジョンのみをテストしてください。

ロールバックの方針

コードのロールバックとデータベースの復旧は、別々の操作です。

コードリリースは、次の両方を基準に保持します。

• 最低リリース数
• 最低経過期間

両方の条件で許可された場合に限り、リリースをクリーンアップできます。

承認済みのロールバック操作を1回実行すると、コードリリースをちょうど1つ前に戻せます。再度ロールバックする前に、Runner MCP は停止し、ヘルスチェックを行い、状況を再評価する必要があります。

データベースの復元がコードのロールバックに伴って自動実行されることは決してなく、必ず人間による明示的な承認が必要です。

開発

対象ランタイム：Python 3.12+。

主要な技術：

• 公式 MCP Python SDK
• Pydantic
• PyYAML
• Starlette
• Uvicorn
• pytest
• Ruff

実装では、MCP に Streamable HTTP を使用します。

信頼できないパブリックプルリクエストのコードに、特権を持つ永続的なセルフホスト型ランナーを接続しないでください。

プロジェクトのステータス

現在の実装状況は、次のファイルで管理されています。

• handover/CURRENT_STATE.md
• roadmap/ROADMAP.md
• FUTURE_LAB.md — 安定したコアとは分けて管理する、実験的な調査、ベンチマーク、ムーンショット

Runner MCP v0.1.3 は、現在の正規のレジストリ横断アルファリリースです。技術的なアルファ版／MVP のコアは完成しており、プロジェクトは現在メンテナンスモードです。ランタイム、セルフアップデート／復旧、範囲を限定したファーストパーティ制御、GitHub メールボックス／Agent Bus のサポート、任意の粗粒度 Runner Fabric ブリッジには、実環境での受け入れエビデンスがあります。今後の Runner MCP の変更は、セキュリティ、欠陥、互換性、または具体的な運用上の要件に基づいて行ってください。より広範なオーケストレーションや新たな自動化は、Runner MCP を汎用リモート制御レイヤーへ拡張するのではなく、Runner Fabric に実装してください。