HireNimbus home services MCP

Home Services MCP Server

住宅サービスの検索、事業者プロフィールとレビュー、住宅所有者の本人確認、予約リクエスト、予約後のフォローアップに対応する、オープンソースでセルフホスト可能な Model Context Protocol サーバーです。サーバーはワークフローと MCP インターフェースを提供し、各運営者が API、データ、認証情報、ブランド、デプロイ環境を用意します。

このリポジトリには、顧客データ、事業者データ、API キー、非公開の本番エンドポイントは含まれていません。利便性のため、文書化された公開ホスト型 MCP フォールバックが 1 つ含まれています。完全なセルフホスト型デプロイでは、運営者独自のエンドポイントと認証情報に置き換えられます。

含まれるもの

• /mcp の Streamable HTTP MCP トランスポート（対応が必要なクライアント向けに、ルートエンドポイントもマッピングされています）。
• OAuth 認証情報が設定されている場合の、PKCE を使用した OAuth 2.0 認可コードフロー。
• 事業者の検索、詳細、レビュー、住宅所有者プロフィール、予約、過去の作業、予約状況、再予約のワークフロー。
• カテゴリー固有の検索／予約ツールの別名（任意）。
• 入力の検証、個人を特定できる情報を考慮したログ記録、送信先ホストの許可リスト、レート制限、サーキットブレーカーの動作。
• ローカル ASGI 開発、汎用 Docker イメージ、AWS SAM/Lambda デプロイ設定。

公開 MCP コントラクトは意図的に安定させています。運営者は、クライアント向けのツール名やワークフローの動作を変更せずに、バックエンドを置き換えられます。

クイックスタート

python3.10 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
# The default setup uses the hosted MCP relay. For self-hosting, edit .env
# with your own upstream MCP endpoint, API URLs, and credentials.
uvicorn src.main:app --reload --port 8000

サーバーは http://localhost:8000/mcp で利用できます。

リリースやマーケットプレイスのレビューに進む前に、次を含む docs/RELEASE_CHECKLIST.md のチェック項目を実行してください。

python3 scripts/audit_public_release.py

コンテナーをビルドする場合：

docker build -t home-services-mcp .
docker run --env-file .env -p 8000:8080 home-services-mcp

AWS SAM の場合は、デプロイ固有の値をパラメーターオーバーライドまたはシークレットマネージャー経由で指定してください。template.yaml、samconfig ファイル、コンテナーレイヤー、ソース管理にシークレットを含めないでください。

設定

.env.example から始めてください。任意のエンドポイント変数を空にすると、関連する機能が無効になります。上流 MCP リレーは例外で、文書化された公開ホスト型サービスがデフォルトで設定されており、上書きできます。

運営者が用意する主なエンドポイント：

変数	用途
PROVIDERS_API	事業者検索エンドポイント
COORDS_RESOLVE_API	テキスト／座標の位置情報解決エンドポイント
ZIP_RESOLVE_API	郵便番号の位置情報解決エンドポイント
GEOCODING_API / GEOCODING_API_KEY	任意の住所情報拡充連携
REVIEWS_API	事業者プロフィールとレビューのエンドポイント
BOOKING_API	予約／リクエスト作成エンドポイント
SERVICE_REQUESTS_URL	予約履歴／状況のエンドポイント
SERVICE_REQUESTS_METADATA_URL	通知メタデータ用の任意のエンドポイント
PROFILE_LOOKUP_API	電話番号／プロフィール検索用の任意のエンドポイント
AUTH_WEBHOOK_URL	OTP の送信／検証用の任意のエンドポイント
HOMEOWNER_PROFILE_API	トークンによるプロフィール取得用の任意のエンドポイント
CANCEL_BOOKING_API	認証と所有権の確認を行う、キャンセル用の任意のエンドポイント

任意の連携には、通知エンドポイント、運営者による永続化、モニタリング用 Webhook、OAuth、OpenAI アプリの検証チャレンジが含まれます。すべての URL とシークレットは運営者が指定する必要があります。

OAuth の相互運用性

OAuth が有効な場合、アクセストークンとリフレッシュトークンには別々の ES256 署名キーが使用されます。アクセストークンの公開検証キーは、メタデータの jwks_uri を通じて公開されます。クライアントが使用するホスト型コールバックまたはクレーム済みスキームのコールバックを正確に指定するには、OAUTH_ALLOWED_REDIRECT_URIS を設定してください。ネイティブクライアントは、明示的なポートを任意に指定して、localhost、127.0.0.1、または [::1] の HTTP ループバックコールバックを登録できます。ネイティブアプリは一般にエフェメラルポートにバインドするため、これらを列挙する必要はありません。任意のカスタムスキーム（任意の cursor:// や vscode:// コールバックなど）は、完全な URI が明示的に設定されていない限り拒否されます。動的登録だけでは、プライベートスキームの所有権を証明できないためです。OAUTH_DYNAMIC_CLIENT_REGISTRATION_ENABLED を有効にすると、パブリック PKCE クライアントは /oauth/register から一意で永続化されたクライアント ID を取得できます。従来の設定済みクライアント ID と、未登録の PKCE クライアントも引き続きサポートされます。

OAUTH_CLIENT_SECRET には、暗号学的にランダムな 32 バイト以上の値を使用してください。サーバーはこのシークレットからドメイン分離された ES256 キーを導出します。そのため、ステートレスなインスタンスはリフレッシュトークンの署名に同じキーを再利用することなく、同じアクセストークンキーを公開して検証できます。OAuth トークンには不透明な homeowner セッション ID が含まれます。プロフィールの個人情報と上流のベアラー認証情報は、サーバー側の状態ストアに保持されます。

上流 MCP リレー

デフォルトでは、サーバーは /upstream/mcp からのリクエストを https://mcp.hirenimbus.com/mcp に中継します。運用者が管理する MCP サービスを使用するには、UPSTREAM_MCP_URL を設定してください。選択した上流サービスで認証が必要な場合は、UPSTREAM_MCP_AUTH_TOKEN を設定してください。トークンは同梱されず、受信したクライアントの認証情報が自動的に転送されることはありません。

ユーザーのリクエストを送信する前に、選択した上流サービスのデータ取り扱い、保持、利用規約、アクセス方針を確認してください。完全なセルフホスト型デプロイでは、デフォルトの上流サービスを置き換え、運用者が所有するビジネス API を設定してください。

セキュリティとデータの所有権

このサーバーは、プログラム可能な統合レイヤーであり、組み込みのテナントを持つデータプロセッサーではありません。運用者は、以下の責任を負います。

• API の認可、テナント分離、データ保持、バックアップ、削除。
• シークレットの保管とローテーション、最小権限のスコープ、本番環境のネットワークポリシー。
• プライバシー通知、利用規約、サポート連絡先、地域および法的要件、サードパーティによる処理に関する開示。
• 設定済みの API が、MCP クライアントに必要な範囲を超える個人情報を返さないことの確認。

デフォルトの開発設定では、外部ビジネス API は空のままです。本番環境では、必要な機能が設定されていない場合はフェイルクローズにし、OAuth と冪等性には永続的な共有状態を使用し、エンドポイントを明示的に設定しない限り監視を無効にしてください。複数インスタンスでの OAuth または予約処理では、AUTH_STATE_TABLE_NAME に共有 DynamoDB テーブルを設定し、REQUIRE_DURABLE_STATE=true を設定してください。これらの設定がない場合、開発用フォールバックはプロセス内でのみ有効で、インスタンス間のリプレイ防止機能は提供されません。

確定済みの予約リクエストでは、クライアントが生成する idempotency_key を任意で指定できます。タイムアウト後も、クライアントは同じキーを再利用してください。設定済みの予約 API も同じフィールドを処理する必要があります。サーバーが結果不明の予約リクエストを自動的に再試行することはありません。

テスト

開発用依存関係をインストールして、次を実行してください。

pytest -q
ruff check .

テストでは、外部連携にモックまたはローカルのフィクスチャを使用する必要があります。稼働中の運用者エンドポイントを呼び出してはなりません。

マーケットプレイスパッケージ

サーバーとポータブルなワークフロースキルは、ホスト型デプロイとは独立しています。ファーストパーティの配布では、独自のホスト型 MCP URL とブランド化されたアプリを参照する別個のマーケットプレイスマニフェストを追加できます。これらの値をこのリポジトリに含める必要はありません。

ポータブルなホームサービスのワークフローは、skills/home-service-concierge/SKILL.md で利用できます。このアプリへの引き継ぎでは、運用者が設定した APP_LINK の値を使用します。

ツール

• get_my_profile — すでにサインインしている場合に、保存済みの住宅所有者プロフィール／住所を読み込みます
• search_providers — 専用の find_* カテゴリ以外の、確認済みの専門業者を検索します
• get_provider_details — スラッグで専門業者の詳細なプロフィールを取得します
• get_provider_reviews — 専門業者のレビューを取得します
• create_booking — 専門業者の選択後に、予約内容をプレビュー／送信します
• get_previous_jobs — 過去／進行中の作業を取得します（認証が必要）
• get_booking_status — ID で予約状況を取得します（認証が必要）
• book_same_pro_again — 過去に依頼した専門業者を再予約します（認証が必要）
• cancel_booking — 予約をキャンセルします（認証が必要）
• find_handyman / book_handyman
• find_hvac / book_hvac
• find_plumber / book_plumber
• find_electrician / book_electrician
• find_renovation / book_renovation
• get_more_tools — 専門ツールをさらに見つけます

ライセンス

Apache License 2.0 の下でライセンスされています。製品名、商標、非公開サービス、運営者との統合は、このコードベースのデフォルトには含まれていません。文書化されている公開ホスト型 MCP のフォールバックは意図的な例外であり、認証情報や顧客データは含まれていません。