飞书文档 MCP Server — 帮助 AI Agent 读取飞书文档富文本、图片与表格内容

Project description

FeishuMCP - 飞书文档 Block 内容获取 MCP 服务器

版本: v3.3.0 | 更新日期: 2026-06-15 | 核心升级: 新增子文档链接获取工具 + wiki 子节点权限授权 + 显式应用凭证配置 + 智能图片位置关联

这是一个基于 Python 和 MCP（Model Context Protocol）实现的飞书文档 Block 内容获取服务器。它提供了获取飞书文档中富文本块（Block）内容的功能，支持图片自动提取、表格转换、画板导出等特性。

💡 推荐搭配使用：本项目专注于文档内容深度解析和媒体处理，建议与飞书官方 MCP 配合使用，以获得完整的飞书 API 能力（如多维表格操作、云文档搜索等）。

✨ 功能特性

核心功能

🆕 一键获取增强内容 (get_document_with_media) - 推荐首选！ 只需提供URL，自动完成链接解析、获取文档、下载图片画板（支持 max_text_chars 控制文本截断，0 表示不截断）
🔥 智能图片位置关联 (v2.1) - 文件路径作为唯一标识，精准关联图片和文档内容
- 文本中插入 [📷 图片: feishu_images/xxx.png - 所属章节] 标记
- 自动提取图片所属章节、前后文本、位置索引
- 容错处理：某张图片下载失败不影响其他图片
- Cursor 可通过文件路径直接读取图片，结合上下文分析
🆕 文档内容搜索 (search_document_content) - 在大文档中搜索关键词，v2.2 返回标题层级上下文（H1/H2/H3），让 AI 决定读取范围
🆕 读取电子表格 (get_sheet_content) - 读取文档中嵌入的电子表格内容，支持 Markdown 表格格式输出
✅ 获取文档所有块 (get_document_blocks) - 获取文档中所有块的富文本内容，支持分页查询，支持缓存（10分钟）
🧩 增强文本长度可控 (get_document_with_media.max_text_chars) - 默认返回前10000字符，设为 0 可返回完整增强文本
✅ 获取单个块详情 (get_block_detail) - 获取指定块的详细信息，包括类型、内容、样式等
✅ 获取块的子块 (get_block_children) - 获取指定块的所有子块列表，支持分页查询
🔗 解析文档链接 (parse_document_id) - 从飞书文档链接中自动解析 document_id，支持 docx 和 wiki 链接
🔗 获取子文档链接 (get_child_documents) - 获取 wiki/docx-in-wiki 节点的直接子文档链接与元数据
🖼️ 下载图片块 (download_image_blocks) - 下载指定的图片块到工作区，支持批量下载，v2.1 新增上下文信息
🎨 下载画板为图片 (download_board_as_image) - 将画板导出为图片，支持视觉理解

v3.0 新增工具 ⭐

通用文档分析工具（3个）

🆕 预览表格表头 (preview_document_tables) - 智能识别文档中所有表格类型，辅助决策该解析哪个表格
🆕 提取文档标题树 (extract_document_structure) - 提取H1/H2/H3/H4标题，构建树状结构，适用于任何文档的结构分析
🆕 按标题拆解文档 (get_document_section_digests) - 按标题层级拆解文档，生成章节摘要和结构化信号（图片/表格/代码/接口），供模块归因决策

测试用例生成专用工具（特定需求）

⭐ 解析排期表格 (parse_schedule_table) - 解析任务排期表格，自动提取模块划分，专用于测试用例生成
✅ 生成模块索引 (generate_module_index) - 为测试用例生成提供章节索引（v3.0优化支持 chapter_hints）

v3.0+ 工具统计：

v3.0 新增工具总数：4个（3个通用 + 1个专用）
工具总数：20个（15个文档工具 + 1个辅助工具 + 4个授权工具）

专用工具的核心价值（测试用例生成场景）：

🌟 100%准确的模块定义：基于排期表格的权威数据
🌟 完整兜底策略：无排期表格时使用标题树自动推断
🌟 零人工干预：端到端自动化，6秒完成42个模块提取
🌟 精准章节定位：chapter_hints替代关键词搜索

📌 说明：parse_schedule_table 和 generate_module_index 是为"根据飞书云文档生成测试用例"这一特定需求设计的工具。而 preview_document_tables、extract_document_structure 和 get_document_section_digests 是通用工具，适用范围更广。

授权管理

🔍 查看 Token 信息 (get_current_token) - 查看当前使用的 user_access_token 信息，包括有效期、剩余时间等
🔄 重新授权 (reauthorize) - 手动触发重新授权流程，获取新的 token
🔌 端口检查 (check_auth_port) - 检查授权回调端口占用情况
🧹 端口清理 (cleanup_auth_port) - 清理占用授权回调端口的进程

数据处理

🖼️ 图片元数据提取 - 自动识别图片块，提取图片的 block_id、token、尺寸等元数据
📊 表格内容转换 - 自动将表格块转换为 Markdown 格式，便于 Cursor 理解和处理
📝 文本内容提取 - 自动提取 Block 中的纯文本内容，包括标题、列表、代码块等结构化文本
🎨 画板识别 - 自动识别画板块并提取元数据

🔥 v2.1 核心能力：智能图片位置关联（BlockProcessor）

核心方法：extract_text_with_media_markers()

功能说明：从文档块中提取文本内容，并在媒体位置插入带有文件路径的标记，使 Cursor 能够精准关联图片和文档内容。

关键特性：

文件路径作为唯一标识：feishu_images/xxx.png（基于 block_id + token）
文件路径在下载前就能确定：不受下载顺序影响
容错处理：某张图片下载失败不影响其他图片的关联
自动章节定位：提取所属章节路径、前后文本、最近标题
Cursor 友好：可以通过文件路径直接读取图片文件

使用示例：

text, media_list = BlockProcessor.extract_text_with_media_markers(blocks)
# 文本中包含：[📷 图片: feishu_images/doxcn123_abc456.png - 需求背景]
# media_list 包含：文件路径、所属章节、上下文等元数据

表格处理能力（BlockProcessor）

项目提供完整的表格处理方法链，支持多种表格操作场景：

方法	职责	使用场景
`extract_table_info()`	提取表格结构元信息	了解表格行列数、单元格ID等
`extract_table_summary()`	生成表格摘要描述	快速展示表格概况
`build_cell_content_map()`	构建单元格ID→内容映射	表格内容提取的预处理
`table_to_matrix()`	转换为二维字符串矩阵	自定义格式化或数据分析
`table_to_text()`	转换为纯文本格式	文本搜索、日志输出
`table_to_markdown()`	转换为Markdown格式	导出文档、生成报告

画板处理能力（BlockProcessor）

项目支持将画板导出为图片，便于 Cursor 使用视觉能力理解画板内容：

方法	职责	使用场景
`extract_board_info()`	提取画板结构元信息	了解画板token等元数据
`extract_board_summary()`	生成画板摘要描述	快速展示画板标识
`get_board_download_token()`	获取导出图片用token	供 download_board_as_image 使用

系统特性

🔄 Token 自动管理 - 支持 user_access_token 的自动获取、刷新和过期检测，提前 5 分钟自动刷新，无需手动维护
🚀 开箱即用 - 支持 uvx 直接安装；配置应用凭证后即可完成浏览器授权并开始使用
🏗️ 模块化架构 - 工具采用模块化设计，易于维护和扩展
🐛 完善的调试支持 - 详细的日志输出和错误处理，便于问题排查

📖 详细工具文档：查看 MCPTOOLS.md 了解每个工具的详细使用方法

🚀 快速开始

方式一：uvx 一键安装（推荐，无需 clone 仓库）

在 MCP 配置文件中添加：

Cursor：~/.cursor/mcp.json
Claude Code 用户级：~/.claude.json
Claude Code 项目级：项目根目录的 .mcp.json

{
  "mcpServers": {
    "feishu-docx-blocks": {
      "command": "uvx",
      "args": ["feishu-docx-blocks@latest"],
      "env": {
        "FEISHU_APP_ID": "<your_app_id>",
        "FEISHU_APP_SECRET": "<your_app_secret>"
      }
    }
  }
}

⚠️ env 字段必需：FEISHU_APP_ID / FEISHU_APP_SECRET 由分发方通过内部渠道发给团队成员（不再内置在代码中）。

也可以把凭证写入 ~/.config/feishu-docx-blocks/.env 文件，env 字段留空即可。

重启 Cursor / Claude Code，首次使用工具时会自动弹出浏览器完成飞书授权，之后的 token 会保存到 ~/.config/feishu-docx-blocks/.env。

需要先安装 uv（curl -LsSf https://astral.sh/uv/install.sh | sh）

方式二：从源码安装（开发者）

git clone 本仓库
安装依赖：pip install -e .
把 FEISHU_APP_ID / FEISHU_APP_SECRET 写入 ~/.config/feishu-docx-blocks/.env
运行授权脚本：python auto_auth_and_setup.py
在浏览器中完成授权
重启 Cursor，开始使用！

🎯 搭配官方 MCP 使用（推荐）

本项目专注于文档内容深度解析和媒体处理，建议与飞书官方 MCP 配合使用，形成完整的飞书 API 能力：

能力	feishu-docx-blocks（本项目）	feishu-mcp（官方）	推荐优先级
读取文档内容	✅ 富文本+图表元数据+缓存	⚠️ 仅纯文本（`docx_v1_document_rawContent`）	🥇 优先本项目
下载图片/画板	✅ 封装完善，一键下载	⚠️ 可用 `drive_v1_media_batchGetTmpDownloadUrl` 手动下载	🥇 优先本项目
读取电子表格	✅ 文档内嵌入Sheet	❌ 不支持	🥇 仅本项目
文档内容搜索	✅ 关键词定位+上下文	❌ 不支持	🥇 仅本项目
一键获取完整内容	✅ URL→文本+图片+画板	❌ 需多步调用	🥇 仅本项目
操作多维表格	❌ 不支持	✅ `bitable_v1_*` 系列	🥈 仅官方
全局搜索云文档	❌ 不支持	✅ `docx_builtin_search`	🥈 仅官方
创建/编辑文档	❌ 只读	✅ `docx_v1_document_create` 等	🥈 仅官方
知识库管理	⚠️ 仅解析链接	✅ `wiki_v2_*` 系列	🥈 仅官方
Token 管理	✅ 完整支持	❌ 不支持	🥇 仅本项目

工具选择原则

📖 读取文档内容：优先使用本项目的 get_document_blocks 或 get_document_with_media
- ✅ 本项目优势：缓存机制、图表元数据提取、Markdown表格转换
- ⚠️ 官方兜底：如果本项目失败，可使用 docx_v1_documentBlock_list（无缓存）
🖼️ 下载图片/画板：优先使用本项目的 download_image_blocks 和 download_board_as_image
- ✅ 本项目优势：一键下载、自动保存、返回ImageContent、支持批量处理
- ⚠️ 官方兜底：如果本项目失败，可以通过以下步骤手动实现：
  1. 使用 drive_v1_media_batchGetTmpDownloadUrl 获取临时下载链接
  2. 使用代码下载图片到本地
  3. 但此方法需要更多步骤，封装不如本项目完善
🔍 搜索内容：
- 文档内搜索：仅本项目支持 search_document_content
- 全局搜索：仅官方支持 docx_builtin_search（跨文件夹搜索）
✏️ 创建/编辑：仅官方支持，本项目为只读工具
📊 多维表格：
- 文档内嵌入Sheet：使用本项目 get_sheet_content
- 独立Bitable：使用官方 bitable_v1_* 系列工具

配置双 MCP 服务

在 ~/.cursor/mcp.json 中同时配置两个服务：

{
  "mcpServers": {
    "feishu-docx-blocks": {
      "command": "uvx",
      "args": ["feishu-docx-blocks@latest"],
      "env": {
        "FEISHU_APP_ID": "<your_app_id>",
        "FEISHU_APP_SECRET": "<your_app_secret>"
      }
    },
    "feishu-mcp": {
      "url": "https://open.feishu.cn/mcp/stream/your_private_key",
      "headers": {}
    }
  }
}

📖 飞书官方 MCP 安装说明：https://open.feishu.cn/page/mcp/

📋 添加 Project Rules（强烈推荐）

为了帮助 Cursor 更高效地选择正确的工具，项目提供了 .cursorrules 文件，包含两个 MCP 服务的工具选择指南。

启用方法

.cursorrules 文件已包含在项目中，Cursor 会自动读取。文件内容包括：

两个 MCP 服务的能力对比
不同场景下的工具选择决策表
常见错误处理方案
最佳实践工作流程

核心规则摘要

📌 获取文档内容 → 优先使用 feishu-docx-blocks 的 get_document_blocks
📌 下载图片/画板 → 只能使用 feishu-docx-blocks
📌 操作多维表格 → 只能使用 feishu-mcp
📌 Wiki链接解析 → parse_document_id，失败则用 wiki_v2_space_getNode
📌 Token问题排查 → 使用 get_current_token 和 reauthorize

💬 使用 Prompt 模板

项目在 prompts/ 目录下提供了常用任务的提示词模板，帮助您快速开始。

目录结构

prompts/
└── 飞书文档分析.md    # 文档分析相关的 Prompt 模板

使用方法

方法一：直接复制使用

打开 prompts/飞书文档分析.md，复制所需的模板，替换其中的占位符（如 [文档URL]、【关键词】）后发送给 Cursor。

方法二：在对话中引用

在 Cursor 对话中使用 @prompts/飞书文档分析.md 引用模板文件，然后告诉 AI 使用哪个模板。

模板示例

# 获取文档特定章节内容
请帮我获取飞书文档 https://xxx.feishu.cn/wiki/XXX 中与【青少年模式】相关的内容，包括：
1. 相关章节的文字描述
2. 该章节中的图片和画板（如有）
3. 对图表内容的分析

# 技术文档分析
请分析这个技术文档 https://xxx.feishu.cn/docx/XXX：
1. 提取所有接口定义（找到相关表格）
2. 下载并分析流程图/架构图
3. 总结核心实现逻辑

📦 安装

方式一：uvx 一键安装（推荐）

前提：已安装 uv

curl -LsSf https://astral.sh/uv/install.sh | sh

在 MCP 配置文件中添加（路径见上文"快速开始"）：

{
  "mcpServers": {
    "feishu-docx-blocks": {
      "command": "uvx",
      "args": ["feishu-docx-blocks@latest"],
      "env": {
        "FEISHU_APP_ID": "<your_app_id>",
        "FEISHU_APP_SECRET": "<your_app_secret>"
      }
    }
  }
}

⚠️ FEISHU_APP_ID / FEISHU_APP_SECRET 由分发方提供（团队内部渠道），或在飞书开发者后台自建应用获取。

重启 Cursor / Claude Code，首次调用任意工具时会自动弹出浏览器完成飞书授权。

授权后 token 自动保存到 ~/.config/feishu-docx-blocks/.env，后续启动自动读取，长期有效（自动刷新）。

方式二：从源码安装（开发者）

git clone https://github.com/your-org/FeishuMCP.git
cd FeishuMCP
pip install -e .
# 先把 FEISHU_APP_ID / FEISHU_APP_SECRET 写入 ~/.config/feishu-docx-blocks/.env
python auto_auth_and_setup.py  # 授权并自动写入 mcp.json

自建飞书应用需要配置：

重定向 URL：http://localhost:8082/callback
权限：docx:document:readonly、wiki:node:read、wiki:node:retrieve 等（详见 docs/权限申请指南.md）

说明：

应用凭证由用户显式提供（env 字段或 .env 文件），不再内置默认值
Token 配置：token 统一保存在 ~/.config/feishu-docx-blocks/.env，不要将 token 放入 mcp.json

🚀 使用

在 Cursor 中使用

配置完成后，重启 Cursor，即可在对话中使用 MCP 工具。

快速开始示例：

# 场景1：获取文档内容
# 1. 解析文档链接获取 document_id
parse_document_id(url="https://xxx.feishu.cn/docx/VQdXdKssaognlrxD5CIcaA7OnDf")

# 2. 获取文档的所有块
get_document_blocks(document_id="VQdXdKssaognlrxD5CIcaA7OnDf")

# 3. 下载图片
download_image_blocks(
    document_id="VQdXdKssaognlrxD5CIcaA7OnDf",
    image_block_ids=["block_id_1", "block_id_2"]
)

v3.0 智能模块提取示例： ⭐

# 场景2：自动提取模块划分（v3.0推荐）
# 1. 并行调用工具获取结构化数据
schedule = parse_schedule_table(document_id="排期文档ID")
# → 返回：42个模块，包含优先级、测试点等

structure = extract_document_structure(document_id="需求文档ID")
# → 返回：910个标题，树状结构+扁平列表

# 2. Cursor智能提炼（自动执行）
# - 在标题树中查找与表格模块匹配的章节
# - 生成chapter_hints（精准章节定位）
# - 标注置信度（high/medium/low）
# → 输出：modules-list.json（100%准确）

# 3. 逐模块生成索引（使用chapter_hints）
generate_module_index(
    module_id="M25",
    module_name="首页-发现-专栏",
    document_id="需求文档ID",
    keywords=["专栏", "发现页"],
    chapter_hints=["2.3 发现Tab", "专栏模块"]  # ⭐ 精准定位
)
# → 输出：module-M25-index.md（只包含相关章节，节省60-80% token）

📖 详细使用说明：查看 MCPTOOLS.md 了解每个工具的详细使用方法、参数说明和使用场景。

🚀 v3.0 快速开始：查看快速开始指南-v3.0.md 了解智能模块提取完整流程。

获取文档 ID

文档 ID 可以通过以下方式获取：

使用解析工具（推荐）：使用 parse_document_id 工具从文档链接中自动解析
从文档 URL 获取：对于云文档，URL 中的 token 即为 document_id（27 字符）
从 Wiki URL 获取：对于 Wiki 文档，推荐使用两步法：
- 步骤1：使用 wiki_v2_space_getNode MCP 工具获取节点信息，提取 obj_token（即 document_id）
- 步骤2：使用 get_document_blocks 工具获取文档内容
- 或者：使用 parse_document_id 工具解析 Wiki URL（需要有效的 token）

🔧 配置说明

环境变量

可以通过环境变量配置以下参数：

FEISHU_APP_ID - 飞书应用 ID（必需，由分发方在内部渠道提供）
FEISHU_APP_SECRET - 飞书应用密钥（必需，由分发方在内部渠道提供）
FEISHU_ACCESS_TOKEN - 用户访问令牌（可选，会自动获取）
FEISHU_REFRESH_TOKEN - 刷新令牌（首次启动时通过浏览器授权获取）
FEISHU_REDIRECT_URI - 重定向 URI（默认：http://localhost:8082/callback）

配置方式：

推荐：在 MCP 配置的 env 字段中传入 FEISHU_APP_ID / FEISHU_APP_SECRET
备选：写入 ~/.config/feishu-docx-blocks/.env 文件
Token（FEISHU_ACCESS_TOKEN / FEISHU_REFRESH_TOKEN）由程序自动管理，首次启动会弹出浏览器授权，授权后持久化到 ~/.config/feishu-docx-blocks/.env
每个用户需要单独完成浏览器授权（用户级 token，不能跨人共享）
新增或变更权限（例如 wiki:node:retrieve）后，需要先在飞书开发者后台申请/审批，再使用 reauthorize 或 python auto_auth_and_setup.py 重新授权。

Token 管理

自动刷新机制

提前刷新：系统会在 token 剩余有效期少于 5 分钟时自动刷新，避免过期
过期检测：每次调用 API 时自动检测 token 是否过期
自动刷新：如果配置了 FEISHU_REFRESH_TOKEN，系统会自动刷新过期的 token
失败处理：如果 refresh_token 也过期，系统会清除无效 token 并提示重新授权

Token 有效期

user_access_token：默认有效期 2 小时
refresh_token：如果应用申请了 offline_access 权限，refresh_token 长期有效
自动刷新：系统会在 token 剩余时间少于 5 分钟时自动刷新

Token 管理工具

查看 Token 信息：使用 get_current_token 工具查看当前 token 状态
手动重新授权：使用 reauthorize 工具手动触发重新授权流程
自动授权：如果 token 无效且没有 refresh_token，系统会自动启动授权流程

Token 存储

统一使用 .env 文件：所有 token 统一存储在 ~/.config/feishu-docx-blocks/.env 中
- FEISHU_ACCESS_TOKEN：访问令牌
- FEISHU_REFRESH_TOKEN：刷新令牌（用于自动刷新）
- FEISHU_APP_ID：应用 ID（必需，来自 MCP env 字段或用户级 .env）
- FEISHU_APP_SECRET：应用密钥（必需，来自 MCP env 字段或用户级 .env）
TokenManager：仅作为内存缓存使用，实际持久化存储统一使用 .env 文件
不再使用 JSON 文件：已移除对 ~/.feishu_mcp_tokens.json 的依赖

📊 版本历史

v3.3.0 (2026-06-15) - Wiki 子文档链接获取

核心升级：

🔗 新增 get_child_documents 工具：支持获取 wiki/docx-in-wiki 节点的直接子文档链接与元数据
🧭 支持二级/多级文档树探索：返回 node_token、obj_token、obj_type、has_child 和后续解析建议
🔐 授权 scope 更新：自动授权范围新增 wiki:node:retrieve，用于获取知识库子节点列表
📚 文档补充：更新 README、MCPTOOLS 和权限申请指南，明确新增权限后需要重新授权

v3.2.2 (2026-04-16) - 凭证与回调链路修正

核心升级：

🔐 移除内置应用凭证：FEISHU_APP_ID / FEISHU_APP_SECRET 必须通过 MCP env 字段或用户级 .env 显式提供
🧭 统一回调端口：默认 OAuth 回调地址统一为 http://localhost:8082/callback
🧰 uvx 启动检查：启动时 fail-fast 提示缺失凭证，并将 .env 读取到的凭证同步给下游模块
🛠️ 源码入口对齐：run_server.py 启动前也会校验并传播应用凭证，行为与 uvx 入口一致

v3.1 (2026-03-20) - uvx 一键安装 🚀

核心升级：

🚀 uvx 一键安装：无需 clone 仓库，uvx feishu-docx-blocks@latest 即可运行
🔧 用户配置目录：token 存储迁移到 ~/.config/feishu-docx-blocks/.env，升级包不丢失 token
🖼️ 图片路径修复：feishu_images/ 保存至调用方工作目录而非包安装目录
🐛 BUG-04 修复：get_media_context section_path 章节路径计算错误（只保留真实父级标题）

v2.2 (2026-01-27) - 智能层级搜索 🔥

核心升级：

🔥 不再粗暴返回前后 N 个块：返回关键词的标题层级上下文
✅ 返回上一个 H1/H2/H3 标题及其位置和范围
✅ 返回建议的读取范围（narrow/medium/wide）
✅ AI 可以根据层级决定读取多大范围的内容

效果提升：

信息精准度：❌ 可能多余或缺少 → ✅ 按层级精准控制
AI 决策能力：❌ 无法选择范围 → ✅ 可选 narrow/medium/wide
Token 消耗：❌ 返回大量内容 → ✅ 只返回位置信息

核心设计：

# v2.1 前（粗暴方案）：
返回关键词前后 5 个块
问题：可能包含无关内容或缺少完整章节

# v2.2 后（智能层级方案）：
返回：
H1 [  10] 功能需求      → wide 范围 [10-100]
  H2 [  30] 账号安全    → medium 范围 [30-80]
    H3 [  40] 青少年保护 → narrow 范围 [40-60]
      >>> [  45] 关键词匹配位置

AI 可以决定：读取 narrow/medium/wide 哪个范围？

v2.1 (2026-01-27) - 智能图片位置关联 🔥

核心升级：

🔥 文件路径作为唯一标识：每张图片都有确定的文件路径，不会混淆
✅ 新增 extract_text_with_media_markers() - 在文本中插入媒体位置标记
✅ 优化 download_image_blocks - 返回图片的上下文信息（章节、前后文本）
✅ 优化 get_document_with_media - 返回媒体位置索引表
✅ 容错处理：某张图片下载失败不影响其他图片的关联

效果提升：

图片关联准确率：序号方案 70% → 文件路径方案 100%
容错能力：❌ 一张失败全部错位 → ✅ 单张失败不影响
Cursor 使用体验：⚠️ 需要猜测图片对应关系 → ✅ 通过文件路径精准读取

核心设计：

# v2.1 前（序号方案）：
文本：这是功能1的图 [图片 #1] 这是功能2的图 [图片 #2]
问题：如果图片1下载失败，图片2会被标记为#1，导致错位

# v2.1 后（文件路径方案）：
文本：这是功能1的图 [📷 图片: feishu_images/doxcn123_abc.png - 功能1]
     这是功能2的图 [📷 图片: feishu_images/doxcn456_def.png - 功能2]
优势：文件路径唯一，即使图片1失败，图片2的路径不变

v3.0 (2026-01-26) - 智能模块提取 ⭐

核心升级：

✅ 新增 preview_document_tables - 预览表格表头，智能识别表格类型（300+行）
✅ 新增 extract_document_structure - 提取文档标题树（462行）
✅ 新增 parse_schedule_table - 解析排期表格（516行）
✅ 新增 get_document_section_digests - 按标题拆解文档生成章节摘要（315行）
✅ 优化 generate_module_index - 支持 chapter_hints 精准定位
✅ 智能图片处理规则 - 防止模块错位

效果提升：

模块划分准确率：70% → 100%
人工干预时间：30分钟 → 0秒（自动化）
Token消耗：降低 60-80%

v2.0 (2026-01-19) - 模块化架构

核心升级：

✅ 重构为模块化工具架构
✅ 新增 get_document_with_media - 一键获取完整内容
✅ 新增 search_document_content - 文档内容搜索
✅ 完整的表格处理能力（Markdown转换）

v1.0 (2026-01-18) - 基础功能

初始版本：

✅ 基础的文档块获取
✅ 图片元数据提取
✅ Token自动管理

📁 项目结构

FeishuMCP/
├── feishu_docx_blocks/    # uvx 入口包
│   ├── __init__.py
│   └── server.py          # 入口函数 run()
├── pyproject.toml         # 包构建配置（hatchling）
├── .cursorrules           # 🆕 Cursor 工具选择规则（Project Rules）
├── prompts/               # 🆕 常用 Prompt 模板
│   └── 飞书文档分析.md    #     文档分析任务模板
├── src/                    # 核心代码
│   ├── mcp_server.py      # MCP 服务器主文件（约 380 行，已重构优化）
│   ├── feishu_client.py   # 飞书 API 客户端
│   ├── block_processor.py # Block 内容处理器
│   ├── token_manager.py   # Token 管理器
│   ├── auto_auth.py       # 自动授权模块
│   └── tools/             # 工具包（模块化架构）
│       ├── __init__.py    # 工具注册和导出
│       ├── base.py        # 工具基类
│       ├── document/      # 文档相关工具（15个）⭐ v3.0新增4个
│       │   ├── get_document_with_media.py  # 🆕 一键获取完整内容
│       │   ├── get_child_documents.py      # 🆕 获取 wiki/docx-in-wiki 子文档链接
│       │   ├── search_document_content.py  # 🆕 文档内容搜索
│       │   ├── get_document_blocks.py
│       │   ├── get_document_section_digests.py  # ⭐ v3.0新增：按标题拆解文档
│       │   ├── get_block_detail.py
│       │   ├── get_block_children.py
│       │   ├── download_image_blocks.py
│       │   ├── download_board_as_image.py
│       │   ├── extract_document_structure.py  # ⭐ v3.0新增：提取标题树
│       │   ├── parse_schedule_table.py        # ⭐ v3.0新增：解析排期表格
│       │   ├── preview_document_tables.py     # ⭐ v3.0新增：预览表格表头
│       │   └── generate_module_index.py       # ⭐ v3.0优化：支持chapter_hints
│       ├── utils/         # 辅助工具（1个）
│       │   └── parse_document_id.py
│       └── auth/          # 授权管理工具（4个）
│           ├── get_current_token.py
│           ├── reauthorize.py
│           ├── check_auth_port.py
│           └── cleanup_auth_port.py
├── docs/                   # 文档目录
│   ├── 权限申请指南.md    #     权限配置说明
│   └── 未来增强建议.md    #     功能增强计划
├── feishu_images/         # 下载的图片存放目录
├── run_server.py          # 服务器启动脚本
├── auto_auth_and_setup.py # 自动授权和配置脚本
├── requirements.txt       # Python 依赖
├── README.md             # 本文档
├── MCPTOOLS.md           # 工具详细文档
├── 架构优化分析.md        # 架构重构分析文档
└── 代码改进说明.md        # 代码改进说明文档

架构说明

项目采用模块化工具架构，具有以下优势：

✅ 可维护性：每个工具独立文件（50-500行），职责清晰
✅ 可扩展性：添加新工具只需创建文件并注册，无需修改核心代码
✅ 可读性：工具按功能分类（document/utils/auth），结构清晰
✅ 便于调试：详细的日志输出，便于追踪问题
✅ 测试友好：可以单独测试每个工具

详细架构说明请参考架构优化分析.md

v3.0 架构升级 ⭐

新增智能模块提取能力：

前端（Cursor）- 智能分析
    ↓ 调用MCP工具
后端（FeishuMCP）- 数据提取
    ├─ parse_schedule_table     → 权威模块定义（100%准确）
    ├─ extract_document_structure → 标题树（兜底保障）
    └─ generate_module_index    → 精准章节定位（chapter_hints）
    ↓ 返回结构化数据
前端（Cursor）- 智能提炼
    ├─ 数据融合（表格+标题树）
    ├─ 标题匹配算法（语义理解）
    ├─ chapter_hints自动生成
    └─ 置信度标注
    ↓
输出：modules-list.json（42个模块，100%准确）

工具数量统计：

v2.0: 15个工具
v3.0: 19个工具（新增4个核心工具）
v3.3: 20个工具（新增 get_child_documents）

代码行数（v3.0新增）：

preview_document_tables.py: ~300行
extract_document_structure.py: 462行
parse_schedule_table.py: 516行
get_document_section_digests.py: 315行
generate_module_index.py: 已有（优化支持chapter_hints）
总计新增: ~1593行

💡 使用技巧

Cursor 对话技巧

技巧	说明
@ 引用规则文件	在对话中使用 `@.cursorrules` 快速提醒 AI 遵循工具选择规则
@ 引用模板文件	使用 `@prompts/飞书文档分析.md` 引用 Prompt 模板
明确指定工具	如 "使用 `get_document_blocks` 获取..." 可避免工具选择歧义
直接粘贴URL	AI 会自动识别并解析飞书文档链接

常见问题快速解决

❌ 问题：画板下载失败（权限不足）
✅ 解决：使用 reauthorize 重新授权

❌ 问题：Wiki链接解析失败
✅ 解决：使用 wiki_v2_space_getNode 获取节点信息

❌ 问题：文档内容不完整
✅ 解决：使用 get_document_blocks 并设置 fetch_all=true

🐛 调试和日志

日志输出

所有工具执行都会输出详细的日志到 stderr，包括：

工具调用日志：工具名称、参数、执行状态
API 调用日志：API 请求和响应信息
错误日志：异常堆栈和错误详情
Token 管理日志：Token 获取、刷新、过期等信息

示例日志：

[CALL_TOOL] 调用工具: get_document_blocks, 参数: {...}
[CALL_TOOL] ✅ 工具 'get_document_blocks' 已实例化
[CALL_TOOL] 工具 'get_document_blocks' 需要 token，正在获取...
[TOKEN] ✅ Token已就绪，剩余有效期: 115分钟
[CALL_TOOL] ✅ Token 已获取，FeishuClient 已创建
[get_document_blocks] 获取文档块: document_id=...
[get_document_blocks] ✅ 成功获取 10 个块
[CALL_TOOL] ✅ 工具 'get_document_blocks' 执行成功，返回 1 个内容项

调试工具

get_current_token - 查看当前 token 状态、有效期、来源等信息
check_auth_port - 检查授权回调端口占用情况
reauthorize - 手动触发重新授权流程

错误排查

如果工具执行失败，错误响应会包含：

错误类型和详细消息
工具名称和传入参数
异常堆栈（如果适用）
API 错误码和响应（如果是 API 调用失败）

详细调试方法请参考代码改进说明.md

🔍 常见问题

Q: v3.0 相比之前版本有什么优势？

A: v3.0新增了智能模块提取能力，核心优势：

✅ 100%准确：基于排期表格的权威模块定义
✅ 零干预：6秒自动完成42个模块提取，无需人工整理
✅ 兜底保障：无排期表格时使用标题树自动推断
✅ 精准定位：chapter_hints替代关键词搜索，token降低60-80%
✅ 图片智能处理：防止模块错位

推荐场景：大型复杂需求的测试用例生成

使用方法：查看快速开始指南-v3.0.md

Q: 如何使用v3.0的智能模块提取？

A: 最简单方式（自动执行）：

告诉AI：请生成XXX的测试用例
- 排期: https://...
- 需求: https://...
- 技术: https://...

AI会自动：

调用 parse_schedule_table + extract_document_structure
智能提炼模块列表
生成 modules-list.json
展示给你确认
逐模块生成用例

详细文档：

工具文档: MCPTOOLS.md
规则文档: ../.cursor/rules/case-module-extraction.mdc
技术细节: ../optimize-scheme/v3.0实施总结报告.md

Q: 没有排期文档怎么办？

A: 完全没问题！v3.0支持兜底策略：

# AI会自动使用标题树提取
extract_document_structure(document_id="需求文档ID")
# → 基于H1/H2/H3层级推断模块
# → 置信度标记为"medium"，建议人工review

提示：AI会提示"基于标题划分，请确认"

Q: 应用凭证怎么获取？

本包不再内置默认应用凭证。团队成员请向分发方索取 FEISHU_APP_ID / FEISHU_APP_SECRET
凭证放在 MCP 配置的 env 字段里（见上文"快速开始"的 JSON 示例）
每个人还需要用自己的飞书账号完成浏览器授权，获取各自的 user_access_token 和 refresh_token
每个人的权限是独立的，只能访问自己有权限的文档
如果要自建飞书应用，登录飞书开发者后台创建应用，将 app_id 和 app_secret 填入 MCP 配置

Q: Token 过期怎么办？

自动刷新：如果配置了 FEISHU_REFRESH_TOKEN，系统会在 token 剩余时间少于 5 分钟时自动刷新
查看状态：使用 get_current_token 工具查看当前 token 状态和剩余有效期
手动重新授权：使用 reauthorize 工具手动触发重新授权流程
脚本重新授权：也可以运行 python auto_auth_and_setup.py 重新授权

Q: 如何查看当前使用的 token 信息？

A: 在 Cursor 中使用 get_current_token 工具，可以查看：

Token 来源（环境变量或缓存）
Token 有效性状态
过期时间和剩余有效期
是否配置了 refresh_token

Q: Token 失效后没有提示怎么办？

系统会在 token 过期时自动检测并尝试刷新
如果刷新失败，会在错误信息中提示需要重新授权
可以使用 get_current_token 工具主动检查 token 状态
如果发现 token 已过期，使用 reauthorize 工具重新授权

Q: 授权时提示 redirect_uri 错误？

团队分发应用：确认分发方提供的应用已在飞书开发者后台配置重定向 URL：http://localhost:8082/callback
自建应用：在飞书开发者后台的 安全设置 → 重定向 URL 中添加 http://localhost:8082/callback

Q: 如何获取文档的 document_id？

推荐方式：使用 parse_document_id 工具从文档链接中自动解析
手动方式：从文档 URL 中提取 token（27 字符）
Wiki 文档：使用 parse_document_id 工具会自动调用 API 获取，或使用 wiki_v2_space_getNode 工具获取 obj_token（即 document_id）

Q: 图片无法显示？

A: 确保：

授权时包含了 docx:document:readonly 权限
include_images 参数设置为 true
Token 有效且有访问文档的权限

Q: 工具调用没有输出怎么办？

查看日志：所有工具执行都会输出详细日志到 stderr，查看日志可以了解执行过程
检查参数：确保传入的参数符合要求，特别是必需参数
检查 Token：使用 get_current_token 工具检查 token 状态
查看错误信息：工具执行失败时会返回详细的错误信息，包括错误类型、消息和参数
参考文档：查看代码改进说明.md 了解调试方法

Q: 如何调试工具执行问题？

查看执行日志：工具执行时会输出详细日志，包括：
- 工具名称和参数
- 执行状态（开始、成功、失败）
- API 调用结果
- 错误信息和堆栈
使用调试工具：
- get_current_token - 检查 token 状态
- check_auth_port - 检查授权端口
查看错误响应：工具返回的错误信息包含：
- 错误类型和消息
- 工具名称和参数
- 异常堆栈（如果适用）

🎉 v3.0 新增能力 ⭐

核心升级

v3.0版本新增了4个核心工具，包括：

3个通用工具：适用于任何文档分析场景（preview_document_tables、extract_document_structure、get_document_section_digests）
1个专用工具：专门用于"测试用例生成"这一特定需求（parse_schedule_table）

新增工具（4个）

工具	功能	代码行数	测试状态
`preview_document_tables`	预览表格表头	300+行	✅ 已验证
`extract_document_structure`	提取文档标题树	462行	✅ 已验证
`parse_schedule_table`	解析排期表格	516行	✅ 已验证
`get_document_section_digests`	按标题拆解文档生成摘要	315行	✅ 已验证

核心特性

1. 权威模块定义 ⭐⭐⭐

parse_schedule_table(document_id="排期文档ID")
# → 从表格自动提取42个模块
# → 100%准确的模块定义
# → 包含：优先级、测试点、功能描述、工时等
# → 自动处理合并单元格

2. 完整兜底策略 ⭐⭐⭐

extract_document_structure(document_id="需求文档ID")
# → 提取910个标题（H1/H2/H3/H4）
# → 树状结构 + 扁平列表
# → 无排期表格时作为模块划分依据
# → 与表格交叉验证

3. 精准章节定位 ⭐⭐⭐

generate_module_index(
    module_id="M25",
    chapter_hints=["2.3 发现Tab", "专栏模块"]  # ⭐ 精准定位
)
# → 替代关键词搜索
# → 100%准确定位
# → 节省60-80% token

工作流程

用户提供文档链接
  ↓
并行调用MCP工具
  ├─ parse_schedule_table（排期文档）
  └─ extract_document_structure（需求文档）
  ↓ 返回结构化数据
Cursor智能提炼
  ├─ 数据融合（表格+标题树）
  ├─ 智能标题匹配
  ├─ chapter_hints自动生成
  └─ 置信度标注
  ↓
modules-list.json（42个模块）
  ↓
逐模块生成索引（chapter_hints精准定位）
  ↓
生成测试用例

效果对比

维度	v2.0（旧方案）	v3.0（新方案）
模块来源	AI推理	表格+标题树
准确率	~70%	100% ⭐
兜底策略	❌ 无	✅ 标题树兜底 ⭐
chapter_hints	手动编写	自动生成 ⭐
Token消耗	高	降低60-80% ⭐
人工干预	需30分钟	零干预（6秒） ⭐
置信度标注	❌ 无	✅ high/medium/low

技术突破

1. Cell内容提取方案 ⭐

问题：调用 get_block_detail(cell_id) 失败（400错误）

发现：Cell block（type=32）本身没有文本，Cell的children才是真正的文本blocks

解决方案：从 all_blocks 中查找cell的children，避免额外API调用

2. 合并单元格处理 ⭐

问题：排期表格的"所属系统"列使用合并单元格

解决方案：检测空单元格，自动继承上一行的值

3. 智能标题匹配算法 ⭐

问题：如何从910个标题中找到与模块相关的章节？

解决方案：

1. 从表格字段提取关键词（page、function_module）
2. 在标题中查找包含这些关键词的标题
3. 计算匹配分数（精确匹配10分，部分匹配3分）
4. 返回最佳匹配（100%成功率）

使用指南

详细使用方法请参考：

工具文档: MCPTOOLS.md
规则文档: ../.cursor/rules/case-module-extraction.mdc
快速开始: ../快速开始指南-v3.0.md
技术细节: ../optimize-scheme/v3.0实施总结报告.md

📝 许可证

本项目基于 MIT 许可证开源。

🤝 贡献

欢迎提交 Issue 和 Pull Request！

版本: v3.0 (v2.2)
更新日期: 2026-01-27
核心升级: 智能模块提取 + 图片位置关联 + 智能层级搜索 ⭐

Project details

Release history Release notifications | RSS feed

3.4.0

Jul 25, 2026

This version

3.3.0

Jun 15, 2026

3.2.2

Apr 16, 2026

3.2.1

Apr 16, 2026

3.2.0

Mar 25, 2026

3.1.0

Mar 23, 2026

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

feishu_docx_blocks-3.3.0.tar.gz (288.3 kB view details)

Uploaded Jun 15, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

feishu_docx_blocks-3.3.0-py3-none-any.whl (162.6 kB view details)

Uploaded Jun 15, 2026 Python 3

File details

Details for the file feishu_docx_blocks-3.3.0.tar.gz.

File metadata

Download URL: feishu_docx_blocks-3.3.0.tar.gz
Upload date: Jun 15, 2026
Size: 288.3 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.13.5

File hashes

Hashes for feishu_docx_blocks-3.3.0.tar.gz
Algorithm	Hash digest
SHA256	`42722ab4a9424620102035cacd25b65281ea23665bf4d32edc46d41dfd1f4afe`
MD5	`10e9b8ef1ae101b4ce4bec03cebd4097`
BLAKE2b-256	`7f1e9489a92df6815a978249323226393b2b1f703bea00f1e37f2460040688fc`

See more details on using hashes here.

File details

Details for the file feishu_docx_blocks-3.3.0-py3-none-any.whl.

File metadata

Download URL: feishu_docx_blocks-3.3.0-py3-none-any.whl
Upload date: Jun 15, 2026
Size: 162.6 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.13.5

File hashes

Hashes for feishu_docx_blocks-3.3.0-py3-none-any.whl
Algorithm	Hash digest
SHA256	`97c25960093631516482c79c5963918a3698edfd38069173825a6707879ce91c`
MD5	`77e1c3a5a32a3ab7d80ed46a7648d6ce`
BLAKE2b-256	`4c206d11ceb7c089725eaa5dbbc9d3bf81c5b0ac6d276a28fe6dd5d36ac2a791`

See more details on using hashes here.

feishu-docx-blocks 3.3.0

Navigation

Verified details

Maintainers

Unverified details

Meta

Project description

FeishuMCP - 飞书文档 Block 内容获取 MCP 服务器

✨ 功能特性

核心功能

v3.0 新增工具 ⭐

通用文档分析工具（3个）

测试用例生成专用工具（特定需求）

授权管理

数据处理

🔥 v2.1 核心能力：智能图片位置关联（BlockProcessor）

表格处理能力（BlockProcessor）

画板处理能力（BlockProcessor）

系统特性

🚀 快速开始

方式一：uvx 一键安装（推荐，无需 clone 仓库）

方式二：从源码安装（开发者）

🎯 搭配官方 MCP 使用（推荐）

工具选择原则

配置双 MCP 服务

📋 添加 Project Rules（强烈推荐）

启用方法

核心规则摘要

💬 使用 Prompt 模板

目录结构

使用方法

模板示例

📦 安装

方式一：uvx 一键安装（推荐）

方式二：从源码安装（开发者）

🚀 使用

在 Cursor 中使用

获取文档 ID

🔧 配置说明

环境变量

Token 管理

自动刷新机制

Token 有效期

Token 管理工具

Token 存储

📊 版本历史

v3.3.0 (2026-06-15) - Wiki 子文档链接获取

v3.2.2 (2026-04-16) - 凭证与回调链路修正

v3.1 (2026-03-20) - uvx 一键安装 🚀

v2.2 (2026-01-27) - 智能层级搜索 🔥

v2.1 (2026-01-27) - 智能图片位置关联 🔥

v3.0 (2026-01-26) - 智能模块提取 ⭐

v2.0 (2026-01-19) - 模块化架构

v1.0 (2026-01-18) - 基础功能

📁 项目结构

架构说明

v3.0 架构升级 ⭐

💡 使用技巧

Cursor 对话技巧

推荐的对话开场白

常见问题快速解决

🐛 调试和日志

日志输出

调试工具

错误排查

🔍 常见问题

Q: v3.0 相比之前版本有什么优势？

Q: 如何使用v3.0的智能模块提取？

Q: 没有排期文档怎么办？

Q: 应用凭证怎么获取？

Q: Token 过期怎么办？

Q: 如何查看当前使用的 token 信息？

Q: Token 失效后没有提示怎么办？

Q: 授权时提示 redirect_uri 错误？

Q: 如何获取文档的 document_id？

Q: 图片无法显示？

Q: 工具调用没有输出怎么办？

Q: 如何调试工具执行问题？

🎉 v3.0 新增能力 ⭐

核心升级