✨ 特性

• 飞书云文档集成：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 或更高版本

安装

1. 克隆仓库：

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

2. 进入目录：

cd mcp-feishu-doc

3. 安装依赖：

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

1. 构建 Worker 包：

pnpm run build

2. 使用 Wrangler 本地运行：

pnpm run deploy:dev

3. 部署到 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 文件。