内容
# BackCrew Housecall Pro MCP 服务器
把这个项目想象成一个员工徽章，而不是万能钥匙。
它允许你将像 Claude 这样的 AI 助手连接到你的 [Housecall Pro](https://www.housecallpro.com/) 账户，这样你可以用纯英文询问事情——“查找这个客户”，“星期二的日程是什么”，“这个发票是否已付”——而不是自己点击 Housecall Pro 网站。要了解更多信息，请访问 [Housecall Pro 官网](https://www.housecallpro.com/)。
## 目录
- [它实际的作用](#它实际的作用)
- [一些术语解释](#一些术语解释)
- [默认情况下如何保持安全](#默认情况下如何保持安全)
- [它可以查询的内容（始终安全）](#它可以查询的内容始终安全)
- [⚠️ 它可以更改的内容（默认关闭）](#⚠️-它可以更改的内容默认关闭)
- [如何设置](#如何设置)
- [连接到 Claude](#连接到-claude)
- [可以尝试的询问](#可以尝试的询问)
- [安全测试](#安全测试)
- [开发者](#开发者)
- [下一步](#下一步)
- [由 BackCrew 构建](#由-backcrew-构建)
- [许可证](#许可证)
## 它实际的作用
准确地说，这不是一个全知的办公助手，它可以理解你的业务并为你处理事情。它是一组特定的、列出的操作——“查找客户”、“安排工作”、“发送发票”——当你用纯英文请求时，AI 助手可以触发这些操作。AI 没有业务判断；它将你请求的内容与列表中最近的操作相匹配，并准确地执行该操作，而不执行其他操作。
## 一些术语解释
- **API** —— “应用程序接口”的缩写。一个进入 Housecall Pro 数据的锁定门，只有软件（不是点击鼠标的人员）才能打开。这个项目是一个可以打开该门的钥匙，以便 AI 可以直接读取和更新你的数据，而无需通过屏幕点击。
- **MCP** —— “模型上下文协议”的缩写。AI 助手（如 Claude）被告知“这里是你可以执行的确切操作，以及如何执行”的标准方式。这个项目遵循该标准，这就是为什么它可以与 Claude（和其他工具）无缝连接，无需自定义设置。
- **服务器** —— 在 Claude 和 Housecall Pro 之间运行的小程序，翻译请求和响应。你启动它并让它运行；你永远不会直接与它交互。
- **存储库** （简称“repo”）—— 整个项目的代码文件夹。“克隆存储库”只是意味着“下载该项目的副本”。
## 默认情况下如何保持安全
顶部的徽章比喻是真正的架构，而不仅仅是一个很好的描述方式：
- **开箱即用，此服务器只能查询。** 它以**只读模式**发货 - 它所做的任何操作都无法在你的 Housecall Pro 账户中创建、更改、删除或发送任何内容，因为这些操作甚至没有启用。如果在默认设置中意外触发写操作的唯一方法是服务器没有向 AI 公开它们。
- **当你准备好更多操作时，你选择一个徽章级别，而不是一个全有或全无的开关。** 启用写访问（`HCP_MCP_MODE=read_write` - 请参见 [设置](#如何设置)）仍然需要选择一个**配置文件**来限制允许的操作：
- `readonly-owner` —— 与默认值相同。仅限查询。
- `office-ops` —— 日常前台工作：预订工作、更新客户、发送发票。**不删除，不作废，不锁定，不设置 webhook/集成** - 即使在此模式下，这些操作仍保持关闭。
- `admin` —— 所有操作，包括删除、作废、锁定工作和技术集成设置（webhooks）。这是唯一一个可能进行难以逆转的操作的级别。
## 它可以查询的内容（始终安全）
这些操作仅读取数据 - 这里的任何内容都无法更改记录、向客户发送内容或导致您运行成本。以下是在默认设置下无需额外步骤即可使用的内容：
| 涵盖内容 | 可以查询的示例 |
| --- | --- |
| 客户 | 搜索、查看个人资料和服务地址 |
| 工作 | 查看工作详情、行项目、使用的材料、时间表 |
| 预约 | 查看预约时间和状态 |
| 估算 | 查看估算及其选项 |
| 发票 | 查看发票、付款状态 |
| 员工 | 查看技术人员和办公室工作人员 |
| 线索 | 查看线索及其来源 |
| 材料和定价 | 查看您的价格簿、材料、服务 |
| 公司信息和时间表 | 查看公司详情、技术人员时间表、日历 |
| 标签 | 查看现有标签 |
共 30 个查询操作。
## ⚠️ 它可以更改的内容（默认关闭）
以下所有内容都可以创建、编辑、发送或删除您 Housecall Pro 账户中的实际内容。**除非您有意启用（请参见 [默认情况下如何保持安全](#默认情况下如何保持安全)），否则这些操作均不可用** - 本节内容仅用于您了解启用后会发生什么，而不是现在实际发生的内容。
**`office-ops` 级别**（日常前台操作）：
| 涵盖内容 | 可以执行的操作示例 |
| --- | --- |
| 客户 | 添加或更新客户、添加服务地址 |
| 工作 | 创建工作、安排工作、分配技术人员、添加行项目/材料/备注、附加文件 |
| 预约 | 创建、重新安排、确认预约 |
| 估算 | 创建估算、添加备注 |
| 发票 | 从工作生成发票、发送给客户 |
| 线索 | 创建/更新线索、添加备注 |
| 材料和定价 | 添加或更新材料 |
| 标签 | 创建或重命名标签 |
**仅限 `admin` 级别**（难以逆转，或技术/集成相关 - 有意与日常办公工作分开）：
- 删除工作的行项目、备注、时间表或标签
- 锁定工作以便不能进一步编辑
- 作废发票
- 删除物料、标签或线索备注
- 与 **webhooks**（向其他软件的技术事件通知）相关的任何操作 - 整个区域仅限管理员，包括查看 webhook 设置，因为它是一个集成/工程问题，而不是日常办公工作。
## 如何设置
您需要：
- 安装了 [Node.js](https://nodejs.org) 的计算机（此项目运行的免费软件）
- Housecall Pro 账户（仅在您准备连接到您实际的账户时需要 - 不需要下载和查看项目）
### 步骤 1：下载项目
打开终端并输入：
```bash
git clone https://github.com/jayson-svg/backcrew-mcp.git
cd backcrew-mcp
npm install
npm run build
```
### 步骤 2：获取您的 Housecall Pro 密钥
1. 登录您的 Housecall Pro 账户
2. 进入 **应用商店 → API 密钥管理 → 生成**
3. 复制为您生成的密钥
Housecall Pro 自己的说明：[Housecall Pro API 文档](https://docs.housecallpro.com)。
### 步骤 3：保存您的密钥并选择安全级别
```bash
cp .env.example .env
```
在任何文本编辑器中打开新的 `.env` 文件：
```bash
HOUSECALL_PRO_API_KEY=请在此处粘贴您的密钥
# 在您阅读完
# “安全测试”并准备好进行比查询更多的操作之前，请保持以下两项不变。
HCP_MCP_MODE=read_only
HCP_MCP_PROFILE=readonly-owner
```
保存文件。**请保密** - 任何拥有您的密钥的人都可以访问您 Housecall Pro 的数据。
## 连接到 Claude
### Claude 桌面版 / Claude 代码
打开 Claude 的设置文件（对于 Claude 桌面版，这是 `claude_desktop_config.json`）并添加：
```json
{
"mcpServers": {
"housecall-pro": {
"command": "node",
"args": ["/绝对路径/to/backcrew-mcp/dist/index.js"],
"env": {
"HOUSECALL_PRO_API_KEY": "您的密钥在此",
"HCP_MCP_MODE": "read_only",
"HCP_MCP_PROFILE": "readonly-owner"
}
}
}
}
```
将 `/绝对路径/to/backcrew-mcp` 替换为您下载项目的位置。
重启 Claude。您应该会看到 Housecall Pro 显示为 Claude 可以使用的内容 - 默认情况下仅限查询操作。
## 可以尝试的询问
在默认（只读）设置下：
- “显示我过去 30 天内创建的所有客户”
- “明天有哪些工作安排？”
- “哪些发票是从上个月开始未付的？”
- “查找 918 Sycamore Court 的客户并显示她的服务历史”
如果您稍后启用 `office-ops`：
- “在 918 Sycamore Court, Round Rock TX 为 Maria Alvarez 建立一个新账户，并标记她为来自 Dave 的推荐”
- “为该客户安排下周二 9 点的工作，并派遣给 Mike”
- “添加一个季度害虫防治项目，费用为 89 美元”
- “将该工作标记为‘白蚁’，并添加备注，说明爬行空间已锁定 - 请提前联系”
## 安全测试
如果您决定启用写访问，请养成几个习惯：
1. **首先以只读模式启动并保持一段时间。** 在您允许 AI 更改任何内容之前，先了解 AI 如何解释您的请求。
2. **当您启用 `office-ops` 时，请先在明显虚假的客户上进行测试。** 创建一个测试客户，名称明显为“ZZZ Test Customer - Do Not Use”，并在该记录上尝试您的第一个写操作，而不是在真实记录上。
3. **永远不要直接进入 `admin` 模式。** 删除、作废和锁定操作难以或无法撤销。`office-ops` 涵盖了实际的日常工作，而不暴露任何这些操作。
4. **永远不要分享您的 API 密钥** - 在聊天、截图、支持票或任何地方。像对待密码一样对待它，因为它具有类似的功能。
5. **如果看起来有问题，请立即切换回 `HCP_MCP_MODE=read_only`。** 单独保证在配置文件设置下不会发生进一步的更改。
## 开发者
本节以下内容假设具备编程背景。
### 工具参考
运行服务器并从任何 MCP 客户端调用 `tools/list` 以查看确切的输入/输出模式 - 每个工具的描述都包括它映射到的 HTTP 方法/路径及其访问级别（例如 `映射到 GET /jobs/{id}/line_items. [级别：readonly-owner]`）。每个域都存在于 [`src/tools/`](src/tools) 下的单独文件中。
## 许可证
[MIT](LICENSE)
