Home Services MCP Server

オープンソースで自己ホスト可能な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: Home Assistant 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とシークレットはオペレーターが提供する必要があります。

アップストリーム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 値を使用します。

ライセンス

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