Skip to main content
Glama
AvatarGanymede

MinerU Document to Markdown MCP Server

by AvatarGanymede
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

MinerU Document to Markdown MCP Server

English | 中文

一个 Model Context Protocol (MCP) 服务器，用于通过 MinerU API 将多种格式文档转换为 Markdown 格式。支持 URL 和本地文件两种输入方式。

功能特点

  • 🔄 使用 Python requests 调用 MinerU API

  • 📄 支持多种格式：PDF, DOC, DOCX, PPT, PPTX, PNG, JPG, JPEG, HTML

  • 📁 支持本地文件自动上传解析

  • 🔍 支持 OCR、公式识别、表格识别

  • 🧠 智能参数自动配置（根据文件类型自动选择模型和参数）

  • 📦 大文件智能拆分（>200MB 自动物理拆分，>600 页自动使用 page_ranges）

  • ⚡ 提供完整的转换工作流（提交任务 → 轮询状态 → 获取结果）

Related MCP server: MCP-PDF2MD

安装

1. 安装依赖

pip install -r requirements.txt

2. 获取 MinerU API Token

访问 https://mineru.net 注册并申请 API Token。

3. 配置 MCP 客户端

方式一：uvx 启动（推荐，无需手动安装依赖）

安装 uv 后，可直接通过 uvx 运行，无需 pip install：

uvx mineru-converter-mcp-server stdio

编辑 Claude Desktop 或 Cursor MCP 配置文件：

Windows: %APPDATA%\Claude\claude_desktop_config.json 或 Cursor 设置中的 MCP 配置 macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "mineru": {
      "command": "uvx",
      "args": ["--with", "mineru-converter-mcp-server", "python", "-m", "mineru_mcp", "stdio"],
      "env": {
        "MINERU_API_KEY": "your_mineru_api_token"
      }
    }
  }
}

说明：使用 -m mineru_mcp 模块方式启动，可规避 Windows 下 uvx console script 的兼容问题。开发阶段可从源码安装：uv pip install -e . 后使用 mineru-converter-mcp-server stdio。

方式二：Python 版（功能完整，支持本地文件和大文件拆分）

需先安装依赖：pip install -r requirements.txt

编辑 Claude Desktop 配置文件：

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "mineru": {
      "command": "python",
      "args": ["src/mineru_mcp/server.py"],
      "cwd": "C:/path/to/MinerU-MCP",
      "env": {
        "MINERU_API_KEY": "your_mineru_api_token"
      }
    }
  }
}

将 C:/path/to/MinerU-MCP 替换为项目实际路径。cwd 确保从项目根目录运行。

方式三：TypeScript 版（适用于 Smithery 部署和本地开发）

需要先安装 Node.js 20+ 和项目依赖：

npm install

在项目根目录创建 .mcp.json（Claude Code）或编辑 claude_desktop_config.json（Claude Desktop）：

macOS / Linux:

{
  "mcpServers": {
    "mineru": {
      "command": "npx",
      "args": ["tsx", "src/main.ts"],
      "env": {
        "MINERU_API_KEY": "your_mineru_api_token"
      }
    }
  }
}

Windows:

{
  "mcpServers": {
    "mineru": {
      "command": "cmd",
      "args": ["/c", "npx", "tsx", "src/main.ts"],
      "env": {
        "MINERU_API_KEY": "your_mineru_api_token"
      }
    }
  }
}

注意：TypeScript 版仅支持 URL 输入，不支持本地文件上传和大文件拆分。如需这些功能请使用 Python 版。

本地 HTTP 服务（可选）：npm run start:http 或 MINERU_API_KEY=xxx npx tsx src/server-http.ts，默认监听 10000 端口，暴露 /mcp 和 /.well-known/mcp-config。

两种方式均需将 your_mineru_api_token 替换为你的 MinerU API Token（在 https://mineru.net/apiManage/token 申请）。

部署到 Render（Deploy via URL，免费）

使用 Render 将 TypeScript 版 MCP 部署为公开 HTTPS 服务，然后在 Smithery 选择「Deploy via URL」即可免费分发。无需 smithery dev，自建 HTTP 服务即可运行。

  1. Fork 并推送：确保本仓库代码已推送到 GitHub

  2. 创建 Blueprint：打开 Render Dashboard → New → Blueprint

  3. 连接仓库：选择 MinerU-MCP 仓库，Render 会自动读取根目录的 render.yaml

  4. 部署：点击 Create / Apply，等待构建完成

  5. 获取 URL：部署完成后会得到 https://mineru-mcp.onrender.com 之类的 HTTPS 地址

  6. 登记到 Smithery：

    • 网页：在 Smithery New Server 选择 External MCP / Deploy via URL，填入上述 URL（会有 config schema 警告，可忽略；用户在 Add Parameter 中手动填 mineruApiKey）

    • CLI（推荐，消除警告）：smithery auth login 登录后执行：

      smithery mcp publish "https://你的Render地址/mcp" -n @你的命名空间/mineru-mcp --config-schema '{"type":"object","properties":{"mineruApiKey":{"type":"string","title":"MinerU API Key","description":"Your MinerU API Key (obtain from https://mineru.net/apiManage/token)","x-from":{"header":"x-mineru-api-key"}}}}'

Smithery Deploy via URL：不设置 MINERU_API_KEY，每个用户会在 Smithery 添加 MCP 时填写自己的 API Key。

自托管单租户：在 Render Environment 中设置 MINERU_API_KEY，则所有请求共用该 Key。

支持的文件格式

格式

扩展名

自动配置

PDF

.pdf

默认使用 vlm 模型

Word

.doc, .docx

默认使用 vlm 模型

PowerPoint

.ppt, .pptx

默认使用 vlm 模型

图片

.png, .jpg, .jpeg

自动开启 OCR

网页

.html

自动使用 MinerU-HTML 模型

大文件处理

服务器自动处理超大文件，无需手动干预：

  • 文件 >200MB（仅 PDF）：自动物理拆分为多个小文件，分别处理后返回结果

  • 文件 >600 页（仅 PDF）：自动使用 page_ranges 参数分段处理

  • 拆分算法：同时考虑文件大小（180MB/片）和页数（600页/片）双重约束，取较大值确保每个分片同时满足两个限制

使用方法

工具 1: create_parse_task

创建一个文档解析任务。支持 URL 或本地文件路径，本地文件会自动上传。

参数：

  • url (必需): 文档的 URL 或本地文件路径（支持 PDF, DOC, DOCX, PPT, PPTX, PNG, JPG, JPEG, HTML）

  • model_version (可选): 模型版本，根据文件类型自动选择（vlm / pipeline / MinerU-HTML）

  • is_ocr (可选): 是否启用 OCR（图片格式自动启用），默认 false

  • enable_formula (可选): 是否启用公式识别，默认 true

  • enable_table (可选): 是否启用表格识别，默认 true

返回值：

  • URL 输入：返回 task_id

  • 本地文件输入：返回 batch_id

  • 大文件拆分：返回 batch_ids 列表

示例：

# PDF 文件
请解析这个 PDF：https://example.com/report.pdf

# Word 文档
请解析本地 Word 文档：C:/Documents/report.docx

# PowerPoint 文件
请解析本地 PPT：C:/Documents/slides.pptx

# 图片（自动 OCR）
请解析这张图片：C:/Documents/scan.png

# HTML 网页
请解析本地 HTML：C:/Documents/page.html

工具 2: get_task_status

查询任务状态。支持通过 task_id（URL 解析）或 batch_id（本地文件上传）查询。

参数：

  • task_id (可选): 任务 ID（URL 方式创建的任务）

  • batch_id (可选): 批量任务 ID（本地文件上传创建的任务）

两个参数至少提供一个。

工具 3: download_result

下载解析结果 zip 文件。

参数：

  • zip_url (必需): 结果文件的 URL

  • output_path (必需): 本地保存路径

工具 4: convert_to_markdown (推荐)

完整的转换工作流，自动提交任务、等待完成并下载结果。支持所有格式的 URL 或本地文件路径。

参数：

  • url (必需): 文档的 URL 或本地文件路径

  • output_path (必需): 结果 zip 文件的本地保存路径

  • model_version (可选): 模型版本（自动检测），默认 vlm

  • max_wait_seconds (可选): 最大等待时间（秒），默认 300

  • poll_interval (可选): 轮询间隔（秒），默认 10

示例：

# 转换 PDF
帮我把这个 PDF 转成 Markdown：
url: C:/Documents/report.pdf
output_path: C:/output/result.zip

# 转换 Word 文档
帮我把这个 Word 文档转成 Markdown：
url: C:/Documents/report.docx
output_path: C:/output/result.zip

# 转换 PPT
帮我把这个 PPT 转成 Markdown：
url: C:/Documents/slides.pptx
output_path: C:/output/result.zip

注：convert_pdf_to_markdown 仍可使用（向后兼容），功能与 convert_to_markdown 完全相同。

Claude Code Skill 快捷用法

本项目提供了 /convert-to-markdown skill，可在 Claude Code 中通过斜杠命令快速调用文档转 Markdown 功能。

基本用法

/convert-to-markdown <文档路径或URL> [指令]

示例

# 转换 PDF
/convert-to-markdown C:/Documents/report.pdf 分析并总结这个文档内容

# 转换 Word 文档
/convert-to-markdown C:/Documents/report.docx 提取文档要点

# 转换 PPT
/convert-to-markdown C:/Documents/slides.pptx

# 转换图片
/convert-to-markdown C:/Documents/scan.png 识别图片中的文字

说明

  • 支持本地文件路径和 HTTP(S) URL 两种输入

  • 支持 PDF, DOC, DOCX, PPT, PPTX, PNG, JPG, JPEG, HTML 格式

  • 未指定输出路径时，默认保存到 ./temp/<文件名>.zip

  • 转换完成后自动解压 zip 并读取 Markdown 内容

  • 可附加自然语言指令，让 Claude 对转换结果进行分析、总结或回答问题

API 限制

根据 MinerU API 文档：

  • 单个文件不超过 200MB（PDF 超过此限制会自动拆分）

  • 文件页数不超过 600 页（超过此限制会自动使用 page_ranges）

  • 每账号每天有 2000 页高优先级额度

  • 不支持 GitHub、AWS 等国外 URL（网络限制）

输出格式

转换完成后，会得到一个包含以下内容的 zip 文件：

  • Markdown 文件: 提取的文档内容

  • JSON 文件: 结构化数据

  • 可选格式: 如果指定了 extra_formats，还可能包含 DOCX、HTML、LaTeX 等格式

详细说明请参考：https://opendatalab.github.io/MinerU/reference/output_files/

技术实现

本 MCP 服务器使用 Python requests 库与 MinerU API 交互：

URL 输入流程：

  1. 创建任务: POST https://mineru.net/api/v4/extract/task

  2. 查询状态: GET https://mineru.net/api/v4/extract/task/{task_id}

  3. 下载结果: GET {zip_url} 流式下载到本地

本地文件输入流程：

  1. 申请上传链接: POST https://mineru.net/api/v4/file-urls/batch

  2. 上传文件: PUT {upload_url} 上传文件内容

  3. 系统自动提交解析任务

  4. 查询批量结果: GET https://mineru.net/api/v4/extract-results/batch/{batch_id}

  5. 下载结果: GET {zip_url} 流式下载到本地

大文件处理流程（>200MB PDF）：

  1. 智能拆分: 同时考虑大小(180MB)和页数(600页)约束

  2. 逐片上传: 每个分片独立上传和处理

  3. 分别下载: 每个分片结果独立下载

故障排除

问题：Token 无效

请确保：

  1. 从官网正确复制了 Token

  2. Token 前后没有空格

  3. Token 未过期

问题：解析失败

可能原因：

  1. 文件 URL 无法访问

  2. 文件格式不支持（请检查是否在支持列表中）

  3. 文件为空（0字节）

  4. 网络问题（国外 URL）

问题：大文件拆分失败

可能原因：

  1. 未安装 PyPDF2（运行 pip install PyPDF2>=3.0.0）

  2. 非 PDF 格式的大文件无法自动拆分，需手动缩小

许可证

MIT License

相关链接

Available Tools

5 tools
convert_pdf_to_markdownB

Alias for convert_to_markdown. Same one-step workflow for Supported formats: PDF, DOC, DOCX, PPT, PPTX, PNG, JPG, JPEG, HTML.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYesURL of the document. Supported formats: PDF, DOC, DOCX, PPT, PPTX, PNG, JPG, JPEG, HTML
model_versionNoModel version (auto-detected)vlm
poll_intervalNoSeconds between status checks (default: 10)
max_wait_secondsNoMaximum time to wait for completion (default: 300)

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose behavioral traits. It only mentions a 'one-step workflow' but does not explain whether the operation is synchronous, what side effects occur, or any authentication or rate-limiting requirements. Critical behavioral context is missing.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that is front-loaded with the most important information (alias relationship). It is concise and contains no unnecessary words, making it efficient for an agent to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool is a conversion with four parameters and no output schema, the description is incomplete. It omits crucial context such as how results are returned, error handling, and whether the process is asynchronous. The presence of sibling tools like get_task_status suggests async workflow, but this is not clarified.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema covers all four parameters with descriptions (100% coverage). The description adds no new parameter-level information beyond what the schema already provides. Thus, the description provides no added value for parameter understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states it is an alias for convert_to_markdown and lists all supported formats. The verb 'convert' and resource 'to markdown' are clear, and it distinguishes itself from siblings by being a direct alias.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description lacks explicit guidance on when to use this tool versus alternatives. It only states it's an alias, but does not explain when to prefer it over other sibling tools like get_task_status or create_parse_task.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

convert_to_markdownA

One-step document conversion. Purpose: Submit URL, poll until done, return download link. Constraints: Supported formats: PDF, DOC, DOCX, PPT, PPTX, PNG, JPG, JPEG, HTML. Auto-configures model and OCR. Side effect: Creates task and polls MinerU API. Use for quick conversion.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYesURL of the document. Supported formats: PDF, DOC, DOCX, PPT, PPTX, PNG, JPG, JPEG, HTML
model_versionNoModel version (auto-detected)vlm
poll_intervalNoSeconds between status checks (default: 10)
max_wait_secondsNoMaximum time to wait for completion (default: 300)

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It discloses the side effect: 'Creates task and polls MinerU API,' and explains auto-configuration of model and OCR. It does not mention auth needs or rate limits, but for a conversion tool this is acceptable and adds significant value beyond the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with three brief sentences and front-loaded key information. Every sentence adds value: purpose, steps, constraints, side effect, and use case. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and 4 params, the description explains the conversion process and what the tool returns (download link). It covers supported formats, auto-configuration, and side effects. It could explicitly state that it combines create and poll steps, but 'one-step' and 'Creates task and polls' imply that.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description does not add new semantic meaning to parameters beyond what the schema already provides. It mentions auto-configuration, which relates to model_version, but does not enhance understanding of poll_interval or max_wait_seconds.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'One-step document conversion' with explicit steps: 'Submit URL, poll until done, return download link.' It distinguishes from siblings like convert_pdf_to_markdown by being a general converter supporting multiple formats (PDF, DOC, DOCX, etc.) and being 'quick conversion.'

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It says 'Use for quick conversion' and lists supported formats, giving context for when to use it. However, it does not explicitly mention when not to use it or provide alternatives to siblings like create_parse_task or download_result. The guidance is implied but not thorough.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_parse_taskA

Create a document parsing task on MinerU API. Purpose: Submit a document URL for async conversion. Returns task_id for tracking. Constraints: Supported formats: PDF, DOC, DOCX, PPT, PPTX, PNG, JPG, JPEG, HTML only. Side effect: Calls MinerU API.

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYesURL of the document to parse. Supported formats: PDF, DOC, DOCX, PPT, PPTX, PNG, JPG, JPEG, HTML
is_ocrNoEnable OCR (auto-enabled for images)
enable_tableNoEnable table recognition
model_versionNoModel version (auto-detected: 'vlm' for most, 'MinerU-HTML' for HTML)vlm
enable_formulaNoEnable formula recognition

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the behavioral burden. It discloses that it calls MinerU API and returns a task_id for tracking, but omits details like rate limits, authentication needs, or idempotency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, front-loaded with the primary action, and every sentence adds value. No unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description adequately covers the purpose, side effect, constraints, and return value (task_id) despite lacking an output schema. Minor omission: no mention of error handling.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3. The description adds no new parameter meaning beyond repeating supported formats; it does not compensate for any gaps.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool creates a document parsing task on MinerU API, with a specific verb 'Create' and resource 'parse task'. It distinguishes from siblings (get_task_status, download_result, etc.) by focusing on submission for async conversion.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies this is the entry point for document conversion via async parsing, but does not explicitly state when to use it versus alternatives. It lacks when-not or exclusion guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

download_resultA

Get the download URL for a completed parsing result. Purpose: Return the zip URL from get_task_status. After calling, download with curl to ./temp/ and unzip: curl -L -o ./temp/.zip "" --retry 3 -f -s -S && unzip -o ./temp/.zip -d ./temp/. No side effect.

ParametersJSON Schema
NameRequiredDescriptionDefault
zip_urlYesURL of the result zip file (from get_task_status)

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Explicitly states 'No side effect', which is valuable since no annotations are provided. Discloses that the tool returns a URL (not the file), and explains the expected download process. Could mention error handling or rate limits, but overall good.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is relatively concise with two clear parts: purpose and usage instructions. The inline command is lengthy but necessary for usability. Could be split into separate lines, but overall well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with no output schema, the description covers the return type (URL) and downstream actions (curl/unzip). Missing details about error handling or URL validation, but these are not critical for a download URL getter.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema already describes zip_url as 'URL of the result zip file (from get_task_status)'. The description adds context by stating the purpose is to return the zip URL from get_task_status, reinforcing the source and usage pattern.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action: 'Get the download URL for a completed parsing result'. It uses a specific verb and resource, distinguishing it from siblings like get_task_status which provides the URL source.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit post-call steps: download with curl and unzip. Implicitly ties usage to get_task_status by mentioning zip_url, but does not explicitly state when to use this vs alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_task_statusA

Check the status of a document parsing task. Purpose: Poll task progress and get download URL when done. Provide task_id (URL) or batch_id (file upload). Returns state and full_zip_url. Side effect: Read-only API call.

ParametersJSON Schema
NameRequiredDescriptionDefault
task_idNoTask ID returned from create_parse_task (URL-based)
batch_idNoBatch ID returned from create_parse_task (file upload)

TDQS

A4.3/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Explicitly declares side effect as read-only API call. No annotations provided, so description carries full burden and fulfills it. Describes return values.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four concise sentences, front-loaded with purpose, no redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers purpose, parameters, return values, and side effect. For a simple polling tool with no output schema, this is sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema provides full descriptions (100% coverage); description adds minimal nuance by specifying 'URL-based' and 'file upload', which is already in schema. Baseline 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States specific verb 'check' and resource 'status of a document parsing task'. Differentiates from siblings like create_parse_task (creation) and download_result (download).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Indicates polling use case and parameter choice but does not explicitly exclude when not to use or compare with siblings. Context is clear but lacks directiveness.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 5 tool updatesv2.0.0
    • First observedconvert_pdf_to_markdown
    • First observedconvert_to_markdown
    • First observedcreate_parse_task
    • First observeddownload_result
    • First observedget_task_status
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.4/5.0

Scored across 5 tools

Disambiguation1/5

Two tools (convert_to_markdown and convert_pdf_to_markdown) are explicitly aliases, causing direct confusion. Additionally, the multi-step workflow tools (create_parse_task, get_task_status, download_result) overlap with the one-step conversion, making it unclear which to choose without careful context.

Naming Consistency3/5

All tools use snake_case and a verb_noun pattern, but convert_pdf_to_markdown is an alias that adds no semantic value and breaks the expected distinct naming convention.

Tool Count4/5

Five tools is a reasonable number for a document conversion server, though the alias reduces effective distinct tools to four. The scope is well-contained.

Completeness3/5

The server covers the core conversion workflow (submit, track, download, one-step) but lacks batch processing support, cancelation, or listing of past tasks, leaving minor gaps.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers