MCPHub

MCPHub

MCPHub は、AI サービス向けの組み込み可能な Model Context Protocol（MCP）ソリューションです。MCP サーバーをあらゆる AI フレームワークにシームレスに統合できるため、開発者はアプリケーション内で MCP サーバーを簡単に設定、セットアップ、管理できます。OpenAI Agents、LangChain、Autogen のいずれを使用している場合でも、MCPHub を使えば、AI サービスを MCP ツールやリソースに接続するための統一された方法を利用できます。

ドキュメント

• CLI ドキュメント - MCP サーバーを管理するためのコマンドラインインターフェース
• API ドキュメント - Python API リファレンス
• 設定ガイド - サーバー設定の詳細
• サンプル - 使用例とチュートリアル

クイックスタート

前提条件

以下のツールがインストールされていることを確認してください。

# Install uv (Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install git (for repository cloning)
sudo apt-get install git  # Ubuntu/Debian
brew install git         # macOS

# Install npx (comes with Node.js)
npm install -g npx

# Install MCPHub
pip install mcphub  # Basic installation

# Optional: Install with framework-specific dependencies
pip install mcphub[openai]    # For OpenAI Agents integration
pip install mcphub[langchain] # For LangChain integration
pip install mcphub[autogen]   # For Autogen integration
pip install mcphub[all]       # Install all optional dependencies

設定

プロジェクトのルートに .mcphub.json ファイルを作成します。

{
    "mcpServers": {
        "sequential-thinking-mcp": {
            "package_name": "smithery-ai/server-sequential-thinking",
            "command": "npx",
            "args": [
                "-y",
                "@smithery/cli@latest",
                "run",
                "@smithery-ai/server-sequential-thinking"
            ]
        }
    }
}

新しい MCP サーバーの追加

新しい MCP サーバーは、次の 2 つの方法で追加できます。

1. 手動設定：サーバーの設定を .mcphub.json ファイルに直接追加します。

2. GitHub からの自動設定：add_server_from_repo メソッドを使って、GitHub リポジトリからサーバーを自動的に設定します。

from mcphub import MCPHub

# Initialize MCPHub
hub = MCPHub()

# Add a new server from GitHub
hub.servers_params.add_server_from_repo(
    server_name="my-server",
    repo_url="https://github.com/username/repo"
)

自動設定では、以下が行われます。

• GitHub リポジトリから README を取得します
• OpenAI を使って README を分析し、サーバー設定を抽出します
• 設定を .mcphub.json ファイルに追加します
• OpenAI API キーが必要です（OPENAI_API_KEY 環境変数で設定します）

OpenAI Agents での使用

import asyncio
import json
from agents import Agent, Runner
from mcphub import MCPHub

async def main():
    """
    Example of using MCPHub to integrate MCP servers with OpenAI Agents.
    
    This example demonstrates:
    1. Initializing MCPHub
    2. Fetching and using an MCP server
    3. Listing available tools
    4. Creating and running an agent with MCP tools
    """
    
    # Step 1: Initialize MCPHub
    # MCPHub will automatically:
    # - Find .mcphub.json in your project
    # - Load server configurations
    # - Set up servers (clone repos, run setup scripts if needed)
    hub = MCPHub()
    
    # Step 2: Create an MCP server instance using async context manager
    # Parameters:
    # - mcp_name: The name of the server from your .mcphub.json
    # - cache_tools_list: Cache the tools list for better performance
    async with hub.fetch_openai_mcp_server(
        mcp_name="sequential-thinking-mcp",
        cache_tools_list=True
    ) as server:
        # Step 3: List available tools from the MCP server
        # This shows what capabilities are available to your agent
        tools = await server.list_tools()
        
        # Pretty print the tools for better readability
        tools_dict = [
            dict(tool) if hasattr(tool, "__dict__") else tool for tool in tools
        ]
        print("Available MCP Tools:")
        print(json.dumps(tools_dict, indent=2))

        # Step 4: Create an OpenAI Agent with MCP server
        # The agent can now use all tools provided by the MCP server
        agent = Agent(
            name="Assistant",
            instructions="Use the available tools to accomplish the given task",
            mcp_servers=[server]  # Provide the MCP server to the agent
        )
        
        # Step 5: Run your agent with a complex task
        # The agent will automatically have access to all MCP tools
        complex_task = """Please help me analyze the following complex problem: 
                      We need to design a new feature for our product that balances user privacy 
                      with data collection for improving the service. Consider the ethical implications, 
                      technical feasibility, and business impact. Break down your thinking process 
                      step by step, and provide a detailed recommendation with clear justification 
                      for each decision point."""
        
        # Execute the task and get the result
        result = await Runner.run(agent, complex_task)
        print("\nAgent Response:")
        print(result)

if __name__ == "__main__":
    # Run the async main function
    asyncio.run(main())

機能とガイドライン

サーバー設定

• JSON ベースの設定：シンプルな .mcphub.json 設定ファイル
• 環境変数のサポート：設定で環境変数を使用できます
• 定義済みサーバー：事前設定済み MCP サーバーの拡充されていくリストを利用できます
• カスタムサーバーのサポート：カスタム MCP サーバーを簡単に統合できます

MCP サーバーは .mcphub.json で設定します。

{
    "mcpServers": {
        // TypeScript-based MCP server using NPX
        "sequential-thinking-mcp": {
            "package_name": "smithery-ai/server-sequential-thinking",  // NPM package name
            "command": "npx",                                         // Command to run server
            "args": [                                                // Command arguments
                "-y",
                "@smithery/cli@latest",
                "run",
                "@smithery-ai/server-sequential-thinking"
            ]
        },
        // Python-based MCP server from GitHub
        "azure-storage-mcp": {
            "package_name": "mashriram/azure_mcp_server",            // Package identifier
            "repo_url": "https://github.com/mashriram/azure_mcp_server", // GitHub repository
            "command": "uv",                                         // Python package manager
            "args": ["run", "mcp_server_azure_cmd"],                // Run command
            "setup_script": "uv pip install -e .",                  // Installation script
            "env": {                                                // Environment variables
                "AZURE_STORAGE_CONNECTION_STRING": "${AZURE_STORAGE_CONNECTION_STRING}",
                "AZURE_STORAGE_CONTAINER_NAME": "${AZURE_STORAGE_CONTAINER_NAME}",
                "AZURE_STORAGE_BLOB_NAME": "${AZURE_STORAGE_BLOB_NAME}"
            }
        }
    }
}

MCP サーバーのインストールと管理

• 柔軟なサーバーセットアップ：TypeScript ベースと Python ベースの MCP サーバーの両方をサポートします
• 複数のインストール元：
  • npx による NPM パッケージ
  • GitHub リポジトリ URL による Python パッケージ
  • ローカル開発サーバー
• 自動セットアップ：リポジトリのクローン、依存関係のインストール、サーバーの初期化を処理します

トランスポートのサポート

• stdio トランスポート：MCP サーバーをローカルのサブプロセスとして実行します
• SSE トランスポート：supergateway を使って、Server-Sent Events（SSE）をサポートする MCP サーバーを実行します
• パスの自動管理：サーバーのパスと作業ディレクトリを管理します
• 環境変数の処理：サーバーごとに環境変数を設定できます

SSE 対応でサーバーを実行する

mcphub run コマンドを使って、SSE 対応で MCP サーバーを実行できます。

# Basic usage with default settings
mcphub run your-server-name --sse

# Advanced usage with custom settings
mcphub run your-server-name --sse \
    --port 8000 \
    --base-url http://localhost:8000 \
    --sse-path /sse \
    --message-path /message

SSE サポートは、以下の場合に役立ちます。

• Web アプリケーションから MCP サーバーに接続する場合
• MCP サーバーとリアルタイム通信を行う場合
• SSE をサポートするクライアントと統合する場合

SSE サーバーは 2 つのエンドポイントを提供します。

• /sse：リアルタイム更新用の SSE エンドポイント
• /message：メッセージ送信用の HTTP エンドポイント

.mcphub.json での設定例：

{
    "mcpServers": {
        "sequential-thinking-mcp": {
            "package_name": "smithery-ai/server-sequential-thinking",
            "command": "npx",
            "args": [
                "-y",
                "@smithery/cli@latest",
                "run",
                "@smithery-ai/server-sequential-thinking",
                "--key",
                "your-api-key"
            ]
        }
    }
}

フレームワークとの統合

一般的な AI フレームワーク向けのアダプターを提供します。

• OpenAI Agents（例）
• LangChain（例）
• Autogen（例）

from mcphub import MCPHub

async def framework_quick_examples():
    hub = MCPHub()
    
    # 1. OpenAI Agents Integration
    async with hub.fetch_openai_mcp_server(
        mcp_name="sequential-thinking-mcp",
        cache_tools_list=True
    ) as server:
        # Use server with OpenAI agents
        agent = Agent(
            name="Assistant",
            mcp_servers=[server]
        )
    
    # 2. LangChain Tools Integration
    langchain_tools = await hub.fetch_langchain_mcp_tools(
        mcp_name="sequential-thinking-mcp",
        cache_tools_list=True
    )
    # Use tools with LangChain
    
    # 3. Autogen Adapters Integration
    autogen_adapters = await hub.fetch_autogen_mcp_adapters(
        mcp_name="sequential-thinking-mcp"
    )
    # Use adapters with Autogen

ツール管理

• ツールの検出：MCP サーバーで利用可能なツールを自動的に一覧表示し、管理します
• ツールのキャッシュ：パフォーマンス向上のため、ツール一覧を任意でキャッシュできます
• フレームワーク固有のアダプター：MCP ツールをフレームワーク固有の形式に変換します

MCP サーバーのツールを検出、管理します。

from mcphub import MCPHub

async def tool_management():
    hub = MCPHub()
    
    # List all servers
    servers = hub.list_servers()

    # List all tools from a specific MCP server
    tools = await hub.list_tools(mcp_name="sequential-thinking-mcp")
    
    # Print tool information
    for tool in tools:
        print(f"Tool Name: {tool.name}")
        print(f"Description: {tool.description}")
        print(f"Parameters: {tool.parameters}")
        print("---")
    
    # Tools can be:
    # - Cached for better performance using cache_tools_list=True
    # - Converted to framework-specific formats automatically
    # - Used directly with AI frameworks through adapters

MCPHub：概要

MCPHub は、4 つの主要コンポーネントを通じて、Model Context Protocol（MCP）サーバーと AI アプリケーションの統合を簡素化します。

コアコンポーネント

1. Params Hub

   • .mcphub.json の設定を管理します
   • 使用する MCP サーバーと、そのセットアップ方法を定義します
   • コマンド、引数、環境変数などのサーバーパラメーターを保存します

2. MCP Servers Manager

   • サーバーのインストールとセットアップを処理します
   • 次の 2 種類のサーバーをサポートします：
     • TypeScript ベースのサーバー（npx を使用してインストール）
     • Python ベースのサーバー（GitHub から uv を使用してインストール）
   • サーバーのライフサイクルと環境を管理します

3. MCP Client

   • MCP サーバーとの通信を確立します
   • サーバーとのやり取りに stdio トランスポートを使用します
   • 次の 2 つの主な操作を処理します：
     • list_tools：利用可能なサーバーツールを検出します
     • call_tool：サーバーツールを実行します

4. Framework Adapters

   • MCP ツールをフレームワーク固有の形式に変換します
   • 複数の AI フレームワークをサポートします：
     • OpenAI Agents
     • LangChain
     • Autogen

ワークフロー

1. 設定とセットアップ

   • Params Hub が設定を読み込みます
   • Servers Manager が必要なサーバーをセットアップします
   • サーバーが起動し、利用可能になります

2. 通信

   • MCP Client が stdio 経由でサーバーに接続します
   • ツールが検出され、利用可能になります
   • リクエストとレスポンスがクライアントとサーバーの間でやり取りされます

3. 統合

   • フレームワークアダプターが MCP ツールを変換します
   • AI アプリケーションが、使用するフレームワークを通じて変換済みのツールを利用します
   • 確立された通信チャネルを通じてツールが実行されます

このアーキテクチャにより、関心事を適切に分離し、フレームワークの柔軟性を保ちながら、あらゆる AI アプリケーションに MCP の機能をシームレスに統合できます。

開発

テスト

pytest で単体テストを実行します：

pytest tests/ -v

CI/CD パイプライン

このプロジェクトでは、継続的インテグレーションとデプロイに GitHub Actions を使用しています：

1. 自動テスト：main ブランチと release ブランチへのプッシュごと、およびプルリクエストごとに、Python 3.10、3.11、3.12 でテストを実行します。

2. バージョンの自動更新とタグ付け：コードが release ブランチにプッシュされると：

   • pyproject.toml のパッチバージョンが自動的に引き上げられます
   • リリース用に新しい Git タグ（例：v0.1.2）が作成されます
   • 変更がリポジトリにコミットされます

3. PyPI への公開：コードが release ブランチにプッシュされ、テストに合格すると、パッケージが自動的にビルドされ、PyPI に公開されます。

PyPI デプロイの設定

PyPI への自動デプロイを有効にするには、PyPI API トークンを GitHub Secret として追加する必要があります：

1. https://pypi.org/manage/account/token/ で PyPI API トークンを生成します
2. GitHub リポジトリの設定 → Secrets and variables → Actions に移動します
3. PYPI_API_TOKEN という名前で新しいリポジトリシークレットを追加し、PyPI のトークン値を設定します

コントリビューション

コントリビューションを歓迎します！進め方については、コントリビューションガイドをご確認ください。

ライセンス

このプロジェクトは MIT License のもとでライセンスされています。詳細は LICENSE ファイルをご覧ください。