mcp-portal

mcp-portal

mcp-portal は、最先端のエージェント（Claude Code、Codex、Cursor、または任意の MCP ホスト）が、Cursor CLI の独自のクォータを使って 2 つのタスクを委任できる stdio Model Context Protocol サーバーです。範囲を限定した bulk_read（明示的に選択したファイルを読み取り、検証済みの引用を使って回答する）と code_write（参照ファイルと仕様からボイラープレートを生成し、サーバー が対象ファイルを書き込む）を実行できます。Python 標準ライブラリのみを使用し、Node ランタイムも MCP SDK への依存もありません。

2026-09-08 には、同じ概要に対して composer-2.5-fast が最先端モデルよりも約 5 倍高速 に生成しました（行レートによる測定）。Cursor のクォータはホストモデルのものとは別です。

クイックスタート

uvx mcp-portal

pipx install mcp-portal / pip install mcp-portal でも利用でき、MCP Registry では io.github.apollion69/mcp-portal として掲載されています。 リリース版ではなく開発版を実行するには、次のようにします。

uvx --from git+https://github.com/apollion69/mcp-portal mcp-portal

要件：Python 3.10 以降、インストール済みでログイン済みの Cursor CLI（cursor-agent）。

Doctor（CLI の一覧表示。モデル呼び出しは行いません）：

mcp-portal-doctor

ホストごとの設定

Claude Code

claude mcp add --scope user mcp-portal -- uvx mcp-portal

Codex（~/.codex/config.toml）

[mcp_servers.mcp-portal]
command = "uvx"
args = ["mcp-portal"]
tool_timeout_sec = 150

Cursor（~/.cursor/mcp.json）

{
  "mcpServers": {
    "mcp-portal": {
      "command": "uvx",
      "args": ["mcp-portal"]
    }
  }
}

VS Code（.vscode/mcp.json、servers キー）

{
  "servers": {
    "mcp-portal": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-portal"]
    }
  }
}

汎用の mcpServers JSON

{
  "mcpServers": {
    "mcp-portal": {
      "command": "uvx",
      "args": ["mcp-portal"]
    }
  }
}

環境変数（任意）：

変数	用途
MCP_PORTAL_HOME	キャッシュ、レシート、エビデンス（デフォルト ~/.cache/mcp-portal）
MCP_PORTAL_CLI	cursor-agent / agent のパス

ツール

bulk_read

引数	必須	説明
paths	はい	1～16 個のファイルパス（root からの相対パス、または絶対パス）
question	はい	それらのファイルのみを基に回答する質問
root	いいえ	共通のルート。デフォルトは paths の最長共通親ディレクトリ
model	いいえ	モデルを上書きします。省略時はポリシーが適用されます

status、run_id、answer.findings[]（file、start、end、quote、fact）、gaps[]、metrics、model_decision を返します。

code_write

引数	必須	説明
spec	はい	生成する内容
reference_path	はい	スタイルやコンテキストの参照ファイル
target_path	いいえ	設定されている場合、サーバーがこのパスに書き込みます
model	いいえ	モデルを上書きします

生成された code、任意の bytes_written、run_id、metrics を返します。

status

引数はありません。CLI のパス、認証のヒント、デフォルトモデル、ポリシーの概要、キャッシュの場所、レシートのカウンターを返します。

モデルポリシー

model-policy.json（パッケージデータ）に含まれています。デフォルト：

• Cursor ネイティブモデルを優先します（composer-2.5、次に cursor-grok-*）
• -fast サフィックスを取り除きます（高速版を自動選択することはありません）
• 他のベンダーのモデルは、明示的に 要求され、cursor-agent --list-models に掲載されている場合にのみ使用します

インストール済みパッケージ内の model-policy.json を編集するか、MCP_PORTAL_HOME にあるカスタムファイルでポリシーのフィールドを設定すると上書きできます（今後対応予定）。現時点では、パッケージファイルを置き換えるか、フォーク内の preferred を修正してください。各ツールの結果には model_decision.reason（default_preferred、fast_suffix_stripped、cursor_native_explicit、explicit_other_vendor、requested_unavailable_fallback）が含まれます。

仕組み

1. 認可 — サーバーは一覧に記載されたパスのみを読み取り、認証情報のようなパスやシークレットのパターンをブロックします。
2. マニフェスト — リクエストの JSON には、ファイルごとの SHA-256 ハッシュが含まれます。
3. 分離 — Cursor CLI は、新しい CURSOR_CONFIG_DIR、すべての権限を拒否する設定、--mode ask、サンドボックス有効の状態で実行されます。
4. 検証 — bulk_read の回答に含まれるすべての quote は、引用された行範囲にそのまま記載されている必要があります。不正な引用は除外されるか、安全側に倒して処理が失敗します。
5. 証跡 — 実行ごとに MCP_PORTAL_HOME/runs/<run_id>/ の下にディレクトリが作成され、マニフェスト（ハッシュ、メトリクス。ソース全体は含みません）が保存されます。
6. 上限 — ファイル数は16、入力の合計サイズは128 KiB、タイムアウトは90秒、標準入出力フレームは上限付きです。

Windows

Windows では、次のいずれかに該当する場合、デリゲートは Cursor CLI をローカルで実行します。

• MCP_PORTAL_CLI が実行可能ファイル（テスト用スタブを含む）を指している、または
• cursor-agent / agent が PATH 上で見つかり、実ファイルである

それ以外の場合は、Ubuntu/WSL 上の wsl.exe ブリッジ（python3 -m mcp_portal.delegate --worker）にフォールバックします。MCP_PORTAL_BACKEND=local または MCP_PORTAL_BACKEND=wsl を指定すると、いずれかのモードを強制できます。

• MCP の設定では、CLI が PATH 上にあればネイティブの uvx mcp-portal を、なければ wsl.exe + uvx mcp-portal を使用できます
• clients/windows/ のヘルパー（delegate.ps1、parse_read.ps1）
• MCP_PORTAL_WORKER でデフォルトの WSL ワーカーコマンドを上書きします
• MCP_PORTAL_WSL_CD で WSL の作業ディレクトリを設定します（デフォルトは ~）

Claude Code のオプションのルーティングフック

読み取りゲート + スキルをインストールします（汎用、トランザクション型）。

python3 -m mcp_portal.install_router prepare --client claude --python python3 \
  --state-root ~/.cache/mcp-portal/router-tx --shell bash --command-shell bash
# then apply with the printed transaction id

エージェント向けのガイダンスについては、docs/skills/cursor-bulk-reader/SKILL.md を参照してください。ルーターは、大きなファイル全体の読み取り（350行超または128 KiB超）をブロックまたは警告し、エージェントに bulk_read を案内します。

リポジトリレベルの MCP 登録ヘルパー：

python3 -m mcp_portal.install plan
python3 -m mcp_portal.install apply --target claude-mcp

セキュリティ

SECURITY.md を参照してください。概要：どのファイルをマシンの外部に送るかはユーザーが選択できます。CLI は読み取り専用で実行され、ツールの使用は拒否されます。引用はサーバー側で検証されます。シークレットを適切に管理する代わりにはなりません。

関連プロジェクト

Cursor を MCP 経由で公開する、Node ベースのブリッジがいくつかあります（SDK／Node スタック、分離や検証の方式はそれぞれ異なります）。

• lipey1/cursor-agent-mcp
• andreilungeanu/cursor-delegate-mcp
• sailay1996/cursor-agent-mcp
• ai-nuke/cursor-agent-mcp
• JaimeJunr/cursor-mcp-bridge

mcp-portal は、Python 標準ライブラリ、ハッシュで固定されたマニフェスト、引用検証、code_write のサーバー側書き込み、モデルポリシー、WSL を優先する Windows サポートに重点を置いています。

ライセンス

MIT — LICENSE を参照してください。