飞书需求池 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：

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

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

安装与预检

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

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

启动

直接运行：

python -m feishu_demand_mcp.server

或 Docker：

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

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

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

连接器请求需携带：

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：写操作审计日志位置。

生成鉴权密钥：

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 的 Python/httpx、环境配置、表解析和字段分页模式。
• 远程挂载方式基于 MCP Python SDK v1.x Streamable HTTP 示例。生产依赖固定为稳定的 mcp>=1.27,<2，避免自动升级到预发布 v2。