Home Services MCP Server

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

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

包含内容

• 在 /mcp 处提供可流式传输的 HTTP MCP 传输（根端点也映射给需要它的客户端）。

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

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

• 可选的按类别查找/预订工具别名。

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

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

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

Related MCP server: Home Assistant 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 和密钥必须由运营商提供。

上游 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 表，并为多实例 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 回退是一个有意的例外，不包含凭据或客户数据。