mcpware

Gateway MCP Server

MCP リクエストを複数のバックエンドサーバーにインテリジェントにルーティングします。

🎯 主な機能

🚀 ツール数の制限を回避

• 課題：MCP クライアントでは、一度に読み込めるツール数に制限があることがよくあります
• 解決策：mcpware は 2 つのルーティングツールのみを公開しながら、無制限のバックエンドツールを利用できるようにします
• 結果：単一のゲートウェイを通じて、GitHub（50 以上のツール）、データベースなどに接続できます！

🔧 その他のメリット

• 複数の MCP サーバーに対する単一のエントリーポイント
• バックエンドサーバーのプロセスを自動管理
• Docker ベースの分離とデプロイ

クイックスタート

# Clone the repository
git clone https://github.com/delexw/mcpware.git
cd mcpware

# Build the Docker image
docker build -t mcpware . --no-cache

# Configure MCP client (see Installation section)

次に、インストールセクションの手順に従って MCP クライアントを設定します。

動作の仕組み

mcpware は Docker コンテナとして実行され、以下の処理を行います。

1. stdio 経由で MCP クライアントからリクエストを受信します
2. 適切なバックエンド MCP サーバー（同じく Docker で実行）にリクエストをルーティングします
3. 応答を MCP クライアントに返します

重要：バックエンドでは、任意のコマンド（docker、npx、node、python など）を使用できます。Docker で mcpware を実行する場合、npx や node などのローカルコマンドを使うバックエンドは、mcpware コンテナ内で実行されます。

インストール

前提条件

• Docker
• MCP クライアント（Cursor など）

MCP クライアントでのセットアップ

1. このリポジトリをクローンします。

   git clone https://github.com/delexw/mcpware.git
   cd mcpware
   

2. config.json でバックエンドを設定します（下記の「設定」セクションを参照）。

3. 環境変数を設定します。

   1. サンプルファイルをコピーします：cp env.example .env
   2. .env を実際の値で編集します。

      GITHUB_PERSONAL_ACCESS_TOKEN=your_github_token_here
      BUILDKITE_API_TOKEN=your_buildkite_token_here
      # 必要に応じて他の環境変数を追加
      

4. MCP クライアントの設定に追加します。

   注：シークレットやトークンは、mcpware の config.json に直接設定することもできます。

   設定（Docker を直接実行する場合）：

   {
     "mcpServers": {
       "mcpware": {
         "command": "docker",
         "args": [
           "run",
           "-i",
           "--rm",
           "-v",
           "/path/to/mcpware/config.json:/app/config.json:ro",
           "-v",
           "/var/run/docker.sock:/var/run/docker.sock",
           "--env-file",
           "/path/to/mcpware/.env",
           "mcpware"
         ]
       }
     }
   }
   

   重要：

   • /path/to/mcpware を、クローンしたリポジトリの絶対パスに置き換えてください
   • mcpware が Docker ベースのバックエンドを起動するには、Docker ソケットのマウント（/var/run/docker.sock）が必要です。それ以外の場合は不要です

   Docker ソケットをマウントする理由

   • mcpware は、バックエンド MCP サーバー（ghcr.io/github/github-mcp-server など）の Docker コンテナを起動する必要があります
   • Docker ソケットをマウントすると、mcpware が Docker と通信できるようになります
   • このマウントがないと、Docker コンテナとして実行されるバックエンドサーバーを mcpware が起動できません

プラットフォーム別の Docker ソケット設定

ゲートウェイがバックエンドコンテナを起動するには、Docker ソケットへのアクセスが必要です。マウントパスはプラットフォームによって異なります。

Docker ソケットへのアクセスが必要な理由 mcpware は、バックエンド MCP サーバーを起動するプロセスマネージャーとして機能します。バックエンドを Docker コンテナ（例：ghcr.io/github/github-mcp-server）として実行するように設定した場合、mcpware は以下を行う必要があります。

• Docker コンテナを作成して起動する
• コンテナのライフサイクルを管理する（停止／再起動）
• stdio 経由でコンテナと通信する

Docker ソケットにアクセスできない場合、mcpware は Docker ベースのバックエンドを起動できず、権限エラーが発生します。

簡易チェック

以下のスクリプトを実行して、Docker の設定を確認します。

python scripts/check_docker_socket.py

Linux/macOS/WSL2

変更は不要です。デフォルト設定で動作します。

volumes:
  - /var/run/docker.sock:/var/run/docker.sock

Windows（ネイティブコンテナ）

Docker ソケットのパスを更新します。

{
  "mcpServers": {
    "mcpware": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/path/to/mcpware/config.json:/app/config.json:ro",
        "-v",
        "//./pipe/docker_engine://./pipe/docker_engine",
        "--env-file",
        "/path/to/mcpware/.env",
        "mcpware"
      ]
    }
  }
}

Docker ソケットのパスが異なり、/var/run/docker.sock ではなく //./pipe/docker_engine を使用する点に注意してください。

Docker の種類を確認する

Windows で使用している Docker バックエンドを確認するには、次のコマンドを実行します。

docker version --format '{{.Server.Os}}'

• linux = WSL2/Hyper-V バックエンド（デフォルト設定を使用）
• windows = Windows コンテナー（オーバーライドファイルを使用）

設定

バックエンドサーバーを指定した config.json を作成します。

{
  "backends": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}"
      },
      "description": "GitHub MCP Server",
      "timeout": 60
    },
    "database": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "bytebase/dbhub", "--transport", "stdio"],
      "description": "Database MCP Server"
    }
  }
}

設定に関する注意：

• バックエンドのコマンドには、任意の実行可能ファイル（docker、npx、node、python など）を指定できます。
• docker コマンドを使用する場合は、Docker ソケットがマウントされていることを確認してください（インストール手順を参照）。

その他のバックエンドの例（データベース、API など）については、config.example.json を参照してください。

使い方

ゲートウェイでは、主に次の 2 つのツールを使用できます。

use_tool

指定したバックエンドサーバーにツール呼び出しをルーティングします。

パラメーター：

• backend_server：バックエンドサーバーの名前
• server_tool：呼び出すツールの名前
• tool_arguments：ツールに渡す引数

例：

{
  "backend_server": "github",
  "server_tool": "create_issue",
  "tool_arguments": {
    "owner": "myorg",
    "repo": "myrepo",
    "title": "New issue",
    "body": "Issue description"
  }
}

discover_backend_tools

使用可能なバックエンドとそのツールを検出します。

パラメーター：

• backend_name：（任意）照会する特定のバックエンド

他の MCP サーバーと mcpware を併用する

mcpware は、MCP クライアントの設定で他の MCP サーバーと併用できるように設計されています。次のような使い方ができます。

1. 複数のバックエンドサーバーのゲートウェイとして mcpware を使用する
2. 一部の MCP サーバーは分離したままにして、直接アクセスする
3. 必要に応じて組み合わせる

設定例：

{
  "mcpServers": {
    "mcpware": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/path/to/mcpware/config.json:/app/config.json:ro",
        "-v", "/var/run/docker.sock:/var/run/docker.sock",
        "--env-file", "/path/to/mcpware/.env",
        "mcpware"
      ]
    },
    "redis-direct": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-e", "REDIS_HOST=localhost", "mcp/redis"]
    }
  }
}

これにより、次のことが可能になります。

• ルーティングが必要な場合に、mcpware 経由で複数のサーバーにアクセスする
• 専用のアクセスが必要な場合に、特定のサーバーに直接接続する
• ワークフローに合わせて MCP サーバーを整理する

開発

前提条件

Python 3.10 以降がインストールされていることを確認してください。

python --version  # Should show Python 3.10 or higher

開発環境のセットアップ

1. リポジトリをクローンします。

   git clone https://github.com/delexw/mcpware.git
   cd mcpware
   

2. 仮想環境を作成します（推奨）。

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

3. 開発用の依存関係をインストールします。

   pip install -r requirements.txt
   

開発用の依存関係

このプロジェクトの依存関係は最小限です。主要な機能はすべて Python 標準ライブラリを使用して実装されています。

テスト用の依存関係（requirements.txt に含まれています）：

• pytest - テスト用フレームワーク
• pytest-asyncio - 非同期テストのサポート
• pytest-cov - コードカバレッジのレポート

任意の開発ツール（必要に応じて個別にインストール）：

# Code formatting
pip install black isort

# Linting
pip install flake8 pylint mypy

# Development convenience
pip install pytest-watch  # Auto-run tests on file changes

ローカルでの実行

# Run the gateway server
python gateway_server.py --config config.json

# Run with debug logging
python gateway_server.py --config config.json --log-level DEBUG

コードスタイル

コミットする前にコードをフォーマットしてください。

# Format with black (if installed)
black src/ tests/ gateway_server.py

# Sort imports (if installed)
isort src/ tests/ gateway_server.py

# Run linting (if installed)
flake8 src/ tests/ gateway_server.py --max-line-length=120

テストの実行

# Run all tests
pytest

# Run with coverage report
pytest --cov=src --cov=gateway_server --cov-report=html

# Run specific test file
pytest tests/test_config.py

# Run tests in watch mode (requires pytest-watch)
pytest-watch

Docker

Docker でビルドして実行します。

# Build the image
docker build -t mcpware .

# Run interactively (for testing)
docker run -it --rm \
  -v $(pwd)/config.json:/app/config.json:ro \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e GITHUB_PERSONAL_ACCESS_TOKEN \
  mcpware

# Run with specific config file
docker run -it --rm \
  -v /path/to/your/config.json:/app/config.json:ro \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e GITHUB_PERSONAL_ACCESS_TOKEN \
  mcpware

環境変数

ゲートウェイは、バックエンド設定での環境変数の置換をサポートしています。.env ファイルに次のように設定します。

# Example .env file
GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxxxxxxxxxxxx
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxx
# Add other tokens as needed

${VAR_NAME} 構文を使って config.json 内で参照されている環境変数は、自動的に置換されます。

テスト

このプロジェクトには、包括的な単体テストと統合テストが含まれています。

テストの実行

1. テスト用の依存関係をインストールします。

   pip install -r requirements.txt
   

2. すべてのテストを実行します。

   pytest
   

3. カバレッジを測定しながらテストを実行します。

   pytest --cov=src --cov=gateway_server --cov-report=html
   

4. 特定のテストモジュールを実行します。

   pytest tests/test_config.py
   pytest tests/test_backend.py
   pytest tests/test_protocol.py
   

5. ウォッチモードでテストを実行します。

   pytest-watch
   

ライセンス

MIT