bluente-translate

Traduce tus documentos manteniendo el formato intacto en 2 minutos

Documentación

Servidor MCP de Bluente Translate

Impulsado por IA. Preserva el formato. Diseñado para flujos de trabajo profesionales de traducción de documentos.

bluente-translate-mcp-server es el servidor MCP oficial de código abierto para exponer las capacidades de traducción de Bluente a clientes de IA.

Envuelve las APIs de Bluente en herramientas MCP listas para producción, de modo que los equipos puedan automatizar flujos de trabajo de documentos multilingües desde Claude Desktop, Cursor y otros entornos compatibles con MCP.

Por qué Bluente

Bluente se centra en la traducción de documentos de nivel empresarial donde la precisión, la integridad del formato y la velocidad importan.

Desde Bluente.com y Blu Translate, el posicionamiento principal del producto es:

Traducción impulsada por IA para casos de uso profesional
Conservación del diseño original para flujos de trabajo centrados en documentos
Amplia compatibilidad con idiomas y tipos de archivo
Manejo con prioridad en la seguridad para contenido sensible

Este servidor MCP lleva esas capacidades a los flujos de trabajo de agentes mediante una interfaz de protocolo estándar.

Identidad de Marca

Este repositorio es mantenido por Bluente y forma parte del ecosistema público de desarrolladores de Bluente.

Sitio web de la empresa: https://www.bluente.com
Página del producto: https://www.bluente.com/translator
Documentación de la API: https://www.bluente.com/docs

Qué Obtienes

Servidor MCP modular en Node.js con capas claras (config, client, service, tools)
Implementación de un archivo por herramienta para facilitar el mantenimiento
Envoltorio unificado de respuestas de herramientas (ok/tool/data y errores estructurados)
Herramienta de flujo de trabajo de traducción de extremo a extremo (subir -> iniciar -> consultar -> descargar)
Verificaciones de CI y pruebas locales de humo

Arquitectura

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

Estructura del proyecto:

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 de Bluente Compatibles

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

Referencia: Documentación de la API de Bluente

Herramientas MCP

bluente_get_supported_languages
bluente_upload_file
bluente_get_translation_status
bluente_translate_file
bluente_download_file
bluente_translate_document_workflow

Estas coinciden con las herramientas expuestas por el servidor MCP alojado de Bluente, por lo que un prompt o agente escrito para uno funciona con el otro. Las diferencias son las dos cosas que solo un servidor local puede hacer: file_path como fuente, y output_path para guardar resultados en disco (el servidor alojado entrega enlaces de descarga en su lugar).

Notas sobre el comportamiento de las herramientas:

Puerta de confirmación: bluente_translate_document_workflow es un flujo de dos llamadas. La primera llamada sube el archivo y devuelve page_count más una tarjeta de confirmación para el usuario; no se inicia nada y no se descuentan créditos. Llama de nuevo con los valores devueltos de task_id, confirmed=true y los valores explícitos de to, to_type y bilingual para iniciar realmente. bluente_translate_file no tiene puerta y se inicia de inmediato.
Fuentes de archivo: file_path (un archivo en esta máquina), file_url (un enlace público) o file_content_base64 (menos de 2MB).
bluente_translate_file: from y to son obligatorios cuando action="start" y opcionales cuando action="cancel".
to_type: pdf, word o pptx. La herramienta de flujo de trabajo también acepta un arreglo (por ejemplo, ["word", "pdf"]) — los formatos adicionales son conversiones de descarga de la misma traducción y no cuestan créditos extra.
entry / status_entry: get_status (progreso de la traducción, el predeterminado) o get_page_count (el número de páginas del archivo subido).
Códigos de idioma: Bluente usa códigos no estándar (zh, cht, jp, kor, fra, spa, ...). Las grafías ISO comunes (zh-CN, zh-TW, ja, ko, fr, es) se asignan automáticamente; llama a bluente_get_supported_languages para obtener la lista completa.
bilingual: on conserva el texto original junto con la traducción; off (predeterminado) produce un documento traducido limpio. Cuando on, establece bilingual_layout a left-right (lado a lado) o top-down (apilado) — estas son las únicas dos disposiciones que Bluente admite. El indicador numérico vertical_bilingual es un alias obsoleto.
mode: standard (la mayoría de los documentos digitales), scanned (text) (OCR de un escaneo a un documento limpio solo de texto), scanned (overlay) (colocar la traducción sobre el diseño escaneado original) o image (volver a renderizar un gráfico como un folleto o póster en el idioma de destino; 5 créditos por página — el único modo que se cobra por encima de la tarifa estándar, los modos de escaneo cuestan lo mismo que el estándar). El indicador numérico scanned 0–3 es un alias obsoleto.
page_range (por ejemplo, "1-3,5"): traduce solo las páginas seleccionadas; los créditos se cobran solo por esas páginas.
Glosario: la herramienta de flujo de trabajo siempre traduce con el glosario habilitado (coincidiendo con el producto web de Bluente); sus argumentos glossary/custom_glossary están obsoletos e ignorados. En la herramienta bluente_translate_file sin procesar, el backend aplica el glosario solo cuando ambos glossary y custom_glossary son 1.

Envoltorio de éxito:

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

Envoltorio de error:

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

Inicio Rápido

Requisitos: Node.js >= 20 (verifica con node --version; instala desde nodejs.org) y una clave de API de Bluente.

Cómo obtener una clave de API: inicia sesión en translate.bluente.com y ve a Mis Archivos → Claves de API y Webhook. Trata la clave como una contraseña — autoriza traducciones facturadas a tu cuenta, así que mantenla fuera del control de versiones y de documentos compartidos.

Opción 1: Deja que tu agente de codificación lo haga

La forma más rápida de instalar: no lo hagas. Si usas Claude Code, Cursor o cualquier agente de codificación compatible con MCP, pega este prompt y observa cómo maneja todo — archivo de configuración, clave, verificación — en menos de un minuto. Reemplaza YOUR_KEY_HERE con tu clave de API:

Instala el servidor MCP de Bluente Translate en este cliente. Es el paquete npm @bluente/translate-mcp-server, ejecutado mediante npx -y @bluente/translate-mcp-server (stdio), y necesita la variable de entorno BLUENTE_API_KEY configurada en el bloque env de la configuración del servidor. Usa YOUR_KEY_HERE como clave. Después de configurar, verifica la instalación llamando a la herramienta bluente_get_supported_languages y muéstrame el resultado. Documentación: https://github.com/Bluente/bluente-translate-mcp-server

El agente encuentra el archivo de configuración correcto para su cliente, escribe el bloque y demuestra que la instalación funciona mostrándote la lista de idiomas compatibles.

¿Prefieres no pegar tu clave de API en una conversación con el agente? Haz que el agente use REPLACE_ME como clave, luego edita el archivo de configuración manualmente y reinicia tu cliente.

Opción 2: Instalación manual

Claude Desktop

Abre Configuración → Desarrollador → Editar Configuración (abre claude_desktop_config.json).

Agrega este bloque (combínalo en mcpServers si ya existe), insertando tu clave de API:

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

Cierra y vuelve a abrir Claude Desktop. El ícono de herramientas debería listar seis herramientas bluente_*.

Claude Code — un comando, luego reinicia tu sesión y verifica con /mcp:

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

Cursor — Configuración → MCP → Agregar servidor, o crea .cursor/mcp.json en tu proyecto con el mismo bloque JSON que Claude Desktop.

Prueba de humo (cualquier cliente): pregunta "¿Qué idiomas admite la traducción de Bluente?" — una llamada gratuita y de solo lectura. Una lista de idiomas de vuelta significa que la clave y la conexión funcionan. La primera ejecución toma unos segundos extra mientras npx descarga el paquete.

Solución de problemas de la clave de API

El servidor lee BLUENTE_API_KEY de su entorno — nunca lo pasas como argumento de herramienta ni lo almacenas en un archivo. Si el servidor informa Missing BLUENTE_API_KEY, la clave no está llegando al proceso del servidor: verifica el bloque env por errores tipográficos y reinicia tu cliente. Al probar desde una terminal, antepone el comando del servidor (BLUENTE_API_KEY=your_api_key_here npx -y @bluente/translate-mcp-server); en una canalización de shell, la asignación debe colocarse directamente antes de npx — colocada al inicio de la línea se aplica solo al primer comando de la tubería.

Variables de entorno opcionales:

Variable	Predeterminado	Propósito
`BLUENTE_API_KEY`	(obligatorio)	Tu clave de API de Bluente
`BLUENTE_API_BASE_URL`	`https://api.bluente.com/api/20250924`	URL base de la API
`BLUENTE_API_TIMEOUT_MS`	`90000`	Tiempo de espera HTTP en milisegundos

Desarrollo 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 apuntar un cliente MCP a tu copia local, usa "command": "node" con "args": ["/absolute/path/to/bluente-translate-mcp-server/src/index.js"] en lugar de la configuración npx anterior.

Notas Operativas

La herramienta de flujo de trabajo regresa tan pronto como comienza la traducción. Consulta bluente_get_translation_status hasta que READY, luego llama a bluente_download_file.
auto_download=true en su lugar bloquea hasta que la traducción termina y guarda los archivos en disco. Solo es seguro para documentos pequeños — la traducción a menudo toma minutos y tu cliente MCP puede agotar el tiempo de espera de la solicitud primero.
max_poll_attempts es un presupuesto único compartido entre las fases de subida y traducción.
El tiempo de espera es configurable mediante BLUENTE_API_TIMEOUT_MS.
Para producción, usa claves de API separadas por entorno.

Manejo de Datos y Privacidad

Los documentos que traduces se suben a la API de Bluente (api.bluente.com por defecto) para su procesamiento. No traduzcas documentos que no tengas permitido enviar a un servicio de terceros.
El modelo de IA controla las herramientas. Cuando se ejecuta localmente (stdio), file_path permite que el modelo lea cualquier archivo que tu cuenta de usuario pueda leer y lo suba a Bluente, y output_path le permite escribir archivos descargados en cualquier ruta escribible. Revisa las llamadas de herramientas en tu cliente MCP antes de aprobarlas, especialmente al trabajar con documentos no confiables — un documento malicioso podría intentar instruir al modelo para que haga mal uso de estas herramientas.
La salida traducida devuelta por las herramientas (contenido de archivos, cargas de estado) entra en el contexto de tu cliente de IA y, por lo tanto, es visible para tu proveedor de LLM.
Tu clave de API permanece en tu máquina: se lee del entorno y se envía solo como un encabezado Authorization a la URL base de la API de Bluente configurada. Nunca se registra ni se incluye en las respuestas de las herramientas.

Seguridad

No confirmes claves de API ni archivos .env.
Rota las claves filtradas de inmediato.
Usa el informe de vulnerabilidades privado del repositorio.

Consulta SECURITY.md para la política de divulgación.

Hoja de Ruta

Agregar herramientas de traducción de texto si se exponen en la documentación pública de la API
Agregar pruebas de integración más ricas con simulación de API
Agregar imagen de contenedor y perfil de lanzamiento local de un comando

Contribuciones y Gobernanza

Guía de contribuciones: CONTRIBUTING.md
Política de seguridad: SECURITY.md
Registro de cambios: CHANGELOG.md
Propiedad del código: .github/CODEOWNERS

Acerca de Bluente

Bluente construye soluciones de traducción con IA y comunicación empresarial para equipos profesionales.

Sitio web: bluente.com
Página del producto: Blu Translate
Documentación de la API: bluente.com/docs

Licencia

MIT