Home Services MCP Server

Un servidor de Model Context Protocol de código abierto y autoalojable para el descubrimiento de servicios para el 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 APIs, 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 de producción privados. Incluye un respaldo MCP público alojado y documentado por conveniencia; los operadores pueden reemplazarlo con su propio endpoint y credenciales para un despliegue totalmente autoalojado.

Qué se incluye

• Transporte MCP HTTP transmisible en /mcp (el endpoint raíz también está mapeado para 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 reserva y re-reserva.

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

• Validación de entrada, registro consciente de PII, lista blanca de hosts salientes, limitación de tasa y comportamiento de interruptor de circuito.

• Desarrollo ASGI local, 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: @qasperai/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, ejecute 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, proporcione valores específicos del despliegue mediante anulaciones de parámetros o su administrador de secretos. No coloque secretos en template.yaml, archivos samconfig, capas de contenedor ni en el control de versiones.

Configuración

Comience con .env.example. Las variables de endpoint opcionales vacías deshabilitan la capacidad relacionada. La excepción es el relay MCP ascendente: 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 URLs y secretos deben ser proporcionados por el operador.

Interoperabilidad OAuth

Cuando OAuth está habilitado, los tokens de acceso y de actualización usan claves de firma ES256 separadas; la clave pública de verificación del token de acceso se expone a través del jwks_uri de los metadatos. Establezca OAUTH_ALLOWED_REDIRECT_URIS a las devoluciones de llamada exactas alojadas o de esquema reclamado que usen sus clientes. Los clientes nativos pueden registrar devoluciones de llamada de bucle local en localhost, 127.0.0.1 o [::1] con cualquier puerto explícito; estas no necesitan enumerarse porque las aplicaciones nativas suelen vincular un puerto efímero. Otros esquemas personalizados (incluidas devoluciones de llamada arbitrarias cursor:// o vscode://) se rechazan a menos que su URI completa esté configurada explícitamente, ya que el registro dinámico por sí solo no demuestra la propiedad de un esquema privado. Habilite OAUTH_DYNAMIC_CLIENT_REGISTRATION_ENABLED para que los clientes PKCE públicos obtengan identificadores de cliente únicos y persistidos desde /oauth/register; el identificador de cliente configurado heredado y los clientes PKCE no registrados siguen siendo compatibles.

Use al menos 32 bytes criptográficamente aleatorios para OAUTH_CLIENT_SECRET. El servidor deriva claves ES256 separadas por dominio de ese secreto, de modo que las instancias sin estado publican y verifican la misma clave de token de acceso sin reutilizarla para firmas de tokens de actualización. Los tokens OAuth llevan un identificador de sesión de propietario opaco; la PII del perfil y las credenciales de portador ascendentes permanecen en el almacén de estado del lado del servidor.

Relay MCP ascendente

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

Revise el manejo de datos, retención, términos y política de acceso del ascendente seleccionado antes de enviarle solicitudes de usuario. Para un despliegue totalmente autoalojado, reemplace el ascendente predeterminado y configure las APIs comerciales 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 inquilino integrado. Los operadores son responsables de:

• Autorización de API, aislamiento de inquilinos, 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 APIs configuradas no devuelven más información personal de la que el cliente MCP necesita.

La configuración de desarrollo predeterminada deja vacías las APIs comerciales externas. 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. Establezca 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 respaldo 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 deben reutilizar esa clave después de un tiempo de espera. La API de reserva configurada también debería honrar el mismo campo; el servidor nunca reintenta automáticamente una solicitud de reserva ambigua.

Pruebas

Instale las dependencias de desarrollo y ejecute:

pytest -q
ruff check .

Las pruebas deben usar mocks o accesorios 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 portátiles son independientes de cualquier despliegue alojado. Una distribución de primera parte puede agregar un manifiesto de marketplace separado que apunte a su propia URL MCP alojada y aplicación de marca, sin poner esos valores en este repositorio.

El flujo de trabajo portátil de servicios para el 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. Nombres de productos, marcas comerciales, servicios privados e integraciones de operadores no se incluyen como valores predeterminados en este código. El respaldo MCP público alojado documentado es una excepción intencional y no incluye credenciales ni datos de clientes.