Doc2X MCP

Converta PDFs e imagens em Markdown/LaTeX com fórmulas e tabelas, e traduza documentos por meio da API Doc2X.

Documentação

Servidor Doc2x MCP

Doc2x MCP

简体中文 | English

Encapsula as capacidades de PDF/imagem do Doc2x v2 como um Servidor MCP baseado em stdio, fornecendo tools semânticas estáveis e combináveis.

Sumário

Posicionamento do projeto
Versão e ambiente
Início rápido
Referência de configuração
Visão geral da API de Tools
Fluxos de trabalho comuns
Desenvolvimento local
Pipeline de CI / publicação
Como publicar
Instalar Skill deste repositório (opcional)
Segurança e solução de problemas
Feedback de problemas
Changelog
Licença

Posicionamento do projeto

Fornece capacidades do Doc2x para clientes MCP (Codex CLI / Claude Code / Agentes personalizados).
Usa o modelo unificado de tarefas assíncronas submit/status/wait para facilitar a orquestração automatizada.
Oferece limites de segurança em tempo de execução, como timeout controlável, polling e lista de permissões de download.

Versão e ambiente

Execução local: Node.js >=18 é suficiente.
Verificação em CI: Node.js 18 e 20 executam o build.
Ambiente de publicação: tarefas de publicação no GitHub Actions usam Node.js 24.
Gerenciador de pacotes: usa pnpm de forma consistente (arquivo de lock pnpm-lock.yaml).

Início rápido

Método A: via npx (recomendado)

Adicione na configuração do 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: execução local a partir do código-fonte

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

Aponte o cliente MCP para o artefato de build 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"
  }
}

Referência de configuração

Variável de ambiente	Obrigatória	Valor padrão	Descrição
`DOC2X_API_KEY`	Sim	-	Chave da API Doc2x (`sk-xxx`)
`DOC2X_BASE_URL`	Não	`https://v2.doc2x.noedgeai.com`	Endereço base da API Doc2x
`DOC2X_HTTP_TIMEOUT_MS`	Não	`60000`	Timeout de HTTP por requisição (milissegundos)
`DOC2X_POLL_INTERVAL_MS`	Não	`2000`	Intervalo de polling (milissegundos)
`DOC2X_MAX_WAIT_MS`	Não	`600000`	Tempo máximo de espera para tools do tipo wait (milissegundos)
`DOC2X_PARSE_PDF_MAX_OUTPUT_CHARS`	Não	`5000`	Número máximo de caracteres retornados por `doc2x_parse_pdf_wait_text`; `0` = sem limite
`DOC2X_PARSE_PDF_MAX_OUTPUT_PAGES`	Não	`10`	Número máximo de páginas mescladas por `doc2x_parse_pdf_wait_text`; `0` = sem limite
`DOC2X_DOWNLOAD_URL_ALLOWLIST`	Não	`.amazonaws.com.cn,.aliyuncs.com,.noedgeai.com`	Lista de permissões de URL de download; `*` permite qualquer host (não recomendado)

Visão geral da API de Tools

Fase	Tools	Descrição
Análise de PDF	`doc2x_parse_pdf_submit` / `doc2x_parse_pdf_status` / `doc2x_parse_pdf_wait_text` / `doc2x_materialize_pdf_layout_json`	Enviar tarefa, consultar status, aguardar e obter texto, ou salvar o resultado do layout v3 como JSON local
Exportação de resultados	`doc2x_convert_export_submit` / `doc2x_convert_export_result` / `doc2x_convert_export_wait`	Iniciar exportação, consultar resultado, aguardar conclusão da exportação
Download e salvamento	`doc2x_download_url_to_file` / `doc2x_materialize_convert_zip`	Baixar URL para o local, descompactar zip de conversão
Análise de layout de imagem	`doc2x_parse_image_layout_sync` / `doc2x_parse_image_layout_submit` / `doc2x_parse_image_layout_status` / `doc2x_parse_image_layout_wait_text`	OCR de imagem síncrono/assíncrono e análise de layout
Diagnóstico	`doc2x_debug_config`	Retorna a análise de configuração e a origem da chave da API, facilitando a solução de problemas

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

Parâmetro opcional: model
Valores possíveis: v2 (padrão) / v3-2026 (modelo mais recente)
Se não for informado, o padrão é v2

{
  "model": "v3-2026"
}

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

Parâmetro obrigatório: output_path
uid e pdf_path são mutuamente exclusivos (escolha um)
v2 não suporta layout; se precisar de pages[].layout, use v3-2026
Se pdf_path for informado sem model, a tool usará v3-2026 por padrão
Em caso de sucesso, o JSON bruto de result é salvo localmente

layout contém a estrutura de blocos da página e informações de coordenadas, adequado para recorte de figuras/tabelas, destaque de regiões, extração estruturada e análise de layout; se você quiser apenas o conteúdo do texto, priorize a exportação em Markdown / DOCX.

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

Parâmetros de fórmulas na exportação (`doc2x_convert_export_submit` / `doc2x_convert_export_wait`)

Parâmetro obrigatório: formula_mode (normal / dollar)
Parâmetro opcional: formula_level (aplicável somente quando a tarefa de análise de origem for model=v3-2026)
Descrição dos valores:
- 0: preserva fórmulas
- 1: degrada apenas fórmulas inline (\$...\$, $...$ )
- 2: degrada todas as fórmulas (\$...\$, $...$ , \\[...\\], $$...$$)

Fluxos de trabalho comuns

Fluxo de trabalho 1: PDF -> arquivo Markdown local

doc2x_parse_pdf_submit envia a análise do PDF.
doc2x_convert_export_wait aguarda a exportação (to=md, e especifica formula_mode).
doc2x_convert_export_result obtém a URL de download.
doc2x_download_url_to_file baixa para o caminho de destino.

Fluxo de trabalho 2: OCR de layout de imagem com resultado rápido

doc2x_parse_image_layout_sync analisa diretamente de forma síncrona.
Se precisar de polling estável, use a combinação submit/status/wait.

Fluxo de trabalho 3: PDF -> arquivo JSON de layout v3 local

Chame doc2x_materialize_pdf_layout_json, informando pdf_path e output_path.
A tool aguarda a conclusão do parse e salva o JSON bruto de result localmente.
Esse JSON pode ser usado diretamente por scripts de recorte de figuras/tabelas.

Desenvolvimento local

Requisitos de ambiente

Node.js >=18
pnpm (compatível com o arquivo de lock do repositório)

Comandos comuns

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

Executar o serviço:

DOC2X_API_KEY=sk-xxx pnpm start

Pipeline de CI / publicação

O repositório usa GitHub Actions:

CI: .github/workflows/ci.yml
- Gatilhos: push para main, pull_request, workflow_dispatch, toda segunda-feira às UTC 03:17
- Alterações somente de documentação (**/*.md, LICENSE) são ignoradas automaticamente
- Tarefas:
  - dependency-review (somente PR)
  - build (matriz Node.js 18/20)
  - package-smoke (npm pack --dry-run)
  - security-audit (somente manual/agendado)
Publish: .github/workflows/publish.yml
- Push na branch dev: publica a tag npm dev
- Push na tag v*.*.*: publica npm latest
- Antes de publicar, valida se a versão da tag é igual à versão em package.json
- Comando de publicação: npm publish --provenance

Recomenda-se alinhar localmente antes de enviar:

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

Como publicar

Pré-lançamento de desenvolvimento (dev): após push na branch dev, publica automaticamente na tag npm dev. A versão é alterada automaticamente para x.y.z-dev.<run>.<attempt>.
Lançamento oficial (latest): após push na tag v*.*.*, publica no npm latest. A versão da tag deve ser igual à versão em package.json.

Instalar Skill deste repositório (opcional)

Usado para adicionar ao Codex CLI / Claude Code uma "Skill que ensina o modelo a usar as tools do doc2x-mcp".

Dica: a cada atualização da versão doc2x-mcp, recomenda-se executar novamente o comando de instalação para atualizar a Skill, garantindo que o modelo use as descrições de tools e fluxos de trabalho mais recentes.

Instalação com um clique sem clonar o repositório (recomendado):

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

Instalação no diretório do código-fonte deste repositório:

pnpm run skill:install

Diretórios de instalação padrão:

Codex CLI: ~/.codex/skills/public/doc2x-mcp (pode ser substituído por CODEX_HOME)
Claude Code: ~/.claude/skills/doc2x-mcp (pode ser substituído por CLAUDE_HOME)

Observações:

--target auto (padrão) instala simultaneamente no Codex + Claude.
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

Segurança e solução de problemas

Não envie DOC2X_API_KEY reais para o repositório.
A lista de permissões restringe domínios de download por padrão; se precisar liberar, avalie os riscos antes de usar DOC2X_DOWNLOAD_URL_ALLOWLIST=*.
Em caso de configuração anormal, priorize chamar doc2x_debug_config para identificar a origem das variáveis de ambiente e o resultado da análise.

Feedback de problemas

Problemas de uso ou relatórios de bugs: GitHub Issues
https://github.com/NoEdgeAI/doc2x-mcp/issues
Recomenda-se incluir no issue uma entrada mínima para reprodução, o nome da tool acionada e o resultado de doc2x_debug_config (pode ser anonimizado).

Licença

Licença MIT, consulte LICENSE.