内容
# hawksoft-mcp
**模型上下文协议（MCP）服务器，适用于 [HawkSoft](https://www.hawksoft.com/) 保险机构管理。**
通过 Claude、Cursor 或任何 MCP 客户端与您的 HawkSoft 数据进行交互 - 读取客户、保单和索赔，并以纯英文写入日志笔记、附件和收据。
基于 [HawkSoft 合作伙伴 API v3.0](https://partner.hawksoft.app/v3/api.html) 构建。HawkSoft 没有现成的 MCP 服务器 - 这是第一个。
## 功能
```
你可以： "显示自星期一以来修改过的所有 HawkSoft 客户，并按保险公司分组。"
Claude： *调用 list_changed_clients，然后为每个客户调用 get_client，然后总结*
你可以： "查找保单 POR83741 并记录与被保险人关于其续期的电话。"
Claude： *按保单搜索 → 打开客户 → 调用 create_log_note，通道=5*
```
代理商擅长的其他功能：
- 会前简报 - 在电话之前提取客户的完整历史记录（保单、索赔、之前的对话）
- 自动记录保险公司接触点 - 与保险公司的每次电子邮件/电话都成为结构化的日志记录
- 批量活动报告 - “给我一份每周的客户电话总结”
- 保险证书/声明页面接收 - 直接将 PDF 附件到正确的客户记录中
- 对账帮助 - 显示有未结发票的客户，草拟后续跟进
## 安装
```bash
pip install -e .
```
或者，如果您喜欢，可以使用 `uv` / `pipx`。
## 配置
您需要 HawkSoft 合作伙伴 API 凭证 - 由 HawkSoft 在您的应用程序通过其合作伙伴计划批准后颁发的用户名 + 密码。
```bash
export HAWKSOFT_USERNAME="您的供应商用户名"
export HAWKSOFT_PASSWORD="您的供应商密码"
```
您也可以将这些内容放入 `.env` 文件中（参见 `.env.example`）。
### 谁使用此服务器？
两类用户：
1. **已批准的 HawkSoft API 合作伙伴**，他们正在为独立机构构建工具。您的供应商凭证直接有效。
2. **独立机构**，他们正在进行自己的自定义集成工作。HawkSoft 已经明确开放了这条路径 - 参见 [V3.0 启动帖](https://blog.hawksoft.com/partner-api-3.0)：
> “任何构建自定义 API 集成的机构”可以直接使用 V3.0 合作伙伴 API。
如果您是机构，但尚未拥有供应商凭证，请发送电子邮件至 `opportunities@hawksoft.com` 以开始使用。
## 与 Claude Desktop 一起使用
将以下内容添加到 `~/Library/Application Support/Claude/claude_desktop_config.json`：
```json
{
"mcpServers": {
"hawksoft": {
"command": "hawksoft-mcp",
"env": {
"HAWKSOFT_USERNAME": "您的供应商用户名",
"HAWKSOFT_PASSWORD": "您的供应商密码"
}
}
}
}
```
重启 Claude Desktop。您应该会看到 9 个新工具 + 1 个资源（`hawksoft://channels`）。
## 与 Claude Code 一起使用
```bash
claude mcp add hawksoft -- hawksoft-mcp \
--env HAWKSOFT_USERNAME=您的用户名 --env HAWKSOFT_PASSWORD=您的密码
```
## 与 Cursor 一起使用
在 Cursor 设置中添加一个新的 MCP 服务器，指向 `hawksoft-mcp` 命令，并使用相同的环境变量。
## 工具
| 工具 | 类型 | 功能 |
| --- | --- | --- |
| `list_agencies` | 读取 | 列出已订阅您的供应商应用程序的机构 ID |
| `list_offices` | 读取 | 列出给定机构的办公室 |
| `list_changed_clients` | 读取 | 增量同步 - 自时间戳以来更改的客户 |
| `get_client` | 读取 | 完整的客户记录（详细信息、人员、联系人、索赔、保单） |
| `get_clients_bulk` | 读取 | 一次调用获取最多 200 个客户 |
| `search_client_by_policy` | 读取 | 按确切保单号码查找客户 |
| `create_log_note` | 写入 | 添加日志记录 + 可选的后续任务 |
| `create_attachment` | 写入 | 将 base64 文件（PDF / 图片 / 文档）附加到客户 |
| `create_receipts` | 写入 | 记录发票的付款 |
| `list_channels_tool` | 参考 | 所有 56 个 HawkSoft LogAction 代码 |
另外还有一个资源：
| URI | 描述 |
| --- | --- |
| `hawksoft://channels` | 完整的通道目录（值 / 标签 / 类别） |
## 常见模式
### 会前简报
```
用户： 我即将致电客户 4231。给我完整的资料。
代理： list_changed_clients(agency_id=1, as_of="2020-01-01")
→ [4231, ...]
get_client(agency_id=1, client_id=4231)
→ 返回详细信息、保单、人员、之前的索赔
总结： 2 个个人汽车保单、1 个雨伞保单、无近期索赔、上次联系 2 周前关于账单问题...
```
### 记录电话后
```
用户： 我刚刚与约翰逊夫妇讨论了他们的续期。汽车保单。续期看起来不错，他们想下个月添加一个青少年驾驶员。
代理： search_client_by_policy(agency_id=1, policy_number="AUTO-7741")
→ 找到客户
create_log_note(
agency_id=1,
client_id=client_id,
channel="来自被保险人的电话",
description="续期讨论；想要下个月添加青少年驾驶员",
body="讨论了即将到来的续期。客户对当前费率感到满意。提到了下个月添加青少年驾驶员。",
task_title="发送青少年驾驶员申请表",
task_description="客户提到了下个月将青少年驾驶员添加到汽车保单中。发送标准申请表。",
task_due_date="2026-07-15",
task_assigned_to_role="CSR",
)
```
### 每天的活动摘要
```
用户： 今天我和客户做了什么？
代理： 为每天的每个接触点创建_log_note，...
然后对于摘要： get_clients_bulk(client_numbers=[recent_ids])
并总结。
```
## 通道目录
通道在 API 中使用友好的名称 - 从不使用整数。`来自被保险人的电话`、`发送给保险公司的电子邮件`等。完整的 56 项目录通过 `list_channels_tool` 工具和 `hawksoft://channels` 资源公开。
## API 覆盖
| HawkSoft 端点 | MCP 工具 |
| --- | --- |
| `GET /vendor/agencies` | `list_agencies` |
| `GET /vendor/agency/{id}/offices` | `list_offices` |
| `GET /vendor/agency/{id}/clients` | `list_changed_clients` |
| `GET /vendor/agency/{id}/client/{id}` | `get_client` |
| `POST /vendor/agency/{id}/clients` | `get_clients_bulk` |
| `GET /vendor/agency/{id}/clients/search` | `search_client_by_policy` |
| `POST /vendor/agency/{id}/client/{id}/log` | `create_log_note` |
| `POST /vendor/agency/{id}/client/{id}/attachment` | `create_attachment` |
| `POST /vendor/agency/{id}/client/{id}/receipts` | `create_receipts` |
完整的 HawkSoft 合作伙伴 API v3.0 文档：<https://partner.hawksoft.app/v3/api.html>
## 开发
```bash
# 使用开发依赖项安装
pip install -e ".[dev]"
# 运行测试
pytest
# 在本地运行服务器（标准输入/输出）
hawksoft-mcp
```
如果您还没有 HawkSoft 凭证，客户端将在第一次调用时引发明确的错误 - 服务器不会在导入时尝试连接。
## 许可证
MIT - 参见 [LICENSE](LICENSE)。
## 贡献
问题和 PR 欢迎。两件事总是有所帮助：
1. **更多工具。** 如果您发现我们错过了 HawkSoft 端点（或需要更友好的包装器），请开一个问题。
2. **更好的提示。** 您能分享的最有用的东西是一个实际的保险工作流示例，它帮助您完成了什么 - 我们在 `/examples` 中收集这些。
## 另见
- [HawkSoft 合作伙伴 API V3.0 文档](https://partner.hawksoft.app/v3/api.html)
- [HawkSoft 合作伙伴计划](https://www.hawksoft.com/about/partners/)
- [模型上下文协议规范](https://modelcontextprotocol.io)
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
