# 飞书项目 MCP 接入手册

> 2026-07-09 实战打通。宝锐生物飞书项目 → Hermes 完整接入流程。

## 快速连接

### 1. 获取凭证
飞书项目 → 设置 → MCP Server → 复制 `X-Mcp-Token` 和域名。

### 2. 测试连接
```bash
curl -s -X POST "https://project.feishu.cn/mcp_server/v1" \
  -H "X-Mcp-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
```

### 3. 接入 Hermes
```yaml
# ~/.hermes/config.yaml
mcp_servers:
  feishu-project:
    url: https://project.feishu.cn/mcp_server/v1
    transport: sse   # 飞书项目使用 SSE 传输
    headers:
      X-Mcp-Token: YOUR_TOKEN
```

⚠️ `transport: sse` 必须设置，否则 Hermes 默认 HTTP 会报 405。

## MQL 查询（核心能力）

48个工具中最实用的。语法：

```sql
SELECT field1, field2 FROM `空间名`.`工作项类型名` LIMIT 50 OFFSET 0
```

### 关键规则
- **不支持 `SELECT *`**，必须显式列字段
- 字段名用反引号包裹：`` `创建时间` ``
- 关系字段（关联客户、关联订单）不暴露在 MQL 中
- `project_key` 作为独立参数传入，不在 MQL 中
- OFFSET 分页有效，session_id 分页会循环

### 已知可用字段

| 空间 | 类型 | 可用字段 |
|------|------|---------|
| 销售管理 | story (商机) | `名称`, `创建时间`, `创建者`, `description`, `work_item_id` |
| 销售管理 | 销售订单 | `单据编号`, `创建时间`, `创建者`, `金额` |
| 售后管理 | 客户反馈单 | — (使用 list_todo) |
| 客户项目管理 | story | 同销售管理 |

### 不可用字段（关系型）

- `活动关联客户` → 需通过 `list_related_workitem` 获取
- `活动对应销售订单` → 同上
- `销售员` → 需通过 `get_workitem_brief` → `role_members.销售员`
- `产品/货号` → 当前未找到路径

### 数据规模参考
- 销售管理 story: 3104条（2024.5至今）
- 销售管理 销售订单: 47,709条
- 客户项目管理 story: 407条
- 售后管理 客户反馈单: 24条待办

## 关系查询（突破隐藏字段）

MQL不暴露的关系字段，通过两步获取：

### 1. 查关系定义
```
list_workitem_relations → 获取 relation_id
```
关键关系ID（宝锐销售管理空间）：
- `relation_1713785263022`: 销售订单 → 客户
- `relation_1715302203273`: 销售订单 → 商机
- `relation_1715284999934`: 活动 → 销售订单

### 2. 查关联实例
```
list_related_workitem(project_key, work_item_id, relation_id) → 返回关联的工作项名称
```

### 3. 查角色成员
```
get_workitem_brief → role_members → 销售员/下单人/客户所属人
```

## 踩坑记录

1. **Device Code 授权连续4次失败**：最终用 MCP Token 直连方案解决
2. **URL `sj/detail` vs `story/detail`**：URL路径中的类型名是 api_name（`sj`），但实际页面路由是 type_key（`story`）
3. **MQL OFFSET vs session_id 分页**：OFFSET 正确，session_id 会重复循环
4. **字段名需要反引号**：不带反引号的中文字段名会语法错误
5. **`SELECT *` 不支持**：报错 "unsupported expression type *"