基于MCP协议实现AI内容自动写入飞书文档的工程实践

1. 项目概述与核心价值

最近在折腾企业知识库和自动化文档生成，发现一个痛点：很多内部技术文档、产品说明、会议纪要的初稿撰写，其实是一个高度重复且耗时的过程。工程师写完代码，产品经理定好需求，最后往往卡在“把想法变成结构清晰、表述专业的文档”这一步。手动操作不仅效率低，还容易因为格式、术语不统一导致团队协作出现信息差。正是在这个背景下，我注意到了bert995/feishu-mcp-doc-write-stable这个项目。顾名思义，这是一个旨在实现“飞书文档稳定写入”的 MCP（Model Context Protocol）服务器项目。

简单来说，这个项目扮演了一个“智能桥梁”的角色。它允许各类 AI 助手（比如 Claude Desktop、Cursor 等内置了 MCP 客户端的工具）直接与你的飞书云文档进行交互，核心功能是稳定、可靠地将 AI 生成的内容写入到指定的飞书文档中。这不仅仅是简单的“复制粘贴”，而是通过一套标准的协议和健壮的接口，实现了内容的结构化写入、现有文档的智能更新以及操作的状态管理。对于需要高频产出文档的研发、产品、运营团队而言，这意味着你可以直接对 AI 说：“帮我把刚才讨论的 API 接口规范整理一下，生成一个飞书文档，放在‘技术文档’文件夹里。” 然后，一份格式工整、内容准确的文档初稿就瞬间出现在团队的共享知识库中。

它的核心价值在于“自动化最后一公里”。很多 AI 工具能生成不错的文本，但如何将这些文本无缝、无误地归集到企业既定的协作平台（如飞书），往往需要额外的、不稳定的脚本或手动操作。这个项目通过实现 MCP 协议，将飞书文档的写入能力标准化，并注入到你的 AI 工作流中，使得从“创意/数据”到“成型文档”的路径变得极其顺畅和可靠。接下来，我将深入拆解这个项目的设计思路、关键技术细节以及如何将它应用到实际场景中。

2. 项目核心架构与 MCP 协议解析

2.1 什么是 MCP？为什么是它？

MCP（Model Context Protocol）是由 Anthropic 提出的一种开放协议，旨在标准化 AI 模型与外部工具、数据源之间的通信方式。你可以把它想象成 AI 世界的“USB 协议”。在没有 MCP 之前，每个 AI 应用（客户端）想要连接一个新的工具（服务器），都需要定制开发一套连接逻辑，混乱且低效。MCP 定义了标准的“插口”和“通信规则”，只要工具方（服务器）按照 MCP 的规范实现对应的接口，任何支持 MCP 的 AI 应用（客户端）就能即插即用地使用它。

feishu-mcp-doc-write-stable项目就是一个标准的 MCP 服务器实现。它对外暴露了 MCP 协议规定的几个核心能力（在协议中称为Tools和Resources），例如“写入文档”、“追加内容”、“读取文档信息”等。当 Claude Desktop 这类客户端启动时，它可以配置加载这个服务器。之后，用户在客户端的对话中，就可以直接调用“写入飞书文档”这个工具，客户端会按照 MCP 协议将用户的指令和参数打包发送给我们的服务器，服务器执行飞书 API 调用后，再将结果返回给客户端呈现给用户。

选择 MCP 协议来实现，有以下几个关键考量：

1. 生态兼容性：直接对接未来主流 AI 工作台。随着 Claude、Cursor 等大力推广 MCP，其生态会越来越丰富。基于 MCP 开发，相当于一次性接入了整个生态。
2. 关注点分离：项目只需专注于做好“飞书文档写入”这一件事，实现稳定、健壮的飞书 API 调用逻辑即可。UI 交互、对话管理、上下文理解等由 AI 客户端负责。
3. 标准化与可维护性：协议标准化意味着接口清晰，文档完备，降低了后续维护和扩展的成本。例如，未来要增加“创建表格”、“插入图片”等功能，只需在服务器端增加对应的 Tool 实现即可。

2.2 项目整体架构设计

项目的架构清晰体现了 MCP 服务器的典型模式：

用户指令 -> [MCP 客户端 (如 Claude Desktop)] -> [MCP 协议通信 (stdin/stdout 或 SSE)] -> [feishu-mcp-doc-write-stable 服务器] -> [飞书开放平台 API] -> [飞书云文档] ↑ [令牌管理、错误重试、日志]

1. 协议层：项目核心是一个实现了 MCP 协议Server接口的 Node.js 应用。它通过标准输入输出(stdin/stdout)或 Server-Sent Events (SSE) 与客户端通信，解析来自客户端的 JSON-RPC 请求（如tools/call），并返回执行结果。
2. 业务逻辑层：将 MCP 请求中的参数（如文档 ID、写入内容、位置信息）映射为具体的飞书 API 调用逻辑。这里封装了飞书文档区块（Block）的操作，特别是“分片上传”和“增量更新”机制，这是实现“稳定写入”的关键。
3. 稳定性保障层：这是项目命名为stable的核心。围绕飞书 API 的限流、网络波动、令牌刷新等问题，实现了完整的应对策略，包括：
   • 智能重试机制：对可重试的错误（如网络超时、5xx 服务器错误）进行指数退避重试。
   • 令牌自动刷新：飞书访问令牌有过期时间，项目内置了基于刷新令牌的自动续期逻辑，确保长时运行无忧。
   • 操作幂等性处理：对于文档写入，尽可能设计幂等操作，或通过状态检查避免重复写入。
   • 详尽日志与错误分类：所有操作都有不同级别的日志输出，错误被明确分类（如配置错误、权限错误、网络错误），便于排查。

2.3 飞书文档 API 的关键特性利用

飞书云文档的开放 API 功能强大，但直接使用其原始 API 进行复杂内容写入并不简单。本项目深入利用了以下几个特性：

• 文档即区块树：飞书文档在 API 层面被视为一棵由“区块”组成的树。每个段落、标题、表格、代码块都是一个区块，有唯一的block_id和类型。写入内容实质上是向这棵树中插入或更新某个节点。
• 分片上传：对于大段文本，直接调用更新接口可能失败。飞书推荐使用“创建草稿区块”再“分片更新内容”的方式。本项目对大内容自动执行分片处理，将长文本拆分为多个符合 API 限制的请求顺序发送，极大地提高了大文档写入的成功率。
• 增量更新：并非每次写入都替换整个文档。项目支持指定在文档末尾追加，或在某个特定区块（如标题）之后插入新内容。这依赖于客户端（用户）提供目标位置信息，服务器将其转换为对特定block_id的children字段的更新操作。

注意：飞书 API 的速率限制比较严格。个人应用和企业自建应用有不同的配额。本项目在实现重试逻辑时，必须特别注意 429（请求过多）错误，并采用遵循飞书建议的退避策略，而不是盲目重试，否则可能导致应用被临时禁用。

3. 环境配置与核心实操步骤

要让这个项目跑起来，你需要完成服务器配置和客户端配置两部分工作。下面以 macOS/Linux 开发环境为例，进行详细说明。

3.1 前置条件与飞书应用创建

首先，确保你的系统已安装 Node.js (版本 >= 18) 和 npm/pnpm/yarn 等包管理器。

第一步：创建飞书自建应用这是整个流程中最关键的一步，因为它决定了你的服务器是否有权限操作文档。

1. 登录 飞书开放平台 ，进入“开发者后台”。
2. 点击“创建企业自建应用”。给它起个名字，比如MCP文档助手。
3. 进入应用后，找到“凭证与基础信息”，记录下App ID和App Secret。这两个是服务器用来获取访问令牌的凭据。
4. 配置权限：在“权限管理”页面，为应用添加以下权限：
   • contact:contact:readonly_as_app(建议)：读取部门用户信息，用于后续按人名查找文档分享对象（可选）。
   • drive:drive:readonly：读取云空间目录结构。
   • drive:file:readonly：读取文件（文档）。
   • drive:file:write：核心权限，写入和更新文件（文档）。
   • drive:block:write：核心权限，写入和更新文档区块。 添加后，记得点击“申请线上发布”或“版本管理与发布”创建一个版本并申请发布。通常在企业内部使用，由管理员审核通过即可。

第二步：获取访问令牌项目运行需要访问令牌。飞书 API 调用通常使用“租户访问令牌”或“用户访问令牌”。对于后台服务，我们使用“租户访问令牌”。

1. 在开放平台文档中找到“获取租户访问令牌”的 API。
2. 你可以使用一个简单的 curl 命令或 Postman 来初次获取，用于测试：

   curl -X POST https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal/ \ -H "Content-Type: application/json" \ -d '{ "app_id": "你的App ID", "app_secret": "你的App Secret" }'

3. 响应中会包含tenant_access_token和expire（过期时间，通常为2小时）。但我们的项目会自动处理令牌的获取和刷新，你只需要在配置文件中提供app_id和app_secret。

3.2 项目部署与配置

第一步：获取项目代码

git clone https://github.com/bert995/feishu-mcp-doc-write-stable.git cd feishu-mcp-doc-write-stable pnpm install # 或 npm install

第二步：配置文件详解项目根目录下通常需要一个配置文件（如.env或config.json），用于存放飞书应用的敏感信息。绝对不要将此文件提交到版本库。

一个典型的.env文件内容如下：

# 飞书应用凭证 FEISHU_APP_ID=cli_xxxxxx FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxx # 日志级别，开发时设为 DEBUG，生产环境设为 INFO 或 WARN LOG_LEVEL=DEBUG # MCP 服务器监听的传输方式，可选 stdio 或 sse MCP_TRANSPORT=stdio # 如果是SSE，可能需要配置端口 # MCP_PORT=3000

第三步：启动 MCP 服务器开发环境可以直接用 Node 运行：

node index.js # 或者如果配置了 npm script: npm run start

如果看到类似MCP server running on stdio...的日志，说明服务器已就绪，正在通过标准输入输出等待客户端连接。

3.3 客户端配置（以 Claude Desktop 为例）

Claude Desktop 是当前最流行的 MCP 客户端之一。配置它来使用我们的服务器。

1. 定位配置文件：

   • macOS:~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows:%APPDATA%\Claude\claude_desktop_config.json
   • Linux:~/.config/Claude/claude_desktop_config.json

2. 编辑配置文件：如果文件不存在就创建它。我们需要在mcpServers字段下添加我们的服务器配置。

   { "mcpServers": { "feishu-doc-writer": { "command": "node", "args": [ "/ABSOLUTE/PATH/TO/YOUR/feishu-mcp-doc-write-stable/index.js" ], "env": { "FEISHU_APP_ID": "cli_xxxxxx", "FEISHU_APP_SECRET": "xxxxxxxxxxxx", "LOG_LEVEL": "INFO" } } } }

   • command: 启动服务器的命令，这里是node。
   • args: 命令的参数，第一个是项目入口文件的绝对路径。
   • env: 直接在这里传递环境变量，比使用.env文件更安全，尤其是当 Claude Desktop 以不同用户权限运行时。

3. 重启 Claude Desktop：保存配置文件后，完全退出并重启 Claude Desktop。

4. 验证连接：重启后，在 Claude 的对话中输入/mcp或查看设置中的 MCP 选项，应该能看到feishu-doc-writer服务器已连接，并列出其提供的工具，例如write_to_feishu_doc。

实操心得：在配置args中的路径时，使用绝对路径是最稳妥的。相对路径可能会因为 Claude Desktop 的工作目录不同而导致找不到模块。另外，首次配置后如果工具未出现，可以查看 Claude Desktop 的日志文件（通常在配置文件的同级目录或系统标准日志位置），里面会有 MCP 服务器启动失败的详细错误信息。

4. 核心工具使用详解与场景示例

服务器启动并连接成功后，AI 助手（如 Claude）就获得了操作飞书文档的能力。这些能力以“工具”的形式暴露。我们来深入看看几个核心工具的使用。

4.1write_to_feishu_doc：核心写入工具

这是最常用的工具，用于向一个已存在的飞书文档写入内容。

参数解析：

• document_token(必填): 飞书文档的唯一标识。如何获取？打开目标飞书文档，其 URL 格式为https://your-domain.feishu.cn/docx/DOCUMENT_TOKEN，其中的DOCUMENT_TOKEN就是它。
• content(必填): 要写入的文本内容。支持 Markdown 格式。服务器会将其转换为飞书文档支持的区块格式（如标题、列表、代码块）。
• insert_position(可选): 指定插入位置。默认为end（文档末尾）。也可以是start（文档开头），或者一个具体的block_id（在该区块后插入）。
• overwrite(可选): 布尔值。如果为true，且insert_position为start，则会先清空文档再写入。慎用。

使用示例：在 Claude 对话中，你可以直接说：

“请将下面这段产品需求概述，写入到飞书文档DOCNabc123def456的末尾。” 内容： “# 智能报表 V2.0 需求

目标

提升报表生成速度 50%。

核心功能

1. 支持实时数据预览
2. 新增自定义图表类型
3. 优化导出性能”

Claude 在理解你的意图后，会在后台调用write_to_feishu_doc工具，传入相应的参数。片刻之后，你就会在指定的飞书文档末尾看到格式清晰的新内容。

背后的技术细节：

1. Markdown 解析：服务器收到 Markdown 文本后，会将其解析为抽象的语法树。
2. 区块映射：将语法树节点映射为飞书区块创建请求。例如，# 标题映射为heading1区块，- 列表项映射为bullet区块，```python ... ``` 映射为code区块并设置语言。
3. 分片与顺序写入：如果内容很长，服务器会将其按顺序拆分成多个符合飞书 API 长度限制的区块创建请求，依次发送，确保所有内容都被完整写入。
4. 错误回滚：在分片写入过程中，如果某一片失败，项目会尝试记录已成功写入的点，并在日志中明确报错，避免文档处于“半截”状态。但它通常不会自动回滚已成功的部分，因为这可能破坏文档其他内容。这是设计上的权衡，强调了“稳定”而非“事务性”。

4.2append_to_feishu_doc：追加内容工具

可以看作是write_to_feishu_doc的一个特化版，语义更清晰，专用于在文档末尾追加内容。其参数和使用方式与write_to_feishu_doc当insert_position为end时基本一致。提供这个独立工具是为了让 AI 客户端能更精确地理解用户意图。

4.3read_feishu_doc_info：文档信息读取工具

在写入前，有时需要先了解文档的现有结构，比如获取根节点的block_id，以便进行更精确的插入。

参数：

• document_token(必填): 文档令牌。

返回信息：该工具会返回文档的元信息，如标题、根区块的block_id、创建时间等。更重要的是，它可能会返回文档的顶层区块列表，这为后续的“在某个章节后插入”提供了可能。

场景示例：用户：“我想在飞书文档DOCNxxx的‘项目背景’章节后面，添加新的‘技术选型’部分。” 要实现这个，AI 需要：

1. 调用read_feishu_doc_info或相关工具，获取文档结构，找到标题为“项目背景”的区块及其block_id。
2. 然后调用write_to_feishu_doc，设置insert_position为那个block_id，并传入“技术选型”的内容。

注意事项：飞书 API 获取完整文档树结构可能需要多个请求，并且对于大型文档可能数据量很大。本项目中的信息读取工具可能只返回了基础元信息。如果需要复杂的文档结构分析，可能需要扩展该工具或结合飞书的其他 API（如获取指定区块的子区块列表）。

5. 高级应用与集成模式

掌握了基本操作后，我们可以将这个能力嵌入到更复杂的自动化工作流中。

5.1 与 CI/CD 流水线集成

想象一个场景：每次代码合并到主分支，CI 流程不仅运行测试，还自动生成或更新 API 文档、更新迭代总结。

1. 在 CI 脚本中（如 GitHub Actions, GitLab CI），在构建步骤中，使用脚本生成文档内容（例如，用swagger-jsdoc生成 OpenAPI 描述，或用模板引擎生成迭代报告）。
2. 调用 MCP 服务器：CI 环境可以作为一个无头的 MCP 客户端。你需要一个能运行 Node.js 脚本的环境。可以编写一个简单的 Node.js 脚本，使用@modelcontextprotocol/sdk或其他 MCP 客户端 SDK，连接到你自己部署的feishu-mcp-doc-write-stable服务器（可能需要通过 SSE 传输模式部署在某个内网 URL）。
3. 执行写入：该脚本模拟 AI 客户端，调用write_to_feishu_doc工具，将生成的文档内容写入到指定的、作为知识库基石的飞书文档中。

这样，你的飞书文档就成了一个“活”的、与开发流程同步的文档中心。

5.2 构建自定义的文档生成机器人

你可以基于此项目，构建一个更复杂的、专属于你团队的文档机器人。

1. 部署服务器：将feishu-mcp-doc-write-stable部署为常驻的后台服务（使用 PM2、Docker 等），并通过 SSE 模式暴露一个 HTTP 端点。
2. 开发机器人逻辑：创建一个新的应用（可以是 Slack/钉钉/飞书自己的机器人，也可以是一个简单的 Web 服务）。这个应用负责接收触发条件（如“生成周报”、“整理会议录音”）。
3. 编排 AI 与工具：当机器人被触发时，它首先通过调用大语言模型 API（如 OpenAI, Claude）来生成或整理内容。然后，它作为 MCP 客户端，调用我们部署的飞书写入服务器，将最终内容输出到文档。
4. 扩展工具集：你甚至可以扩展这个 MCP 服务器，除了写入，再增加“从 Confluence 导入”、“从 Jira 同步问题列表”等工具，让机器人的能力更强大。

这种模式下，feishu-mcp-doc-write-stable成为了一个专精的、稳定的“文档输出模块”，被更上层的自动化大脑所调用。

5.3 权限管理与安全考量

在企业环境中使用，安全至关重要。

• 应用权限最小化：如前所述，只授予应用必要的权限（drive:file:write,drive:block:write）。避免授予drive:drive的写权限，除非确实需要移动或删除文件。
• 访问范围控制：飞书自建应用可以设置“可用范围”，只对特定的部门或人员生效。确保只授权给需要使用此功能的团队。
• 令牌安全：tenant_access_token是应用级别的密钥，拥有其权限范围内的所有能力。确保服务器部署环境的安全，配置文件（.env）的访问权限应严格控制。
• 操作审计：飞书开放平台会记录应用的所有 API 调用日志。定期审计这些日志，可以了解使用情况并发现异常操作。项目本身也应记录详细的操作日志，便于追溯。

6. 常见问题排查与性能优化

在实际部署和使用中，你可能会遇到一些问题。以下是一些常见情况的排查思路和优化建议。

6.1 连接与配置问题

6.2 稳定性与性能优化

• 应对飞书 API 限流：飞书 API 有严格的 QPS（每秒查询率）限制。如果频繁写入大量文档，可能触发 429 错误。

  • 策略：项目中的指数退避重试机制是第一道防线。对于批量操作，你需要在业务逻辑层（调用 MCP 的工具层）自己实现限流，例如在 CI 流水线中，在多次写入之间添加延迟（如sleep(1)）。
  • 监控：关注服务器日志中 429 错误出现的频率。如果很高，需要降低操作频率或联系飞书开放平台调整配额（企业版可能支持）。

• 大文档写入优化：写入一个包含数万字和复杂格式的文档。

  • 分片大小：检查项目代码中关于分片大小的配置。通常飞书 API 对一个区块的文本内容有长度限制（如几万字符）。确保分片逻辑正常工作。
  • 异步处理：对于超大型文档生成，可以考虑将“生成内容”和“写入飞书”解耦。先将内容生成到临时文件或数据库，然后通过一个后台队列任务异步执行写入操作，避免阻塞主流程。

• 网络与超时：服务器部署在海外，调用国内飞书 API 可能延迟高。

  • 部署位置：将 MCP 服务器部署在离飞书 API 服务器网络更近的区域（如国内云服务器）。
  • 超时设置：在项目 HTTP 客户端配置中（如axios），适当增加timeout值，以应对网络波动。

6.3 日志分析与调试

日志是排查问题的生命线。项目应配置不同级别的日志（DEBUG, INFO, WARN, ERROR）。

• 开发环境：设置LOG_LEVEL=DEBUG，可以看到详细的请求/响应信息、分片过程等。
• 生产环境：设置LOG_LEVEL=INFO或WARN，只记录关键操作和错误，避免日志量过大。
• 关键信息：在日志中搜索document_token、block_id、status、error等关键词，可以快速定位失败的操作和原因。

例如，一个典型的错误日志可能如下：

[ERROR] Failed to write slice 3/5 for document DOCNxxx. Status: 429, Message: Too Many Requests. Retrying after 2000ms... [INFO] Retry 1/3 succeeded for slice 3.

这清楚地告诉我们发生了限流，并且重试机制正在工作。

7. 总结与未来扩展方向

经过对bert995/feishu-mcp-doc-write-stable项目的深度拆解，我们可以看到，它虽然聚焦于一个看似简单的“写入”动作，但其背后是 MCP 协议生态、飞书 API 复杂性和工程稳定性设计的结合体。它成功地将一个常见的需求封装成了一个标准化、可复用的组件。

在实际使用几个月后，我个人最大的体会是：它极大地改变了团队内容生产的流程。以前，工程师可能需要复制代码片段、产品经理需要整理用户反馈，然后手动在飞书里调整格式。现在，这些都可以通过一句自然语言的指令，或者一个自动化的脚本触发来完成。文档的即时性和一致性得到了保障。更重要的是，它为更复杂的知识管理自动化打开了大门。

当然，目前这个项目主要解决的是“写入”问题。围绕飞书文档和 MCP 生态，还有更多可以探索的方向：

1. 文档读取与智能分析：扩展 MCP 工具，使其能够读取文档内容并进行分析总结。例如，Claude 可以回答“我们上周的会议纪要里关于项目时间线是怎么说的？”这样的问题。
2. 模板化与变量填充：结合飞书文档的“内容组件”或“数据表”能力，实现更智能的模板填充。例如，自动从数据库拉取本周数据，填入预设的周报模板文档中。
3. 多文档与目录操作：增加创建文档、移动文档、在指定知识库目录下创建文档等工具，实现全生命周期的文档管理。
4. 更丰富的格式支持：深入集成飞书文档的高级区块，如任务列表、投票、流程图、双向链接等，使 AI 生成的内容更具交互性和表现力。

项目的“stable”后缀体现了作者对稳定性的追求，这在企业级应用中至关重要。如果你正受困于文档生产的效率瓶颈，或者希望将 AI 更深度地融入团队协作流程，将这个项目作为你的起点，无疑是一个明智的选择。从配置好第一个自动生成的会议纪要开始，你会逐渐发现，人与信息的协作方式，正在悄然改变。