内容
# 克林特 MCP 服务器
适用于 [克林特 CRM API](https://clint-api.readme.io/reference/)（巴西，`https://api.clint.digital`）的 MCP 服务器。
**14 类别下的 46 个端点** — 联系人、交易、标签、组织、群组、丢失状态、来源、用户、账户、渠道账户、消息模板、聊天、消息（WhatsApp 官方）、仪表盘。
使用 [FastMCP](https://github.com/jlowin/fastmcp) + 代码模式（3 个元工具：`search` / `get_schema` / `execute`）构建。
## 质量
通过 **414 提示评估**（3 个人物 × 46 个工具 × 3 个变体，程序化评估）验证：
| 指标 | 值 |
|---|---|
| 工具选择准确率 | **100%** （414/414） |
| 参数形状准确率 | **97.3%** （403/414） |
| 两者均正确 | **97.3%** |
| 阈值（技能标准 ≥ 0.95） | ✅ 通过 |
涵盖的人物：初级（Carla， mentoria solo）、中级（Felipe，SDR/Closer）、高级（Renata，Head Comercial）。完整 ICP 配置文件见 `tests/personas.json`。
## 设置
```bash
uv venv && uv pip install -e .
export CLINT_API_TOKEN=<your-token>
clint-mcp
```
## 在 Claude Code 中注册
编辑 `~/.claude.json`:
```json
{
"mcpServers": {
"clint": {
"type": "stdio",
"command": "/absolute/path/to/clint-mcp/.venv/bin/clint-mcp",
"args": [],
"env": {
"CLINT_API_TOKEN": "<your-token>"
}
}
}
}
```
然后 `/exit` 并重新打开 Claude Code。
## 配置
| 环境变量 | 默认值 | 目的 |
|---|---|---|
| `CLINT_API_TOKEN` | （必填） | 作为 `api-token` 头部发送的 API 令牌 |
| `CLINT_MAX_RPS` | `5` | 客户端速率限制（请求/秒） |
## 覆盖范围
| 类别 | 工具 | 备注 |
|---|---|---|
| 联系人 | 8 | 列表 / 获取 / 创建 / 更新 / 删除 + 附件 + 标签添加/删除 |
| 交易 | 5 | 列表 / 获取 / 创建 / 更新 / 删除 |
| 标签 | 4 | 列表 / 获取 / 创建 / 删除 |
| 组织 | 2 | 获取 / 更新 |
| 群组 | 2 | 列表 / 获取 |
| 丢失状态 | 2 | 列表 / 获取 |
| 来源 | 2 | 列表 / 获取 |
| 用户 | 2 | 列表 / 获取 |
| 账户 | 1 | 列表自定义字段 |
| 渠道账户 | 2 | 列表 / 获取 — WhatsApp 官方 |
| 消息模板 | 2 | 列表 / 获取 — HSM 模板 |
| 聊天 | 3 | 获取 + 按联系人列表 + 按渠道列表 |
| 消息 | 7 | 按聊天列表 + 获取 + 发送（文本/图像/音频/文档/模板） |
| 仪表盘 | 4 | 列表 / 获取 / 数据 + 单个图表数据 |
| **总计** | **46** | |
## 重新生成工具
```bash
python -m clint_mcp.generator
```
读取 `specs/openapi.json`（从 `specs/endpoints/` 中的 46 个 ReadMe `.md` 页面合并而来）并重写 `src/clint_mcp/tools/*.py`。
## 重新运行评估
```bash
python scripts/judge.py
```
重新生成候选项需要重新调度子代理（手动）。有关当前提示/候选项/结果，请参见 `tests/`。
## 设计笔记
- **默认代码模式** — 所有 46 个工具折叠为 3 个元工具（`search`/`get_schema`/`execute`），无论规模大小，令牌预算可扩展性更好。
- **`inputSchema.properties[].description` 中的提示**（SEP-1382 兼容），不在工具级文档字符串中 — 代理可靠地读取每个参数描述；截断的文档字符串会使它们丢失。
- **带有 ⚠️ 的反词汇提示**，用于 API 真实性与 LLM 直觉相悖的正文字段（`message` 与 `text`、`url` 与 `audio_url`/`image_url`、`template_id` 与 `template_name`）。这些单独将参数准确率从 73% 提升至 97%，在评估的第三次迭代中。
- **路径 `id` 语义化重命名** — `/v1/contacts/{id}` 公开 `contact_id`（而非 `id_`）。LLM 猜测实体前缀名称；对齐节省约 110 种失败模式。
- **驼峰路径 → 蛇形参数** — `/v2/chats/contact/{contactId}` 在 Python 签名中接受 `contact_id`；在 URL 构建中替换回 `contactId`。
