HireNimbus home services MCP

Home Services MCP 服务

一个开源、可自托管的 Model Context Protocol 服务，用于发现家居服务、查看服务商资料和评价、管理房主身份、提交预约请求以及跟进预约。该服务提供工作流和 MCP 接口；各运营方自行提供 API、数据、凭据、品牌信息和部署环境。

此代码库不包含客户数据、服务商数据、API 密钥或私有生产端点。为方便使用，其中包含一个有文档说明的公共托管 MCP 备用服务；运营方可将其替换为自己的端点和凭据，以实现完全自托管部署。

包含内容

• 在 /mcp 提供 Streamable HTTP MCP 传输（也映射了根端点，以兼容需要该端点的客户端）。
• 配置 OAuth 凭据后，支持 OAuth 2.0 授权码流程和 PKCE。
• 服务商搜索、详情、评价、房主资料、预约、历史服务、预约状态和重新预约工作流。
• 可选的特定类别查找/预约工具别名。
• 输入验证、考虑 PII 的日志记录、出站主机白名单、速率限制和断路器行为。
• 本地 ASGI 开发、通用 Docker 镜像以及 AWS SAM/Lambda 部署配置。

公共 MCP 契约有意保持稳定。运营方可以替换后端，无需更改面向客户端的工具名称或工作流语义。

快速开始

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 中继是例外：它默认使用有文档说明的公共托管服务，也可覆盖。

由运营方管理的核心端点：

变量	用途
PROVIDERS_API	服务商搜索端点
COORDS_RESOLVE_API	文本/坐标位置解析器
ZIP_RESOLVE_API	邮政编码位置解析器
GEOCODING_API / GEOCODING_API_KEY	可选的地址补充集成
REVIEWS_API	服务商资料和评价端点
BOOKING_API	预约/请求创建端点
SERVICE_REQUESTS_URL	预约历史/状态端点
SERVICE_REQUESTS_METADATA_URL	可选的通知元数据端点
PROFILE_LOOKUP_API	可选的电话/资料查询端点
AUTH_WEBHOOK_URL	可选的 OTP 发送/验证端点
HOMEOWNER_PROFILE_API	可选的按令牌查询资料端点
CANCEL_BOOKING_API	可选的、经过身份验证且强制执行所有权校验的取消端点

可选集成包括通知端点、运营方持久化、监控 Webhook、OAuth 以及 OpenAI 应用验证质询。所有 URL 和密钥均须由运营方提供。

OAuth 互操作性

启用 OAuth 后，访问令牌和刷新令牌会使用不同的 ES256 签名密钥；访问令牌的公钥验证密钥通过元数据 jwks_uri 公开。将 OAUTH_ALLOWED_REDIRECT_URIS 设置为客户端使用的确切托管回调或自定义协议回调。原生客户端可以注册使用 localhost、127.0.0.1 或 [::1] 的 HTTP 本地回环回调，并指定任意显式端口；这些回调无需逐一列出，因为原生应用通常会绑定临时端口。其他自定义协议（包括任意 cursor:// 或 vscode:// 回调）都会被拒绝，除非完整 URI 已明确配置，因为仅凭动态注册无法证明对私有协议的所有权。启用 OAUTH_DYNAMIC_CLIENT_REGISTRATION_ENABLED，即可让公开 PKCE 客户端通过 /oauth/register 获取唯一且持久化的客户端 ID；仍支持旧版已配置的客户端 ID 和未注册的 PKCE 客户端。

OAUTH_CLIENT_SECRET 至少应包含 32 个密码学安全的随机字节。服务器会根据此密钥派生出具有域分离的 ES256 密钥，使无状态实例发布并验证相同的访问令牌密钥，同时不会将其用于刷新令牌签名。OAuth 令牌包含不透明的房主会话 ID；个人资料中的个人身份信息和上游承载凭据则保留在服务器端状态存储中。

上游 MCP 中继

默认情况下，服务器会将 /upstream/mcp 的请求中继到 https://mcp.hirenimbus.com/mcp。将 UPSTREAM_MCP_URL 设置为使用由运营方控制的 MCP 服务。如果所选上游需要身份验证，请设置 UPSTREAM_MCP_AUTH_TOKEN；此处不会附带令牌，也不会自动转发传入客户端的授权信息。

在向所选上游发送用户请求之前，请查看其数据处理、保留、条款和访问政策。对于完全可自托管的部署，请替换默认上游并配置由运营方拥有的业务 API。

安全与数据所有权

该服务器是可编程集成层，并非内置租户的数据处理方。运营方负责：

• API 授权、租户隔离、数据保留、备份和删除；
• 密钥存储、轮换、最小权限范围和生产网络策略；
• 隐私声明、条款、支持联系方式、区域／法律要求，以及任何第三方数据处理披露；
• 确认已配置的 API 返回的个人信息不会超出 MCP 客户端所需范围。

默认开发配置不会配置外部业务 API。生产部署应在所需功能未配置时默认拒绝请求，为 OAuth 和幂等性使用持久化共享状态，并且除非明确配置了监控端点，否则应禁用监控。将 AUTH_STATE_TABLE_NAME 设置为共享 DynamoDB 表，并将 REQUIRE_DURABLE_STATE=true，以支持多实例 OAuth 或预订工作负载。未设置这些值时，开发环境的备用方案仅在进程本地运行，不提供跨实例重放保护。

已确认的预订调用可接受可选的客户端生成的 idempotency_key。发生超时后，客户端应重复使用该键。已配置的预订 API 也应遵循相同字段；对于结果不确定的预订请求，服务器绝不会自动重试。

测试

安装开发依赖并运行：

pytest -q
ruff check .

测试必须使用外部集成的模拟或本地测试夹具。不得调用运营方的线上端点。

Marketplace 包

服务器和可移植工作流技能独立于任何托管部署。第一方发行版可以添加单独的 Marketplace 清单，指向其自有的托管 MCP URL 和品牌应用，而无需将这些值放入此代码库。

可移植的家庭服务工作流位于 skills/home-service-concierge/SKILL.md。 其应用交接使用运营方配置的 APP_LINK 值。

工具

• get_my_profile — 已登录时加载已保存的房主个人资料／地址
• search_providers — 在专用 find_* 类别之外搜索经过验证的专业服务人员
• get_provider_details — 按 slug 获取完整的服务人员个人资料
• get_provider_reviews — 获取服务人员的评价
• create_booking — 选定专业服务人员后预览／提交预约
• get_previous_jobs — 过往／进行中的工作（需身份验证）
• get_booking_status — 按 id 查询预约状态（需身份验证）
• book_same_pro_again — 再次预约之前的专业服务人员（需身份验证）
• cancel_booking — 取消预约（需身份验证）
• find_handyman / book_handyman
• find_hvac / book_hvac
• find_plumber / book_plumber
• find_electrician / book_electrician
• find_renovation / book_renovation
• get_more_tools — 探索其他专用工具

许可证

根据 Apache License 2.0 授权。本代码库默认不包含产品名称、商标、 私有服务和运营方集成。文档中说明的公共托管 MCP 备用方案是有意保留的 例外，不包含凭据或客户数据。