Onemcp

🚀 OneMCP - 汎用MCPアグリゲーター

複数の外部MCPサーバーを統合インターフェイスにまとめ、段階的な検出機能を備えた汎用的なモデルコンテキストプロトコル（MCP）アグリゲーターです。

バージョン0.2.0 - 効率と拡張性を向上させるメタツールアーキテクチャを備えた、本番環境で使用可能な汎用アグリゲーターです。

公式のMCP Go SDK を使用して構築されており、これはAnthropicとGoogleが共同開発したものです。

🚀 クイックスタート

1. アグリゲーターのビルド

# macOS用にビルド
GOOS=darwin GOARCH=amd64 go build -o one-mcp ./cmd/one-mcp

# Linux用にビルド
GOOS=linux GOARCH=amd64 go build -o one-mcp-linux ./cmd/one-mcp

2. OneMCPの設定

.onemcp.json を作成します。

{
  "settings": {
    "searchResultLimit": 5,
    "searchProvider": "claude"
  },
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp"],
      "category": "browser",
      "enabled": true
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      "category": "filesystem",
      "enabled": true
    }
  }
}

3. アグリゲーターの実行

# OneMCPアグリゲーターを起動（デフォルトで .onemcp.json を使用）
./one-mcp

# カスタム設定ファイルを使用
ONEMCP_CONFIG=/path/to/config.json ./one-mcp

# またはカスタムサーバー名/バージョンを指定
MCP_SERVER_NAME=my-aggregator MCP_SERVER_VERSION=0.2.0 ./one-mcp

# デバッグログを有効化
MCP_LOG_LEVEL=debug ./one-mcp

4. MCPクライアントでの使用

MCPクライアントの設定に追加します。例えば、Claude Desktop（~/Library/Application Support/Claude/claude_desktop_config.json）に追加する場合：

{
  "mcpServers": {
    "onemcp": {
      "command": "/path/to/one-mcp",
      "env": {
        "MCP_SERVER_NAME": "my-aggregator",
        "MCP_LOG_FILE": "/tmp/onemcp.log"
      }
    }
  }
}

✨ 主な機能

OneMCPは以下のような汎用的なMCPアグリゲーターです。

• 複数の外部MCPサーバーからのツールを集約します。
• 型安全な登録を通じて、カスタム内部ツールをサポートします。
• 統一されたメタツールインターフェイスを公開し、トークンの使用量を削減します。
• 段階的なツール検出をサポートします（スキーマを読み込む前に検索可能）。
• 任意のMCP準拠サーバーと動作します。

📦 インストール

上記のクイックスタートセクションの手順に従って、OneMCPをビルド、設定、実行してください。

💻 使用例

基本的な使用法

{
  "tool_name": "tool_search",
  "arguments": {
    "query": "navigate",
    "detail_level": "summary"
  }
}

高度な使用法

{
  "tool_name": "tool_search",
  "arguments": {
    "query": "browser",
    "category": "browser",
    "detail_level": "detailed",
    "offset": 5
  }
}

📚 ドキュメント

Meta-Tools API

1. tool_search

オプションのフィルターを使用して利用可能なツールを検出します。LLMによる意味検索を使用して、クエリを最も関連するツールにインテリジェントにマッチさせます。デフォルトではクエリごとに 5つのツール を返します（.onemcp.json で設定可能）。

引数:

• query (オプション) - 自然言語での検索クエリ（例: "take a screenshot", "navigate to webpage", "read files"）
• category (オプション) - カテゴリでフィルターをかけます（例: "browser", "filesystem"）
• detail_level (オプション) - 返す詳細レベル:
  • "names_only" - ツール名とカテゴリのみ（最小限のトークン）
  • "summary" - 名前、カテゴリ、説明（デフォルト）
  • "detailed" - 引数スキーマを含む
  • "full_schema" - すべての詳細を含む完全なスキーマ
• offset (オプション) - ページネーションのためにスキップする結果の数（デフォルト: 0）

意味検索: LLMは自然言語クエリ、コンテキスト、意図を理解します。キーワードだけでなく、クエリをツールの説明と意味的にマッチさせます。

スキーマキャッシュ: 外部ツールのスキーマは起動時にキャッシュされ、高速な繰り返し検索が可能です。

ハイブリッドアプローチ: 検索はデフォルトで 5つのツールをインラインで返し（設定可能）、さらに schema_file パス（/tmp/onemcp-tools-schema.json）を含み、これには すべての実行可能ツールの完全なスキーマ が含まれています（外部および内部ツールのみ、メタツールはMCPの tools/list を通じてすでに公開されているため除外）。包括的なツール探索のために、ファイルシステムツールを使用してスキーマファイルを検索することをお勧めします。これにより、トークンの使用量を削減しながら、完全なツール情報にアクセスできます。

2. tool_execute

ツール名を指定して単一のツールを実行します。

引数:

• tool_name (必須) - ツールの名前（例: playwright_browser_navigate）
• arguments (必須) - ツール固有の引数

設定

OneMCPは .onemcp.json を使用して設定します。設定ファイルは JSON with comments (JSONC) 形式をサポートしており、// で行コメント、/* */ でブロックコメントを追加して設定をドキュメント化できます。

設定項目

{
  "settings": {
    "searchResultLimit": 5,
    "searchProvider": "claude"
  }
}

利用可能な設定項目:

• searchResultLimit (数値) - 検索クエリごとに返すツールの数。デフォルト: 5。値を下げるとトークンの使用量が減少しますが、検出にはより多くの検索が必要になります。
• searchProvider (文字列) - 意味検索に使用するLLMプロバイダー。オプション: "claude" (デフォルト), "codex", "copilot"。詳細は「LLMによる意味検索」セクションを参照してください。
• claudeModel (文字列) - searchProvider が "claude" の場合に使用するClaudeモデル。オプション: "haiku" (デフォルト), "sonnet", "opus"。
• codexModel (文字列) - searchProvider が "codex" の場合に使用するCodexモデル。オプション: "gpt-5-codex-mini" (デフォルト), "gpt-5-codex"。
• copilotModel (文字列) - searchProvider が "copilot" の場合に使用するCopilotモデル。デフォルト: "claude-haiku-4.5"。

外部サーバーの設定

mcpServers セクションで外部MCPサーバーを定義します。OneMCPは複数のトランスポートタイプをサポートしています。

1. コマンドトランスポート (stdio) - 最も一般的で、ローカルコマンドを実行します。

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp"],
      "env": {
        "DEBUG": "1"
      },
      "category": "browser",
      "enabled": true
    }
  }
}

2. HTTPトランスポート (Streamable HTTP) - HTTPを介してリモートMCPサーバーに接続します。

{
  "mcpServers": {
    "remote-server": {
      "url": "https://api.example.com/mcp",
      "category": "api",
      "enabled": true
    }
  }
}

注意: OneMCPはすべてのHTTP接続にStreamable HTTPトランスポート（MCP仕様2025-03-26+）を使用します。これは、非推奨のSSEトランスポートに代わる最新の標準です。

環境変数

• ONEMCP_CONFIG - 設定ファイルのパス（デフォルト: ".onemcp.json"）
• MCP_SERVER_NAME - サーバー名（デフォルト: "one-mcp-aggregator"）
• MCP_SERVER_VERSION - サーバーバージョン（デフォルト: "0.2.0"）
• MCP_LOG_FILE - ログファイルのパス（デフォルト: "/tmp/one-mcp.log"）
• MCP_LOG_LEVEL - ログレベル: "debug" または "info"（デフォルト: "info"）

ツールの命名規則

外部ツールは自動的にサーバー名が接頭辞として付けられます。

• playwright の browser_navigate → playwright_browser_navigate
• chrome の take_screenshot → chrome_take_screenshot

これにより、複数のサーバーを集約する際の名前の衝突を防ぎます。

段階的な検出ワークフロー

LLMに推奨されるワークフローは以下の通りです。

1. ツールを検索する: tool_search をフィルターとともに使用して、関連するツールを見つけます。
2. 詳細なスキーマを取得する: 使用する予定のツールについて、detail_level: "full_schema" を使用します。
3. ツールを実行する: 検証済みの引数で tool_execute を使用します。

ログ

ログは MCP_LOG_FILE で指定されたファイルに書き込まれます（デフォルト: /tmp/one-mcp.log）。

トラブルシューティング

外部サーバーが起動しない場合

• .onemcp.json のコマンドパスが正しいことを確認してください。
• 必要な環境変数が設定されていることを確認してください。
• MCP_LOG_FILE のログを確認して、起動エラーをチェックしてください。
• サーバーコマンドを手動でテストしてください: command args...

ツールが見つからない場合

• tool_search を使用して、ツールが存在することを確認してください。
• ツール名にサーバーの接頭辞が含まれていることを確認してください（例: playwright_browser_navigate）。
• .onemcp.json で外部サーバーが有効になっていることを確認してください。

ツールの実行が失敗する場合

• detail_level: "full_schema" で tool_search を使用して、必要な引数を確認してください。
• 引数の型がスキーマと一致することを確認してください。
• 詳細なエラーメッセージをログで確認してください。

🔧 技術詳細

アーキテクチャ

OneMCP Aggregator
    ├── Meta-Tools (2)
    │   ├── tool_search        - 利用可能なツールを検出する
    │   └── tool_execute       - 単一のツールを実行する
    │
    ├── Internal Tools (オプション)
    │   └── 型安全なハンドラーを持つカスタムGoベースのツール
    │
    └── External MCP Servers (`.onemcp.json` で設定)
        ├── Playwright (21ツール) - ブラウザ自動化
        ├── Filesystem (Nツール) - ファイル操作
        └── Your Server (Nツール) - 任意のMCP準拠サーバー

メリット

1. トークン効率: 99%の削減 - 数百の個別ツールではなく、2つのメタツールを公開します。
2. 段階的な検出: 最初に検索し、必要なツールのスキーマのみを読み込みます。
3. 汎用性: 任意のMCP準拠サーバーと動作します。
4. 柔軟性: 外部サーバー（設定）と内部ツール（Goコード）の両方をサポートします。
5. 型安全性: 組み込みツールはGoの型システムを利用し、自動的にスキーマを推論します。

パフォーマンス最適化

OneMCPには、トークン効率と速度のためのいくつかの最適化が含まれています。

1. 検索結果の制限を設定可能: デフォルトでは検索ごとに5つのツールを返します（.onemcp.json で設定可能）。
2. LLMによる意味検索: Claude、Codex、またはCopilotを使用して、クエリをツールにインテリジェントにマッチさせます。
3. 段階的な検出: 4つの詳細レベル（names_only → summary → detailed → full_schema）。
4. スキーマキャッシュ: 外部ツールのスキーマは起動時にキャッシュされ、繰り返しの取得を避けます。
5. 遅延読み込み: 明示的に detail_level で要求された場合のみ、スキーマが送信されます。

技術構成

OneMCPは以下の技術を使用して構築されています。

• 公式MCP Go SDK v1.1.0 - Anthropic/Googleの共同開発
• Go 1.25 - 最新で効率的かつ型安全な言語
• JSON-RPC 2.0 - MCP通信の標準プロトコル
• 複数のトランスポート - Stdio（コマンド）、HTTP（SSE）など

サポートされるトランスポート

• Command (stdio): ローカルコマンドを実行し、JSON-RPCを使用してstdin/stdoutを介して通信します - ローカルツールで最も一般的です。
• Streamable HTTP: JSON-RPC over HTTPを使用して、リモートのHTTPベースのMCPサーバーに接続します。オプションでSSEストリーミングをサポートします（MCP仕様2025-03-26+） - クラウドサービスに最適です。
• In-Memory: 直接のプロセス内通信 - テストに便利です。

プロトコルの詳細

• すべてのMCP通信は、メッセージエンコーディングに JSON-RPC 2.0 を使用します。
• Stdioトランスポート: stdin/stdoutを介したJSON-RPCメッセージ。
• Streamable HTTPトランスポート: HTTP POST/GETを介したJSON-RPC。オプションでServer-Sent Events（SSE）を使用してストリーミングレスポンスをサポートします。
  • 単一のエンドポイント（二重エンドポイントの複雑さがない）
  • リクエスト/レスポンスとストリーミングの両方をサポート
  • Mcp-Session-Id ヘッダーを使用したセッション管理
  • Last-Event-ID を使用した自動再接続機能

📄 ライセンス

MITライセンスです。詳細は LICENSE ファイルを参照してください。

貢献

貢献は大歓迎です！GitHubでイシューまたはPRを開いてください。