@hibson/mcp-feishu-doc

v2.6.4

Published

10 days ago

A Model Context Protocol (MCP) server for Feishu (Lark) cloud document and wiki management. Supports OAuth, Markdown upload, document reading/updating/deleting, search, and multi-app configuration.

0High
0Medium
0Low

hibson

feishu lark mcp model-context-protocol mcp-server typescript wiki document markdown oauth

✨ 特性

飞书云文档集成：OAuth 2.0 认证、Markdown 上传/更新/删除、批量上传、文档搜索。
知识库管理：列出知识库空间、文件夹、知识库节点。
多应用配置：支持多个飞书应用、设置默认应用。
抽象化存储：支持 in-memory、filesystem、Supabase、SurrealDB 等后端。
强大的错误处理：统一的 McpError 系统确保一致的错误响应。
全栈可观测性：结构化日志（Pino）和可选的 OpenTelemetry。
边缘就绪：支持本地或 Cloudflare Workers 运行。

🏗️ 架构

本项目遵循模块化、领域驱动的架构，具有清晰的关注点分离：

┌─────────────────────────────────────────────────────────┐
│              MCP 客户端（Claude Code、ChatGPT 等）        │
└────────────────────┬────────────────────────────────────┘
                     │ JSON-RPC 2.0
                     ▼
┌─────────────────────────────────────────────────────────┐
│           MCP 服务器（工具、资源）                        │
│           📖 [MCP 服务器指南](src/mcp-server/)          │
└────────────────────┬────────────────────────────────────┘
                     │ 依赖注入
                     ▼
┌─────────────────────────────────────────────────────────┐
│          依赖注入容器                                     │
│              📦 [容器指南](src/container/)              │
└────────────────────┬────────────────────────────────────┘
                     │
        ┌────────────┼────────────┐
        ▼            ▼            ▼
 ┌──────────┐   ┌──────────┐   ┌──────────┐
 │ 服务     │   │ 存储     │   │ 工具     │
 │ 🔌 [→]   │   │ 💾 [→]   │   │ 🛠️ [→]   │
 └──────────┘   └──────────┘   └──────────┘

[→]: src/services/    [→]: src/storage/    [→]: src/utils/

核心模块：

MCP 服务器 - 工具、资源、提示和传输层实现
容器 - 使用 tsyringe 进行依赖注入设置，实现清晰的架构
服务 - 外部服务集成（LLM、语音、图），具有可插拔的提供者
存储 - 抽象化的持久层，支持多个后端
工具 - 横切关注点（日志记录、安全、解析、遥测）

💡 提示：每个模块都有自己的综合 README，包含架构图、使用示例和最佳实践。点击上面的链接深入了解！

🛠️ 功能概览

飞书工具

🚀 快速开始

MCP 客户端设置/配置

将以下内容添加到您的 MCP 客户端配置文件（例如，cline_mcp_settings.json）。

{
  "mcpServers": {
    "mcp-feishu-doc": {
      "command": "npx",
      "args": ["-y", "@hibson/mcp-feishu-doc@latest"],
      "env": {
        "FEISHU_DEFAULT_APP_ID": "cli_xxx",
        "FEISHU_DEFAULT_APP_SECRET": "xxx",
        "FEISHU_OAUTH_CALLBACK_URL": "http://localhost:3010/oauth/feishu/callback",
        "MCP_TRANSPORT_TYPE": "stdio",
        "LOGS_DIR": "~/.mcp-feishu-doc/logs",
        "STORAGE_PROVIDER_TYPE": "filesystem",
        "STORAGE_FILESYSTEM_PATH": "~/.mcp-feishu-doc/storage"
      }
    }
  }
}

前置要求

Node.js v20.0.0 或更高版本
pnpm v10.0.0 或更高版本

安装

克隆仓库：

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

cd mcp-feishu-doc

安装依赖：

pnpm install

⚙️ 配置

所有配置都在 src/config/index.ts 中集中管理并在启动时验证。.env 文件中的关键环境变量包括：

身份验证和授权

模式：none（默认）、jwt（需要 MCP_AUTH_SECRET_KEY）或 oauth（需要 OAUTH_ISSUER_URL 和 OAUTH_AUDIENCE）。
强制执行：使用 withToolAuth([...]) 或 withResourceAuth([...]) 包装您的工具/资源 logic 函数以强制执行范围检查。当身份验证模式为 none 时，为方便开发人员，范围检查会被绕过。

存储

服务：DI 管理的 StorageService 为持久化提供一致的 API。永远不要从工具逻辑直接访问 fs 或其他存储 SDK。
提供者：默认是 in-memory。仅 Node 的提供者包括 filesystem。边缘兼容的提供者包括 supabase、surrealdb、cloudflare-kv 和 cloudflare-r2。
SurrealDB 设置：使用 surrealdb 提供者时，在首次使用前使用 docs/surrealdb-schema.surql 初始化数据库架构。
多租户：StorageService 需要 context.tenantId。启用身份验证时，这会自动从 JWT 中的 tid 声明传播。
高级功能：
- 安全分页：带有租户 ID 绑定的不透明游标可防止跨租户攻击
- 批处理操作：getMany()、setMany()、deleteMany() 的并行执行
- TTL 支持：所有提供者的生存时间，具有适当的过期处理
- 全面验证：租户 ID、密钥和选项的集中输入验证

可观测性

结构化日志记录：Pino 已开箱即用集成。所有日志都是 JSON 格式，并包含 RequestContext。
OpenTelemetry：默认禁用。通过设置 OTEL_ENABLED=true 并配置 OTLP 端点来启用。每次工具调用都会自动捕获跟踪、指标（持续时间、负载大小）和错误。

▶️ 运行服务器

本地开发

构建并运行生产版本：

# 一次性构建
pnpm run rebuild

# 运行构建的服务器
pnpm run start:http
# 或
pnpm run start:stdio

运行检查和测试：

pnpm run typecheck  # 类型检查
pnpm run lint       # 代码检查
pnpm run test       # 运行测试套件

Cloudflare Workers

构建 Worker 包：

pnpm run build

使用 Wrangler 本地运行：

pnpm run deploy:dev

部署到 Cloudflare：

pnpm run deploy:prod

注意：wrangler.toml 文件已预配置以启用 nodejs_compat 以获得最佳结果。

📂 项目结构

📚 文档

每个主要模块都包含综合文档，包括架构图、使用示例和最佳实践：

核心模块

MCP 服务器指南 - 构建 MCP 工具和资源的完整指南
- 使用声明式定义创建工具
- 使用 URI 模板进行资源开发
- 身份验证和授权
- 传输层（HTTP/stdio）配置
- SDK 上下文和客户端交互
- 响应格式化和错误处理
容器指南 - 使用 tsyringe 进行依赖注入
- 理解 DI 令牌和注册
- 服务生命周期（单例、瞬态、实例）
- 构造函数注入模式
- 使用模拟依赖进行测试
- 向容器添加新服务
服务指南 - 外部服务集成模式
- LLM 提供者集成（OpenRouter）
- 语音服务（使用 ElevenLabs、Whisper 的 TTS/STT）
- 图数据库操作（SurrealDB）
- 创建自定义服务提供者
- 健康检查和错误处理
存储指南 - 抽象化的持久层
- 存储提供者实现
- 多租户和租户隔离
- 基于游标的安全分页
- 批处理操作和 TTL 支持
- 特定于提供者的设置指南

其他资源

AGENTS.md - AI 代理的严格开发规则
CHANGELOG.md - 版本历史和重大变更
docs/DEVELOPMENT_GUIDE.md - 开发指南

🧑‍💻 代理开发指南

有关使用 AI 代理开发本项目的规则，请参阅 AGENTS.md。关键原则包括：

逻辑抛出，处理器捕获：永远不要在工具/资源 logic 中使用 try/catch。而是抛出 McpError。
使用引导获取缺失输入：如果工具需要用户输入但未提供，请使用 SdkContext 中的 elicitInput 函数向用户询问。
传递上下文：始终通过调用堆栈传递 RequestContext 对象。
使用桶导出：仅在 index.ts 桶文件中注册新工具和资源。

❓ 常见问题

这同时支持 STDIO 和 Streamable HTTP 吗？
- 是的。两种传输都是一等公民。使用 pnpm run dev:stdio 或 pnpm run dev:http。
我可以将其部署到边缘吗？
- 是的。本项目支持 Cloudflare Workers。运行 pnpm run build 后使用 pnpm run deploy:dev 或 pnpm run deploy:prod 部署。
我必须使用 OpenTelemetry 吗？
- 不，默认情况下它是禁用的。通过在 .env 文件中设置 OTEL_ENABLED=true 来启用它。

🤝 贡献

欢迎提交问题和拉取请求！如果您计划贡献，请在提交 PR 之前运行本地检查和测试。

pnpm run typecheck && pnpm run lint
pnpm run test

📜 许可证

本项目根据 Apache 2.0 许可证授权。有关详细信息，请参阅 LICENSE 文件。