Model Context Protocol (MCP) Server

Model Context Protocol (MCP) サーバー

複数のトランスポートオプションと動的なサービス選択に対応した、AI サービス向けのモジュール式 Model Context Protocol サーバーです。保守性と拡張性を高めるため、SOLID 原則に基づいて構築されています。

特長

• 複数の AI サービス：Claude、OpenAI、モックサービスに対応
• 動的なサービス選択：リクエストごとに AI サービスを選択
• 複数のトランスポート：
  • stdio：コマンドラインでの使用やスクリプト向け
  • TCP：ネットワークベースのアプリケーション向け
  • WebSocket：ウェブブラウザーやリアルタイムアプリケーション向け
• JSON-RPC 2.0：予測可能なやり取りを実現する準拠インターフェース
• モジュール式アーキテクチャ：新しいサービスやトランスポートを簡単に追加可能
• 環境設定：.env ファイルを使った簡単なセットアップ
• ストリーミング対応：対応するトランスポートでリアルタイムに応答をストリーミング

リポジトリ構成

basic-mcp-server/
├── .env                      # Environment configuration
├── .gitignore                # Git ignore rules
├── README.md                 # Project documentation
├── examples/                 # Example clients
│   ├── example_client.py     # Command-line client example
│   └── websocket_client.html # Browser WebSocket client
├── mcp_server.py             # Main entry point
└── mcp_server/               # Core package
    ├── config/               # Configuration management
    │   ├── settings.py       # Environment and settings handling
    │   └── __init__.py
    ├── core/                 # Core server logic
    │   ├── server.py         # Main server implementation
    │   └── __init__.py
    ├── handlers/             # Method handlers
    │   ├── base_handlers.py  # Standard MCP handlers
    │   ├── system_handlers.py # System info handlers
    │   └── __init__.py
    ├── models/               # Data models
    │   ├── json_rpc.py       # JSON-RPC data structures
    │   └── __init__.py
    ├── services/             # AI service implementations
    │   ├── claude_service.py # Anthropic Claude API
    │   ├── openai_service.py # OpenAI API
    │   └── __init__.py       # Service registry
    ├── transports/           # Communication protocols
    │   ├── base.py           # Transport interfaces
    │   ├── websocket.py      # WebSocket implementation
    │   └── __init__.py
    └── __init__.py

インストール

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

   git clone https://github.com/shaswata56/basic-mcp-server.git
   cd basic-mcp-server
   

2. 仮想環境を作成し、依存関係をインストールします：

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   pip install -e .
   

3. .env ファイルを編集し、API キーと設定を指定して環境を構成します。

設定

環境変数

サーバーは、.env ファイル内の環境変数を使って設定できます。

変数	説明	デフォルト
AI_SERVICE_TYPE	使用するデフォルトの AI サービス（"claude"、"openai"、"mock"）	"claude"
SECRETS_FILE	API シークレットを含む JSON ファイルのパス	None
ANTHROPIC_API_KEY	Anthropic API キー	None
OPENAI_API_KEY	OpenAI API キー	None
MCP_SERVER_NAME	サーバー名	"ai-mcp-server"
MCP_SERVER_VERSION	サーバーのバージョン	"1.0.0"
MCP_TRANSPORT_TYPE	トランスポートの種類（"stdio"、"tcp"、"websocket"）	"stdio"
MCP_TCP_HOST	TCP/WebSocket のホストアドレス	"127.0.0.1"
MCP_TCP_PORT	TCP サーバーのポート	9000
MCP_WS_PORT	WebSocket サーバーのポート	8765
MCP_WS_PATH	WebSocket サーバーのパス	"/"
MCP_WS_ORIGINS	許可するオリジンをカンマ区切りで指定したリスト	None（すべて許可）
CLAUDE_DEFAULT_MODEL	デフォルトの Claude モデル	"claude-3-opus-20240229"
CLAUDE_DEFAULT_MAX_TOKENS	Claude のデフォルトの最大トークン数	4096
CLAUDE_DEFAULT_TEMPERATURE	Claude のデフォルトの temperature	0.7
OPENAI_DEFAULT_MODEL	デフォルトの OpenAI モデル	"gpt-4o"
OPENAI_DEFAULT_MAX_TOKENS	OpenAI のデフォルトの最大トークン数	1024
OPENAI_DEFAULT_TEMPERATURE	OpenAI のデフォルトの temperature	0.7

| EMBEDDINGS_3_LARGE_API_URL | text-embedding-3-large の Azure エンドポイント | None | | EMBEDDINGS_3_LARGE_API_KEY | text-embedding-3-large の API キー | None | | EMBEDDINGS_3_SMALL_API_URL | text-embedding-3-small の Azure エンドポイント | None | | EMBEDDINGS_3_SMALL_API_KEY | text-embedding-3-small の API キー | None | | AZURE_OPENAI_EMBEDDING_DEPLOYMENT | 埋め込みの Azure デプロイ名 | <model name> | | QDRANT_URL | Qdrant サーバーの URL（インメモリーで使用する場合は :memory:） | None | | QDRANT_API_KEY | Qdrant Cloud の API キー | None |

埋め込み API の認証情報が指定されていない場合、外部サービスなしでテストを実行できるよう、サーバーは決定論的なモック埋め込みを生成します。

本番環境にデプロイする場合は、専用の Qdrant サーバーを指すように QDRANT_URL を設定してください。リモートサーバーを使用すると、デフォルトのインメモリーモードと比較して、永続ストレージと優れたベクトル検索パフォーマンスが得られます。

オプションの SECRETS_FILE 変数を使用すると、環境変数の代わりに JSON ファイルに API キーを保存できます。シークレットファイルに定義された値は、対応する環境変数が設定されていない場合に使用されます。シークレット値が配列の場合、キーが要求されるたびにサーバーは値を順番に切り替えるため、簡単なキーのローテーション戦略を実現できます。

使用方法

サーバーの起動

標準の stdio モード

python mcp_server.py

TCP サーバーモード

python mcp_server.py --tcp --host 127.0.0.1 --port 9000

WebSocket サーバーモード

python mcp_server.py --websocket --host 127.0.0.1 --port 8765 --ws-path /

コマンドラインオプション

usage: mcp_server.py [-h] [--tcp | --websocket] [--host HOST] [--port PORT]
                     [--ws-path WS_PATH] [--service-type {claude,openai,mock}]
                     [--claude-api-key CLAUDE_API_KEY]
                     [--openai-api-key OPENAI_API_KEY]
                     [--qdrant-url QDRANT_URL]
                     [--qdrant-api-key QDRANT_API_KEY] [--mock]
                     [--log-level {DEBUG,INFO,WARNING,ERROR}]
                     [--env-file ENV_FILE]

AI MCP Server with JSON-RPC

options:
  -h, --help            show this help message and exit
  --log-level {DEBUG,INFO,WARNING,ERROR}
                        Logging level
  --env-file ENV_FILE   Path to .env file (default: .env in project root)

Transport Options:
  --tcp                 Run as TCP server
  --websocket           Run as WebSocket server
  --host HOST           Host to bind server
  --port PORT           Port for server
  --ws-path WS_PATH     URL path for WebSocket server (default: /)

AI Service Options:
  --service-type {claude,openai,mock}
                        AI service to use
  --claude-api-key CLAUDE_API_KEY
                        Anthropic API key
  --openai-api-key OPENAI_API_KEY
                          OpenAI API key
  --qdrant-url QDRANT_URL
                          Qdrant server URL
  --qdrant-api-key QDRANT_API_KEY
                          Qdrant API key
  --mock                Use mock AI service (for testing)

クライアントの例

コマンドラインクライアント

examples/example_client.py を使用すると、サーバーと簡単にやり取りできます。

# Initialize connection
python examples/example_client.py initialize

# List available tools
python examples/example_client.py list-tools

# Echo text
python examples/example_client.py echo "Hello, world!"

# Calculate expression
python examples/example_client.py calculate "2 + 3 * 4"

# Ask AI with dynamic service selection
python examples/example_client.py ask "What is the capital of France?" --service claude

# System information
python examples/example_client.py system-info

WebSocket ブラウザクライアント

WebSocket トランスポートを使用する場合は、ブラウザーで examples/websocket_client.html を開きます。

1. WebSocket URL（例：ws://localhost:8765/）を入力します
2. 「Connect」をクリックします
3. インターフェースを使ってサーバーにリクエストを送信します

JSON-RPC インターフェース

統合 AI メッセージリクエスト

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "ai/message",
    "arguments": {
      "prompt": "What is the capital of France?",
      "service_name": "claude"  // Optional: "claude", "openai", "mock" or omit for default
    }
  },
  "id": 1
}

サービス固有のリクエスト（後方互換性のため）

Claude：

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "claude/message",
    "arguments": {
      "prompt": "What is the capital of France?"
    }
  },
  "id": 2
}

OpenAI：

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "openai/message",
    "arguments": {
      "prompt": "What is the capital of France?"
    }
  },
  "id": 3
}

利用可能なメソッド

メソッド	説明
initialize	サーバー接続を初期化します
tools/list	利用可能なツールの一覧を取得します
tools/call	引数を指定してツールを呼び出します
resources/list	利用可能なリソースの一覧を取得します
resources/read	リソースを読み取ります
system/info	システム情報を取得します
system/health	システムの健全性を確認します

サーバーの拡張

新しいメソッドハンドラーの追加

1. handlers ディレクトリに、HandlerInterface を実装する新しいハンドラークラスを作成します
2. AIMCPServerApp.initialize() メソッドに登録します

新しい AI サービスの追加

1. services ディレクトリに、AIServiceInterface を実装する新しいサービスクラスを作成します
2. create_ai_services_from_config() のサービスレジストリに追加します

新しいトランスポートの追加

1. transports ディレクトリに、Transport クラスを継承する新しいトランスポートクラスを作成します
2. 新しいトランスポートを使用するようにメイン関数を更新します

WebSocket とロードバランサー

このサーバーの前段で、TLS/SSL を終端するロードバランサー（AWS ELB など）を使用する場合：

• クライアントはセキュア WebSocket（wss://）を使用してロードバランサーに接続します
• ロードバランサーが TLS/SSL の終端を処理します
• ロードバランサーは通常の WebSocket（ws://）を使用して MCP サーバーにトラフィックを転送します
• アプリケーション自体で WSS を実装する必要はありません

パフォーマンスに関する考慮事項

非常に大規模なリポジトリ、特に C# プロジェクトを処理すると、多数のデータベース操作が発生することがあります。 MongoDB でパフォーマンスの問題が発生した場合は、挿入をバッチ処理するか、別のストレージ戦略を検討してください。

ライセンス

MIT ライセンス

謝辞

• Anthropic による Claude API
• OpenAI API
• JSON-RPC 2.0 仕様
• WebSockets プロトコル