thumbtack-mcp

thumbtack-mcp

非官方的 Thumbtack MCP 服务——搜索本地服务专业人员，并查看其个人资料、评分、评价和资质。

只读且匿名。 Thumbtack 的消费者页面和 GraphQL 端点无需登录即可访问，因此此服务不需要账户、API 密钥或浏览器扩展。它也无法写入：Thumbtack 的写入接口需要登录并通过 reCAPTCHA 验证，任何服务端客户端都无法通过。

Thumbtack 没有面向消费者的公开 API。此服务会读取其服务端渲染的页面和匿名 GraphQL 端点，可能会失效或违反其服务条款。 由 AI（Claude）开发和维护。请自行决定是否使用。

安装

// .mcp.json
{ "mcpServers": { "thumbtack": { "command": "npx", "args": ["-y", "@chrischall/thumbtack-mcp"] } } }

无需配置——没有环境变量。

工具

工具	功能
thumbtack_search_pros	按服务类型和美国 ZIP 邮编搜索专业人员。最多返回 10 条结果，包含评分、评价数量、累计雇用次数、平均响应时间和个人资料 URL。
thumbtack_resolve_service	通过查询 Thumbtack，将较宽泛的服务名称规范化（plumbing → plumbers）。
thumbtack_get_pro	专业人员的个人资料：姓名、描述、所在地、综合评分、资质和内容区块列表。
thumbtack_get_pro_reviews	专业人员个人资料中的评价——星级、作者、日期和文本。
thumbtack_graphql	用于执行任意只读 GraphQL 查询的备用入口。拒绝执行变更操作。
thumbtack_healthcheck	分别探测页面和 GraphQL 接口，并报告响应格式是否仍符合预期；每项探测都会标明 kind，CDN/WAF 拒绝页面会标记为 edge_blocked。

所有读取工具都接受 view: "compact" | "full"，且默认值为 compact。对于 thumbtack_search_pros，该模式使用手写的字段投影；对于 thumbtack_get_pro、thumbtack_get_pro_reviews 和 thumbtack_graphql，该模式会剥离图片 URL，无需了解负载的结构。传入 view: "full" 可获取未经处理的上游记录——它们体积庞大，且大多是跟踪元数据，因此默认提供精简格式。

thumbtack_resolve_service 和 thumbtack_healthcheck 不接受 view：两者本来就只返回少量标量字段，而一个无法产生任何作用的选项不如不提供。

仅用 Shell 的替代方案

skills/thumbtack/ 是一个独立技能，使用纯 curl + jq 覆盖相同接口，无需运行服务进程。适用于单次查询和脚本。

工作原理

三个已验证的接口，均记录在 docs/THUMBTACK-API.md 中：

1. 搜索页面——结果嵌入在 __NEXT_DATA__ 中。
2. 个人资料页面——window.__APOLLO_STATE__（裸 JS 赋值，因此需要提取平衡的大括号内容）以及 schema.org JSON-LD。
3. GraphQL（app.thumbtack.com/graphql）——接受临时的匿名查询；已禁用内省。

阅读这些页面时，有两点容易踩坑：

• JSON-LD 的 @type 是特定服务类型的子类型，而不是 LocalBusiness——水管工的节点类型为 "@type":"Plumber"。应根据结构匹配，而不是类型名称。
• GraphQL 可能返回 HTTP 200，但响应正文中包含 errors[]。 仅凭状态码永远不够。

未涵盖的内容

• 你自己的 Thumbtack 账户（项目、消息、报价）——登录需要通过 reCAPTCHA 验证，因此无法使用服务端密码登录。
• Partner Platform API（developers.thumbtack.com）——该 API 真实存在且有文档，但需要合作伙伴凭据（“Request Access”）才能使用。它面向服务提供方，而非消费者。

开发

npm install
npm run build
npm test            # unit + server-boot smoke tests
npm run test:coverage

覆盖率要求为 100%。

许可证

MIT