mistral-mcp

Servidor MCP Mistral para extração de documentos

Transforme faturas em texto ou Markdown em JSON tipado via MCP. mistral-mcp usa o Mistral chat para extrair fornecedores, totais, itens de linha e datas de vencimento, e então valida o esquema da resposta. O OCR opcional do Mistral lida com entradas em PDF e imagem. process_document também suporta contratos, documentos de identidade e classificação automática. Seis ferramentas estão disponíveis por padrão, incluindo chat, visão, transcrição e conclusão de código.

Français · Guia de migração · Exemplos · Implantação

pacote npm · notas da versão 1.0.0 · lançamentos no GitHub · documentação da API Mistral

Versão 1.0.0 — mudanças significativas em relação à 0.11.0: core agora expõe seis ferramentas; clientes de orquestração existentes devem escolher um perfil explícito. Resultados de documentos exigem extraction_source, e ocr_confidence / page_count podem ser null. Instruções de migração e reversão.

Instalação em um cliente MCP

Requer Node.js 20+, npm e uma chave de API Mistral com acesso e cota para o modelo solicitado. Para clientes que usam mcpServers JSON, configure o servidor stdio:

{
  "mcpServers": {
    "mistral": {
      "command": "npx",
      "args": ["-y", "mistral-mcp@1.0.0"],
      "env": {
        "MISTRAL_API_KEY": "your_key_here",
        "MISTRAL_DEFAULT_MODEL": "ministral-3b-latest",
        "MISTRAL_MCP_PROFILE": "core"
      }
    }
  }
}

Isso executa npx -y mistral-mcp@1.0.0. Reinicie o cliente e atualize seu catálogo de ferramentas. O servidor lê o ambiente fornecido pelo cliente; ele não carrega .env automaticamente. Use a configuração de segredos do seu cliente para a chave. ministral-3b-latest foi verificado na conta de teste; o acesso ao modelo e a cota gratuita dependem da sua conta. Verifique seus limites antes de fazer chamadas. A hospedagem MCP local ainda envia solicitações de extração para a Mistral.

Início rápido: uma fatura existente em texto ou Markdown

O script de fatura e os fixtures são exemplos de código-fonte, não incluídos no pacote npm. Confira a tag de lançamento e compile a partir da raiz do repositório:

git clone https://github.com/Swih/mistral-mcp.git
cd mistral-mcp
git checkout v1.0.0
npm ci
npm run build

Defina a chave e o modelo de chat no seu ambiente ou em um arquivo .env local:

MISTRAL_API_KEY=your_key_here
MISTRAL_DEFAULT_MODEL=ministral-3b-latest

O exemplo carrega .env com dotenv. Mantenha a chave fora do controle de versão. Escolha um modelo de chat com cota na sua conta; o padrão pode ter cota zero.

npm run example:invoice -- test/fixtures/invoice-text.md --output invoice-result.json

Isso usa a fatura Markdown sintética. Para sua própria fatura existente em .txt ou .md UTF-8, a sintaxe do comando é:

node examples/invoice.mjs <local-file.txt|local-file.md> [--output result.json]

O script lê o texto localmente e chama process_document com source: { type: "text", text: "..." }, kind: "invoice" e options.cache: "bypass" através do perfil core do servidor local. O texto deve conter conteúdo não vazio e caber em 60.000 unidades de código UTF-16 (comprimento de string em JavaScript). Markdown e espaços em branco são preservados inalterados. Não há upload de arquivos nem chamada de OCR; a extração de fatura envia o texto para o Mistral chat. O exemplo usa apenas o Mistral Cloud e ainda exige chave e cota de chat; o processamento não é totalmente local nem garantidamente gratuito. Verifique os limites da sua conta.

Sem --output, ele imprime JSON validado; com ele, grava em um novo arquivo e imprime esse caminho. Arquivos existentes não são sobrescritos. O caminho de saída é reservado antes das chamadas de API e pode permanecer vazio após uma falha; remova-o ou escolha um novo caminho antes de tentar novamente.

Em 28/09/2026, o teste de texto ao vivo e o exemplo de CLI foram bem-sucedidos com ministral-3b-latest, usando apenas chat. Os campos verificados foram fornecedor ACME SAS, total 12960 EUR, data de vencimento 2026-09-11 e as quantidades, preços unitários e valores das três linhas da fatura. Isso verifica uma fatura sintética, não uma pontuação geral de precisão ou confiabilidade.

Para PDF ou imagem, a rota de OCR existente permanece disponível:

npm run example:invoice -- test/fixtures/corpus/invoice-fr-table.pdf --output invoice-ocr-result.json

Arquivos PDF, PNG, JPEG e WebP de até 20 MiB exigem acesso e cota de Files, OCR e chat. O script envia o arquivo, chama process_document e tenta excluir o upload em finally, inclusive após falha na extração. Não há sonda separada de prontidão do OCR. Upload e limpeza usam a API Files sem expor ferramentas administrativas em core. Limitação conhecida: o HTTP 429 da conta de teste / cota zero de OCR bloqueou a validação de OCR ao vivo. A execução de texto bem-sucedida não valida a extração por OCR.

Compare qualquer resultado extraído com sua fonte. O PDF sintético e a verdade básica do fixture descrevem o conteúdo esperado do documento, não a saída ao vivo capturada. A validação de esquema verifica a forma e os tipos da resposta; ela não verifica precisão factual, aritmética de fatura, tratamento tributário ou correção contábil. Revise os campos extraídos em relação à fonte antes de usá-los.

Perfis

MISTRAL_MCP_PROFILE seleciona um dos cinco perfis. O padrão é core para Mistral Cloud; um MISTRAL_BASE_URL personalizado infere self-hosted a menos que você defina um perfil explicitamente.

Perfil	Ferramentas	Escopo em 1.0.0
core (padrão)	6	Documentos, chat, visão, transcrição e conclusão de código
metier-docs	17	Perfil legado preservado: as seis ferramentas principais mais todas as 11 ferramentas de orquestração; um superconjunto do antigo núcleo de 16 ferramentas
workflows	11	Workflows, conectores e descoberta de índice de busca
admin	46	Todas as ferramentas implementadas por este servidor, incluindo Files, Batch, Conversations e Libraries
self-hosted	5	Chat, chat por streaming, embeddings, chamada de função e visão em um endpoint compatível

full permanece como um alias obsoleto de admin, não um sexto perfil. Defina MISTRAL_MCP_PROFILE=metier-docs para preservar o antigo conjunto de ferramentas principais após a atualização; escolha workflows para orquestração apenas ou admin para o conjunto completo de ferramentas. Reinicie o servidor e atualize a descoberta de ferramentas após alterar os perfis.

npx -y mistral-mcp@1.0.0 --doctor relata o perfil local e a lista de ferramentas sem chamadas de API. O recurso mistral://capabilities relata o endpoint ativo, as famílias de ferramentas e os motivos das ferramentas omitidas. Nenhum deles comprova acesso ou cota da conta.

Ferramentas principais e comportamento de documentos

Ferramenta	Finalidade
process_document	Texto/Markdown fornecido ou OCR, classificação opcional e extração validada por esquema para faturas, contratos, documentos de identidade ou texto genérico
mistral_ocr	Texto OCR bruto, tabelas, anotações e blocos opcionais de PDFs ou imagens
mistral_vision	Chat com imagens fornecidas por URL ou base64
mistral_chat	Conclusão de chat, incluindo formatos de resposta estruturados
voxtral_transcribe	Transcrição de áudio com diarização opcional de falantes
codestral_fim	Conclusão de código fill-in-the-middle

process_document aceita source: { type: "text", text: string }, uma URL de documento, uma imagem base64 ou um ID de arquivo enviado. O texto pode conter Markdown e é preservado inalterado; strings vazias ou apenas com espaços em branco e strings acima de 60.000 unidades de código UTF-16 são rejeitadas para cada kind, incluindo generic. kind é auto (padrão), invoice, contract, id_document ou generic. Chamadas bem-sucedidas retornam content legível e structuredContent JSON; falhas retornam isError: true.

Por exemplo, estes são argumentos de ferramenta usando entrada sintética, não um resultado ao vivo:

{
  "source": {
    "type": "text",
    "text": "# Invoice DEMO-001\nVendor: Example Studio\nService: 2 hours at EUR 50\nTotal due: EUR 100\nDue date: 2026-10-15\n"
  },
  "kind": "invoice",
  "options": { "cache": "bypass" }
}

Em uma falha de cache ou com cache: "bypass", auto chama o chat para classificar até uma fonte de texto; invoice, contract e id_document usam chat para extração tipada. kind: "generic" explícito com uma fonte de texto faz nenhuma chamada de API e retorna o texto fornecido como ocr_text e structured_text.

Todo resultado bem-sucedido inclui estes campos:

Campo	Texto / Markdown fornecido	Fonte de OCR bem-sucedida
extraction_source (obrigatório)	"provided_text"	"mistral_ocr"
ocr_text (nome mantido)	Texto de entrada original, inalterado	Texto OCR
ocr_confidence	null	Número de 0 a 1
page_count	null	Número de páginas processadas

• options.maxPages e options.minOcrConfidence aplicam-se apenas a fontes de OCR. Eles não paginam nem pontuam texto fornecido. Para OCR, pontuações de confiança ausentes, incompletas ou inválidas causam erro, assim como pontuações abaixo do mínimo solicitado. O 0.3 padrão não é medido; a confiança do OCR não estabelece precisão de extração.
• Para fontes de OCR, options.maxPages assume como padrão 50 (máximo 200). A extração tipada rejeita texto OCR acima de 60.000 unidades de código UTF-16: divida o documento ou use generic para texto OCR. O limite de entrada de fonte de texto ainda se aplica a generic. options.languageHints orienta a extração tipada, não o modelo de OCR.
• options.cache: "bypass" ignora leituras e gravações de cache. Outros modos são read_only e read_write. Documentos de identidade ignoram o cache por padrão, inclusive após classificação auto; read_write explícito os inclui.
• Arquivos de cache contêm conteúdo extraído. MISTRAL_MCP_CACHE_DIR define o local; MISTRAL_MCP_CACHE_TTL_HOURS assume como padrão 168 horas (0 desativa reutilização e novas gravações). A limpeza é oportunista durante operações de cache. A omissão não apaga entradas mais antigas, e a expiração não garante exclusão em um horário definido. A versão do pipeline v1.0.0-text.1 invalida a reutilização de entradas de cache mais antigas; ela não garante a exclusão imediata delas.

O corpus sintético separa o texto OCR obrigatório dos campos de fatura extraídos esperados. npm run eval:docs avalia esses separadamente por meio de chamadas reais de API. A verdade do fixture não é um resultado de precisão ao vivo; PDFs sintéticos baseados em texto não estabelecem precisão em digitalizações degradadas. Orientação de desenvolvimento e avaliação.

Referências de API e implantação

mistral://capabilities descreve o conjunto de ferramentas ativo. mistral://models lê o catálogo upstream e relata fallback se a chamada de API falhar. mistral://voices está disponível em admin; mistral://workflows está disponível em metier-docs, workflows e admin. A presença no catálogo não estabelece acesso ou cota.

Você pode hospedar o processo MCP e configurar seu endpoint upstream, credenciais, exposição de ferramentas e política de cache. Por padrão, as solicitações vão para o Mistral Cloud: a hospedagem MCP local não torna a inferência de documentos local. Esses controles sozinhos não estabelecem residência de dados ou conformidade regulatória.

Um MISTRAL_BASE_URL personalizado infere self-hosted: chat, chat por streaming, embeddings, chamada de função e visão, sujeito ao suporte do endpoint/modelo. Ele não inclui OCR nem process_document. Um perfil explícito substitui a inferência, mas não adiciona APIs ausentes a um backend.

Referência	Conteúdo
Migração	Ferramentas principais removidas, perfis explícitos, fallback 0.11.0 fixado
Exemplos	Faturas locais, transcrição e conversas com biblioteca
Famílias de ferramentas e esquemas de entrada de ferramentas MCP	Associação completa de ferramentas e referência de argumentos
Prompts	Atas de reunião, respostas de e-mail, commits, resumos jurídicos, lembretes de fatura e revisão de código
Implantação e .env.example	Docker, Compose, Kubernetes, endpoints personalizados, cache e configurações HTTP
Guia de conector público	Implantação HTTPS; chamadas de conector público não são estabelecidas como validadas de ponta a ponta aqui
Plugin Claude Code	Plugin opcional com 11 habilidades, fixado em mistral-mcp@1.0.0
Contribuição	Build, testes, avaliação e verificações de lançamento
Changelog e política de segurança	Mudanças e relato de segurança
stdio é o transporte padrão. --http ou MCP_TRANSPORT=http ativa
Streamable HTTP em 127.0.0.1:3333/mcp por padrão, com autenticação bearer
configurável e origens permitidas. OAuth integrado não é fornecido.
Registros de auditoria de ferramentas vão para stderr e omitem argumentos e cargas de resultado;
MISTRAL_MCP_AUDIT=off os desativa.

Os testes da era do protocolo cobrem MCP 2026-07-28 e o handshake de 2025 usando os mesmos registros. npm run check:release verifica o build e os testes locais, incluindo o pacote instalado contra um stub de API. A validação de API ao vivo é separada; testes ignorados não contam como sucesso. O pinning de pacotes não garante disponibilidade ou compatibilidade futura do upstream.

Licença MIT — Copyright Dayan Decamp.