hljy-lark-doc-helper 0.1.9
MCP server for uploading markdown files to Lark documents with automatic image processing
License: MIT
Requires Python: >=3.12
Keywords: document, feishu, lark, markdown, mcp, upload

# 飞书文档助手 (Lark Doc Helper)

一个 MCP (Model Context Protocol) 服务器，用于将本地 Markdown 文件上传到飞书文档，并自动处理本地图片引用。

## 功能特性

- 📄 上传 Markdown 文件到飞书文档
- 🖼️ 自动检测并上传本地图片引用
- 🔗 自动替换图片链接为公共访问URL
- ⚙️ 可配置的API endpoints和认证信息
- 📊 支持多种图片格式 (jpg, jpeg, png, gif, bmp, webp, svg)

## 安装

确保您的系统已安装 Python 3.12+，然后运行：

```bash
# 使用 uv 安装依赖
uv sync

# 或者使用 pip
pip install -e .
```

## 配置

### 环境变量配置

创建一个 `.env` 文件或设置以下环境变量：

```bash
# API Endpoints配置
UPLOAD_CREDENTIALS_ENDPOINT=http://0.0.0.0:19106/api/v1/obs/post-signature/md-image-upload
OBS_UPLOAD_ENDPOINT=https://hljydc-common.obs.cn-east-3.myhuaweicloud.com
LARK_DOC_UPLOAD_ENDPOINT=http://0.0.0.0:19106/api/v1/lark-doc/helper/markdown-to-docx

# 认证配置
API_KEY=your-api-key
API_SECRET=your-api-secret

# 飞书应用配置
LARK_APP_ID=your-lark-app-id
LARK_APP_SECRET=your-lark-app-secret
LARK_TENANT_TOKEN=your-lark-tenant-token

# 默认挂载密钥（可选，也可以在调用时传入）
DEFAULT_MOUNT_KEY=

# 其他配置
MAX_FILE_SIZE=10485760  # 10MB
REQUEST_TIMEOUT=30      # 30秒
```

### 必需的API接口

您需要提供以下三个API接口：

1. **获取上传凭证接口**
   - 端点：`UPLOAD_CREDENTIALS_ENDPOINT`
   - 方法：POST
   - 请求体：`{"filename": "image.jpg"}`
   - 返回：包含OBS访问凭证的JSON

2. **OBS图片上传接口**
   - 端点：`OBS_UPLOAD_ENDPOINT`
   - 方法：POST
   - 请求：表单数据（multipart/form-data）
   - 返回：204状态码表示成功

3. **飞书文档上传接口**
   - 端点：`LARK_DOC_UPLOAD_ENDPOINT`
   - 方法：POST
   - 请求体：`{"markdown": "...", "doc_name": "...", "mount_key": "..."}`
   - 返回：包含文档URL的JSON

## 使用方法

### 作为 MCP 服务器运行

```bash
python main.py
```

### 在 Cursor 中使用

详细的Cursor配置指南请参考 [cursor-mcp-config.md](cursor-mcp-config.md)

简要配置：
1. 在Cursor设置中添加MCP服务器配置
2. 配置命令：`python /path/to/main.py`
3. 设置环境变量（API endpoints等）
4. 在聊天中直接使用工具

### 在其他 MCP 客户端中使用

服务器提供一个工具：`upload_markdown_to_lark_doc`

参数：
- `markdown_file_path`: 要上传的 Markdown 文件的绝对路径
- `doc_title`: 飞书文档的标题
- `mount_key`: 飞书文档的挂载密钥

示例：
```json
{
  "tool": "upload_markdown_to_lark_doc",
  "arguments": {
    "markdown_file_path": "/path/to/your/document.md",
    "doc_title": "我的文档标题",
    "mount_key": "change-this"
  }
}
```

## 工作流程

1. **读取 Markdown 文件**：从指定路径读取 Markdown 内容
2. **检测本地图片**：使用正则表达式找到所有本地图片引用
3. **上传图片**：
   - 调用接口1获取上传凭证
   - 调用接口2上传每张图片到OBS
   - 获取图片的公共访问URL
4. **替换图片链接**：将 Markdown 中的本地图片路径替换为公共URL
5. **上传文档**：调用接口3将最终的 Markdown 内容上传到飞书文档

## 支持的图片格式

- `.jpg`, `.jpeg`
- `.png`
- `.gif`
- `.bmp`
- `.webp`
- `.svg`

## 错误处理

- 文件不存在时会返回错误
- 图片文件大小超过限制时会返回错误
- API调用失败时会返回详细的错误信息
- 配置验证失败时会返回配置错误信息

## 日志

服务器会记录以下信息：
- 发现的本地图片数量
- 图片上传进度和结果
- API调用错误和异常

## 开发

### 项目结构

```
lark-doc-helper/
├── main.py           # 主程序文件
├── config.py         # 配置管理
├── pyproject.toml    # 项目配置
├── README.md         # 说明文档
└── uv.lock          # 依赖锁定文件
```

### 自定义API接口

您需要实现以下接口格式：

1. **上传凭证接口响应**:
```json
{
  "status": "success",
  "code": 200,
  "message": null,
  "data": {
    "policy": "base64-encoded-policy",
    "signature": "signature-string",
    "accessKeyId": "access-key-id",
    "key": "temp/md-image/20250717/uuid/filename.jpg",
    "originPolicy": "original-policy-json"
  }
}
```

2. **OBS上传接口响应**:
- 状态码：200 或 204 表示成功
- 上传成功后，图片可通过 `{obs_endpoint}/{key}` 访问

3. **飞书文档上传接口响应**:
```json
{
  "status": "success",
  "code": 200,
  "message": null,
  "data": {
    "url": "https://hailiang.feishu.cn/docx/XgWDdPwRCoK7QkxcaztcOMjFnCd"
  }
}
```

## 许可证

本项目使用 MIT 许可证。

## 贡献

欢迎提交 Issue 和 Pull Request！