docmark

docmark

docmark 是一个本地 stdio 前端，用于连接托管的文档转 Markdown 转换服务。提供一个公开 URL、文件的 base64 内容，或其中任意一种的小型批次，它就会请求托管服务进行转换，并返回 Markdown。

docmark 本身不执行任何转换。每次工具调用都会以 JSON POST 的形式转发到托管的 file2markdown API，上游负载会原样返回——包括输出达到 200,000 字符上限时服务返回的 truncated 标志。转换质量、支持的格式范围、可用性和套餐限制均由托管服务决定。

文档列出的输入类型包括 PDF、DOCX、PPTX、XLSX、CSV、JSON、XML、HTML、EPUB、图像（含 OCR）、音频和 ZIP 压缩包。调用 list_supported_formats 可获取实时格式列表、各套餐限制，以及需要 Pro 的功能。

FILE2MARKDOWN_API_KEY 为可选项：免费套餐无需密钥即可使用。设置密钥时，它会作为 Authorization: Bearer <key> 发送；未设置时则不会发送 Authorization 标头。DOCMARK_API_URL 可覆盖 API 基础地址（默认为 https://api.file2markdown.ai，这是对线路格式的标注式还原）。

每次批量转换需包含 2–10 个项目，且会在发送前于本地进行校验。每个项目的格式为 {url} 或 {content_base64, filename}。

安装

npx @reneturcios/docmark convert_url --url https://example.com/report.pdf
docker run -i ghcr.io/cloudcorprecords/docmark

命令行界面

docmark convert_url --url https://example.com/report.pdf
docmark convert_base64 --content-base64 aGVsbG8= --filename note.txt
docmark convert_base64 --file ./report.pdf
docmark convert_batch --items-json '[{"url":"https://example.com/a.pdf"},{"content_base64":"eA==","filename":"x.txt"}]'
docmark list_supported_formats
docmark usage_status
docmark --version

退出代码：0 表示成功，1 表示上游或校验错误，2 表示用法错误。

MCP 服务

npx -y @reneturcios/docmark mcp

{
  "mcpServers": {
    "docmark": {
      "command": "npx",
      "args": ["-y", "@reneturcios/docmark", "mcp"],
      "env": { "FILE2MARKDOWN_API_KEY": "your-key-if-you-have-one" }
    }
  }
}

env 块为可选项——使用无需密钥的免费套餐时可省略。

工具

工具	输入	返回内容
convert_url	url（字符串，必填）	对该 URL 对应的页面或文档进行上游转换的结果。
convert_base64	content_base64（字符串，必填），filename（字符串，可选）	对所提供文件内容进行上游转换的结果。
convert_batch	items（数组，必填，2–10 个项目，每个项目格式为 {url} 或 {content_base64, filename}）	各项目的上游结果。
list_supported_formats	—	服务支持的格式、各套餐限制，以及需要 Pro 的功能。
usage_status	—	调用者的套餐以及当天剩余的转换次数。

上游故障（包括 HTTP 错误和无法访问的主机）会作为工具错误报告，并附带底层错误消息。

开发

npm install
npm run build
npm test
npm run dev

测试完全使用模拟 fetch 夹具运行；不会使用网络，也不会调用托管服务。

许可证

MIT — 详见 LICENSE。