🚀 Light MCP Agents

🚀 Light MCP Agents

Light MCP Agents とは？

Light MCP Agents は、Model Context Protocol (MCP) を使用して AI エージェントを構築およびオーケストレーションするための軽量フレームワークです。特殊化されたエージェントがタスクを委任し、機能を共有し、複雑な問題を解決するために協力できるという階層的なエージェントシステムの作成を可能にします。 設定駆動型のアプローチにより、拡張可能なアーキテクチャで、広範なコーディングなしに高度なエージェントネットワークを迅速に構築できます。

なぜ重要なのか？

✅ シンプルな設定ファイルで、任意の MCP サーバーに接続するエージェントを作成します。

✅ 追加コードなしで複数エージェントワークフローを作成します。エージェントごとに設定ファイル 1 つだけです。

✅ エージェント設定を他のユーザーと簡単に共有して実行します。

アーキテクチャの概要

目次

• クイックスタート
  • インストール
  • 最初のエージェントを実行する
  • 複数エージェント例を試す
  • Claude Desktop でエージェントを実行する
• サンプルエージェント
• 実行オプション
  • 基本的なコマンド構造
  • その他のオプション
• 独自のエージェントを作成する
  • 基本的なエージェント設定
  • 機能を持つエージェント
  • オーケストレーターエージェント設定
• 動作方法
  • エージェント機能
  • 例：リサーチワークフロー
• アーキテクチャの詳細
  • 主要コンポーネント
  • アーキテクチャの利点

クイックスタート

インストール

# Clone the repository
git clone https://github.com/nicozumarraga/light-mcp-agents.git
cd light-mcp-agents

# Create a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

最初のエージェントを実行する

# Run the base agent example (simple client agent)
python src/agent/agent_runner.py --config examples/base_agent/base_agent_config.json

成功すれば、エージェントとチャットしてそのツールを使用できます！

複数エージェント例を試す

1 つ目のターミナルで、リサーチエージェントをサーバーモードで開始します：

python src/agent/agent_runner.py --config examples/orchestrator_researcher/research_agent_config.json --server-mode

2 つ目のターミナルで、リサーチエージェントに接続するオーケストレーターを開始します：

python src/agent/agent_runner.py --config examples/orchestrator_researcher/master_orchestrator_config.json

これでオーケストレーターにトピックのリサーチを依頼でき、特殊化されたリサーチエージェントに委任するか、直接ツールを使用します。

Claude Desktop でエージェントを実行する

Claude Desktop は設定システムを通じて MCP エージェントをサポートしています。Claude でエージェント設定を直接構成して実行でき、カスタム機能を使用できるようになります。

セットアップ手順

1. Claude Desktop の設定ファイルを探します：

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json

2. mcpServers セクションにエージェント設定を追加します：

{
  "mcpServers": {
    "research-agent": {
      "command": "/bin/bash",
      "args": ["-c", "/path/to/your/venv/bin/python /path/to/your/agent_runner.py --config=/path/to/your/agent_config.json --server-mode"],
      "env": {
        "PYTHONPATH": "/path/to/your/project",
        "PATH": "/path/to/your/venv/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
      }
    }
  }
}

サンプルエージェント

リポジトリの examples/ ディレクトリには、サンプルエージェントが含まれています：

1. Base Agent (examples/base_agent/)

   • 外部ツールサーバーに接続する単純なエージェント
   • エージェントの動作を理解するのに適した最初の例です

2. Orchestrator-Researcher (examples/orchestrator_researcher/)

   • 階層的なエージェント構造を実証します
   • エージェント間で機能を共有する方法を示します

🤝 コミュニティのための独自のサンプルアーキテクチャを送信したいですか？ ご連絡ください！

実行オプション

基本的なコマンド構造

python src/agent/agent_runner.py --config <config_file_path>

その他のオプション

# Run in server mode (makes it available to other agents)
python src/agent/agent_runner.py --config <config_file_path> --server-mode

# Run with a custom server name
python src/agent/agent_runner.py --config <config_file_path> --server-mode --server-name "my-custom-server"

独自のエージェントを作成する

基本的なエージェント設定

エージェント用の設定ファイルを作成します（例：my_agent_config.json）：

{
  "agent_name": "my-agent",
  "llm_provider": "groq",
  "llm_api_key": "YOUR_API_KEY_HERE",
  "server_mode": false,
  "servers": {
    "tool-server": {
      "command": "npx",
      "args": ["@anthropic-ai/mcp-tooling", "start", "-q"],
      "env": {
        "PORT": "3001"
      }
    }
  }
}

機能を持つエージェント

特殊な機能を持つエージェントを作成するには：

{
  "agent_name": "research-agent",
  "llm_provider": "groq",
  "llm_api_key": "YOUR_API_KEY_HERE",
  "server_mode": true,
  "server_name": "research-agent-server",
  "capabilities": [
    {
      "name": "summarize_document",
      "description": "Summarize a document in a concise way",
      "input_schema": {
        "type": "object",
        "properties": {
          "document_text": {
            "type": "string",
            "description": "The text of the document to summarize"
          },
          "max_length": {
            "type": "integer",
            "description": "Maximum length of the summary in words",
            "default": 200
          }
        },
        "required": ["document_text"]
      },
      "prompt_template": "Summarize the following document in {max_length} words or fewer:\n\n{document_text}"
    }
  ],
  "servers": {
    "brave-search": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "BRAVE_API_KEY", "mcp/brave-search"],
      "env": {
        "BRAVE_API_KEY": "YOUR_BRAVE_API_KEY"
      }
    }
  }
}

オーケストレーターエージェント設定

他のエージェントに委任するオーケストレーターを作成します：

{
  "agent_name": "master-orchestrator",
  "llm_provider": "groq",
  "llm_api_key": "YOUR_API_KEY_HERE",
  "server_mode": false,
  "servers": {
    "research-agent": {
      "command": "python",
      "args": ["src/agent/agent_runner.py", "--config=research_agent_config.json", "--server-mode"],
      "env": {}
    },
    "kanye": {
      "command": "npx",
      "args": ["-y", "kanye-mcp"]
    }
  }
}

動作方法

エージェント機能

機能は LLM の推論が必要な高レベルの関数です。機能が呼び出されるとき：

1. プロンプトテンプレートが提供された引数で埋められます
2. エージェントは独自の推論プロセスを開始します
3. 利用可能なツールを使用できます
4. 最終結果を呼び出し元のエージェントに返します

例：リサーチャーワークフロー

オーケストレーターにトピックのリサーチを依頼するとき：

1. オーケストレーターがリサーチエージェントの機能に委譲します
2. リサーチエージェントが検索ツールを使用して情報を収集します
3. リサーチエージェントが結果を一貫性のある応答に処理します
4. 最終結果がオーケストレーターに送り返され、あなたに提示されます

これが実際に動作していることを示すログの抜粋です：

2025-03-19 10:17:46,252 - INFO - agent:master-orchestrator - Executing tool: research_topic
2025-03-19 10:17:46,252 - INFO - agent:master-orchestrator - With arguments: {'topic': 'quantum computing', 'focus_areas': 'recent breakthroughs'}
2025-03-19 10:17:46,261 - INFO - mcp-server-wrapper:research-agent-server - Executing as capability: research_topic
2025-03-19 10:17:46,262 - INFO - agent:research-agent - Executing capability: research_topic with arguments: {'topic': 'quantum computing', 'focus_areas': 'recent breakthroughs'}
2025-03-19 10:17:46,973 - INFO - agent:research-agent - Executing tool: brave_web_search
2025-03-19 10:17:46,973 - INFO - agent:research-agent - With arguments: {'query': 'quantum computing recent breakthroughs', 'count': 10}
2025-03-19 10:17:49,839 - INFO - agent:research-agent - Capability research_topic execution completed

アーキテクチャの詳細

再帰的なアーキテクチャは MCP（Model Context Protocol）標準に基づいており、以下を実現します：

1. エージェント階層: エージェントを階層構造に配置でき、上位レベルのエージェントがタスクを特化した下位レベルのエージェントに委譲できます。
2. 機能委譲: 推論が必要な複雑なタスクは、機能を通じて特化したエージェントに委譲できます。
3. ツール集約: 下位レベルのエージェントのツールは自動的に上位レベルのエージェントに公開されます。
4. 再帰的推論: 各エージェントは利用可能なツールを使用して独自の推論プロセスを実行できます。この再帰に制限を設定できます。

主要なコンポーネント

1. AgentServer: エージェントをクライアントとサーバーの両方のモードで管理する主要なクラスで、初期化、他のサーバーへの接続、ツール/機能の検出を処理します。
2. MCPServerWrapper: エージェントを MCP サーバーとしてラップして、MCP プロトコルを通じてそのツールと機能を公開します。
3. Agent: ユーザーリクエストを処理し、ツールを実行し、機能を管理するコアエージェント実装です。
4. CapabilityRegistry: LLM 推論が必要なエージェント機能のレジストリで、設定から機能を読み込む責任があります。
5. ToolRegistry: MCP サーバーのすべてのツールのレジストリで、検出と登録を処理します。

アーキテクチャの利点

1. 階層的なコンポジション: エージェントが他のエージェントの機能を使用でき、強力なコンポジションモデルを作成します。
2. カプセル化: 各エージェントが特定のドメインまたは機能をカプセル化します。
3. 推論委譲: 複雑なタスクを特化したエージェントに委譲できます。
4. ツール伝播: 下位レベルのエージェントが利用可能なツールは、上位レベルのエージェントの機能を通じて、および直接アクセスでアクセスできます。
5. 設定駆動: コードを変更せずに単純な設定ファイルで機能を定義します。
6. スケーラビリティ: 既存のものを変更せずに新しい機能または特化したエージェントを追加します。

謝辞

このプロジェクトの MCP サーバーリソース管理プラクティスは mcp-agents からインスピレーションを受けました。