Agentic MCP

Agentic MCP — ChatGPT Developer Mode 向けローカルコーディングツール

プロジェクトのウェブサイト · GitHub リポジトリ · npm パッケージ · MCP Registry

対応する ChatGPT Web アカウントを、MCP Developer Mode を通じてローカルのコーディングツールに接続します。

Agentic MCP は、セキュアな Model Context Protocol（MCP）サーバーを通じて、ChatGPT Web Developer Mode をローカルのリポジトリに接続します。構造化ファイル編集、シェル実行、Git worktree、セマンティックナビゲーション、チェックポイントに対応しています。

ChatGPT Web → Developer Mode → HTTPS Tunnel → Agentic MCP → Local Repository

警告

セキュリティに関する注意：このツールはローカルマシン上で実行され、シェルコマンドを実行できます。管理された Git worktree は、メインリポジトリを汚染しないよう、分離された Git チェックアウトを提供しますが、オペレーティングシステムのサンドボックスではありません。ネットワークアクセスやサブプロセスを制限するものではありません。LLM が実行しようとしている内容は、必ず確認してください。

メモ

免責事項：Agentic MCP は独立したオープンソースプロジェクトであり、OpenAI とは提携、資金提供、推奨のいずれも受けていません。ChatGPT と OpenAI は OpenAI の商標です。メンテナーは Developer Mode と HTTPS トンネルを使用し、ChatGPT Plus でテストしています。MCP 機能を利用できるかどうかは、ユーザーの ChatGPT プラン、ワークスペースの設定、OpenAI による現在の展開状況によって異なります。

🌐 公式 MCP Registry

Agentic MCP は、公式 MCP Registry に次の名前で公開されています： io.github.hugolsramos01-bit/mcp-agentic-server

Claude Desktop、Cursor、その他のローカル MCP クライアント向けに、ローカルでインストールして実行します：

npx -y mcp-agentic-server@latest stdio

---

⚡ クイックスタート：ChatGPT Plus のセットアップ（3 分）

既存の Web プランを使って、ChatGPT Web をメインのローカルコーディングエージェントにします：

1. サーバーを初期化して起動します：

   npx -y mcp-agentic-server@latest init
   npx -y mcp-agentic-server@latest serve
   

2. HTTPS トンネル経由でローカルポート（7676）を公開します：

   ngrok http 7676
   

3. ChatGPT Web で Developer Mode を有効にします：

   • chatgpt.com > Settings > Apps / Developer Mode（または Plugins / Apps）に移動します。
   • Developer Mode を有効にします。

4. カスタム MCP アプリを接続します：

   • 新しい Custom MCP App を追加します。
   • 末尾が /mcp の公開 ngrok HTTPS URL を入力します：

     https://YOUR-SUBDOMAIN.ngrok.app/mcp
     

5. OAuth 認証を完了します：

   • 表示されたら、ローカルブラウザーの OAuth 認証プロンプトを完了します。

6. コーディングを開始します：

   • 新しい ChatGPT Web チャットでカスタム MCP アプリを有効にし、次のプロンプトを入力します：

     「C:/path/to/project のワークスペースを open_workspace で開き、アーキテクチャを要約してください。」

---

🙋 よくある質問（FAQ）

ChatGPT Plus で使えますか？

メンテナーは Developer Mode と公開 HTTPS トンネル（ngrok、Cloudflare Tunnel など）を使い、ChatGPT Plus でテストしています。利用できるかどうかは、アカウント、地域、プラン、展開状況によって異なる場合があります。

利用制限や請求にはどのような影響がありますか？

ChatGPT Developer Mode から直接接続する場合、モデルの利用は OpenAI Platform API キーではなく、ユーザーの ChatGPT アカウントによって処理されます。適用される利用制限は、ユーザーのプランと OpenAI のポリシーによって異なります。

OpenAI API キーは必要ですか？

OpenAI のモデル API キーは必要ありません。MCP サーバーとトンネルの認証は、モデル API の請求とは別です。

Codex や Claude Code の代替になりますか？

はい。ChatGPT Web に、ファイルの確認、構造化された行単位の正確な編集、シェル実行、Git worktree、AST ナビゲーション、チェックポイントなど、ローカルコーディングの全機能を提供します。

---

🔐 リリース 1.8.1：セキュリティと分離

バージョン 1.8.1 では、ワークスペースのサブプロセスを Agentic MCP のコントロールプレーンから分離します。シェルコマンド、パッケージスクリプト、プロセスセッション、依存関係のインストール、トーナメントの検証には、AGENTIC_* サーバーの認証情報や設定が引き継がれなくなりました。MCP サーバーのバインドには AGENTIC_HOST と AGENTIC_PORT を使用してください。従来の HOST／PORT も引き続き受け付けますが、Agentic の設定に使われる場合、ワークスペースのコマンドには引き継がれません。

ローカルリポジトリでの構造化 grep も強化されました。.git／Agentic のチェックポイント内部、.env などの秘密情報を含む可能性のあるファイルや秘密鍵ファイル、Windows の nul パスを除外し、公開用の include glob を正しく適用します。

🚀 リリース 1.8.0 の主な変更点

バージョン 1.8.0 では、read_many を単なる複数ファイルの読み取り機能ではなく、範囲を制限した複合調査のプリミティブとして機能させます。

1. 1 回のラウンドトリップで複数の関連調査を実行 — 順序付きの項目で、正確な読み取り／範囲指定、コンテキスト付きのスコープ指定レキシカルマッチ、スコープ指定 glob を組み合わせられます。
2. 共有出力予算 — シリアライズ後のエビデンスの推定サイズ、返却行数、ユニークなファイル数の上限が呼び出し全体に適用されます。先行する項目には明示的な優先度があり、glob の結果は上限内に収まる有用な部分だけを返します。レスポンスでは、最終ペイロードの推定オーバーヘッドも別途報告します。
3. コンテキストの重複排除 — 同じファイル内で重なるマッチウィンドウを統合してからモデルに渡します。
4. 段階的な絞り込み — 広範な探索は、アーキテクチャが本当に不明な場合に限られます。対象領域が判明した後は、エージェントに広範なコンテキスト収集のやり直しではなく、範囲を制限した複合調査を促します。
5. クロスプラットフォーム対応の範囲制限付き探索 — Git を考慮したファイル一覧表示では、スコープを指定した結果が空でも無視対象ファイルを除外します。Git がない場合は範囲を制限したフォールバックを使用し、スキャンが途中で打ち切られたことをメタデータで明示します。マッチ項目では include glob でファイルを絞り込むこともできます。
6. 範囲制限付き正規表現のオプトイン — デフォルトではリテラル検索を使用します。正規表現モードを明示的に有効にすると、リスクの高いバックトラッキング構文をいくつか拒否し、スキャンするバイト数に上限を設け、異常に長い行をスキップします。これにより、1 回の検索がサーバーを占有し続けるのを防ぎます。
7. リソース上限のフェイルクローズ — 互換性のない操作フィールドは無視せず拒否します。従来の paths 呼び出しは引き続き使用できます。また、複合読み取りではパス数／ファイル数／ソースバイト数の読み込みと診断文字列のサイズに上限を設けるため、対象を絞ったリクエストが誤って過大なファイルシステム負荷やレスポンスペイロードを生むことはありません。

🚀 リリース 1.6.0 の主な変更点

バージョン 1.6.0 では、1.5.0 で導入されたセキュリティと検証の境界を弱めずに、コーディングの反復にかかるレイテンシーを削減します。

1. 3 つのコマンドセキュリティモード — デフォルトは引き続き safe です。trusted では破壊的なコマンドへの保護を維持しつつ、実用的なインラインスクリプトやシェルによるファイル書き込みを有効にします。また、明示的に無制限のローカル実行を行う場合は full を利用できます。
2. 変更に応じたコーディングワークフロー — QUICK、STANDARD、CRITICAL の変更に同一の PVDL および検証コストを適用しません。厳格な PVDL は、必要な環境で明示的に指定できます。
3. 探索停止の徹底 — すでに十分に対象が絞れていることを再確認するためだけに、広範な初期化／コンテキスト探索を開始するのではなく、判明しているファイルやシンボルを直接調査します。
4. 範囲を制限した高速コンテキスト — read_many のデフォルトは 12k トークンです。高速タスクコンテキストでは大きなコード領域の読み取りを 160 行のアンカーウィンドウに制限し、通常のモデル推論の中断をまたいでもファイルインデックスを保持します。
5. QUICK レビューの高速化 — AGENTIC_WIDGETS=changes の場合、単一ファイルに対する edit／write の変更ではレビュー UI が直接表示されるため、冗長な show_changes の集約ラウンドトリップが不要になります。

🔥 主な革新点

1. コンテキストの肥大化を防ぐスマートな仕組み

LLM のコンテキストウィンドウが限界に達するのを防ぎ、ChatGPT Web のメッセージ上限を維持します。

• workspace_summary：ワークスペース全体を巨大なファイルにまとめて返す代わりに、ワークスペースの概要マップ（Git のステータス、パッケージマネージャー、主要なスクリプト、スキーマ）をコンパクトに返します。
• 強化されたファイル読み込み：read ツールでは、オフセットと制限の指定が必須で、行範囲も厳しく制限されます。モデルは必要な内容だけを行単位で取得できるため、大きなファイルによる壊滅的なトークンの肥大化を防げます。

2. 真の Git Worktree サンドボックス

メインディレクトリで実験的なコードやテストを実行したり、LLM に破壊的な編集をさせたりすると、Hot Module Replacement（HMR）が壊れたり、Next.js／Vite で無限ループが発生したり、node_modules に問題が起きたりする可能性があります。

• open_workspace (mode="worktree")：プロジェクトのメインディレクトリの外部（例：~/.agentic/worktrees/）に、分離された detached git worktree を自動的に作成します。
• LLM は、ライブの開発環境に一切触れることなく、環境を壊したり、worktree_install_deps で新しい依存関係をインストールしたり（allowLifecycleScripts は安全に制御されます）、worktree_sync_changes で未コミットの変更を同期したりできます。

3. セマンティック AST ナビゲーション

サーバーは TypeScript と JavaScript を動的に解析し（CPU を節約するインメモリ LRU キャッシュ付き）、アーキテクチャのセマンティックマップをモデルに提供します。

• next_route_map：Next.js の App Router と Pages Router を動的にマッピングし、役割（api、page、layout）と動的セグメントを表示します。
• payload_schema_map：Payload CMS のコレクションを分析し、フィールド、フック、リレーションシップのクリーンなマップを返します。
• file_dependencies：ファイルがインポートする依存関係（外向き）と、そのファイルをインポートするファイル（内向き）を即座にマッピングします。

4. 安全な編集とドライラン

• edit_dry_run：置換をシミュレーションして、文字列の完全一致と一意性を検証し、実際にディスクへ保存することなく、編集される箇所の周辺コンテキストを返します。
• changed_files_summary：git status --porcelain を使用して、変更されたファイルと新たにステージされたファイルの概要を高速かつ正確に表示します。

5. チェックポイントシステム

長時間にわたる自律セッションでは、エージェントがワークスペースの特定時点のスナップショットを保存し（checkpoint_save）、一覧表示し（checkpoint_list）、アーキテクチャの方針を誤った場合にロールバックできます（checkpoint_restore）。

---

💻 ローカルおよびデスクトップ MCP クライアント（Claude Desktop、Cursor、Roo Code）

デスクトップ MCP ホストを使用する場合は、stdio トランスポートを使うようにクライアント設定ファイルを構成してください。

{
  "mcpServers": {
    "agentic-mcp": {
      "command": "npx",
      "args": ["-y", "mcp-agentic-server@latest", "stdio"],
      "env": {
        "AGENTIC_ALLOWED_ROOTS": "C:/path/to/projects"
      }
    }
  }
}

---

🛠 利用可能なツールのリファレンス

利用可能なツールは、AGENTIC_TOOL_MODE の設定によって異なります。

モード	含まれるツール	用途
assistant（デフォルト）	標準的なコーディングワークフロー：ワークスペース、コンテキスト、読み込み／検索、Git、チェックポイント、編集／ドライラン、パッケージスクリプト、worktree、診断、セマンティックマップ。	モデル向けの厳選された指示を含む、コーディングエージェントの完全なワークフロー。
full	基本ツール + grep、glob、ls	シェルを使った手動の調査
minimal	open_workspace、read、write、edit、bash	制限されたツールセット

注： 完全なエージェント型コーディング体験には、assistant モードを推奨します。.env または環境変数に AGENTIC_TOOL_MODE=assistant を設定してください。

コマンドのセキュリティモード

ツールモードとコマンドのセキュリティは別々に設定されます。AGENTIC_SECURITY_MODE は、ポリシーエンジンが許可するシェルコマンドを制御します。

セキュリティモード	動作
safe（デフォルト）	厳格なコマンドポリシーです。インラインスクリプトやファイル書き込みを行うシェル構文、破壊的なコマンドをブロックします。
trusted	python -c、node -e、リダイレクト、ヒアドキュメント、シェルによるインプレース書き込みを許可しますが、破壊的な操作は引き続き保護されます。
full	破壊的なコマンドのルールを含め、コマンドポリシーの制限を回避します。

agentic config set securityMode safe|trusted|full で設定を保存してから、サーバーを再起動してください。OAuth は引き続き必須です。シェルは OS サンドボックスではなく、ローカルユーザーアカウントで利用可能なものすべてにアクセスできるため、trusted、特に full は意図的な場合にのみ有効にしてください。

コアツール（常に利用可能）

ツール	説明
open_workspace	プロジェクトを開きます。mode="checkout" または mode="worktree" を指定できます。
read	startLine、endLine、offset、limit を指定できる、強化されたファイルリーダーです。
write	ファイルを作成または上書きします。
edit	対象を絞った文字列置換を行います。
bash	型付きツールがないシェル操作のフォールバックです。パッケージスクリプトには run_package_script を、Git 操作には Git ツールを優先してください。
visual_review	ローカルのウェブアプリを、レスポンシブなデスクトップ／ラップトップ／タブレット／モバイルのビューポートでキャプチャし、PNG スクリーンショットをモデルに直接返します。カスタムビューポートに対応しています。ローカル URL のみ使用できます。

アシスタントツール（モード：assistant）

ツール	説明
workspace_summary	ワークスペースの簡潔なアーキテクチャ概要です。
project_bootstrap	パッケージマネージャー、モノレポの範囲、基本的な依存関係をスキャンします。
read_many	範囲を指定した複合的な調査を行います。正確な読み取り／範囲指定、対象を絞った一致箇所とコンテキストの取得（任意のファイル include glob を指定可能）、対象を絞った glob 検索を、共有のシリアライズ済み証拠／行数／ファイル数の予算とペイロードコストのレポートを用いて、1 回の順序付き呼び出しで実行します。
tree	ディレクトリツリーを表示します。
next_route_map / payload_schema_map	Next.js / Payload CMS のスキーマを抽出します。
file_dependencies	内向きおよび外向きの依存関係マップです。
checkpoint_*	スナップショットの保存、復元、一覧表示、削除を行います。
edit_dry_run	書き込みを行わずに編集内容をプレビューします。
worktree_*	分離された Git ワークツリーを管理します（作成、一覧表示、同期、破棄）。
worktree_install_deps	管理対象のワークツリーに依存関係をインストールします。ネイティブバインディングを読み込むには verify: true を指定してください。
agentic_doctor	Node、パッケージマネージャー、Git、ネイティブ SQLite の利用可否を診断します。
semantic_pack	トークン予算内で、目標に関連する簡潔な要約を作成します。
context_budget	ファイルのトークン数を推定します。
expand_compressed_block	read_compressed で省略されたブロックを展開します。
token_audit	読み取ったファイル全体のトークン使用量を分析します。
tournament_*	変更の自律的な評価と判定を行います。
risk_assess_command	bash の実行前にポリシー評価をプレビューします。
changed_files_summary	Git の状態と差分を素早く抽象化して表示します。
task_context	対象を絞ったパスから RiskProfile（リスクレベル、スコア、影響範囲）を算出します。
suggest_checks	決定的な VerificationPlan を返す、参考用のプランナーです。

検証とリスク（1.5.0 で拡張）

リスクと検証のパイプラインにより、厳密で決定論的な計画を実施します。

• task_context は、機密性の高い設定、ファンアウト、テストとの近接性、分析の信頼度を考慮した RiskProfile を生成するようになりました。
• suggest_checks は VerificationPlan を返しますが、あくまで助言のみです（コマンドは実行されません）。変更を加えるチェックと存在しないスクリプトは除外されます。信頼度が低い場合は、固有の riskLevel を変更せずに policyLevel を引き上げることがあります。ローカルの Git メタデータを利用できない場合、プランナーは祖先リポジトリを引き継ぐのではなく、記述された目標と対象を絞ったパスから goal_discovery を使用します。

サポートされている入力：

{
  workspaceId: string;
  changedPaths?: string[]; // Actual paths changed
  goal?: string;           // Optional goal for discovery
  taskType?: "auto" | "bug_fix" | "feature" | "refactor" | "security_review" | "migration" | "frontend" | "release";
  focusPaths?: string[];   // Specific files to focus on

  // Legacy compatibility transition (deprecated)
  paths?: string[];
  scope?: "changed" | "workspace";
  level?: "minimal" | "recommended" | "full";
}

非推奨の互換性エイリアスはデフォルトで非表示になっており、モデルの標準ワークフローには一切表示されません。既存のクライアントは AGENTIC_LEGACY_ALIASES=1 で一時的に有効化できますが、次のメジャーリリースで削除されます。新しいクライアントでは、上記の正式名称 edit_dry_run、next_route_map、payload_schema_map、changed_files_summary、project_bootstrap を使用してください。

🧠 エージェントのメンタルモデル

このサーバーは、リモート AGI の「手と目」として動作するように設計されています。 自律型エージェントを構築する場合や、コーディングに Claude/ChatGPT を使用する場合は、エージェントに次のように指示してください。

1. 段階的に対象を絞ってください。 関連ファイルが不明な場合は task_context を使用し、対象がすでに明確な場合は、広範な探索を省略してください。
2. read_many を使って、関連する正確な読み取り、マッチ箇所と前後のコンテキストの確認、範囲を限定した glob を1回のラウンドトリップでまとめて実行してください。項目の順序は予算の優先順位となるため、最重要項目を先頭に置いてください。
3. ドメイン全体の構造やファイル間の関係が本当に不明な場合に限り semantic_pack を使用してください。実装対象が十分に明確になったら、広範な探索を止めてください。
4. ファイル全体の概要を把握するために、サイズの大きなファイルには read_compressed を使用してください。編集する前に、省略されたブロックを展開してください。
5. タスクに複雑なシェルコマンドの実行や破壊的なテストが含まれる場合は mode="worktree" を使用し、曖昧またはリスクの高い置換の前には edit_dry_run を使用してください。

分離境界

管理対象のワークツリーは分離された Git チェックアウトであり、オペレーティングシステムのサンドボックスではありません。実験をプライマリチェックアウトから隔離しますが、ネットワークアクセス、サブプロセス、認証情報、CPU／メモリの使用、またはサーバーで許可されているその他のパスを制限するものではありません。スクリプトは実際のローカルコマンドとして扱い、まず型付けされた Git／スクリプト用ツールを使用してください。Git ツールは、開かれたワークスペース自体がリポジトリのルートである場合にのみ動作します。祖先リポジトリは、兄弟プロジェクトを公開しないよう拒否されます。

📝 ライセンスと謝辞

MIT License の下でライセンスされています。詳しくは LICENSE をご覧ください。

このプロジェクトでは、社内のセキュリティアーキテクチャから強く着想を得たコンポーネントを使用しています。オープンソースコミュニティの標準的なベストプラクティスに感謝します。

皆さまからの貢献を歓迎します。始め方については CONTRIBUTING.md をご覧ください。