Home Services MCP Server

Un servidor Model Context Protocol de código abierto y autoalojable para el descubrimiento de servicios del hogar, perfiles y reseñas de proveedores, identidad del propietario, solicitudes de reserva y seguimiento de reservas. El servidor proporciona el flujo de trabajo y la interfaz MCP; cada operador proporciona las API, los datos, las credenciales, la marca y el entorno de despliegue.

Este repositorio no contiene datos de clientes, datos de proveedores, claves de API ni endpoints privados de producción. Incluye un respaldo MCP público alojado documentado por conveniencia; los operadores pueden reemplazarlo con su propio endpoint y credenciales para un despliegue totalmente autoalojado.

Qué se incluye

• Transporte MCP HTTP streamable en /mcp (el endpoint raíz también está mapeado para los clientes que lo requieran).

• Flujo de código de autorización OAuth 2.0 con PKCE, cuando se configuran credenciales OAuth.

• Flujos de trabajo de búsqueda de proveedores, detalles, reseñas, perfil del propietario, reserva, trabajo anterior, estado de la reserva y re-reserva.

• Aliases opcionales de herramientas de búsqueda/reserva específicos por categoría.

• Validación de entrada, registro con conciencia de PII, lista de permitidos de hosts de salida, limitación de tasa y comportamiento de interruptor de circuito.

• Desarrollo ASGI local, una imagen Docker genérica y configuración de despliegue AWS SAM/Lambda.

El contrato MCP público es intencionalmente estable. Los operadores pueden reemplazar los backends sin cambiar los nombres de las herramientas visibles para el cliente ni la semántica del flujo de trabajo.

Related MCP server: Home Assistant MCP Server

Inicio rápido

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

El servidor está entonces disponible en http://localhost:8000/mcp.

Antes de abrir una revisión de lanzamiento o de marketplace, ejecuta las comprobaciones en docs/RELEASE_CHECKLIST.md, incluyendo:

python3 scripts/audit_public_release.py

Para una compilación de contenedor:

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

Para AWS SAM, proporciona valores específicos del despliegue mediante anulaciones de parámetros o tu gestor de secretos. No coloques secretos en template.yaml, archivos samconfig, capas de contenedores ni en el control de fuentes.

Configuración

Comienza con .env.example. Las variables de endpoint opcionales vacías deshabilitan la capacidad correspondiente. El relay MCP ascendente es la excepción: por defecto usa el servicio público alojado documentado y se puede anular.

Endpoints principales propiedad del operador:

Las integraciones opcionales incluyen endpoints de notificación, persistencia del operador, webhooks de monitoreo, OAuth y el desafío de verificación de la aplicación OpenAI. Todas las URL y secretos deben ser proporcionados por el operador.

Relay MCP ascendente

Por defecto, el servidor retransmite solicitudes de /upstream/mcp a https://mcp.hirenimbus.com/mcp. Configura UPSTREAM_MCP_URL para usar un servicio MCP controlado por el operador en su lugar. Si el ascendente seleccionado requiere autenticación, configura UPSTREAM_MCP_AUTH_TOKEN; no se incluye ningún token, y la autorización del cliente entrante nunca se reenvía automáticamente.

Revisa el manejo de datos, la retención, los términos y la política de acceso del ascendente seleccionado antes de enviar solicitudes de usuario. Para un despliegue totalmente autoalojado, reemplaza el ascendente predeterminado y configura las API de negocio propiedad del operador.

Seguridad y propiedad de los datos

El servidor es una capa de integración programable, no un procesador de datos con un tenant integrado. Los operadores son responsables de:

• Autorización de API, aislamiento de tenants, retención de datos, copias de seguridad y eliminación;

• almacenamiento de secretos, rotación, alcances de privilegio mínimo y política de red de producción;

• avisos de privacidad, términos, contactos de soporte, requisitos regionales/legales y cualquier divulgación de procesamiento por terceros;

• confirmar que las API configuradas no devuelvan más información personal de la que el cliente MCP necesita.

La configuración de desarrollo predeterminada deja las API de negocio externas vacías. Los despliegues de producción deberían fallar de forma segura cuando una capacidad requerida no está configurada, usar estado compartido duradero para OAuth e idempotencia, y mantener el monitoreo deshabilitado a menos que su endpoint esté configurado explícitamente. Configura AUTH_STATE_TABLE_NAME a una tabla DynamoDB compartida y REQUIRE_DURABLE_STATE=true para cargas de trabajo OAuth o de reservas de múltiples instancias. Sin esos ajustes, el fallback de desarrollo es local al proceso y no proporciona protección de reproducción entre instancias.

Las llamadas de reserva confirmadas aceptan una idempotency_key opcional generada por el cliente. Los clientes deberían reutilizar esa clave después de un tiempo de espera. La API de reserva configurada también debería respetar el mismo campo; el servidor nunca reintenta automáticamente una solicitud de reserva ambigua.

Pruebas

Instala las dependencias de desarrollo y ejecuta:

pytest -q
ruff check .

Las pruebas deben usar mocks o fixtures locales para integraciones externas. No deben llamar a un endpoint de operador en vivo.

Paquete de marketplace

El servidor y las habilidades de flujo de trabajo portables son independientes de cualquier despliegue alojado. Una distribución de primera parte puede añadir un manifiesto de marketplace separado que apunte a su propia URL MCP alojada y a su aplicación con marca, sin poner esos valores en este repositorio.

El flujo de trabajo portable de servicios del hogar está disponible en skills/home-service-concierge/SKILL.md. Su traspaso de aplicación usa el valor APP_LINK configurado por el operador.

Licencia

Licenciado bajo la Apache License 2.0. Los nombres de productos, marcas comerciales, servicios privados e integraciones de operadores no se incluyen como valores predeterminados por este código. El respaldo MCP público alojado documentado es una excepción intencional y no incluye credenciales ni datos de clientes.