# 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+

#### 安装依赖
```bash
pip install -r requirements.txt
```

#### 配置环境变量
复制环境模版并配置您的飞书应用凭证：
```bash
cp .env.example .env
```

在 `.env` 中填写您的 `FEISHU_APP_ID` 和 `FEISHU_APP_SECRET`：
```env
FEISHU_APP_ID=cli_xxxxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxx
PORT=8080
HOST=0.0.0.0
```

#### 启动服务
```bash
python main.py
```
服务默认监听在 `http://0.0.0.0:8080/mcp`。

---

### 2. Docker 部署

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

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

---

## 🧪 单元测试

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

```bash
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                 # 项目说明文档
```