Floyd

Floyd MCP Server

AI エージェントに Floyd Engine のスケジュール管理および予約ツールを提供する MCP サーバーです。Model Context Protocol の Streamable HTTP トランスポート上に構築されています。

Engine の API ドキュメントについては、engine リポジトリの docs フォルダーを参照してください。

ツール

ツール	説明
floyd_get_available_slots	サービスの予約可能な時間を確認します
floyd_hold_booking	時間枠を一時的に確保します
floyd_confirm_booking	確保した予約を確定します（ユーザーの明示的な同意が必要です）
floyd_cancel_booking	確保済みまたは確定済みの予約をキャンセルします
floyd_reschedule_booking	予約を別の時間に変更します
floyd_update_booking	予約のメタデータを更新します
floyd_get_booking	予約の詳細とステータスを取得します

セットアップ

pnpm install

環境変数

変数	必須	デフォルト	説明
FLOYD_BASE_URL	いいえ	http://localhost:4000/v1	Floyd Engine のベース URL
PORT	いいえ	3000	HTTP サーバーのポート

使い方

HTTP モード（Streamable HTTP）

pnpm dev

MCP エンドポイント：POST / ヘルスチェック：GET /health

Stdio モード

pnpm dev -- --stdio

認証

Floyd engine で認証が必要な場合、接続するエージェントは以下の方法で API キーを提供します。

1. Authorization: Bearer <token> ヘッダー（推奨）
2. ?token=<value> クエリパラメーター

API キーはリクエストごとに Floyd engine に転送されます。engine で認証が無効になっている場合（セルフホストの場合など）、キーは不要です。

予約フロー

get_available_slots → hold_booking → confirm_booking
                                   ↘ cancel_booking
                                   ↘ reschedule_booking
                                   ↘ update_booking (metadata)

1. 時間枠を取得 — 予約可能な時間を照会し、署名付きの slotId トークンを返します
2. 確保 — slotId（または明示的なフィールド）を使って時間枠を予約します。予約は held 状態で作成されます
3. 確定 — 予約を確定します。userConfirmed: true が必要です
4. キャンセル — 確保済みまたは確定済みの予約を解放します
5. 再スケジュール — 予約の識別情報を維持したまま、別の時間に変更します
6. 更新 — メタデータ（人数や特別なリクエストなど）を追加または置き換えます

開発

pnpm test          # run tests
pnpm typecheck     # type-check
pnpm lint          # eslint
pnpm format        # prettier
pnpm build         # bundle with tsup

本番環境

pnpm build
pnpm start

サーバーは、正常なシャットダウンのために SIGTERM／SIGINT を処理します。Floyd API への HTTP リクエストには 10 秒のタイムアウトが設定されています。