# feishu-doc-mcp

飞书云文档 MCP Server，为 Claude Code 提供飞书文档的创建、读取、编辑能力。

通过代理飞书 MCP 网关（`mcp.feishu.cn`），以用户身份（User Access Token）操作文档，支持 token 自动刷新，一次授权长期使用。

## 功能

| 工具 | 说明 |
|------|------|
| `feishu_auth` | OAuth 2.0 认证（PKCE + offline_access），首次使用需在浏览器授权 |
| `feishu_fetch_doc` | 读取文档内容，返回 Markdown 格式，支持分页 |
| `feishu_create_doc` | 从 Markdown 创建新文档，可指定文件夹/知识库位置 |
| `feishu_update_doc` | 更新文档，支持 7 种模式：追加、覆盖、范围替换、全文替换、前/后插入、删除 |

## 前置条件

1. **Node.js >= 18**
2. **飞书开放平台应用**（[创建应用](https://open.feishu.cn/app)）
   - 记下 App ID 和 App Secret
   - 在 **安全设置 → 重定向 URL** 中添加：`http://localhost:<端口>/callback`（默认端口 `9876`）
   - 在 **权限管理** 中开通需要的权限（如 `docx:document`）

## 安装

```bash
git clone https://github.com/ShacklesLay/feishu-doc-mcp.git
cd feishu-doc-mcp
npm install
```

## 配置 Claude Code

编辑 `~/.claude.json`，在 `mcpServers` 中添加：

```json
{
  "mcpServers": {
    "feishu-doc": {
      "type": "stdio",
      "command": "bash",
      "args": [
        "-c",
        "export FEISHU_APP_ID=你的AppID FEISHU_APP_SECRET=你的AppSecret; exec node /path/to/feishu-doc-mcp/server.mjs"
      ]
    }
  }
}
```

### 环境变量

| 变量 | 必填 | 说明 |
|------|------|------|
| `FEISHU_APP_ID` | 是 | 飞书应用 App ID |
| `FEISHU_APP_SECRET` | 是 | 飞书应用 App Secret |
| `FEISHU_AUTH_PORT` | 否 | OAuth 回调端口，默认 `9876`，需与飞书后台重定向 URL 一致 |

## 使用

### 首次认证

1. 在 Claude Code 中调用 `feishu_auth`（mode=start）
2. 在浏览器中打开返回的授权链接
3. 点击授权，页面显示"授权成功"即完成

认证后 token 会自动刷新（通过 refresh_token），无需重复授权。

### 读取文档

```
feishu_fetch_doc(doc_id: "文档ID或URL")
```

支持分页参数 `offset` 和 `limit`。

### 创建文档

```
feishu_create_doc(title: "标题", markdown: "# 内容")
```

可选参数指定位置：
- `folder_token` — 放入指定文件夹
- `wiki_space` — 放入知识空间（`my_library` 表示个人空间）
- `wiki_node` — 放入知识库节点下

三者互斥，只能选一个。

### 更新文档

```
feishu_update_doc(doc_id: "文档ID", mode: "append", markdown: "追加的内容")
```

7 种更新模式：

| 模式 | 说明 |
|------|------|
| `append` | 在文档末尾追加 |
| `overwrite` | 覆盖整个文档 |
| `replace_range` | 替换指定范围（配合 `selection_by_title` 或 `selection_with_ellipsis`） |
| `replace_all` | 全文查找替换 |
| `insert_before` | 在指定位置前插入 |
| `insert_after` | 在指定位置后插入 |
| `delete_range` | 删除指定范围 |

### 检查认证状态

```
feishu_auth(mode: "status")
```

## Token 存储

Token 以 JSON 明文存储在 `~/.local/share/feishu-doc-mcp/tokens.json`，仅限本地使用。

## 架构

```
Claude Code
  └── feishu-doc MCP Server (stdio)
        ├── feishu_auth     → OAuth 2.0 + PKCE → 飞书开放平台
        ├── feishu_fetch_doc ─┐
        ├── feishu_create_doc ├→ JSON-RPC 2.0 → mcp.feishu.cn/mcp
        └── feishu_update_doc ─┘
              Headers: X-Lark-MCP-UAT, X-Lark-MCP-Allowed-Tools
```

## License

MIT