Home Services MCP Server

Ein Open-Source-, selbst hostbarer Model-Context-Protocol-Server für die Hausservice-Suche, Anbieterprofile und Bewertungen, Hauseigentümeridentität, 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 privaten Produktionsendpunkte. Es enthält der Einfachheit halber einen dokumentierten, öffentlich gehosteten MCP-Fallback; Betreiber können ihn durch ihren eigenen Endpunkt und ihre Anmeldeinformationen ersetzen, um eine vollständig selbst gehostete Bereitstellung zu erreichen.

Was enthalten ist

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

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

• Workflows für Anbietersuche, Details, Bewertungen, Hauseigentümerprofil, Buchung, frühere Aufträge, Buchungsstatus und Wiederbuchung.

• Optionale kategoriespezifische Tool-Aliasse für Finden/Buchen.

• Eingabevalidierung, PII-bewusste Protokollierung, Allowlisting ausgehender Hosts, Ratenbegrenzung und Circuit-Breaker-Verhalten.

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

Der öffentliche MCP-Vertrag ist bewusst stabil. Betreiber können die Backends ersetzen, ohne die für Clients sichtbaren Toolnamen oder die Workflowsemantik zu ändern.

Related MCP server: Home Assistant 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.

Bevor Sie ein Release oder eine Marketplace-Überprüfung anstoßen, führen Sie 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-Overrides oder Ihren Secret Manager bereit. Platzieren Sie keine Geheimnisse in template.yaml- oder samconfig-Dateien, Container-Layern oder der Quellcodeverwaltung.

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.

Vom Betreiber bereitgestellte Kern-Endpunkte:

Optionale Integrationen umfassen Benachrichtigungsendpunkte, Betreiberpersistenz, Monitoring-Webhooks, OAuth und die OpenAI-App-Verifizierungs-Challenge. Alle URLs und Geheimnisse müssen vom Betreiber bereitgestellt werden.

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 stattdessen 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 die eingehende Client-Autorisierung wird niemals automatisch weitergeleitet.

Prüfen Sie die Datenverarbeitung, Aufbewahrung, Bedingungen und Zugriffsrichtlinie des ausgewählten Upstreams, bevor Sie Benutzeranfragen an ihn senden. Ersetzen Sie für eine vollständig selbst gehostete Bereitstellung den Standard-Upstream und konfigurieren Sie die vom Betreiber bereitgestellten Geschäfts-APIs.

Sicherheit und Dateneigentum

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

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

• Geheimnisspeicherung, Rotation, Scopes mit geringsten Rechten und Netzwerkrichtlinie für die Produktion;

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

• die Sicherstellung, dass die konfigurierten APIs nicht mehr persönliche Informationen zurückgeben, als der MCP-Client benötigt.

Die Standardentwicklungskonfiguration lässt externe Geschäfts-APIs leer. Produktionsbereitstellungen sollten bei nicht konfigurierter erforderlicher Funktion standardmäßig verweigern (Fail Closed), dauerhaften gemeinsamen Zustand für OAuth und Idempotenz verwenden und das Monitoring deaktiviert lassen, es sei denn, der zugehörige Endpunkt ist explizit konfiguriert. Setzen Sie AUTH_STATE_TABLE_NAME auf eine gemeinsame DynamoDB-Tabelle und REQUIRE_DURABLE_STATE=true für OAuth- oder Buchungsworkloads mit mehreren Instanzen. Ohne diese Einstellungen ist der Entwicklungs-Fallback prozesslokal und bietet keinen instanzübergreifenden Replay-Schutz.

Buchungsbestätigungsaufrufe akzeptieren einen optionalen, clientseitig generierten idempotency_key. 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 für externe Integrationen Mocks oder lokale Fixtures verwenden. Sie dürfen keinen Live-Endpunkt des Betreibers aufrufen.

Marketplace-Paket

Der Server und die portablen Workflow-Skills sind unabhängig von jeder gehosteten Bereitstellung. Eine First-Party-Distribution kann ein separates Marketplace-Manifest hinzufügen, das auf ihre eigene gehostete MCP-URL und ihre gebrandete App verweist, ohne diese Werte in dieses Repository aufzunehmen.

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

Lizenz

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