おもてなしQR MCP Server

ChatGPTなどのMCP対応クライアントから、おもてなしQRの音声生成APIを呼び出すための最小構成MCPサーバーです。

概要

このMCPサーバーは、Model Context Protocol (MCP) に準拠したAPIゲートウェイとして機能し、MCPクライアントからのリクエストを既存のおもてなしQR音声生成APIにプロキシします。

アーキテクチャ

ChatGPT（MCPクライアント） │ （MCP API KEY 認証） ▼ mcp.omotenashiqr.com（Node MCPサーバー） │ （内部固定 session_token） ▼ omotenashiqr.com/api/v2/video/generate-audio（既存API）

機能

MCP準拠: Model Context Protocol 2024-11-05 に準拠
API KEY認証: MCPクライアントからのリクエストをAPI KEYで認証
音声生成ツール: generate_audio ツールを提供
セッション管理: StreamableHTTP transportを使用したセッション管理
ロギング: 詳細なログ出力で動作を追跡

必要な環境

Node.js 18以上
npm または yarn

セットアップ

1. 依存関係のインストール

npm install

2. 環境変数の設定

.env ファイルを作成し、以下の環境変数を設定します：

# MCP Server API Key (MCPクライアントからのリクエスト認証用) MCP_API_KEY=your-mcp-api-key-here # おもてなしQR 管理者セッショントークン（既存APIへのリクエスト用） OMOTENASHI_SESSION_TOKEN=your-admin-session-token-here # 既存APIのベースURL BASE_API_URL=https://omotenashiqr.com # MCPサーバーのポート番号（デフォルト: 8001） MCP_PORT=8001

3. サーバーの起動

npm start

サーバーが起動すると、以下のエンドポイントが利用可能になります：

POST /mcp - MCPリクエストエンドポイント
GET /mcp - SSEストリームエンドポイント
DELETE /mcp - セッション終了エンドポイント
GET /health - ヘルスチェックエンドポイント

使用方法

ヘルスチェック

curl http://localhost:8001/health

MCP初期化

curl -X POST http://localhost:8001/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{ "jsonrpc": "2.0", "method": "initialize", "params": { "protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": { "name": "test-client", "version": "1.0.0" } }, "id": 1 }'

レスポンスヘッダーから Mcp-Session-Id を取得してください。

ツールリストの取得

音声生成ツールの実行

curl -X POST http://localhost:8001/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "Mcp-Session-Id: YOUR_SESSION_ID" \ -H "X-API-Key: YOUR_API_KEY" \ -d '{ "jsonrpc": "2.0", "method": "tools/call", "params": { "name": "generate_audio", "arguments": { "content": "こんにちは、世界", "language": "ja", "voice_speaker": "Orus", "voice_speed": 1.0 } }, "id": 3 }'

ツール仕様

`generate_audio`

テキストから音声を生成します。

パラメータ:

パラメータ	型	必須	デフォルト	説明
`content`	string	✓	-	音声化するテキスト内容
`language`	enum		`ja`	言語 ( `ja` , `en` , `zh` , `ko` )
`voice_speaker`	string		`Orus`	音声スピーカー名
`voice_speed`	number		`1.0`	音声速度 (0.5-2.0)

レスポンス例:

{ "content": [ { "type": "text", "text": "{\"success\": true, \"project_id\": \"...\", \"status\": \"...\", ...}" } ] }

Nginx リバースプロキシ設定

本番環境では、Nginxをリバースプロキシとして使用することを推奨します。

設定例（/etc/nginx/sites-available/mcp.omotenashiqr.com）：

server { listen 80; server_name mcp.omotenashiqr.com; location / { proxy_pass http://localhost:8001; proxy_http_version 1.1; # WebSocket/SSE対応 proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; # ヘッダー転送 proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; # タイムアウト設定 proxy_read_timeout 300; proxy_connect_timeout 300; proxy_send_timeout 300; } }

SSL設定（Let's Encrypt）：

sudo certbot --nginx -d mcp.omotenashiqr.com

PM2による常駐化（推奨）

本番環境では、PM2を使用してサーバーを常駐させることを推奨します：

# PM2のインストール npm install -g pm2 # サーバーの起動 pm2 start server.mjs --name mcp-omotenashi # 自動起動設定 pm2 startup pm2 save # ログの確認 pm2 logs mcp-omotenashi

トラブルシューティング

サーバーが起動しない

環境変数が正しく設定されているか確認してください
ポート8001が使用可能か確認してください：lsof -i :8001
Node.jsのバージョンを確認してください：node --version (18以上必要)

API呼び出しでエラーが発生する

OMOTENASHI_SESSION_TOKEN が有効か確認してください
BASE_API_URL が正しいか確認してください
サーバーログを確認してください：ログには詳細なエラー情報が出力されます

開発

ローカル開発

# サーバーを起動（開発モード） npm start # 別のターミナルでテスト curl http://localhost:8001/health

ログレベル

サーバーは以下のログレベルでメッセージを出力します：

info: 通常の操作情報
debug: デバッグ情報（API呼び出し詳細など）
error: エラー情報

セキュリティ

API KEY認証: すべてのMCPリクエスト（初期化を除く）にはX-API-Keyヘッダーが必要
セッション管理: 各クライアントに固有のセッションIDが割り当てられます
環境変数: 機密情報は.envファイルで管理（Gitにコミットしない）

ライセンス

ISC

作者

おもてなしQR開発チーム

Omotenashi QR MCP Server