# 飞书项目 MCP 集成完整指南

> 日期: 2026-07-09 | 关联技能: hermes-pitfalls-learned

## 概述

飞书项目（project.feishu.cn）提供 MCP Server，可通过 X-Mcp-Token 直连Hermes。
覆盖3个空间：销售管理(3104商机) / 客户项目管理(407商机) / 售后管理(24客诉)。

## 接入流程

### 1. 获取 X-Mcp-Token（一次性）

飞书项目 → 帮助中心「功能入口」→ 复制：
- 域名: `https://project.feishu.cn`
- Token: `m-xxxxxx`

### 2. Hermes 配置

```bash
# 方式A: 直接配置（当前方案）
# 在 config.yaml 的 mcp_servers 下添加:
mcp_servers:
  feishu-project:
    url: https://project.feishu.cn/mcp_server/v1
    transport: sse
    headers:
      X-Mcp-Token: m-abfb29e8-3104-434f-9944-8d0bb592f8cd

# 方式B: CLI (不推荐，不支持自定义header)
hermes mcp add feishu-project --url "https://project.feishu.cn/mcp_server/v1" --auth header
```

### 3. 重新加载

```bash
hermes gateway restart  # 或 /reload-mcp
```

## 可用工具（48个）

见 [tools-list.md](./tools-list.md)

## MQL 查询语法（关键！）

### ✅ 正确语法

```
SELECT name FROM `项目名`.`工作项类型` LIMIT N
```

关键规则:
- **`project_key` 是独立参数**，不在MQL字符串内
- **`SELECT *` 不支持**，必须显式列字段
- 字段/表名用**反引号**包裹
- 项目名和工作项类型用**点号**连接

### 正确调用示例

```json
{
  "project_key": "658bb60520ea78a2125f1b99",
  "mql": "SELECT name FROM `客户项目管理`.`story` LIMIT 10"
}
```

### ❌ 常见错误

| 错误写法 | 错误信息 |
|---------|---------|
| MQL里写 `project_key = xxx` | "project_key is empty" |
| `SELECT *` | "unsupported expression type *" |
| 不加 project_key 参数 | "project_key is empty" |
| 不用反引号 | "syntax error" |
| work_item_type用中文 | 需用英文key如`story`非`商机` |

## 三个核心空间

| 空间 | project_key | stories | 用途 |
|------|-------------|:------:|------|
| 销售管理 | `6593cd71471290e3cc6be6e6` | 3104 | 客户档案/商机 |
| 客户项目管理 | `658bb60520ea78a2125f1b99` | 407 | 销售活动/项目 |
| 售后管理 | `658288abfb8bd616b17025f1` | 24(客诉) | 客诉跟踪 |

## 数据管道模式

```
飞书MCP → curl调用 → Python解析(flatten moql_field_list) → JSON → HTTP fetch → HTML页面
```

### 代码模板

```python
def flatten_moql(items):
    """将moql_field_list数组转为普通dict"""
    result = []
    for item in items:
        row = {}
        for f in item.get('moql_field_list', []):
            v = f.get('value', {})
            val = list(v.values())[0] if v else ''
            if isinstance(val, dict):
                val = list(val.values())[0] if val else ''
            row[f['name']] = val
        result.append(row)
    return result
```

## Node Detail 分析模式

客诉/审批阻塞诊断的标准流程:

```python
# 1. 从 list_todo 获取待办
todo = mcp_call("list_todo", {"action": "todo", "page_size": 150})

# 2. 对每个工作项获取节点详情
for item in todo['list']:
    detail = mcp_call("get_node_detail", {
        "project_key": item['project_key'],
        "work_item_id": str(item['work_item_info']['work_item_id'])
    })
    
    # 3. 找进行中的节点及其负责人
    for node in detail['list']:
        if node['basic']['status'] in ('in_progress', 'doing'):
            owners = node['assignees']['owners']
            # 这就是当前阻塞点
```

## 已验证的功能

| 功能 | 工具 | 状态 |
|------|------|:--:|
| 个人待办列表 | list_todo | ✅ |
| 按空间查商机 | search_by_mql | ✅ |
| 工作项详情 | get_workitem_brief | ✅ |
| 节点详情+阻塞诊断 | get_node_detail | ✅ |
| 节点流转 | transition_node | ⚠️ 语法已知(action="confirm") |
| 评论添加 | add_comment | ❌ 未测试 |
| 创建商机 | create_workitem | ❌ 未测试 |

## 潜在扩展

- `list_schedule`: 团队人力分析
- `get_workitem_op_record`: 操作审计
- `create_workitem`: 自动创建商机
- `add_comment`: 自动催办评论