Agent MCP

エージェントMCP

調整された効率的な AI コラボレーションを実現する MCP (モデル コンテキスト プロトコル) を使用してマルチエージェント システムを作成するためのフレームワーク。

クイックスタートガイド

注: 上記のスクリーンショットのように、同じコードベースで異なるカーソル ウィンドウを起動するには、 https://github.com/rinadelph/MultipleCursorを使用することをお勧めします。

1. セットアップ環境:
   • リポジトリをクローンし、 .env.exampleを.envにコピーします。
   • OpenAI APIキーを.envに追加する
   • uv venv && uv pip install -e .
2. MCP サーバーを起動します:
   uv run -m mcp_template.main --port 8080 --project-dir /path/to/your/project
   重要：管理者トークンは、プロジェクトコンテキストの.agent/mcp_state.db SQLite データベースに保存されます。アクセスするには、SQLite ビューア拡張機能をインストールしてください。
3. メインコンテキストドキュメント（MCD）の作成:
   • システム アーキテクチャ、API ルート、データ モデルなどを含む詳細なMCD.mdを作成します。
4. 管理エージェントを起動します:
   • 1つのウィンドウ/セッションで開始
   • 管理者トークンを付与する
5. ワーカーエージェントの初期化:
   • 各ワーカーごとに新しいウィンドウ/セッションを開く
   • 以下のセクション4から自動モードで作業者プロンプトをコピーします
   • 正しいエージェントIDと管理者トークンに置き換えます

詳細については、以下の詳細な手順に従ってください。

特徴

• マルチエージェントコラボレーションフレームワーク
• タスク管理と調整
• エージェント間のコンテキストと知識の共有
• エージェントインタラクションのグラフ可視化
• 埋め込みとRAG機能のサポート
• タスク、エージェント、コンテキストを視覚化するためのインタラクティブなダッシュボード。

メインコンテキストドキュメント（MCD）を使用したプロジェクト計画

開発を始める前に、徹底的な調査を行い、アプリケーションの唯一の情報源となる**メインコンテキストドキュメント（MCD）**を作成することが不可欠です。このドキュメントでは、以下の点を詳細に説明した詳細な計画が提供されます。

• システムアーキテクチャとコンポーネントの関係
• すべての画面とコンポーネントのUI/UXデザイン
• APIルートとエンドポイント
• データ構造とモデル
• 実施単位とタスク
• 依存関係とテクノロジースタック

MCD が重要な理由は次のとおりです。

1. これにより、エージェントは個々のコンポーネントに取り組む前にシステム全体を理解できるようになります。
2. 直線的で調和のとれた建築を可能にする（設計図から家を建てるようなもの）
3. 構造化された関連性の高いコンテキストを提供することでトークンの使用を削減します
4. エージェント間の実装の競合を防ぐ

このリポジトリの**MCD.mdファイルを確認し、**必要な構造と詳細レベルを理解してください。MCDには以下の情報を含める必要があります。

• 概要と目標
• コンテキストとアーキテクチャの図
• 機能要件
• 設計仕様（UI/UX、API、データモデル）
• 実装の詳細
• エージェントのタスクの内訳

包括的な MCD を使用すると、エージェントは各部分が全体の中でどのように適合するかを明確に理解しながら、アプリケーションを部分ごとに実装できます。

インストール

前提条件

• Python 3.8以上
• uv (パッケージのインストールを高速化するために推奨)

設定

1. リポジトリをクローンします。
   git clone https://github.com/your-username/agent-mcp.git cd agent-mcp
2. サンプル ファイルをコピーして環境変数を設定します。
   cp .env.example .env
3. .envファイルを編集し、OpenAI API キーを追加します。
   OPENAI_API_KEY=your_openai_api_key_here
4. uv を使用してインストールします。
   uv venv uv pip install -e .
   または pip を使用する場合:
   pip install -e .

マルチエージェントワークフロー

ワークフローの概要

1. 徹底的な調査から始める: コーディングの前に、AIを活用して包括的なメインコンテキストドキュメント (MCD) を作成します。
2. インフラストラクチャを起動する: MCP サーバーを起動し、データベースで管理者トークンを見つけます。
3. 管理エージェントのセットアップ: トークンとINSTRUCTIONS.mdを使用して管理エージェントを初期化します。
4. ワーカーの作成: 管理者はプロジェクトのさまざまな側面に特化したワーカーを作成します
5. タスクの割り当て: 管理者はMCDを個別のタスクに分割し、作業者に割り当てます。
6. 並行開発: 作業者はMCPを通じてコンテキストを共有しながらタスクを実行します。
7. コンテキスト保存: すべてのエージェントは知識を中央データベースに保存します

開発ループ

アーキテクチャの概要

MCP システムは次の階層構造を使用します。

• 管理エージェント: 他のエージェントを調整し、タスクを割り当て、プロジェクト全体の方向性を維持します
• ワーカー エージェント: 特定のタスク (フロントエンド、バックエンド、データ モデリングなど) を実行する専門エージェント

エージェントのセットアップと操作

1. MCPサーバーの起動

オプション:

• --port : サーバーを実行するポート (デフォルト: 8080)
• --project-dir : プロジェクトのベースディレクトリ

2. 管理者トークンにアクセスする

管理者トークンは MCP サーバーへの特権アクセスを提供するもので、すべてのエージェント操作に必要です。

管理者トークンの検索:

1. サーバーを起動すると、トークンが自動的に生成されます
2. このトークンは.agent/mcp_state.db SQLiteデータベースに保存されます。
3. VS Codeまたは他のSQLiteツール用のSQLiteビューア拡張機能をインストールする
4. データベースを開き、 project_contextテーブルを確認します。
5. 管理者トークンのエントリを探す

エージェントトークン：エージェント固有のトークンも.agentフォルダに保存されます。これらのトークンは、MCPシステム内で各エージェントに固有の権限とIDを付与します。

3. エージェントの起動

1. まずMCPサーバーを起動します。
   uv run -m mcp_template.main --port 8080 --project-dir /path/to/your/project
   サーバーは起動時に管理者トークンを生成します。このトークンはエージェントの認証に必要となるため保存してください。
2. 管理エージェント: 以下を使用して単一の管理エージェントを起動します。
   uv run -m mcp_template.mcp_client_runner --admin
   ModuleNotFoundError: No module named 'mcp_client'のようなインポート エラーが発生した場合は、プロジェクト ルートから実行していること、および Python パッケージが適切にインストールされていることを確認してください。
3. ワーカーエージェント：ワーカーエージェントを直接起動するのではなく、管理エージェントにワーカーエージェントの作成と管理を指示します。これは、管理エージェントに以下の指示を与えることで実行されます。
   "Create a new agent with ID 'frontend-worker' and assign it to implement the login page based on the MCD."
   管理エージェントは、タスクの作成とワーカーエージェントへの割り当てを処理します。

4. ワーカーエージェントでAUTOモードを使用する

ワーカーエージェントを初期化するには、管理エージェントを使用することをお勧めします。エージェントが作成されたら、以下のワーカー初期化プロンプトをそのまま使用してください（これをコピーしてワーカーエージェントに貼り付けてください）。

[agent_id]を実際のワーカー ID (例: "frontend-worker") に置き換え、 your_admin_token_hereを MCP サーバーの起動時に生成されたトークンに置き換えます。

これはエージェントに次の命令を出します:

• ユーザーの介入なしに自律的に動作する
• タスクステータスの追跡で作業者のプロトコルに従う
• やりとり全体にわたって文脈を保持するために記憶を活用する
• タスクのコンテキストを理解するために、RAG システムに積極的にクエリを実行します。

最良の結果を得るには、エージェントを初期化するときに、INSTRUCTIONS.md からの指示を AUTO コマンドの前にコピーして貼り付けます。

ダッシュボード

http://localhost:8080でダッシュボードにアクセスして、次の操作を行います。

• エージェントの活動をリアルタイムで監視
• タスクのステータスと依存関係を表示する
• エージェントの関係と調整を観察する
• ファイル操作とコンテキスト共有を追跡する

代替開発：複数エージェントセッション

複雑なプロジェクトに推奨されるアプローチは次のとおりです。

1. 管理エージェントに1つの会話を使用する
2. 各ワーカーエージェントごとに個別の会話/セッションを開始する
3. すべてのエージェントで同じ管理トークンを共有する
4. 複数のウィンドウ/セッションでClaude Code、RooCode、またはCursorを使用する

このアプローチにより、共有 MCP システムを通じて共同作業を行う際に、各エージェントに独自の会話コンテキストが与えられます。

ワークフローの例:

1. MCPサーバーを起動し、管理者トークンをメモします。
2. 1つのウィンドウで管理エージェントを作成する
3. 各ワーカーエージェントごとに新しいウィンドウを開き、上記のワーカープロンプトで初期化します。
4. 各ワーカーに独自のエージェントIDを付与するが、管理トークンは同じにする

トークンシステムとリソース管理

トークンを理解する

トークンは、MCP システムにおいて複数の目的に使用されます。

1. 認証トークン: エージェントの識別と管理者アクセスに使用されます
2. RAGトークン: 知識ベースにコンテキストを埋め込んだり取得したりするために使用されます
3. OpenAIトークン:エージェント操作(モデル使用)中に消費される

トークン管理

トークンの使用状況を監視および管理するには:

1. SQLite Viewer プラグインをインストールするか、コマンド ラインを使用します。
   sqlite3 /path/to/project/.agent/mcp_state.db
2. クエリトークンの使用法:
   SELECT * FROM token_usage;
3. ダッシュボードの「リソース」タブで監視する

リソースの最適化

大規模プロジェクトの場合:

1. コンテキストサイズを削減するために、特化した機能を持つ専門エージェントを使用する
2. 明確な依存関係を持つ小さな単位にタスクを分割する
3. RAGシステムを活用して効率的なコンテキスト検索を行う
4. 共有情報はメッセージ内で繰り返すのではなく、プロジェクトのコンテキストに保存します。

プロジェクトRAGとナレッジベース

プロジェクトRAGの設定

検索拡張生成 (RAG) システムにより、エージェントは関連するプロジェクト知識に効率的にアクセスできます。

1. インデックス プロジェクト ファイル:
   python -m mcp_template.rag_indexer --project-dir /path/to/project
2. ナレッジ ベースにドキュメントを追加します。
   python -m mcp_template.rag_indexer --add-doc /path/to/document.md

エージェントワークフローでの RAG の使用

エージェントは以下を使用してナレッジ ベースを照会できます。

これにより、ファイル全体をロードせずに関連コンテキストが返され、トークンが保存され、応答の品質が向上します。

エージェントのタスク割り当て戦略

最適なパフォーマンスを得るには、次のガイドラインに従ってください。

1. タスクの粒度: 大きなタスクを明確な入力/出力を持つ原子単位に分割します
2. 依存関係の追跡: 割り当て時にタスクの依存関係を明示的に定義します
3. 能力マッチング: 関連する能力を持つエージェントにタスクを割り当てます
4. 進捗状況の監視: 明示的なステータス更新を使用してタスクの進捗状況を追跡します
5. コンテキストの共有: 割り当て時に必要なコンテキストを提供することで、後の検索を減らすことができます。

管理者から作業者へのタスク割り当ての例:

新しいワーカーエージェントを作成する場合:

1. 管理エージェントに次のように伝えます。「ID が 'frontend-worker' の新しいエージェントを作成し、MCD に基づいてログイン ページを実装するように割り当てます。」
2. 新しいウィンドウ/セッションを開き、前述のAUTOプロンプトでワーカーエージェントを初期化します。
3. 作業者が割り当てられたタスクにアクセスできるように、管理者トークンを必ず含めてください。

コンポーネント

• main.py : MCPサーバーの実装
• mcp_client.py : エージェントを MCP に接続するためのクライアント ライブラリ
• dashboard_api.py : 可視化のためのAPIエンドポイント
• rag_agent_test.py : RAG対応エージェントの例
• INSTRUCTIONS.md : エージェント向け運用ガイドライン

環境変数

• OPENAI_API_KEY : OpenAI API キー
• MCP_SERVER_URL : MCPサーバーのURL
• MCP_ADMIN_TOKEN : (オプション) 直接アクセス用の管理者トークン
• MCP_PROJECT_DIR : プロジェクトディレクトリへのパス

ライセンス

MITライセンス

コミュニティ

Discordコミュニティに参加して、Agent MCPについて議論したり、プロジェクトを共有したり、サポートを受けたり、AIツールを使って開発している他の開発者と交流したりしましょう。私たちは、マルチエージェントシステムとAIコラボレーションの可能性の限界を押し広げることに注力する、成長を続けるコミュニティです。