hljy-lark-doc-helper 0.1.2

MCP server for uploading markdown files to Lark documents with automatic image processing

飞书文档助手 (Lark Doc Helper)

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

功能特性

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

安装

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

# 使用 uv 安装依赖
uv sync

# 或者使用 pip
pip install -e .

配置

环境变量配置

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

# 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 服务器运行

python main.py

在 Cursor 中使用

详细的Cursor配置指南请参考 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: 飞书文档的挂载密钥

示例：

{
  "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. 上传凭证接口响应:

{
  "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. 飞书文档上传接口响应:

{
  "status": "success",
  "code": 200,
  "message": null,
  "data": {
    "url": "https://hailiang.feishu.cn/docx/XgWDdPwRCoK7QkxcaztcOMjFnCd"
  }
}

许可证

本项目使用 MIT 许可证。

贡献

欢迎提交 Issue 和 Pull Request！