Doc2X MCP

Convierte PDFs e imágenes a Markdown/LaTeX con fórmulas y tablas, y traduce documentos mediante la API de Doc2X.

Documentación

Servidor MCP de Doc2x

Doc2x MCP

简体中文 | English

Envuelve las capacidades de PDF/imágenes de Doc2x v2 como un servidor MCP basado en stdio, proporcionando herramientas semánticas estables y componibles.

Tabla de contenidos

Posicionamiento del proyecto
Versión y entorno
Inicio rápido
Referencia de configuración
Resumen de la API de herramientas
Flujos de trabajo comunes
Desarrollo local
Pipeline de CI / publicación
Cómo publicar
Instalar la Skill de este repositorio (opcional)
Seguridad y solución de problemas
Comentarios y problemas
Registro de cambios
Licencia

Posicionamiento del proyecto

Proporciona capacidades de Doc2x a clientes MCP (Codex CLI / Claude Code / Agentes personalizados).
Utiliza un modelo unificado de tareas asíncronas submit/status/wait para facilitar la orquestación automatizada.
Ofrece límites de seguridad en tiempo de ejecución, como tiempo de espera controlable, sondeo y lista blanca de descargas.

Versión y entorno

Ejecución local: Node.js >=18 es suficiente.
Verificación en CI: Node.js 18, 20 ejecutarán la compilación.
Entorno de publicación: las tareas de publicación en GitHub Actions usan Node.js 24.
Gestor de paquetes: se usa pnpm de forma uniforme (archivo de bloqueo pnpm-lock.yaml).

Inicio rápido

Método A: mediante npx (recomendado)

Agregue en la configuración del cliente MCP:

{
  "command": "npx",
  "args": ["-y", "@noedgeai-org/doc2x-mcp@latest"],
  "env": {
    "DOC2X_API_KEY": "sk-xxx",
    "DOC2X_BASE_URL": "https://v2.doc2x.noedgeai.com"
  }
}

Método B: ejecución desde el código fuente local

cd doc2x-mcp
pnpm install --frozen-lockfile
pnpm run build
DOC2X_API_KEY=sk-xxx pnpm start

El cliente MCP apunta al artefacto de compilación local:

{
  "command": "node",
  "args": ["<ABS_PATH>/doc2x-mcp/dist/index.js"],
  "env": {
    "DOC2X_API_KEY": "sk-xxx",
    "DOC2X_BASE_URL": "https://v2.doc2x.noedgeai.com"
  }
}

Referencia de configuración

Variable de entorno	Obligatoria	Valor predeterminado	Descripción
`DOC2X_API_KEY`	Sí	-	Clave API de Doc2x (`sk-xxx`)
`DOC2X_BASE_URL`	No	`https://v2.doc2x.noedgeai.com`	Dirección base de la API de Doc2x
`DOC2X_HTTP_TIMEOUT_MS`	No	`60000`	Tiempo de espera de HTTP por solicitud (milisegundos)
`DOC2X_POLL_INTERVAL_MS`	No	`2000`	Intervalo de sondeo (milisegundos)
`DOC2X_MAX_WAIT_MS`	No	`600000`	Tiempo máximo de espera para herramientas tipo wait (milisegundos)
`DOC2X_PARSE_PDF_MAX_OUTPUT_CHARS`	No	`5000`	Número máximo de caracteres devueltos por `doc2x_parse_pdf_wait_text`; `0`=sin límite
`DOC2X_PARSE_PDF_MAX_OUTPUT_PAGES`	No	`10`	Número máximo de páginas combinadas por `doc2x_parse_pdf_wait_text`; `0`=sin límite
`DOC2X_DOWNLOAD_URL_ALLOWLIST`	No	`.amazonaws.com.cn,.aliyuncs.com,.noedgeai.com`	Lista blanca de URL de descarga; `*` permite cualquier host (no recomendado)

Resumen de la API de herramientas

Fase	Herramientas	Descripción
Análisis de PDF	`doc2x_parse_pdf_submit` / `doc2x_parse_pdf_status` / `doc2x_parse_pdf_wait_text` / `doc2x_materialize_pdf_layout_json`	Enviar tarea, consultar estado, esperar y obtener texto, o guardar el resultado de layout v3 como JSON local
Exportación de resultados	`doc2x_convert_export_submit` / `doc2x_convert_export_result` / `doc2x_convert_export_wait`	Iniciar exportación, consultar resultado, esperar a que la exportación termine
Descarga y guardado	`doc2x_download_url_to_file` / `doc2x_materialize_convert_zip`	Descargar URL a local, descomprimir zip de convert
Análisis de layout de imágenes	`doc2x_parse_image_layout_sync` / `doc2x_parse_image_layout_submit` / `doc2x_parse_image_layout_status` / `doc2x_parse_image_layout_wait_text`	OCR de imágenes síncrono/asíncrono y análisis de layout
Diagnóstico	`doc2x_debug_config`	Devuelve el análisis de configuración y el origen de la clave API para facilitar la solución de problemas

Modelo de análisis de PDF (`doc2x_parse_pdf_submit` / `doc2x_parse_pdf_wait_text`)

Parámetro opcional: model
Valores opcionales: v2 (predeterminado) / v3-2026 (modelo más reciente)
Si no se envía, el valor predeterminado es v2

{
  "model": "v3-2026"
}

Guardado de JSON de layout de PDF (`doc2x_materialize_pdf_layout_json`)

Parámetro obligatorio: output_path
Se debe elegir uno entre uid y pdf_path
v2 no admite layout; si necesita pages[].layout, use v3-2026
Si se envía pdf_path pero no model, esta herramienta usa v3-2026 de forma predeterminada
En caso de éxito, escribe el JSON original de result en el archivo local

layout es la estructura de bloques de página e información de coordenadas, adecuado para recorte de figuras/tablas, resaltado de regiones, extracción estructurada y análisis de layout; si solo desea ver el contenido del texto, priorice la exportación a Markdown / DOCX.

{
  "pdf_path": "/absolute/path/to/input.pdf",
  "output_path": "/absolute/path/to/input_v3.layout.json"
}

Parámetros de fórmulas de exportación (`doc2x_convert_export_submit` / `doc2x_convert_export_wait`)

Parámetro obligatorio: formula_mode (normal / dollar)
Parámetro opcional: formula_level (solo tiene efecto cuando la tarea de análisis de origen es model=v3-2026)
Descripción de valores:
- 0: conservar fórmulas
- 1: degradar solo fórmulas en línea (\$...\$, $...$ )
- 2: degradar todas las fórmulas (\$...\$, $...$ , \\[...\\], $$...$$)

Flujos de trabajo comunes

Flujo de trabajo 1: PDF -> archivo local Markdown

doc2x_parse_pdf_submit envía el análisis de PDF.
doc2x_convert_export_wait espera la exportación (to=md, y especifica formula_mode).
doc2x_convert_export_result obtiene la URL de descarga.
doc2x_download_url_to_file descarga a la ruta de destino.

Flujo de trabajo 2: resultado rápido de OCR de layout de imágenes

doc2x_parse_image_layout_sync analiza directamente de forma síncrona.
Si necesita sondeo estable, use la combinación submit/status/wait.

Flujo de trabajo 3: PDF -> archivo local JSON de layout v3

Llame a doc2x_materialize_pdf_layout_json, pasando pdf_path y output_path.
La herramienta esperará a que el análisis tenga éxito y escribirá el JSON original de result en el archivo local.
Ese JSON se puede proporcionar directamente a scripts posteriores de recorte de figuras/tablas.

Desarrollo local

Requisitos del entorno

Node.js >=18
pnpm (coincidente con el archivo de bloqueo del repositorio)

Comandos comunes

pnpm install --frozen-lockfile
pnpm run build
pnpm run test
pnpm run format:check

Ejecutar el servicio:

DOC2X_API_KEY=sk-xxx pnpm start

Pipeline de CI / publicación

El repositorio usa GitHub Actions:

CI: .github/workflows/ci.yml
- Activación: push hacia main, pull_request, workflow_dispatch, cada lunes UTC 03:17
- Los cambios solo de documentación (**/*.md, LICENSE) se omiten automáticamente
- Tareas:
  - dependency-review (solo PR)
  - build (matriz de Node.js 18/20)
  - package-smoke (npm pack --dry-run)
  - security-audit (solo manual/programado)
Publicación: .github/workflows/publish.yml
- Push a la rama dev: publica el tag npm dev
- Push del tag v*.*.*: publica npm latest
- Antes de publicar, verifica que la versión del tag coincida con la versión de package.json
- Comando de publicación: npm publish --provenance

Se recomienda alinear localmente antes de enviar:

pnpm install --frozen-lockfile
pnpm run build
npm pack --dry-run
pnpm audit --prod --audit-level high

Cómo publicar

Pre-lanzamiento de desarrollo (dev): después de hacer push a la rama dev, se publica automáticamente en el tag npm dev. La versión se cambiará automáticamente a x.y.z-dev.<run>.<attempt>.
Lanzamiento oficial (latest): después de hacer push del tag v*.*.*, se publica en npm latest. La versión del tag debe coincidir con la versión de package.json.

Instalar la Skill de este repositorio (opcional)

Se usa para agregar a Codex CLI / Claude Code una "Skill que enseña al modelo grande cómo usar las herramientas de doc2x-mcp".

Nota: después de cada actualización de la versión de doc2x-mcp, se recomienda volver a ejecutar el comando de instalación para actualizar la Skill y garantizar que el modelo grande use las descripciones de herramientas y los flujos de trabajo más recientes.

Instalación con un solo clic sin clonar el repositorio (recomendado):

curl -fsSL https://raw.githubusercontent.com/NoEdgeAI/doc2x-mcp/main/scripts/install-skill.sh | sh

Instalación en el directorio del código fuente de este repositorio:

pnpm run skill:install

Directorio de instalación predeterminado:

Codex CLI: ~/.codex/skills/public/doc2x-mcp (se puede sobrescribir con CODEX_HOME)
Claude Code: ~/.claude/skills/doc2x-mcp (se puede sobrescribir con CLAUDE_HOME)

Notas:

--target auto (predeterminado) instalará en Codex + Claude al mismo tiempo.
PowerShell 7+: irm https://raw.githubusercontent.com/NoEdgeAI/doc2x-mcp/main/scripts/install-skill.ps1 | iex
Windows PowerShell 5.1: irm https://raw.githubusercontent.com/NoEdgeAI/doc2x-mcp/main/scripts/install-skill-winps.ps1 | iex

Seguridad y solución de problemas

No envíe DOC2X_API_KEY reales al repositorio.
La lista blanca restringe los dominios de descarga de forma predeterminada; si necesita ampliarla, evalúe los riesgos antes de usar DOC2X_DOWNLOAD_URL_ALLOWLIST=*.
Si hay anomalías de configuración, priorice llamar a doc2x_debug_config para localizar el origen de las variables de entorno y los resultados del análisis.

Comentarios y problemas

Problemas de uso o informes de errores: GitHub Issues
https://github.com/NoEdgeAI/doc2x-mcp/issues
Se recomienda adjuntar en el issue la entrada mínima de reproducción, el nombre de la herramienta activada y el resultado de doc2x_debug_config (se puede desensibilizar).

Licencia

Licencia MIT; consulte LICENSE para más detalles.