OnceHub MCP Server

OnceHub MCP サーバー

OnceHub MCP サーバーを使用すると、AI models と agents が OnceHub のスケジューリング API と直接やり取りするための標準的な方法を利用できます。予約リンクをユーザーに送って手動でスケジュールしてもらう代わりに、AI エージェントは MCP ツールを使用し、自然言語のやり取りを通じて空き状況を取得し、ユーザーに代わってミーティングをスケジュールできます。 このソリューションにより、外部 AI エージェントは、標準化された Model Context Protocol（MCP）リモートサーバーを使用する AI 主導のワークフロー内で、OnceHub のスケジューリング API にアクセスできます。

互換性のあるクライアント： VS Code Copilot、OpenAI、および MCP 互換のあらゆる AI クライアント。

目次

• 機能
• クイックスタート
• アーキテクチャ
• ツール
• クライアントの設定
• インストール
• テスト
• 本番環境へのデプロイ
• 貢献
• ライセンス

機能

• 🔌 MCP プロトコルのサポート - MCP 互換のあらゆる AI クライアントで動作します
• 📅 時間枠の取得 - OnceHub の予約カレンダーから予約可能な時間枠を取得します
• 🗓️ ミーティングのスケジュール設定 - ゲスト情報を使ってミーティングを自動的にスケジュールします
• 🔐 セキュアな認証 - ヘッダーを介した API キーベースの認証
• 🧪 十分なテスト - 包括的な単体テストにより、コードカバレッジは 92% です
• 🐳 Docker 対応 - 簡単にデプロイできるコンテナ化構成
• 📝 AI に適したプロンプト - AI アシスタント向けのワークフローガイダンスを内蔵

クイックスタート

AI クライアントで OnceHub MCP サーバーを使い始めましょう。

1. API キーを取得する

認証ドキュメントから OnceHub API キーを取得します。

2. クライアントを設定する

ワークスペースに .vscode/mcp.json を作成します。

{
  "servers": {
    "oncehub": {
      "url": "https://mcp.oncehub.com/sse",
      "type": "http",
      "headers": {
        "authorization": "Bearer YOUR_ONCEHUB_API_KEY"
      }
    }
  }
}

YOUR_ONCEHUB_API_KEY を実際の API キーに置き換えます。

3. 使用を開始する

AI アシスタントに次のように依頼します。

• 「カレンダー BKC-XXXXXXXXXX の予約可能な時間枠を表示して」
• 「明日の午後 2 時に John Doe とのミーティングをスケジュールして」

⚠️ 独自の MCP サーバーを実行しますか？ セットアップ手順については、インストールとローカルでの実行を参照してください。

✅ 本番サーバー： ホスト型 MCP サーバーは https://mcp.oncehub.com/sse で利用できます。

アーキテクチャ

プロジェクト構成

mcp-server/
├── main.py              # MCP server with tool definitions
├── models.py            # Pydantic data schemas for BookingForm and Location
├── pyproject.toml       # Project dependencies and configuration
├── Dockerfile           # Docker image configuration
├── .dockerignore        # Files to exclude from Docker build
└── README.md            # This file

ツール

1. get_booking_time_slots

予約カレンダーから予約可能な時間枠を取得します。

パラメーター：

• calendar_id (str, required)：予約カレンダー ID（例：'BKC-XXXXXXXXXX'）
• start_time (str, optional)：この日時以降の時間枠に絞り込みます。ISO 8601 形式（例：'2026-02-15T09:00:00Z'）
• end_time (str, optional)：この日時までの時間枠に絞り込みます。ISO 8601 形式（例：'2026-02-28T17:00:00Z'）
• timeout (int, default: 30)：リクエストのタイムアウト時間（秒）

レスポンスの例：

{
  "success": true,
  "status_code": 200,
  "calendar_id": "BKC-XXXXXXXXXX",
  "total_slots": 5,
  "data": [
    {"start_time": "2026-02-10T10:00:00Z", "end_time": "2026-02-10T11:00:00Z"},
    {"start_time": "2026-02-10T14:00:00Z", "end_time": "2026-02-10T15:00:00Z"}
  ]
}

2. schedule_meeting

指定した時間枠でミーティングをスケジュールします。時間枠が利用可能であることを確認するため、必ず最初に get_booking_time_slots を呼び出してください。

パラメーター：

• calendar_id (str, 必須)：予約カレンダーの ID（例：'BKC-XXXXXXXXXX'）
• start_time (str, 必須)：利用可能な時間枠の正確な開始時刻（ISO 8601 形式）
• guest_time_zone (str, 必須)：ゲストのタイムゾーン（IANA 形式。例：'America/New_York'、'Europe/London'）
• guest_name (str, 必須)：ゲストの氏名
• guest_email (str, 必須)：確認通知の送信先となるゲストのメールアドレス
• guest_phone (str, 任意)：ゲストの電話番号（E.164 形式。例：'+15551234567'）
• location_type (str, 任意)：ミーティングの形式。'virtual'、'virtual_static'、'physical'、または 'guest_phone'
• location_value (str, 任意)：形式に応じた場所の詳細：
  • virtual：プロバイダー名（例：'zoom'、'google_meet'、'microsoft_teams'）
  • virtual_static：null を使用
  • physical：住所 ID（例：'ADD-XXXXXXXXXX'）
  • guest_phone：電話番号（E.164 形式）
• custom_fields (dict, 任意)：キーと値のペアで指定するカスタムフォームフィールド（例：{"company": "Acme", "interests": ["Demo"]}）
• timeout (int, デフォルト：30)：リクエストのタイムアウト（秒）

応答例：

{
  "success": true,
  "status_code": 200,
  "booking_id": "BKG-123456789",
  "confirmation": {
    "guest_name": "John Doe",
    "guest_email": "[email protected]",
    "scheduled_time": "2026-02-10T10:00:00Z",
    "timezone": "America/New_York"
  }
}

前提条件

• Python 3.13 以降
• uv パッケージマネージャー（推奨）
• OnceHub API キー：API キーの取得方法については、認証に関するドキュメントを参照してください
• OnceHub API エンドポイント URL（通常は https://api.oncehub.com）

環境変数

.env ファイルを作成するか、以下の環境変数を設定してください。

# Required: Your OnceHub API endpoint
ONCEHUB_API_URL=https://api.oncehub.com

# Note: API key is passed via Authorization header from MCP clients
# Do NOT commit API keys to version control

クライアントの設定

この MCP サーバーは、VS Code Copilot、Claude Desktop、OpenAI、その他の MCP 互換クライアントに対応しています。

VS Code / GitHub Copilot

手順 1：設定ディレクトリを作成する

Windows（PowerShell）：

New-Item -Path ".vscode" -ItemType Directory -Force
New-Item -Path ".vscode\mcp.json" -ItemType File -Force

macOS/Linux：

mkdir -p .vscode
touch .vscode/mcp.json

手順 2：サーバーを設定する

.vscode/mcp.json を編集します。

{
  "servers": {
    "oncehub": {
      "url": "http://0.0.0.0:8000/sse",
      "type": "http",
      "headers": {
        "authorization": "Bearer YOUR_ONCEHUB_API_KEY"
      }
    }
  }
}

設定オプション：

• url：MCP サーバーのエンドポイント（セルフホストする場合は、サーバーの URL に変更してください）
• authorization：Bearer プレフィックスを付けた OnceHub API キー
• サーバー名（oncehub）：任意の識別子に変更できます

手順 3：VS Code を再読み込みする

設定を保存したら、VS Code を再読み込みして MCP サーバーへの接続を有効にしてください。

Claude Desktop

Claude Desktop の設定ファイルを編集します。

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json

Windows： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "oncehub": {
      "url": "http://0.0.0.0:8000/sse",
      "headers": {
        "authorization": "Bearer YOUR_ONCEHUB_API_KEY"
      }
    }
  }
}

保存後、Claude Desktop を再起動してください。

その他の MCP クライアント

その他の MCP 互換クライアントでは、以下に接続するように設定してください。

• エンドポイント： http://0.0.0.0:8000/sse
• プロトコル： Server-Sent Events（SSE）を使用する HTTP
• 認証： Authorization ヘッダー内の Bearer トークン

セキュリティに関する注意： API キーをバージョン管理にコミットしないでください。本番環境へのデプロイでは、環境変数または安全なシークレット管理を使用してください。

uv を使ったローカルでのインストールと実行

1. uv をインストールする（まだインストールしていない場合）

Windows（PowerShell）：

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

macOS/Linux：

curl -LsSf https://astral.sh/uv/install.sh | sh

2. リポジトリをクローンする

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

3. 環境変数を設定する

Windows（PowerShell）：

$env:ONCEHUB_API_URL="https://api.oncehub.com"

macOS/Linux：

export ONCEHUB_API_URL="https://api.oncehub.com"

または .env ファイルを作成します：

echo "ONCEHUB_API_URL=https://api.oncehub.com" > .env

注： API キーは MCP クライアントから Authorization ヘッダー経由で渡されます（環境変数としては渡されません）。

4. uv を使ってサーバーを実行する

オプション 1：直接実行

uv run main.py

オプション 2：スクリプトのエントリーポイントを使用

uv run mcp-server

サーバーは http://0.0.0.0:8000 で起動します。

5. サーバーの起動を確認する

ヘルスチェック：

curl http://localhost:8000/health

SSE エンドポイントに接続する：

curl http://localhost:8000/sse

Docker で実行する

Docker イメージをビルドする

docker build -t mcp-server .

コンテナを実行する

docker run -p 8000:8000 mcp-server

環境変数を指定して実行する

docker run -p 8000:8000 \
  -e ONCEHUB_API_URL="https://api.oncehub.com" \
  mcp-server

Docker Compose を使用する（推奨）

docker-compose.yml を作成します：

version: '3.8'
services:
  mcp-server:
    build: .
    ports:
      - "8000:8000"
    environment:
      - ONCEHUB_API_URL=https://api.oncehub.com
    restart: unless-stopped

次に、以下を実行します：

docker-compose up -d

データスキーマ

Location

会議場所の詳細を表します。

フィールド：

• type (str)：場所の種類（「physical」、「virtual」、「phone」）
• value (str)：場所の詳細（住所、URL、電話番号）

ロギング

サーバーには、OnceHub への HTTP リクエストを包括的に記録するロギング機能が含まれています：

• 送信リクエスト（→）
• レスポンスのステータスコード（←）
• リクエスト／レスポンスの本文

ログは、タイムスタンプとログレベルとともにコンソールに出力されます。

API エンドポイント

• GET /health - ヘルスチェックエンドポイント
• GET /healthy - 代替のヘルスチェックエンドポイント
• GET /sse - MCP プロトコル通信向けの Server-Sent Events エンドポイント
• GET /tools - 登録済みの MCP ツールと、その説明、必須パラメーター、入力フィールドの詳細を返します

開発

依存関係を手動でインストールする

uv pip install fastmcp pydantic httpx

テスト用の依存関係をインストールする

uv pip install -e ".[test]"

異なるログレベルで実行する

main.py を編集し、log_level パラメーターを変更します：

asyncio.run(mcp.run_sse_async(host="0.0.0.0", port=8000, log_level="debug"))

使用可能なログレベル：「debug」、「info」、「warning」、「error」、「critical」

テスト

このプロジェクトには、すべてのツールと関数を対象とした包括的な単体テストが含まれています。

テスト用の依存関係をインストールする

# Install test dependencies
uv pip install pytest pytest-asyncio pytest-cov pytest-mock

テストを実行する

すべてのテストを実行する：

uv run pytest

カバレッジレポート付きでテストを実行する：

uv run pytest --cov=. --cov-report=html --cov-report=term

特定のテストファイルを実行する：

uv run pytest test_tools.py

特定のテストクラスを実行する：

uv run pytest test_tools.py::TestGetBookingTimeSlots

特定のテストを実行する：

uv run pytest test_tools.py::TestGetBookingTimeSlots::test_get_time_slots_success

詳細な出力を表示して実行する：

uv run pytest -v

最初の失敗時に停止して実行する：

uv run pytest -x

テストカバレッジ

カバレッジ付きでテストを実行した後、HTML レポートを開きます：

# Windows
start htmlcov/index.html

# macOS
open htmlcov/index.html

# Linux
xdg-open htmlcov/index.html

テストの構成

• test_tools.py - すべてのツール関数を対象とした単体テスト
  • TestGetApiKeyFromContext - API キーの抽出テスト
  • TestGetBookingTimeSlots - 時間枠の取得テスト
  • TestScheduleMeeting - 会議のスケジュール設定テスト

すべてのテストでは、実際の API 呼び出しを避け、テストをすばやく確実に実行できるようにモックを使用します。

本番環境へのデプロイ

セキュリティのベストプラクティス

1. API キーの管理

   • API キーをバージョン管理にコミットしないでください
   • 環境変数またはシークレット管理システムを使用してください
   • API キーを定期的にローテーションしてください

2. ネットワークセキュリティ

   • 本番環境では HTTPS を使用してください（nginx などのリバースプロキシを追加）
   • 不正利用を防ぐためにレート制限を実装してください
   • アクセスを制限するファイアウォールルールを使用してください

3. モニタリング

   • /health エンドポイントを監視して、可用性を確認してください
   • ログ集約（例：ELK スタック、CloudWatch）を設定してください
   • API の応答時間とエラー率を追跡してください

デプロイの選択肢

Docker によるデプロイ

# Build and tag the image
docker build -t oncehub-mcp-server:1.0.0 .

# Run with restart policy
docker run -d \
  --name oncehub-mcp \
  --restart unless-stopped \
  -p 8000:8000 \
  -e ONCEHUB_API_URL="https://api.oncehub.com" \
  oncehub-mcp-server:1.0.0

クラウドへのデプロイ

• AWS：ECS、Fargate、または EC2 と Application Load Balancer を使用します
• Azure：Azure Container Instances または App Service にデプロイします
• GCP：Cloud Run または Google Kubernetes Engine を使用します

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

• デフォルトのタイムアウトは 30 秒です。必要に応じて調整してください
• サーバーは、同時リクエストの処理に asyncio を使用します
• トラフィックの多い状況では、水平スケーリングを検討してください
• データベースやキャッシュを追加する場合は、コネクションプーリングを使用してください

ヘルスモニタリング

# Simple health check script
curl -f http://localhost:8000/health || exit 1

# Docker healthcheck (add to Dockerfile)
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD curl -f http://localhost:8000/health || exit 1

トラブルシューティング

エラー：「API key is required」

ツールの呼び出し時に api_key パラメーターを渡していることを確認してください。

/health でエラー：「404 Not Found」

サーバーが実行中で、ポート 8000 からアクセスできることを確認してください。

/sse でエラー：「405 Method Not Allowed」

SSE エンドポイントでは POST ではなく GET リクエストが必要です。適切な MCP クライアントライブラリを使用するか、GET を指定して curl を使用してください。

OnceHub リクエストのログが表示されない

main.py でロギングが適切に設定されていること、およびサーバーが log_level="info" または "debug" で実行されていることを確認してください。

ライセンス

このプロジェクトは MIT オープンソースライセンスの条項に基づいてライセンスされています。条項の全文については、MIT を参照してください。

サポート

• ドキュメント：OnceHub API ドキュメント
• 問題：GitHub Issues
• MCP プロトコル：Model Context Protocol

謝辞

• FastMCP を使用して構築されています
• Model Context Protocol と互換性があります
• OnceHub API を利用しています

---

Oncehub チームが作成しました