bluente-translate

Traduza seus documentos com formatação intacta em 2 minutos

Documentação

Servidor MCP Bluente Translate

Com tecnologia de IA. Preserva a formatação. Feito para fluxos de trabalho profissionais de tradução de documentos.

bluente-translate-mcp-server é o servidor MCP oficial de código aberto para expor os recursos de tradução da Bluente a clientes de IA.

Ele encapsula as APIs da Bluente em ferramentas MCP prontas para produção, permitindo que equipes automatizem fluxos de trabalho de tradução de documentos multilíngues a partir do Claude Desktop, Cursor e outros runtimes compatíveis com MCP.

Por que a Bluente

A Bluente é focada em tradução de documentos de nível empresarial, onde precisão, integridade de formatação e velocidade são essenciais.

Do Bluente.com e Blu Translate, o posicionamento central do produto é:

Tradução com tecnologia de IA para casos de uso profissional
Preservação do layout original para fluxos de trabalho centrados em documentos
Amplo suporte a idiomas e tipos de arquivo
Tratamento com foco em segurança para conteúdo sensível

Este servidor MCP traz essas capacidades para fluxos de trabalho de agentes por meio de uma interface de protocolo padrão.

Identidade da Marca

Este repositório é mantido pela Bluente e faz parte do ecossistema público de desenvolvedores da Bluente.

Site da empresa: https://www.bluente.com
Página do produto: https://www.bluente.com/translator
Documentação da API: https://www.bluente.com/docs

O que você obtém

Servidor MCP Node.js modular com camadas claras (config, client, service, tools)
Implementação de um arquivo por ferramenta para facilitar a manutenção
Envelope de resposta unificado para ferramentas (ok/tool/data e erros estruturados)
Ferramenta de fluxo de trabalho de tradução de ponta a ponta (upload -> iniciar -> consultar -> download)
Verificações de CI e testes de fumaça locais

Arquitetura

AI Client (Claude / Cursor / Agents)
            |
            | MCP (stdio)
            v
+---------------------------------------+
| Bluente Translate MCP Server          |
|                                       |
|  tools/  -> MCP tool handlers         |
|  services/ -> workflow orchestration  |
|  clients/ -> Bluente HTTP API client  |
|  config/ + lib/ -> env/errors/results |
+---------------------------------------+
            |
            | HTTPS
            v
      Bluente Translation APIs

Estrutura do projeto:

src/
  clients/bluente-http-client.js
  config/env.js
  constants/api.js
  lib/errors.js
  lib/mcp-result.js
  services/translation-workflow-service.js
  tools/*.tool.js
  tools/schemas.js
  tools/register-tools.js
  server.js
  index.js
tests/smoke/core-smoke.test.js

APIs Bluente suportadas

GET /blu_translate/supported_languages
POST /blu_translate/upload
GET /blu_translate/check
POST /blu_translate/translate
GET /blu_translate/download

Referência: Documentação da API Bluente

Ferramentas MCP

bluente_get_supported_languages
bluente_upload_file
bluente_get_translation_status
bluente_translate_file
bluente_download_file
bluente_translate_document_workflow

Elas correspondem às ferramentas expostas pelo servidor MCP hospedado da Bluente, portanto, um prompt ou agente escrito para uma funciona com a outra. As diferenças são as duas coisas que apenas um servidor local pode fazer: file_path como fonte e output_path para salvar resultados em disco (o servidor hospedado fornece links de download).

Notas sobre o comportamento das ferramentas:

Etapa de confirmação: bluente_translate_document_workflow é um fluxo de duas chamadas. A primeira chamada envia o arquivo e retorna page_count além de um cartão de confirmação para o usuário; nada é iniciado e nenhum crédito é deduzido. Chame novamente com os valores retornados de task_id, confirmed=true e os valores explícitos de to, to_type e bilingual para realmente iniciar. bluente_translate_file não tem etapa de confirmação e inicia imediatamente.
Fontes de arquivo: file_path (um arquivo nesta máquina), file_url (um link público) ou file_content_base64 (menos de 2MB).
bluente_translate_file: from e to são obrigatórios quando action="start" e opcionais quando action="cancel".
to_type: pdf, word ou pptx. A ferramenta de fluxo de trabalho também aceita uma matriz (por exemplo, ["word", "pdf"]) — formatos extras são conversões no momento do download da mesma tradução e não custam créditos adicionais.
entry / status_entry: get_status (progresso da tradução, o padrão) ou get_page_count (a contagem de páginas do arquivo enviado).
Códigos de idioma: a Bluente usa códigos não padronizados (zh, cht, jp, kor, fra, spa, ...). Grafias ISO comuns (zh-CN, zh-TW, ja, ko, fr, es) são alias automáticos; chame bluente_get_supported_languages para a lista completa.
bilingual: on mantém o texto original junto com a tradução; off (padrão) produz um documento traduzido limpo. Quando on, defina bilingual_layout como left-right (lado a lado) ou top-down (empilhado) — esses são os únicos dois layouts que a Bluente suporta. O sinalizador numérico vertical_bilingual é um alias obsoleto.
mode: standard (a maioria dos documentos digitais), scanned (text) (OCR de uma digitalização para um documento limpo somente de texto), scanned (overlay) (colocar a tradução de volta sobre o layout digitalizado original) ou image (renderizar novamente um gráfico como um folheto ou pôster no idioma de destino; 5 créditos por página — o único modo cobrado acima da tarifa padrão, modos de digitalização custam o mesmo que o padrão). O sinalizador numérico scanned 0–3 é um alias obsoleto.
page_range (por exemplo, "1-3,5"): traduzir apenas páginas selecionadas; os créditos são cobrados apenas por essas páginas.
Glossário: a ferramenta de fluxo de trabalho sempre traduz com o glossário habilitado (correspondendo ao produto web da Bluente); seus argumentos glossary/custom_glossary são obsoletos e ignorados. Na ferramenta bruta bluente_translate_file, o backend aplica o glossário apenas quando ambos glossary e custom_glossary são 1.

Envelope de sucesso:

{
  "ok": true,
  "tool": "bluente_upload_file",
  "data": {
    "code": 0,
    "message": "success",
    "data": { "id": "task_xxx" }
  }
}

Envelope de erro:

{
  "isError": true,
  "ok": false,
  "tool": "bluente_translate_file",
  "error": {
    "name": "BluenteApiError",
    "message": "Bluente API request failed.",
    "details": { "status": 401 }
  }
}

Início rápido

Requisitos: Node.js >= 20 (verifique com node --version; instale a partir de nodejs.org) e uma chave de API da Bluente.

Obtendo uma chave de API: faça login em translate.bluente.com e vá para Meus Arquivos → Chaves de API e Webhook. Trate a chave como uma senha — ela autoriza traduções cobradas na sua conta, portanto, mantenha-a fora do controle de versão e de documentos compartilhados.

Opção 1: Deixe seu agente de codificação fazer isso

A maneira mais rápida de instalar: não instale. Se você usa Claude Code, Cursor ou qualquer agente de codificação compatível com MCP, cole este prompt e veja-o lidar com tudo — arquivo de configuração, chave, verificação — em menos de um minuto. Substitua YOUR_KEY_HERE pela sua chave de API:

Instale o servidor MCP Bluente Translate neste cliente. É o pacote npm @bluente/translate-mcp-server, executado via npx -y @bluente/translate-mcp-server (stdio), e precisa da variável de ambiente BLUENTE_API_KEY definida no bloco env da configuração do servidor. Use YOUR_KEY_HERE como a chave. Após configurar, verifique a instalação chamando a ferramenta bluente_get_supported_languages e mostre-me o resultado. Documentação: https://github.com/Bluente/bluente-translate-mcp-server

O agente encontra o arquivo de configuração correto para seu cliente, escreve o bloco e prova que a instalação funciona mostrando a lista de idiomas suportados.

Prefere não colar sua chave de API em uma conversa com o agente? Peça ao agente para usar REPLACE_ME como a chave, depois edite o arquivo de configuração manualmente e reinicie seu cliente.

Opção 2: Instalação manual

Claude Desktop

Abra Configurações → Desenvolvedor → Editar Config (abre claude_desktop_config.json).

Adicione este bloco (mescle em mcpServers se já existir), inserindo sua chave de API:

{
  "mcpServers": {
    "bluente-translate": {
      "command": "npx",
      "args": ["-y", "@bluente/translate-mcp-server"],
      "env": {
        "BLUENTE_API_KEY": "your_api_key_here"
      }
    }
  }
}

Saia e reabra o Claude Desktop. O ícone de ferramentas deve listar seis ferramentas bluente_*.

Claude Code — um comando, depois reinicie sua sessão e verifique com /mcp:

claude mcp add bluente-translate -e BLUENTE_API_KEY=your_api_key_here -- npx -y @bluente/translate-mcp-server

Cursor — Configurações → MCP → Adicionar servidor, ou crie .cursor/mcp.json no seu projeto com o mesmo bloco JSON do Claude Desktop.

Teste de fumaça (qualquer cliente): pergunte "Quais idiomas a tradução da Bluente suporta?" — uma chamada gratuita e somente leitura. Uma lista de idiomas de volta significa que a chave e a conexão funcionam. A primeira execução leva alguns segundos extras enquanto npx baixa o pacote.

Solução de problemas da chave de API

O servidor lê BLUENTE_API_KEY do ambiente — você nunca a passa como argumento de ferramenta nem a armazena em um arquivo. Se o servidor relatar Missing BLUENTE_API_KEY, a chave não está chegando ao processo do servidor: verifique o bloco env quanto a erros de digitação e reinicie seu cliente. Ao testar a partir de um terminal, prefixe o comando do servidor (BLUENTE_API_KEY=your_api_key_here npx -y @bluente/translate-mcp-server); em um pipeline de shell, a atribuição deve ficar diretamente antes de npx — colocada no início da linha, ela se aplica apenas ao primeiro comando do pipe.

Variáveis de ambiente opcionais:

Variável	Padrão	Finalidade
`BLUENTE_API_KEY`	(obrigatório)	Sua chave de API da Bluente
`BLUENTE_API_BASE_URL`	`https://api.bluente.com/api/20250924`	URL base da API
`BLUENTE_API_TIMEOUT_MS`	`90000`	Tempo limite de HTTP em milissegundos

Desenvolvimento local

git clone https://github.com/bluente/bluente-translate-mcp-server.git
cd bluente-translate-mcp-server
npm install
cp .env.example .env   # then set BLUENTE_API_KEY
npm start              # run the server on stdio
npm run check          # syntax check
npm test               # run tests

Para apontar um cliente MCP para seu checkout local, use "command": "node" com "args": ["/absolute/path/to/bluente-translate-mcp-server/src/index.js"] em vez da configuração npx acima.

Notas operacionais

A ferramenta de fluxo de trabalho retorna assim que a tradução começa. Consulte bluente_get_translation_status até READY, depois chame bluente_download_file.
auto_download=true em vez disso bloqueia até que a tradução termine e salve os arquivos em disco. Só é seguro para documentos pequenos — a tradução geralmente leva minutos e seu cliente MCP pode expirar a solicitação antes.
max_poll_attempts é um orçamento único compartilhado entre as fases de upload e tradução.
O tempo limite é configurável via BLUENTE_API_TIMEOUT_MS.
Para produção, use chaves de API separadas por ambiente.

Tratamento de dados e privacidade

Os documentos que você traduz são enviados para a API da Bluente (api.bluente.com por padrão) para processamento. Não traduza documentos que você não tem permissão de enviar a um serviço de terceiros.
O modelo de IA controla as ferramentas. Quando executado localmente (stdio), file_path permite que o modelo leia qualquer arquivo que sua conta de usuário possa ler e o envie para a Bluente, e output_path permite que ele grave arquivos baixados em qualquer caminho gravável. Revise as chamadas de ferramenta no seu cliente MCP antes de aprová-las, especialmente ao trabalhar com documentos não confiáveis — um documento malicioso pode tentar instruir o modelo a usar indevidamente essas ferramentas.
A saída traduzida retornada pelas ferramentas (conteúdo de arquivos, payloads de status) entra no contexto do seu cliente de IA e, portanto, fica visível para o provedor do seu LLM.
Sua chave de API permanece na sua máquina: ela é lida do ambiente e enviada apenas como um cabeçalho Authorization para a URL base da API Bluente configurada. Ela nunca é registrada em logs nem incluída nas respostas das ferramentas.

Segurança

Não faça commit de chaves de API ou arquivos .env.
Gire chaves vazadas imediatamente.
Use relatórios privados de vulnerabilidades do repositório.

Consulte SECURITY.md para a política de divulgação.

Roteiro

Adicionar ferramentas de tradução de texto se expostas na documentação pública da API
Adicionar testes de integração mais ricos com simulação de API
Adicionar imagem de contêiner e perfil de inicialização local com um comando

Contribuição e governança

Guia de contribuição: CONTRIBUTING.md
Política de segurança: SECURITY.md
Registro de alterações: CHANGELOG.md
Propriedade do código: .github/CODEOWNERS

Sobre a Bluente

A Bluente desenvolve soluções de tradução com IA e comunicação empresarial para equipes profissionais.

Site: bluente.com
Página do produto: Blu Translate
Documentação da API: bluente.com/docs

Licença

MIT