MCP Calculator Server

MCP Calculator Server

基本的な電卓ツールを備えた Model Context Protocol（MCP）サーバーの実装です。このサーバーは Smithery にデプロイでき、REST API を介して算術演算を提供します。

Features

• 基本的な算術演算（加算、減算、乗算、除算）
• MCP 準拠の API エンドポイント
• JSON スキーマの検証
• エラー処理
• 複数の通信モード（HTTP、WebSocket、stdio）
• デプロイシナリオに応じた専用エントリーポイント

Installation

1. 仮想環境を作成します（推奨）：

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

2. 依存関係をインストールします：

pip install -r requirements.txt

Running the Server

HTTP Mode (本番環境およびコンテナー向けに推奨)

uvicorn を直接使用して、サーバーを HTTP 専用モードで実行します：

# Set environment variable to ensure only HTTP mode runs
export MCP_HTTP_MODE=1  # On Windows: set MCP_HTTP_MODE=1
uvicorn server:app --host 0.0.0.0 --port 8000

または、付属のスクリプトを使用します：

# On Unix/Linux/Mac
./start-container.sh

# On Windows
start-container.bat

このモードは、次の用途に推奨されます：

• 本番環境へのデプロイ
• コンテナー環境
• 信頼性の高い HTTP エンドポイントが必要なあらゆるシナリオ

Smithery Mode (ローカルツール統合)

ローカルツールとして Smithery と統合する場合は、stdio モードを使用します：

# Set environment variable to ensure only stdio mode runs
export MCP_STDIO_MODE=1  # On Windows: set MCP_STDIO_MODE=1
python server.py

または、付属の便利なスクリプトを使用します：

# On Unix/Linux/Mac
./start-smithery.sh

# On Windows
start-smithery.bat

このモードは Smithery のローカルツール統合専用に設計されており、標準入力／出力を介して通信します。

IMPORTANT: 環境変数を設定せずに python server.py を実行しないでください。このコマンドは HTTP モードと stdio モードの両方を同時に起動するため、競合やタイムアウトが発生する可能性があります。

Dual Mode (開発専用)

開発やテストで両方のインターフェースを同時に使用する場合：

# No environment variables set - runs both modes
python server.py

HTTP サーバーと stdio ハンドラーの両方を同時に起動しますが、stdin が閉じられると早期に終了する場合があります。このモードは、本番環境や Smithery との統合には推奨されません。

API Endpoints

標準エンドポイント

• GET /health：ヘルスチェック用エンドポイント
• GET /tools：利用可能なツールとそのスキーマの一覧
• POST /：MCP プロトコル用の JSON-RPC エンドポイント
• / の WebSocket：MCP プロトコル用の WebSocket エンドポイント

Smithery 統合エンドポイント

• POST /mcp：Smithery 統合専用の MCP 互換 JSON-RPC エンドポイント
• /mcp の WebSocket：Smithery 統合専用の MCP 互換 WebSocket エンドポイント

これらの専用 MCP エンドポイントは Smithery との統合用に設計されており、明示的な初期化手順を必要とせずに、初期化とツール一覧の取得を自動的に処理します。

電卓ツールの使用

REST API

/tools エンドポイントへのリクエスト例：

curl -X GET http://localhost:8000/tools

JSON-RPC (HTTP)

JSON-RPC エンドポイントへのリクエスト例：

curl -X POST http://localhost:8000/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "execute", "params": {"function_calls": [{"name": "calculator", "parameters": {"operation": "add", "numbers": [1, 2, 3, 4]}}]}, "id": 1}'

利用可能な演算：

• add：すべての数値を加算します
• subtract：最初の数値から後続の数値を順に減算します
• multiply：すべての数値を乗算します
• divide：最初の数値を後続の数値で順に除算します

Error Handling

サーバーは、次の内容について明確なエラーメッセージを提供します：

• 無効な演算
• ゼロによる除算
• オペランドの不足
• 無効なパラメーターの型
• JSON-RPC プロトコルエラー

Deployment

Docker Container

Docker コンテナーをビルドして実行します：

docker build -t mcp-calculator-server .
docker run -p 8000:8000 mcp-calculator-server

このコンテナーは uvicorn を直接使用して、シグナルを適切に処理しながら HTTP サーバーを確実に起動します。これにより、API エンドポイントを http://localhost:8000 で利用できます。

Smithery Integration

ローカルツール統合（stdio モード）

ローカルツールとして Smithery と統合するには、必須のログ設定を使用して stdio モードで実行する必要があります：

# Set environment variables for stdio mode and logging
export MCP_STDIO_MODE=1  # On Windows: set MCP_STDIO_MODE=1
export LOGGING_CONFIG=stdio  # On Windows: set LOGGING_CONFIG=stdio

# Run the server
python server.py

または、付属の便利なスクリプトを使用します：

# On Unix/Linux/Mac
./start-smithery.sh

# On Windows
start-smithery.bat

Smithery 統合用 Docker コンテナー

コンテナーで Smithery と統合する場合は、専用の Smithery Dockerfile を使用します：

# Build the Smithery-specific container
docker build -t mcp-calculator-smithery -f Dockerfile.smithery .

# Run the container with stdio mode
docker run -i -e MCP_STDIO_MODE=1 -e LOGGING_CONFIG=stdio mcp-calculator-smithery

または、付属の便利なスクリプトを使用します：

# On Unix/Linux/Mac
./run-smithery-container.sh

# On Windows
run-smithery-container.bat

このコンテナーは Smithery との統合用に特別に設定されており、必須のログ設定を使用して stdio モードで実行されます。

Smithery の設定

サーバーをローカルツールとして使用するように Smithery を設定します。

{
  "name": "calculator",
  "description": "A basic calculator that can perform arithmetic operations",
  "command": ["python", "server.py"],
  "env": {
    "MCP_STDIO_MODE": "1",
    "LOGGING_CONFIG": "stdio"
  },
  "type": "local"
}

この設定により、Smithery がローカルツールとして実行する際にサーバーが stdio 経由で通信し、ロギングシステムが適切に設定されます。

IMPORTANT：ローカルツールとの統合では、LOGGING_CONFIG 環境変数とともに stdio モード（MCP_STDIO_MODE=1）を使用する必要があります。HTTP モードはローカルツールとの統合では機能しません。

リモートツールとの統合（HTTP モード）

Smithery をリモートツール（例：コンテナー内）として統合する場合は、専用の MCP エンドポイントを使用する HTTP モードを使います。

{
  "name": "calculator",
  "description": "A basic calculator that can perform arithmetic operations",
  "url": "http://your-container-host:8000/mcp",
  "type": "remote"
}

この設定により、Smithery は専用の MCP 互換エンドポイントを使用して、HTTP 経由でツールの API エンドポイントにアクセスできます。

コンテナー環境で最も信頼性の高い動作を実現するには、デプロイ設定で uvicorn を直接使用します。

{
  "name": "calculator",
  "description": "A basic calculator that can perform arithmetic operations",
  "command": ["uvicorn", "server:app", "--host", "0.0.0.0", "--port", "8000"],
  "env": {
    "MCP_HTTP_MODE": "1"
  },
  "type": "remote"
}

これにより、コンテナー環境で適切なシグナル処理と、より信頼性の高い起動が実現します。