Banbury Cloud MCP Server

Banbury Cloud MCP Server

LLM および AI アプリケーションに Banbury のバックエンドサービスへのアクセスを提供する、Model Context Protocol（MCP）サーバーです。

クイックスタート

フロントエンドとの統合（HTTP モード）

# Run on default port 3001
./run-http.sh

# Run on custom port
./run-http.sh 8080

次に、フロントエンドの .env に追加します。

REACT_APP_MCP_SERVER_URL=http://localhost:3001

Claude Desktop（Stdio モード）

# Default stdio mode
./run.sh

Claude Desktop の設定に追加します。

{
  "mcpServers": {
    "banbury-mcp": {
      "command": "/path/to/banbury-mcp-server/run.sh"
    }
  }
}

トランスポートモード

HTTP トランスポート

• 用途：フロントエンドとの統合、Web アプリケーション、API アクセス
• ポート：設定可能（デフォルト：3001）
• エンドポイント：
  • POST /tool - MCP ツールを実行します
  • GET /health - サーバーのヘルス状態と情報を取得します

Stdio トランスポート

• 用途：Claude Desktop、プロセスとの直接通信
• 通信：stdin/stdout
• 統合：MCP クライアントライブラリ

環境変数

# Transport mode: 'http' or 'stdio' (default: stdio)
export MCP_TRANSPORT=http

# HTTP port (default: 3001)  
export MCP_HTTP_PORT=8080

# Banbury environment: 'dev' or 'prod' (default: dev)
export BANBURY_ENV=dev

利用可能なツール

認証

• banbury-login - Banbury の認証情報で認証します

デバイス管理

• banbury-get-device-info - デバイス情報を取得します
• banbury-update-device - デバイスデータを更新します
• banbury-declare-online - デバイスをオンライン状態として登録します

ファイル管理

• banbury-get-files - 指定したパスのファイルを取得します
• banbury-get-scanned-folders - スキャン済みフォルダーの一覧を取得します

タスク管理

• banbury-get-sessions - ユーザーセッションを取得します
• banbury-add-task - 新しいタスクを追加します

モデル管理

• banbury-add-model - デバイスにモデルを追加します

ユーティリティツール

• add - 簡単な加算（テスト用）
• get-joke - ランダムなジョーク（エンターテインメント用）

使用例

HTTP モード

# Health check
curl http://localhost:3001/health

# Get a joke
curl -X POST http://localhost:3001/tool \
  -H "Content-Type: application/json" \
  -d '{"tool": "get-joke", "parameters": {}}'

# Login to Banbury  
curl -X POST http://localhost:3001/tool \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "banbury-login", 
    "parameters": {
      "username": "your-username",
      "password": "your-password",
      "environment": "dev"
    }
  }'

# Get device info using Authorization header
curl -X POST http://localhost:3001/tool \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-auth-token" \
  -d '{
    "tool": "banbury-get-device-info",
    "parameters": {
      "device_name": "your-device",
      "environment": "dev"
    }
  }'

# Get device info using X-API-Key and Authorization Bearer headers
curl -X POST http://localhost:3001/tool \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-auth-token" \
  -H "X-API-Key: your-mcp-server-api-key" \
  -d '{
    "tool": "banbury-get-device-info",
    "parameters": {
      "device_name": "your-device",
      "environment": "dev"
    }
  }'

# Get device info using parameters (legacy method)
curl -X POST http://localhost:3001/tool \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "banbury-get-device-info",
    "parameters": {
      "token": "your-auth-token", 
      "apiKey": "your-api-key",
      "device_name": "your-device",
      "environment": "dev"
    }
  }'

フロントエンドとの統合

MCP サーバーは Banbury フロントエンドとシームレスに統合されます。

1. 環境変数を設定します：REACT_APP_MCP_SERVER_URL=http://localhost:3001
2. フロントエンドは保存済みの Banbury 認証情報を自動的に使用します
3. すべてのリクエストに認証ヘッダーが自動的に含まれます：
   • X-Auth-Token：ユーザーの Banbury トークン
   • X-Username：ユーザーの Banbury ユーザー名
   • Authorization：MCP サーバーの API キー（設定されている場合）
4. AI との会話で Banbury ツールを自然に呼び出せます
5. リアルタイムのステータスインジケーターに接続状態と認証状態が表示されます

開発

プロジェクト構成

banbury-mcp-server/
├── main.ts           # Main server code
├── run.sh           # Stdio mode runner
├── run-http.sh      # HTTP mode runner  
├── package.json     # Dependencies
└── README.md        # Documentation

新しいツールの追加

1. main.ts にツール定義を追加します。

server.tool("my-new-tool", {
  token: z.string(),
  my_param: z.string(),
  environment: z.enum(['dev', 'prod']).default('dev')
}, async ({ token, my_param, environment }) => {
  // Implementation
});

2. HTTP ハンドラーのケースを追加します。

case 'my-new-tool':
  result = await handleMyNewTool(parameters);
  break;

テスト

# Install dependencies
npm install

# Run in development
npm run dev

# Type checking
npm run type-check

セキュリティ

• Banbury API の呼び出しにはすべて認証トークンが必要です
• フロントエンドとの統合用に CORS が有効になっています
• 機密データはログに記録されたり、キャッシュされたりしません
• トークンの検証は Banbury バックエンドが処理します

トラブルシューティング

接続の問題

• サーバーが起動していることを確認します：curl http://localhost:3001/health
• HTTP モードのファイアウォール設定を確認します
• Banbury バックエンドの URL にアクセスできることを確認します

認証エラー

• Banbury の認証情報が有効であることを確認します
• トークンが期限切れになっていないことを確認します
• 適切な環境（dev/prod）が選択されていることを確認します

ツール実行エラー

• 詳細なエラーメッセージについては、サーバーログを確認します
• 必須パラメーターが指定されていることを確認します
• トークンに適切な権限があることを確認します

詳しくは、サーバーログまたは Banbury フロントエンド統合ガイドを確認してください。

認証方法

MCP サーバーは複数の認証方法を次の優先順位でサポートしています。

1. Authorization ヘッダー：Authorization: Bearer <token>（最優先 — axios のグローバルヘッダーに準拠）
2. X-Auth-Token ヘッダー：X-Auth-Token: <token>（フォールバック）
3. X-API-Key ヘッダー：X-API-Key: <api-key>（MCP サーバーの API キー用）
4. X-Username ヘッダー：X-Username: <username>（ユーザーコンテキスト用）
5. リクエストパラメーター：パラメーターオブジェクトに token および／または apiKey を含めます（レガシー）

フロントエンドは axios のグローバルヘッダー実装と同じ方式に従い、Authorization: Bearer <token> ヘッダーを介して Banbury ユーザートークンを自動的に送信します。