# 飞书需求池 MCP Server V1

面向 `claude.ai` 自定义连接器的自托管远程 MCP Server。仅暴露需求池和日报归档 5 个工具，不包含通用表读写、删除、文档读取或搜索。

## 工具

| 工具 | 行为 |
|---|---|
| `list_demands` | 状态、负责人、名称关键词筛选，最多 500 条 |
| `get_demand` | 用 `record_id` 或精确名称取单条详情 |
| `create_demand` | 名称查重；创建日期为北京时间当天；状态为待评估 |
| `update_demand` | 只提交传入字段；完成时自动写完成日期 |
| `archive_daily_report` | 在 private/shared 目录新建 docx，V1 以纯文本段落写入 |

## 安全与可靠性

- `/mcp` 由固定 Bearer token 保护，使用常量时间比较；`/health` 可匿名访问。
- 飞书 `tenant_access_token` 提前 5 分钟刷新，鉴权失效自动刷新并重试一次。
- 写操作串行化且间隔至少 200ms。
- 创建前精确查重，不提供删除工具。
- 所有写操作写入 JSON Lines 审计日志；长正文只记录长度，不落完整敏感内容。
- 启动时配置集中于 `.env`、`config/fields.json`、`config/people.json`，业务代码没有表字段名。
- 单选值从实际字段配置动态校验，错误码、HTTP 状态和 request ID 返回给 MCP 调用方。

## 飞书准备

复用 `lx-feishu-bitable` 自建应用凭证即可，但需确认应用拥有：

1. 多维表查看/编辑权限，并已成为需求池多维表的协作者。
2. 通讯录邮箱换 open_id 权限（仅在 `people.json` 使用邮箱时需要）。
3. 创建云文档、编辑云文档权限，并对两个目标文件夹有创建权限。
4. 表内已新增“执行方”单选字段，并补齐各单选字段值域。

人员映射优先使用明确的 open_id：

```json
{
  "温媛媛": { "open_id": "ou_xxx" },
  "刘宗霖": { "email": "user@example.com" }
}
```

录入时无法解析需求方，会降级写入备注；更新负责人时无法解析会明确报错，避免误写。

## 安装与预检

```bash
cp .env.example .env
python3 -m venv .venv
source .venv/bin/activate
pip install -e '.[test]'
python scripts/preflight.py
pytest
```

预检严格执行以下链路：获取多维表元数据 → 列出数据表确认 `table_id` → 拉取并校验字段 → 输出当前单选值域。预检不写数据。

## 启动

直接运行：

```bash
python -m feishu_demand_mcp.server
```

或 Docker：

```bash
docker compose up -d --build
curl https://mcp.example.com/feishu-demand/health
```

Nginx 示例见 `deploy/nginx.conf.example`。反代下挂路径时，Claude 连接器 URL 为：

```text
https://mcp.example.com/feishu-demand/mcp
```

连接器请求需携带：

```text
Authorization: Bearer <MCP_BEARER_TOKEN>
```

如果 claude.ai 管理界面要求标准 OAuth 而不允许静态 Bearer header，需要在反代前增加 OAuth 2.1 网关；本项目严格按 V1 规格实现固定 Bearer 鉴权。

## 配置说明

- `FEISHU_APP_TOKEN`、`FEISHU_TABLE_ID`：唯一允许操作的需求池。
- `FIELD_CONFIG_PATH`：逻辑字段到实际飞书字段名映射。
- `PEOPLE_CONFIG_PATH`：姓名到 open_id 或邮箱映射。
- `FEISHU_DOC_PRIVATE_FOLDER_TOKEN` / `FEISHU_DOC_SHARED_FOLDER_TOKEN`：日报目录。
- `FEISHU_RECORD_URL_TEMPLATE` / `FEISHU_DOC_URL_TEMPLATE`：返回给调用方的网页 URL 模板。
- `AUDIT_LOG_PATH`：写操作审计日志位置。

生成鉴权密钥：

```bash
python -c 'import secrets; print(secrets.token_urlsafe(48))'
```

## 三步验收

1. MCP Inspector 或 claude.ai 连接 HTTPS `/mcp`，确认恰好 5 个工具可见。
2. `create_demand` 新增测试需求，再用 `update_demand` 设置为“完成”，确认创建/完成日期均正确。
3. `archive_daily_report` 分别向目标目录写测试日报，确认返回 URL 可打开。

真实写入验收应先在测试表/测试目录执行。项目自动化测试不会调用真实飞书 API。

## 参考实现

- 复用了 [Digital-sy/lx-feishu-bitable](https://github.com/Digital-sy/lx-feishu-bitable) 的 Python/httpx、环境配置、表解析和字段分页模式。
- 远程挂载方式基于 [MCP Python SDK v1.x Streamable HTTP 示例](https://github.com/modelcontextprotocol/python-sdk/blob/v1.x/examples/snippets/servers/streamable_starlette_mount.py)。生产依赖固定为稳定的 `mcp>=1.27,<2`，避免自动升级到预发布 v2。