純代理アーキテクチャMCPサーバー：機能ツール化、Claude双モードアクセス対応

MCP Server Full

純粋なプロキシアーキテクチャに基づくModel Context Protocol (MCP)サーバーの実装です。すべての機能を専用プロキシを通じてMCPツールの形式で公開し、ClaudeのデスクトップとWebインターフェイスの両方のアクセスモードをサポートします。

人工知能チャットボット開発者ツール #プロキシアーキテクチャ #動的ツール #デュアルモードアクセス #モジュール化 .Python

スコア : 2ポイント

ダウンロード数 : 6.7K

更新時間 : 2025-07-24

インストール

以下のコマンドをクライアントにコピーして設定

{
  "mcpServers": {
    "agentic-mcp": {
      "command": "python",
      "args": ["run_mcp_server.py"],
      "cwd": "d:\\AI Lab\\MCP research\\mcp_server_full"
    }
  }
}

# Check claude_desktop_config.json
   {
     "mcpServers": {
       "agentic-mcp": {
         "command": "python",
         "args": ["run_mcp_server.py"],
         "cwd": "d:\\AI Lab\\MCP research\\mcp_server_full"
       }
     }
   }

注意：あなたのキーは機密情報です。誰とも共有しないでください。

🚀 純粋エージェント型MCPサーバー

このサーバーは、モデルコンテキストプロトコル（MCP）を純粋に実装したもので、エージェント型アーキテクチャに基づいており、すべての機能が専用のエージェントを通じてMCPツールとして公開されます。

✨ 主な機能

🤖 純粋エージェント型アーキテクチャ：すべての機能（OpenAI、Ollama、ファイル操作）がエージェントとして実装されています。
🔗 二重アクセスモード：Claude Desktop用のMCPプロトコルと、Web/Streamlit UI用のHTTPエンドポイントを提供します。
⚡ 動的ツール登録：エージェントは起動時に自動的にツールを登録します。
🔧 モジュール型設計：コアサーバーコードを変更することなく、新しいエージェントを簡単に追加できます。
📱 クリーンなWeb UI：インタラクティブなツール使用のための、モダンなStreamlitインターフェースを備えています。
🛡️ 緩やかな劣化：エージェントは独立して障害を起こし、システム全体に影響を与えません。
🔑 環境変数による設定：環境変数を使用した安全なAPIキー管理をサポートしています。

📦 インストール

前提条件

Python 3.11以上
仮想環境のサポート

インストール手順

git clone <repo-url>
cd mcp_server_full

# 仮想環境の作成とアクティブ化
python -m venv .venv
# Windows
.venv\Scripts\activate
# Linux/Mac
source .venv/bin/activate

# 依存関係のインストール
pip install --upgrade pip
pip install -r requirements.txt

設定

APIキーを含む.envファイルを作成します（すべてオプション）。

# OpenAIエージェント（オプション）
OPENAI_API_KEY=your_openai_api_key_here

# Ollamaエージェント（オプション、ローカルOllamaサーバーを使用）
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=llama3.2

# ファイルエージェント（デフォルトで有効、設定不要）
# ファイルの読み取り、書き込み、リスト表示機能を提供します。

サーバーの起動

Claude Desktop用（MCPプロトコル）

# Claude Desktop用の純粋MCPサーバーを起動
python run_mcp_server.py

Claude Desktopの設定ファイル（claude_desktop_config.json）に以下を追加します。

{
  "mcpServers": {
    "agentic-mcp": {
      "command": "python",
      "args": ["run_mcp_server.py"],
      "cwd": "d:\\AI Lab\\MCP research\\mcp_server_full"
    }
  }
}

Webインターフェース用（HTTP + Streamlit）

# ターミナル1：ツール用のHTTPホストを起動
python simple_mcp_host.py

# ターミナル2：Streamlit UIを起動
streamlit run streamlit_app.py

Webインターフェースには、http://localhost:8501 からアクセスできます。

セットアップのテスト

# エージェントの登録とツールの可用性をテスト
python test_quick.py

# 特定のエージェントをテスト
python test_both.py

# サーバーの機能を検証
python validate_server.py

💻 使用例

利用可能なエージェントとツール

🤖 OpenAIエージェント

状態：APIキーがあれば利用可能
ツール：

openai_chat：GPTモデルを使用したチャット補完
openai_analysis：テキスト分析と洞察提供

セットアップ：.envファイルにOPENAI_API_KEYを追加します。

🦙 Ollamaエージェント

状態：ローカルOllamaサーバーがあれば利用可能
ツール：

ollama_chat：ローカルOllamaモデルとのチャット
ollama_generate：テキスト生成

セットアップ：Ollamaをローカルにインストールして実行し、OLLAMA_BASE_URLとOLLAMA_MODELを設定します。

📁 ファイルエージェント

状態：常に利用可能
ツール：

file_read：ファイル内容の読み取り
file_write：ファイルへの内容書き込み
file_list：ディレクトリ内容のリスト表示

セットアップ：設定不要

APIの使用方法

MCPプロトコル（Claude Desktop）

サーバーを設定すると、Claude Desktopで自動的にツールが利用可能になります。Claudeに以下のように依頼できます。

"file.txtの内容を読み取る"
"Ollamaを使用してテキストを生成する"
"OpenAIでこのテキストを分析する"

HTTP API（Web/Streamlit）

# 利用可能なツールをリスト表示
curl http://localhost:8000/tools

# 特定のツールを呼び出す
curl -X POST http://localhost:8000/tools/call \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "file_read",
    "arguments": {
      "file_path": "example.txt"
    }
  }'

📚 ドキュメント

アーキテクチャの概要

サーバーは純粋エージェント型パターンを実装しており、以下のように構成されています。

エージェント：特定の機能（OpenAI API、Ollama、ファイル操作）をカプセル化します。
レジストリ：動的なツール登録とルーティングを管理します。
MCPサーバー：Claude Desktop用のJSON-RPCプロトコルを提供します。
HTTPホスト：REST APIを介してツールをWebインターフェースに公開します。
Streamlit UI：すべてのツールに対するユーザーフレンドリーなWebアクセスを提供します。

Claude Desktop ←→ MCP Protocol ←→ Pure MCP Server ←→ Agent Registry ←→ Agents
                                                                      ↕
Web Browser    ←→ HTTP API     ←→ Simple MCP Host  ←→ Agent Registry ←→ Agents

コアコンポーネント

pure_mcp_server.py：Claude Desktopとの統合に使用する主なMCP JSON-RPCサーバー
simple_mcp_host.py：REST APIを介してMCPツールを公開するHTTPラッパー
registry.py：動的なエージェントとツールの登録システム
run_mcp_server.py：Claude Desktopの設定用エントリーポイントスクリプト
config.py：環境変数に基づく設定管理
protocol.py：MCPプロトコルのモデルと型

エージェント

agents/base.py：すべてのエージェントが実装する基本エージェントインターフェース
agents/openai_agent.py：OpenAI APIとの統合エージェント
agents/ollama_agent.py：ローカルOllamaモデルとの統合エージェント
agents/file_agent.py：ファイルシステム操作エージェント

ユーザーインターフェース

streamlit_app.py：インタラクティブなツール使用のためのモダンなWeb UI
Claude Desktop：直接的なMCPプロトコル統合

エージェント登録フロー

# 各エージェントは動的にツールを登録します
class YourAgent(BaseAgent):
    def get_tools(self) -> Dict[str, Any]:
        return {
            "your_tool": {
                "description": "What your tool does",
                "inputSchema": {...}
            }
        }
    
    async def handle_tool_call(self, tool_name: str, params: Dict[str, Any]) -> Any:
        # ツール呼び出しを処理します
        pass

# レジストリは自動的にツールを検出してルーティングします
registry.register_agent("your_agent", YourAgent(config))

開発

プロジェクト構造

mcp_server_full/
├── agents/                    # エージェントの実装
│   ├── base.py               # 基本エージェントインターフェース
│   ├── openai_agent.py       # OpenAIとの統合
│   ├── ollama_agent.py       # Ollamaとの統合
│   └── file_agent.py         # ファイル操作
├── pure_mcp_server.py        # Claude Desktop用の主なMCPサーバー
├── simple_mcp_host.py        # Webインターフェース用のHTTPホスト
├── registry.py               # 動的なツール登録
├── run_mcp_server.py         # Claude Desktopのエントリーポイント
├── streamlit_app.py          # Web UI
├── config.py                 # 設定管理
├── protocol.py               # MCPプロトコルのモデル
├── requirements.txt          # 依存関係
├── .env                      # 環境変数（これを作成）
├── ADDING_NEW_AGENTS.md      # 詳細なエージェント開発ガイド
└── README.md                 # このファイル

新しいエージェントの追加

新しいエージェントを追加するための完全な手順については、ADDING_NEW_AGENTS.md を参照してください。

簡単な概要：

agents/ディレクトリにBaseAgentを継承したエージェントファイルを作成します。
get_tools()とhandle_tool_call()メソッドを実装します。
pure_mcp_server.pyとsimple_mcp_host.pyの両方でエージェントを登録します。
設定を追加し、エージェントをテストします。

このガイドには、完全なコード例、ベストプラクティス、トラブルシューティングのヒントが含まれています。

既存のエージェントに新しいツールを追加する

既存のエージェントに新しいツールを追加するには、以下の手順を実行します。

エージェントのget_tools()メソッドを編集して、新しいツールのスキーマを定義します。
エージェントのhandle_tool_call()メソッドにハンドラーメソッドを追加します。
新しいツールの機能をテストします。
ドキュメントを更新します。

例：

# エージェント内で
def get_tools(self):
    return {
        "new_tool": {
            "description": "Description of new tool",
            "inputSchema": {
                "type": "object", 
                "properties": {
                    "param": {"type": "string", "description": "Parameter description"}
                },
                "required": ["param"]
            }
        }
    }

async def handle_tool_call(self, tool_name: str, params: Dict[str, Any]) -> Any:
    if tool_name == "new_tool":
        return await self._handle_new_tool(params)

トラブルシューティング

一般的な問題

エージェントが利用できない：APIキーとサービスの接続性を確認します。
```
# エージェントの登録をテスト
python test_quick.py
```

Claude Desktopが接続できない：設定ファイルのパスとエントリーポイントを確認します。

# claude_desktop_config.jsonを確認
{
  "mcpServers": {
    "agentic-mcp": {
      "command": "python",
      "args": ["run_mcp_server.py"],
      "cwd": "d:\\AI Lab\\MCP research\\mcp_server_full"
    }
  }
}

Streamlit UIに問題がある：HTTPホストが実行されていることを確認します。

# まずHTTPホストを起動
python simple_mcp_host.py
# 次にStreamlitを起動
streamlit run streamlit_app.py

OpenAIエラー：APIキーとクォータを確認します。
```
# 直接OpenAIをテスト
python openai_test.py
```
Ollamaが機能しない：Ollamaサーバーが実行されていることを確認します。
```
# Ollamaの状態を確認
curl http://localhost:11434/api/tags
```

デバッグモード

詳細なログを有効にするには、以下のコマンドを実行します。

# 環境変数を設定
export LOG_LEVEL=DEBUG
python run_mcp_server.py

ヘルスチェック

# HTTP APIのヘルスを確認
curl http://localhost:8000/health

# 登録されたツールをリスト表示
curl http://localhost:8000/tools

# ツール呼び出しをテスト
curl -X POST http://localhost:8000/tools/call \
  -H "Content-Type: application/json" \
  -d '{"tool_name": "file_list", "arguments": {"directory_path": "."}}'