ホームサービスMCPサーバー

ホームサービス検索、プロバイダープロフィールとレビュー、住宅所有者の身元確認、予約リクエスト、予約フォローアップのための、オープンソースで自己ホスト可能なModel Context Protocolサーバーです。このサーバーはワークフローとMCPインターフェースを提供し、各オペレーターがAPI、データ、認証情報、ブランディング、デプロイ環境を提供します。

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

含まれるもの

• /mcp でのストリーミングHTTP MCPトランスポート（ルートエンドポイントも、それを必要とするクライアントのためにマッピングされています）。

• OAuth認証情報が設定されている場合の、PKCEを使用したOAuth 2.0認可コードフロー。

• プロバイダー検索、詳細、レビュー、住宅所有者プロフィール、予約、過去のジョブ、予約ステータス、再予約のワークフロー。

• カテゴリ固有の検索・予約ツールのオプションのエイリアス。

• 入力検証、PII対応ロギング、送信ホストの許可リスト、レート制限、サーキットブレーカー動作。

• ローカルASGI開発、汎用Dockerイメージ、AWS SAM/Lambdaデプロイ設定。

公開MCPコントラクトは意図的に安定しています。オペレーターは、クライアント向けのツール名やワークフローセマンティクスを変更することなく、バックエンドを置き換えることができます。

Related MCP server: @qasperai/mcp-server

クイックスタート

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リレーは例外で、文書化された公開ホスト型サービスをデフォルトとし、上書きできます。

オペレーター所有のコアエンドポイント：

オプションの統合には、通知エンドポイント、オペレーター永続化、監視ウェブフック、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トークンは不透明な住宅所有者セッションIDを保持します。プロフィールPIIとアップストリームのベアラー認証情報は、サーバー側の状態ストアに残ります。

アップストリームMCPリレー

デフォルトでは、サーバーは /upstream/mcp からのリクエストを https://mcp.hirenimbus.com/mcp にリレーします。UPSTREAM_MCP_URL を設定して、オペレーター管理のMCPサービスを使用してください。選択したアップストリームが認証を必要とする場合は、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 値を使用します。

ライセンス

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