GE Feishu Bridge Server (MCP)

ge_feishu_bridge_server_mcp 是一个基于 FastAPI 和 Model Context Protocol (MCP) 架构搭建的飞书（Feishu / Lark）连接器桥接服务。

它作为 Gemini Engine (GE) 及各类支持 MCP 协议的 AI Agent 与飞书开放平台之间的桥梁，提供了高效的 MCP 工具调用接口、飞书 Token 校验以及强大的多类型飞书文档自适应读取与 Markdown 转译功能。

---

🌟 核心特性

• 标准 MCP 协议支持：支持基于 HTTP SSE (Server-Sent Events) 与 JSON-RPC 2.0 的 MCP 规范（接口路线 /mcp），无缝对接各类 MCP 客户端。
• 自适应文档探针 (Adaptive Reader)：
  • 新版文档 (Docx)：提取 Raw Content 富文本。
  • 知识库 (Wiki Node)：自动解译 Wiki 节点对应的实体 obj_token 与 obj_type 并精准加载。
  • 电子表格 (Sheets)：提取工作表数据并格式化为标准 Markdown 表格输出。
  • 多维表格 (Bitable)：解析数据表字段与记录，转译为直观的 Markdown 表格。
  • 旧版文档 (Legacy Doc)：兼容旧版文档 API。
• 快捷路由映射 (Shortcut Map)：支持硬编码关键词元组（如 ("4月", "日志")）直达特定飞书文档 Token，提高高频文档读取速度。
• 友好鉴权与错误防护：精细化识别飞书授权错误码（如 20006, 99991668 等）。捕获 Token 失效时返回标准 JSON-RPC 友好错误信息，防止 HTTP 401 导致 MCP SSE 链接崩溃，并指导用户开启 offline_access 作用域重新登录。
• 云原生云端部署：基于 Docker 与 httpx.AsyncClient 异步连接池，默认绑定 8080 端口，完美兼容 Google Cloud Run 等无服务器容器托管平台。

---

🛠️ MCP 工具说明

本服务向 MCP 客户端暴露以下工具（Tools）：

工具名称	描述	入参
checkToken	检查当前传入的飞书 Bearer Token 是否合法有效	无
searchDocs	根据关键词在飞书中搜索并自适应读取解析目标文档内容	query (string): 搜索关键词或短语

---

🚀 快速开始

1. 本地运行

前置要求

• Python 3.11+

安装依赖

pip install -r requirements.txt

配置环境变量

复制环境模版并配置您的飞书应用凭证：

cp .env.example .env

在 .env 中填写您的 FEISHU_APP_ID 和 FEISHU_APP_SECRET：

FEISHU_APP_ID=cli_xxxxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxx
PORT=8080
HOST=0.0.0.0

启动服务

python main.py

服务默认监听在 http://0.0.0.0:8080/mcp。

---

2. Docker 部署

# 构建镜像
docker build -t ge-feishu-bridge-server .

# 运行容器
docker run -d -p 8080:8080 --env-file .env ge-feishu-bridge-server

---

🧪 单元测试

项目内置了针对 Sheets 与 Bitable 自适应读取转译逻辑的单元测试：

python test_adaptive_reader.py

---

📂 项目结构

.
├── main.py                   # FastAPI + MCP 核心服务逻辑与飞书 API 自适应适配
├── test_adaptive_reader.py   # Sheets 与 Bitable 读取能力的单元测试
├── Dockerfile                # 容器化构建配置 (基于 python:3.11-slim)
├── requirements.txt          # 项目 Python 依赖
├── .env.example              # 环境变量模版
├── .gitignore                # Git 忽略配置 (忽略 .env 密钥及缓存)
└── README.md                 # 项目说明文档