housecallpro-mcp

Housecall Pro MCP

一个 Model Context Protocol 服务，可将 Claude 连接到 Housecall Pro 的客户端——承包商（HVAC、管道、电气、清洁）通过邮件或短信发给你的报价或发票链接。

警告

由 AI 开发的项目。 此代码库由 Claude Code 构建并积极维护。没有人工审核过其实现。使用前请检查所有代码和工具权限。

这是客户端，不是商家端

Housecall Pro 有两个互不相通的部分：

	公共 API	客户门户（本仓库）
主机	api.housecallpro.com	app.housecallpro.com
服务对象	使用 Housecall Pro 的商家	该商家的客户
身份验证	专业人士账户中的 API 密钥	承包商发给你的链接
文档	docs.housecallpro.com	docs/HOUSECALLPRO-API.md

如果你在 Housecall Pro 上经营业务，应使用公共 API。此服务适用于作为他人的客户。

可以做什么

• “我的水管工给我的无水箱冲洗服务报了什么价？”
• “那份报价逐项列了什么？”
• “346 美元中有多少是税费？”
• “我还需要回复这条消息吗？”
• “拒绝选项 2。”

安装

npx -y @chrischall/housecallpro-mcp

使用承包商发给你的链接进行配置：

HOUSECALLPRO_LINK='https://pro.housecallpro.com/mobile_estimate/XXXXXXXXXX'

报价和发票链接都适用，无论短链接还是长链接—— pro.housecall.com/mobile_estimate/… 和 /mobile_invoice/…，或 client.housecall.com/estimates/… 和 /invoices/…。如需配置多份文档：

HOUSECALLPRO_LINKS='[{"label":"tankless","url":"…"},{"label":"hvac","url":"…"}]'

之后，每个工具都可以选择性地传入 link 选择器；配置一个链接后，就无需再传入。

重要

你的链接是持有者凭证。 任何持有该链接的人都可以读取文档；对于报价，还可以拒绝报价。链接从环境中读取，从不记录日志，也不会在工具结果中返回——housecallpro_list_links 只会报告标签。

确认

拒绝报价前会先询问你。能够显示确认提示的客户端（Claude Code）会显示提示。无法显示确认提示的客户端（claude.ai、Claude Desktop）在首次调用时不会拒绝任何报价，而是返回预览和 confirmToken；只有再次调用并提供该令牌时才会执行操作，且仅当报价仍与预览内容一致时才会执行。

变量	默认值
MCP_CONFIRM_MODE	ask-user	对于无法显示确认提示的客户端（claude.ai、Claude Desktop），写入操作的处理方式。ask-user：分两步执行——首次调用不做任何操作，只返回预览和令牌；模型必须先在聊天中征得你的同意，才能再次调用并提供令牌。auto：同样分两步执行，但模型审核预览后可以自行使用令牌。refuse：此类客户端上的写入操作会被拒绝。能够显示提示的客户端（Claude Code）始终会显示实际提示，除非 MCP_CONFIRM_ELICITATION=off。无法识别的值会按 refuse 处理。
MCP_CONFIRM_ELICITATION	on	off 时绝不显示确认提示，因此所有客户端都会遵循 MCP_CONFIRM_MODE 的行为。若某客户端声称可以显示提示，但实际上从不显示（写入操作会挂起——opencode 2.0.x），请设置此项。其他任何值都会按 on 处理，并在 stderr 上显示警告。
MCP_CONFIRM_TTL_SECONDS	600	令牌的有效时长。
MCP_CONFIRM_SECRET	每个进程随机生成	签名密钥；只有在令牌必须在服务重启后继续有效时才设置。

工具

工具
housecallpro_get_estimate	行项目、总额、税费、公司、审批状态
housecallpro_get_invoice	金额、小计、税费、应付余额、是否可付款
housecallpro_get_company	承包商：电话、电子邮件、网站、上门时间范围
housecallpro_list_links	已配置的链接，仅显示标签
housecallpro_decline_estimate	拒绝选项——会先要求你确认
housecallpro_approve_estimate	始终拒绝；说明原因
housecallpro_healthcheck	可访问性 + 链接是否仍能解析

响应格式（view）

housecallpro_get_estimate 和 housecallpro_get_invoice 接受 view: 'compact' | 'raw'，默认值为 compact——来自 @chrischall/mcp-utils 的 fleet 术语。

级别	返回内容
compact (默认)	摘要：行项目、总额、税费、公司、审批状态——金额同时以 *_cents 和 *_usd 返回
raw	上游文档原样返回（估价单约 4.8 KB），包含 {object, data} 包装和显示标志

这里有意不提供 full 级别。full 意味着“此服务了解的所有字段，一个不漏”，而此服务了解的字段恰好就是摘要中列出的字段——因此它只是换了个名字的 compact；再往后的所有内容都是上游文档，也就是 raw。架构绝不应声明一个会悄悄映射为其他值的选项。

如果上游结构变化大到投影无法正常工作，则会返回整个文档（并在 stderr 上发出警告），而不是返回空摘要：空摘要无法与内容为空的估价单区分开来。

估价单和发票是不同的文档

它们使用不同格式的令牌——估价单为 129 个字符，发票为 32 个字符——并且使用不同的端点。客户端会检查格式，并在发起请求前拒绝传给错误工具的令牌，而不是直接返回一个没有解释的 404。

发票不包含行项目，也没有税费字段：已付款的发票在门户中显示为摘要，API 返回的内容也正是如此，因此 tax_usd 是通过 total - subtotal 得出的。is_paid 根据余额判断，而不是根据状态字符串。

金额会以两种形式返回

上游 API 返回整数美分——门户中显示为 $346.39 的估价单，返回值是 total_amount: 34639。直接报告原始值会使每个金额都放大 100 倍，因此每个金额字段都会同时以 *_cents（原样）和 *_usd（换算后）形式输出。tax.rate 是一个分数（0.0825 = 8.25%），绝不会进行换算。

这种成对返回正是投影的用途，因此仅在 compact 中提供。 view: 'raw' 返回的是上游文档，其中的金额为整数美分，不附带美元金额字段——total_amount: 34639 即 $346.39。调用位置对 view 参数的说明已明确指出这一点。

为什么无法批准估价单

housecallpro_approve_estimate 始终拒绝，这是有意为之。

批准操作会提交一个 response_token——这是在页面内针对 estimates_customer_approvals 操作生成的 reCAPTCHA v3 令牌。服务端客户端无法生成该令牌，浏览器桥接传输也无法生成：桥接只会发起 fetch 调用，不会执行页面 JS。拒绝操作不需要此类令牌，因此可以拒绝，但不能批准。

该工具不会提交一个会被拒绝的请求——更糟的是，这类请求或许会成功，使你受报价约束——而是会拒绝操作，并告知你在浏览器中批准。

拒绝操作会先要求你确认（参见确认）：它会读取估价单，拒绝不属于其选项或已处理的 ID，并在提交任何内容之前准确显示将要发送的内容。实际拒绝后，它会重新读取估价单并报告该选项的实际状态，因为 2xx 并不能证明写入已成功生效。

不使用 MCP

skills/housecallpro 使用普通的 curl 和 jq，通过 shell 执行相同的读取操作，适用于未安装该服务的脚本或机器。这里也不涉及浏览器桥接。

无需浏览器桥接

与这个工具集中的许多工具不同，app.housecallpro.com 没有设置机器人拦截——直接使用 curl 就能获得 200。因此，此服务通过 HTTPS 直接与其通信，不依赖 @fetchproxy/server，也无需扩展程序或已登录的标签页，还能轻松作为远程连接器托管——无需配置密钥，因为链接是作为工具参数传递的，而不是作为环境变量传递。

此处未包含的内容

• 付款和银行卡。 有意不纳入范围。
• 账户级门户。 Housecall Pro 提供 OTP／魔法链接客户门户，可查看某个承包商的所有文档，其体验明显优于逐份文档使用链接。搭建该门户需要人工接收一次性验证码，因此这是显而易见的下一步，而非本次初版的一部分。

开发

npm install
npm run build
npm test

许可证

MIT