家庭服务 MCP 服务器

一个开源、可自托管的模型上下文协议（Model Context Protocol）服务器，用于家庭服务发现、服务商档案与评价、房主身份、预约请求以及预约跟进。该服务器提供工作流和 MCP 接口；各运营商自行提供 API、数据、凭据、品牌和部署环境。

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

包含内容

• 位于 /mcp 的流式 HTTP MCP 传输（根端点也已映射，供需要它的客户端使用）。

• 配置了 OAuth 凭据时，支持带 PKCE 的 OAuth 2.0 授权码流程。

• 服务商搜索、详情、评价、房主档案、预约、历史工单、预约状态和重新预约工作流。

• 可选的按类别区分的查找/预约工具别名。

• 输入验证、感知 PII 的日志记录、出站主机白名单、速率限制和熔断器行为。

• 本地 ASGI 开发、通用 Docker 镜像以及 AWS SAM/Lambda 部署配置。

公共 MCP 契约有意保持稳定。运营商可以在不更改面向客户端的工具名称或工作流语义的情况下替换后端。

Related MCP server: @qasperai/mcp-server

快速开始

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 中继是例外：它默认使用文档化的公共托管服务，并且可以被覆盖。

核心运营商自有端点：

可选集成包括通知端点、运营商持久化、监控 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；档案 PII 和上游持有者凭据保留在服务器端状态存储中。

上游 MCP 中继

默认情况下，服务器将来自 /upstream/mcp 的请求中继到 https://mcp.hirenimbus.com/mcp。设置 UPSTREAM_MCP_URL 以改用运营商控制的 MCP 服务。如果所选上游需要身份验证，请设置 UPSTREAM_MCP_AUTH_TOKEN；不捆绑任何令牌，并且入站客户端授权永远不会被自动转发。

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

安全与数据所有权

该服务器是一个可编程集成层，而不是带有内置租户的数据处理器。运营商负责：

• API 授权、租户隔离、数据保留、备份和删除；

• 密钥存储、轮换、最小权限范围和生产网络策略；

• 隐私声明、条款、支持联系方式、区域/法律要求以及任何第三方处理披露；

• 确认所配置的 API 不会返回超出 MCP 客户端所需的更多个人信息。

默认开发配置将外部业务 API 留空。生产部署应在未配置所需功能时默认拒绝（fail closed），为 OAuth 和幂等性使用持久化共享状态，并且除非显式配置了监控端点，否则保持监控禁用。将 AUTH_STATE_TABLE_NAME 设置为共享 DynamoDB 表，并为多实例 OAuth 或预约工作负载设置 REQUIRE_DURABLE_STATE=true。如果没有这些设置，开发回退是进程本地的，不提供跨实例重放保护。

已确认的预约调用接受可选的客户端生成的 idempotency_key。客户端应在超时后重用该密钥。所配置的预约 API 也应遵循同一字段；服务器永远不会自动重试模糊的预约请求。

测试

安装开发依赖并运行：

pytest -q
ruff check .

测试必须对外部集成使用模拟或本地夹具。它们不得调用实时运营商端点。

市场包

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

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

许可证

根据 Apache License 2.0 许可。产品名称、商标、私有服务和运营商集成不包含在本代码库的默认配置中。文档化的公共托管 MCP 备用端点是一个有意例外，不包含凭据或客户数据。