---

项目定位

mcp-feishu-doc 不是对飞书 OpenAPI 的简单直出，而是围绕“文档工作流”做的一层高阶封装。

它重点解决这三件事：

• 把本地 Markdown 稳定上传到飞书云文档或知识库，而不是只暴露底层导入接口。
• 读取文档时返回更适合 AI 消费的结构化结果，而不是只拿一段纯文本。
• 让文档在上传后还能持续维护，包括位置记忆、冲突检测、更新重建和多应用管理。

---

核心亮点

• 文档上传工作流完整：支持 filePath 或 content，支持上传到 drive 或 wiki，支持 targetId 和 parentNodeToken。
• Markdown 处理更强：支持 Front Matter、callout、wiki link、代码块过滤、任务列表、高亮、删除线等语法转换。
• 图片与附件能力完整：支持本地图片/附件上传，支持远程图片/附件下载转存，支持读取时回传媒体资源。
• 文档读取更适合 Agent：返回 content + blocks + assets + revisionId，保留图片/附件在正文中的顺序。
• 更新链路可落地：支持冲突检测、force 覆盖、原位置重建、修订号追踪。
• 本地调试友好：支持 stdio、http、MCP Inspector、本地 mcp.json 配置。
• 工程化完整：支持 DI、存储抽象、结构化日志、OpenTelemetry、单测和集成测试。

---

当前功能

文档工作流

• 上传 Markdown 到飞书文档或知识库
• 批量上传多个 Markdown 文档
• 读取飞书文档内容
• 更新已有飞书文档
• 删除飞书文档
• 搜索飞书文档

媒体能力

• 上传本地图片到文档
• 上传本地附件到文档
• 支持远程图片下载后转存
• 支持远程附件下载后转存
• 读取时返回图片和附件资源
• 读取时提供图片内联 / 本地文件两种交付方式

飞书管理能力

• OAuth 授权与回调处理
• 获取当前用户信息
• 多应用配置与默认应用切换
• 列出知识库空间
• 列出云空间文件夹
• 列出知识库节点

---

工具列表

当前共内置 15 个工具：

工具名	说明
feishu_auth_url	生成飞书 OAuth 2.0 授权链接
feishu_auth_callback	处理飞书 OAuth 授权回调
feishu_upload_markdown	上传 Markdown 文档到飞书云文档或知识库
feishu_update_document	更新已有飞书文档，支持冲突检测
feishu_batch_upload_markdown	批量上传多个 Markdown 文档
feishu_get_document	读取文档内容，返回文本、块结构和媒体资源
feishu_delete_document	删除飞书文档
feishu_search_documents	搜索飞书文档
feishu_list_folders	列出飞书云空间文件夹
feishu_list_wikis	列出飞书知识库空间
feishu_list_wiki_nodes	列出知识库节点
feishu_get_user_info	获取当前飞书用户信息
feishu_set_default_app	设置默认飞书应用
feishu_list_apps	列出已配置的飞书应用
feishu_add_app	添加新的飞书应用配置

工具注册入口见 src/mcp-server/tools/definitions/index.ts。

---

典型使用场景

• 把本地 README.md、方案文档、周报、分享稿直接上传到飞书知识库
• 读取飞书文档后再做总结、改写、翻译或生成更新版本
• 将本地带图片的 Markdown 文档同步到飞书
• 在 AI Agent 中实现“生成文档 -> 上传 -> 读取 -> 更新”的闭环工作流
• 使用多个飞书应用账号切换不同环境或不同租户

---

快速开始

前置要求

• Node.js >= 20
• pnpm >= 10

安装

git clone https://github.com/Hbin-Zhuang/mcp-feishu-doc.git
cd mcp-feishu-doc
pnpm install

配置环境变量

复制示例配置：

cp .env.example .env

最少需要确认这些字段：

• MCP_TRANSPORT_TYPE
• MCP_HTTP_PORT
• STORAGE_PROVIDER_TYPE
• STORAGE_FILESYSTEM_PATH
• FEISHU_DEFAULT_APP_ID
• FEISHU_DEFAULT_APP_SECRET
• FEISHU_OAUTH_CALLBACK_URL

推荐本地调试配置：

MCP_TRANSPORT_TYPE=stdio
MCP_LOG_LEVEL=debug
STORAGE_PROVIDER_TYPE="filesystem"
STORAGE_FILESYSTEM_PATH="./.storage"
FEISHU_OAUTH_CALLBACK_URL=http://localhost:3010/oauth/feishu/callback

如果你要用 OAuth 网页回调，建议再起一个 http 模式实例，或者直接使用 dev:http。

---

本地快速调试

方式一：最快上手，用构建产物 + MCP Inspector

适合检查工具入参、快速点调、验证上传和读取。

pnpm run build
pnpm run inspector

说明：

• pnpm run inspector 会基于 dist/index.js 启动服务。
• 这也是为什么运行 Inspector 前要先执行一次 pnpm run build。
• 如果你刚改了源码但没重新 build，Inspector 里看到的还是旧逻辑。

方式二：源码热更新调试，适合本地开发

STDIO 模式：

pnpm run dev:stdio

HTTP 模式：

pnpm run dev:http

说明：

• dev:stdio 适合 MCP Client 或本地 SDK 客户端直接拉起。
• dev:http 适合调 OAuth 回调、HTTP 接入或浏览器调试。
• 两个命令都基于 tsx watch src/index.ts，改代码会自动重启。

方式三：本地 MCP Client 直接接入

仓库根目录自带一个示例配置文件 mcp.json。

它适合“构建后运行”的场景：

{
  "mcpServers": {
    "mcp-feishu-doc-local": {
      "command": "node",
      "args": ["./dist/index.js"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "debug",
        "FEISHU_DEFAULT_APP_ID": "cli_your_app_id",
        "FEISHU_DEFAULT_APP_SECRET": "your_app_secret",
        "FEISHU_OAUTH_CALLBACK_URL": "http://localhost:3010/oauth/feishu/callback",
        "STORAGE_PROVIDER_TYPE": "filesystem",
        "STORAGE_FILESYSTEM_PATH": "./.storage"
      }
    }
  }
}

使用步骤：

1. 先执行 pnpm run build
2. 将 mcp.json 中的 App ID / Secret 改成你自己的
3. 把这段配置接入你的 MCP Client

如果你想直接调试源码而不是 dist，可以改成这样：

{
  "mcpServers": {
    "mcp-feishu-doc-local-dev": {
      "command": "pnpm",
      "args": ["exec", "tsx", "src/index.ts"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "debug",
        "FEISHU_DEFAULT_APP_ID": "cli_your_app_id",
        "FEISHU_DEFAULT_APP_SECRET": "your_app_secret",
        "FEISHU_OAUTH_CALLBACK_URL": "http://localhost:3010/oauth/feishu/callback",
        "STORAGE_PROVIDER_TYPE": "filesystem",
        "STORAGE_FILESYSTEM_PATH": "./.storage"
      }
    }
  }
}

这个版本的优势是：

• 不需要先 build
• 改完源码即可生效
• 适合本地联调工具定义和服务逻辑

---

常用调试命令

pnpm run build                 # 构建 dist
pnpm run dev:stdio             # 源码热更新，STDIO
pnpm run dev:http              # 源码热更新，HTTP
pnpm run start:stdio           # 运行构建产物，STDIO
pnpm run start:http            # 运行构建产物，HTTP
pnpm run inspector             # 启动 MCP Inspector（依赖 dist）
pnpm run typecheck             # TypeScript 类型检查
pnpm run lint                  # ESLint 检查
pnpm run test                  # 单元测试
pnpm run test:integration:feishu # 飞书集成测试

---

推荐调试路径

调试工具入参与返回值

推荐：

pnpm run build
pnpm run inspector

调试 OAuth 或 HTTP 接口

推荐：

pnpm run dev:http

然后访问：

• http://localhost:3010/oauth/feishu/auth
• http://localhost:3010/oauth/feishu/callback

调试本地 MCP Client 接入

推荐：

• 使用 mcp.json
• 或把 mcpServers 配置复制到你的客户端配置文件

调试源码逻辑

推荐：

pnpm run dev:stdio

然后让本地 MCP Client 使用：

"command": "pnpm",
"args": ["exec", "tsx", "src/index.ts"]

---

配置说明

所有配置在 src/config/index.ts 中统一解析并做 Zod 校验。

常用环境变量如下：

变量	说明	默认值
MCP_TRANSPORT_TYPE	传输方式，stdio 或 http	stdio
MCP_HTTP_HOST	HTTP 服务主机	127.0.0.1
MCP_HTTP_PORT	HTTP 服务端口	3010
MCP_LOG_LEVEL	日志级别	debug
STORAGE_PROVIDER_TYPE	存储后端，推荐本地用 filesystem	filesystem
STORAGE_FILESYSTEM_PATH	本地文件存储路径	./.storage
FEISHU_DEFAULT_APP_ID	默认飞书应用 ID	无
FEISHU_DEFAULT_APP_SECRET	默认飞书应用密钥	无
FEISHU_OAUTH_CALLBACK_URL	飞书 OAuth 回调地址	无
OTEL_ENABLED	是否启用 OpenTelemetry	false

注意：本地调试时推荐使用 filesystem 存储，否则 OAuth 凭证、文档元数据和默认应用信息不会持久保存。

---

当前上传 / 读取 / 更新能力

上传

• 支持 filePath 和 content
• 支持 drive / wiki
• 支持 targetId 和 parentNodeToken
• 支持 Markdown 预处理
• 支持本地图片与附件上传
• 支持远程图片与附件转存

读取

• 返回 title
• 返回近似 Markdown 的 content
• 返回保序的 blocks
• 返回 assets
• 返回 revisionId

更新

• 支持内容或文件路径更新
• 支持冲突检测
• 支持 force 强制覆盖
• 支持原位置重建
• 支持修订号追踪

---

架构概览

核心调用链如下：

MCP Tool Definition
  -> FeishuService
    -> FeishuApiProvider
    -> MarkdownProcessorProvider
    -> StorageService

对应目录：

• src/mcp-server/tools/definitions：工具定义
• src/services/feishu：飞书服务编排与 API 调用
• src/storage：持久化与多后端抽象
• src/container：依赖注入
• src/utils：日志、性能、解析、遥测等横切能力

---

项目结构

目录	用途
src/mcp-server/tools/definitions	MCP 工具定义
src/mcp-server/transports	stdio / http 传输实现
src/services/feishu	飞书文档与知识库核心逻辑
src/storage	存储抽象和 Provider 实现
src/container	依赖注入配置
src/utils	日志、性能、解析、遥测
tests	单元测试与集成测试
docs	设计、开发与技术分享文档

---

测试与质量检查

pnpm run typecheck
pnpm run lint
pnpm run test
pnpm run test:integration:feishu

---

部署

本地运行构建产物

pnpm run build
pnpm run start:stdio

或：

pnpm run build
pnpm run start:http

Cloudflare Workers

pnpm run deploy:dev
pnpm run deploy:prod

---

相关文档

• AGENTS.md
• docs/DEVELOPMENT_GUIDE.md
• src/mcp-server/README.md
• src/storage/README.md

---

许可证

本项目基于 Apache 2.0 许可证发布，详见 LICENSE。