Bluente Translate MCP Server

AI-powered. Format-preserving. Built for professional document translation workflows.

bluente-translate-mcp-server is the official open-source MCP server for exposing Bluente translation capabilities to AI clients.

It wraps Bluente APIs into production-ready MCP tools so teams can automate multilingual document workflows from Claude Desktop, Cursor, and other MCP-compatible runtimes.

Why Bluente

Bluente focuses on enterprise-grade document translation where accuracy, formatting integrity, and speed matter.

From Bluente.com and Blu Translate, the core product positioning is:

• AI-powered translation for professional use cases
• Original layout retention for document-centric workflows
• Broad language and file-type support
• Security-first handling for sensitive content

This MCP server brings those capabilities into agent workflows through a standard protocol interface.

Brand Identity

This repository is maintained by Bluente and is part of Bluente's public developer ecosystem.

• Company website: https://www.bluente.com
• Product page: https://www.bluente.com/translator
• API docs: https://www.bluente.com/docs

Table of Contents

• What You Get
• Architecture
• Supported Bluente APIs
• MCP Tools
• Quick Start
• MCP Client Integration
• Operational Notes
• Security
• Roadmap
• Contributing and Governance
• License

What You Get

• Modular Node.js MCP server with clear layering (config, client, service, tools)
• One-file-per-tool implementation for maintainability
• Unified tool response envelope (ok/tool/data and structured errors)
• End-to-end translation workflow tool (upload -> start -> poll -> download)
• CI checks and local smoke tests

Architecture

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

Project layout:

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

Supported Bluente APIs

• GET /blu_translate/supported_languages
• POST /blu_translate/upload_file
• GET /blu_translate/get_translation_status
• POST /blu_translate/translate_file
• GET /blu_translate/download_file

Reference: Bluente API Docs

MCP Tools

• bluente_get_supported_languages
• bluente_upload_file
• bluente_get_translation_status
• bluente_translate_file
• bluente_download_file
• bluente_translate_document_workflow

Tool behavior notes:

• bluente_translate_file: from and to are required when action="start" and optional when action="cancel".
• bluente_translate_document_workflow: status_entry is configurable (pdf or word) for status polling.

Success envelope:

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

Error envelope:

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

Quick Start

1. Requirements

• Node.js >= 20
• Bluente API key

2. Install

npm install
cp .env.example .env

3. Configure

BLUENTE_API_KEY=your_api_key_here
BLUENTE_API_BASE_URL=https://api.bluente.com/api/20250924
BLUENTE_API_TIMEOUT_MS=90000

4. Run

npm start

5. Validate locally

npm run check
npm test

MCP Client Integration

Example for Claude Desktop:

{
  "mcpServers": {
    "bluente-translate": {
      "command": "node",
      "args": ["/absolute/path/to/bluente-translate-mcp-server/src/index.js"],
      "env": {
        "BLUENTE_API_KEY": "your_api_key_here",
        "BLUENTE_API_BASE_URL": "https://api.bluente.com/api/20250924",
        "BLUENTE_API_TIMEOUT_MS": "90000"
      }
    }
  }
}

Operational Notes

• Workflow tool polls until terminal state (READY or ERROR).
• Output download can be disabled with auto_download=false.
• Timeout is configurable via BLUENTE_API_TIMEOUT_MS.
• For production, use separate API keys per environment.

Security

• Do not commit API keys or .env files.
• Rotate leaked keys immediately.
• Use repository private vulnerability reporting.

See SECURITY.md for disclosure policy.

Roadmap

• Add text translation tools if exposed in public API docs
• Add richer integration tests with API mocking
• Add container image and one-command local launch profile

Contributing and Governance

• Contribution guide: CONTRIBUTING.md
• Security policy: SECURITY.md
• Changelog: CHANGELOG.md
• Code ownership: .github/CODEOWNERS

About Bluente

Bluente builds AI translation and business communication solutions for professional teams.

• Website: bluente.com
• Product page: Blu Translate
• API documentation: bluente.com/docs

License

MIT