Home Services MCP Server

Ein quelloffener, selbst hostbarer Model Context Protocol Server für die Suche nach Hausdienstleistungen, Anbieterprofilen und Bewertungen, die Identität von Hausbesitzern, Buchungsanfragen und Buchungsnachverfolgung. Der Server stellt den Workflow und die MCP-Schnittstelle bereit; jeder Betreiber liefert die APIs, Daten, Anmeldeinformationen, das Branding und die Bereitstellungsumgebung.

Dieses Repository enthält keine Kundendaten, Anbieterdaten, API-Schlüssel oder private Produktionsendpunkte. Es enthält einen dokumentierten öffentlich gehosteten MCP-Fallback für den Komfort; Betreiber können ihn durch ihren eigenen Endpunkt und ihre eigenen Anmeldeinformationen für eine vollständig selbst gehostete Bereitstellung ersetzen.

Was enthalten ist

• Streamable HTTP MCP-Transport unter /mcp (der Root-Endpunkt ist ebenfalls für Clients zugeordnet, die ihn benötigen).

• OAuth-2.0-Autorisierungscode-Flow mit PKCE, wenn OAuth-Anmeldeinformationen konfiguriert sind.

• Anbietersuche, Details, Bewertungen, Hausbesitzerprofil, Buchung, frühere Aufträge, Buchungsstatus und Umbuchungs-Workflows.

• Optionale kategoriespezifische Find-/Book-Tool-Aliase.

• Eingabevalidierung, PII-bewusste Protokollierung, Allowlisting für ausgehende Hosts, Ratenbegrenzung und Circuit-Breaker-Verhalten.

• Lokale ASGI-Entwicklung, ein generisches Docker-Image und AWS-SAM/Lambda- Bereitstellungskonfiguration.

Der öffentliche MCP-Vertrag ist absichtlich stabil. Betreiber können die Backends ersetzen, ohne die clientseitigen Toolnamen oder die Workflowsemantik zu ändern.

Related MCP server: @qasperai/mcp-server

Schnellstart

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

Der Server ist dann unter http://localhost:8000/mcp verfügbar.

Führen Sie vor der Veröffentlichung einer Release- oder Marktplatz-Überprüfung die Prüfungen in docs/RELEASE_CHECKLIST.md aus, einschließlich:

python3 scripts/audit_public_release.py

Für einen Container-Build:

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

Für AWS SAM stellen Sie bereitstellungsspezifische Werte über Parameterüberschreibungen oder Ihren Secret Manager bereit. Legen Sie keine Geheimnisse in template.yaml, samconfig-Dateien, Container-Layer oder Quellcodeverwaltung ab.

Konfiguration

Beginnen Sie mit .env.example. Leere optionale Endpunktvariablen deaktivieren die zugehörige Funktion. Das Upstream-MCP-Relay ist die Ausnahme: Es verwendet standardmäßig den dokumentierten öffentlich gehosteten Dienst und kann überschrieben werden.

Kern-Endpunkte im Besitz des Betreibers:

Optionale Integrationen umfassen Benachrichtigungs-Endpunkte, Betreiberpersistenz, Überwachungs-Webhooks, OAuth und die OpenAI-App-Verifizierungsherausforderung. Alle URLs und Geheimnisse müssen vom Betreiber bereitgestellt werden.

OAuth-Interoperabilität

Wenn OAuth aktiviert ist, verwenden Zugriffs- und Aktualisierungstokens getrennte ES256-Signaturschlüssel; der öffentliche Verifikationsschlüssel für Zugriffstokens wird über die Metadaten-jwks_uri bereitgestellt. Setzen Sie OAUTH_ALLOWED_REDIRECT_URIS auf die genauen gehosteten oder beanspruchten Schema-Callbacks, die Ihre Clients verwenden. Native Clients können HTTP-Loopback-Callbacks auf localhost, 127.0.0.1 oder [::1] mit einem beliebigen expliziten Port registrieren; diese müssen nicht aufgezählt werden, da native Apps häufig einen ephemeren Port binden. Andere benutzerdefinierte Schemas (einschließlich beliebiger cursor://- oder vscode://-Callbacks) werden abgelehnt, sofern ihre vollständige URI nicht explizit konfiguriert ist, da eine dynamische Registrierung allein keinen Besitz eines privaten Schemas beweist. Aktivieren Sie OAUTH_DYNAMIC_CLIENT_REGISTRATION_ENABLED, damit öffentliche PKCE-Clients eindeutige persistente Client-IDs von /oauth/register erhalten; die veraltete konfigurierte Client-ID und nicht registrierte PKCE-Clients bleiben unterstützt.

Verwenden Sie mindestens 32 kryptografisch zufällige Bytes für OAUTH_CLIENT_SECRET. Der Server leitet domänengetrennte ES256-Schlüssel aus diesem Geheimnis ab, sodass zustandslose Instanzen denselben Zugriffstoken-Schlüssel veröffentlichen und verifizieren, ohne ihn für Aktualisierungstoken-Signaturen wiederzuverwenden. OAuth-Tokens tragen eine undurchsichtige Hausbesitzer-Sitzungs-ID; Profil-PII und Upstream-Bearer- Anmeldeinformationen bleiben im serverseitigen Zustandsspeicher.

Upstream-MCP-Relay

Standardmäßig leitet der Server Anfragen von /upstream/mcp an https://mcp.hirenimbus.com/mcp weiter. Setzen Sie UPSTREAM_MCP_URL, um einen vom Betreiber kontrollierten MCP-Dienst zu verwenden. Wenn der ausgewählte Upstream eine Authentifizierung erfordert, setzen Sie UPSTREAM_MCP_AUTH_TOKEN; es ist kein Token enthalten, und eingehende Client-Autorisierung wird niemals automatisch weitergeleitet.

Überprüfen Sie die Datenverarbeitung, Aufbewahrung, Bedingungen und Zugriffsrichtlinie des ausgewählten Upstreams, bevor Sie Benutzeranfragen an ihn senden. Für eine vollständig selbst gehostete Bereitstellung ersetzen Sie den Standard-Upstream und konfigurieren Sie die betreiberseigenen Geschäfts-APIs.

Sicherheit und Dateneigentum

Der Server ist eine programmierbare Integrationsschicht, kein Datenverarbeiter mit einem integrierten Mandanten. Betreiber sind verantwortlich für:

• API-Autorisierung, Mandantenisolierung, Datenaufbewahrung, Backups und Löschung;

• Geheimnisspeicherung, Rotation, Scopes mit geringsten Rechten und Produktionsnetzwerkrichtlinie;

• Datenschutzhinweise, Bedingungen, Support-Kontakte, regionale/rechtliche Anforderungen und Offenlegungen zur Verarbeitung durch Dritte;

• Bestätigung, dass konfigurierte APIs nicht mehr persönliche Informationen zurückgeben, als der MCP-Client benötigt.

Die Standard-Entwicklungskonfiguration lässt externe Geschäfts-APIs leer. Produktionsbereitstellungen sollten bei fehlender konfigurierter erforderlicher Funktion geschlossen ausfallen, dauerhaften gemeinsamen Zustand für OAuth und Idempotenz verwenden und die Überwachung deaktiviert lassen, sofern ihr Endpunkt nicht explizit konfiguriert ist. Setzen Sie AUTH_STATE_TABLE_NAME auf eine gemeinsame DynamoDB-Tabelle und REQUIRE_DURABLE_STATE=true für Multi-Instanz-OAuth- oder Buchungsworkloads. Ohne diese Einstellungen ist der Entwicklungs-Fallback prozesslokal und bietet keinen Schutz vor Wiederholungen über Instanzen hinweg.

Bestätigte Buchungsaufrufe akzeptieren einen optionalen clientgenerierten Idempotenzschlüssel. Clients sollten diesen Schlüssel nach einem Timeout wiederverwenden. Die konfigurierte Buchungs-API sollte dasselbe Feld ebenfalls berücksichtigen; der Server wiederholt eine mehrdeutige Buchungsanfrage niemals automatisch.

Testen

Installieren Sie die Entwicklungsabhängigkeiten und führen Sie aus:

pytest -q
ruff check .

Tests müssen Mocks oder lokale Fixtures für externe Integrationen verwenden. Sie dürfen keinen Live-Betreiber-Endpunkt aufrufen.

Marktplatz-Paket

Der Server und die portablen Workflow-Skills sind unabhängig von einer gehosteten Bereitstellung. Eine Erstanbieter-Distribution kann ein separates Marktplatz-Manifest hinzufügen, das auf seine eigene gehostete MCP-URL und seine gebrandete App verweist, ohne diese Werte in dieses Repository zu legen.

Der portable Hausdienstleistungs-Workflow ist unter skills/home-service-concierge/SKILL.md verfügbar. Seine App-Übergabe verwendet den vom Betreiber konfigurierten APP_LINK-Wert.

Lizenz

Lizenziert unter der Apache License 2.0. Produktnamen, Marken, private Dienste und Betreiberintegrationen sind nicht als Standardwerte in diesem Codebase enthalten. Der dokumentierte öffentlich gehostete MCP-Fallback ist eine absichtliche Ausnahme und enthält keine Anmeldeinformationen oder Kundendaten.