<div align="center">

<a href="https://www.bluente.com/" target="_blank" rel="noopener noreferrer">
  <img src="https://translate.bluente.com/_next/static/media/singleLogo.c3edb4ba.svg" alt="Bluente Logo" width="72" height="72" />
</a>

# Bluente Translate MCP Server

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

[![CI](https://img.shields.io/github/actions/workflow/status/bluente/bluente-translate-mcp-server/ci.yml?branch=main&label=CI)](./.github/workflows/ci.yml)
[![Node.js >=20](https://img.shields.io/badge/node-%3E%3D20-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
[![MCP](https://img.shields.io/badge/protocol-MCP-111111)](https://modelcontextprotocol.io/)

</div>

`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](https://www.bluente.com/) and [Blu Translate](https://www.bluente.com/translator), 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](https://www.bluente.com)
- Product page: [https://www.bluente.com/translator](https://www.bluente.com/translator)
- API docs: [https://www.bluente.com/docs](https://www.bluente.com/docs)

## Table of Contents

- [What You Get](#what-you-get)
- [Architecture](#architecture)
- [Supported Bluente APIs](#supported-bluente-apis)
- [MCP Tools](#mcp-tools)
- [Quick Start](#quick-start)
- [Local Development](#local-development)
- [Operational Notes](#operational-notes)
- [Data Handling & Privacy](#data-handling--privacy)
- [Security](#security)
- [Roadmap](#roadmap)
- [Contributing and Governance](#contributing-and-governance)
- [License](#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

```text
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:

```text
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`
- `GET /blu_translate/check`
- `POST /blu_translate/translate`
- `GET /blu_translate/download`
- `GET /blu_translate/account`

Reference: [Bluente API Docs](https://www.bluente.com/docs)

## MCP Tools

- `bluente_get_supported_languages`
- `bluente_upload_file`
- `bluente_get_translation_status`
- `bluente_translate_file`
- `bluente_download_file`
- `bluente_translate_document_workflow`
- `bluente_get_account` — read-only: the signed-in user's email and name, their organisation (name and role), and credits per feature with balance, who pays (organisation pool or personal credits), and the soonest expiries.

These match the tools exposed by Bluente's hosted MCP server, so a prompt or
agent written against one works against the other. The differences are the two
things only a local server can do: `file_path` as a source, and `output_path`
for saving results to disk (the hosted server hands out download links instead).

Tool behavior notes:

- **Confirmation gate**: `bluente_translate_document_workflow` is a two-call flow. The first call uploads the file and returns `page_count` plus a confirmation card for the user; **nothing starts and no credits are deducted**. The card includes a `Balance:` line with the current translate balance, the balance after this translation, and who pays — or a warning when the balance is not enough; if the account lookup fails or takes over 3 seconds, the card is shown without it. Call again with the returned `task_id`, `confirmed=true`, and explicit `to`, `to_type`, and `bilingual` values to actually start. `bluente_translate_file` has no gate and starts immediately.
- **File sources**: `file_path` (a file on this machine), `file_url` (a public link), or `file_content_base64` (under 2MB).
- `bluente_translate_file`: `from` and `to` are required when `action="start"` and optional when `action="cancel"`.
- **`to_type`**: `pdf`, `word`, or `pptx`. The workflow tool also accepts an array (e.g. `["word", "pdf"]`) — extra formats are download-time conversions of the same translation and cost no extra credits.
- **`entry` / `status_entry`**: `get_status` (translation progress, the default) or `get_page_count` (the uploaded file's page count).
- **Language codes**: Bluente uses nonstandard codes (`zh`, `cht`, `jp`, `kor`, `fra`, `spa`, ...). Common ISO spellings (`zh-CN`, `zh-TW`, `ja`, `ko`, `fr`, `es`) are auto-aliased; call `bluente_get_supported_languages` for the full list.
- **`bilingual`**: `on` keeps the original text alongside the translation; `off` (default) produces a clean translated document. When `on`, set **`bilingual_layout`** to `left-right` (side by side) or `top-down` (stacked) — these are the only two layouts Bluente supports. The numeric `vertical_bilingual` flag is a deprecated alias.
- **`mode`**: `standard` (most digital documents), `scanned (text)` (OCR a scan into a clean text-only document), `scanned (overlay)` (place the translation back over the original scanned layout), or `image` (re-render a graphic like a brochure or poster in the target language; 5 credits per page — the only mode charged above the standard rate, scanned modes cost the same as standard). The numeric `scanned` 0–3 flag is a deprecated alias.
- **`page_range`** (e.g. `"1-3,5"`): translate only selected pages; credits are charged only for those pages.
- **`translate_images`**: `on` also translates the text inside images embedded in a Word or PowerPoint file (DOC, DOCX, PPT, PPTX) — charts, screenshots, scanned figures; `off` (default) translates only the document's text. No extra credits. Standard mode only; not available for PDFs or together with bilingual output (the backend rejects those). Pass it again on the confirmed call; omitted means off.
- **Glossary**: the workflow tool always translates with the glossary enabled (matching the Bluente web product); its `glossary`/`custom_glossary` arguments are deprecated and ignored. On the raw `bluente_translate_file` tool the backend applies the glossary only when *both* `glossary` and `custom_glossary` are `1`.

Success envelope:

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

Error envelope:

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

## Quick Start

Requirements: Node.js `>= 20` (check with `node --version`; install from [nodejs.org](https://nodejs.org)) and a Bluente API key.

**Getting an API key:** log in at [translate.bluente.com](https://translate.bluente.com) and go to **My Files → API Keys and Webhook**. Treat the key like a password — it authorizes translations billed to your account, so keep it out of version control and shared documents.

### Option 1: Just let your coding agent do it

The fastest way to install: don't. If you use Claude Code, Cursor, or any MCP-capable coding agent, paste this prompt and watch it handle everything — config file, key, verification — in under a minute. Replace `YOUR_KEY_HERE` with your API key:

> Install the Bluente Translate MCP server into this client. It's the npm package `@bluente/translate-mcp-server`, run via `npx -y @bluente/translate-mcp-server` (stdio), and it needs the environment variable `BLUENTE_API_KEY` set in the server config's `env` block. Use `YOUR_KEY_HERE` as the key. After configuring, verify the installation by calling the `bluente_get_supported_languages` tool and show me the result. Docs: https://github.com/Bluente/bluente-translate-mcp-server

The agent finds the right config file for its client, writes the block, and proves the install works by showing you the supported-language list.

Prefer not to paste your API key into an agent conversation? Have the agent use `REPLACE_ME` as the key, then edit the config file by hand and restart your client.

### Option 2: Install manually

**Claude Desktop**

1. Open **Settings → Developer → Edit Config** (opens `claude_desktop_config.json`).
2. Add this block (merge into `mcpServers` if it already exists), inserting your API key:

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

3. Quit and reopen Claude Desktop. The tools icon should list seven `bluente_*` tools.

**Claude Code** — one command, then restart your session and verify with `/mcp`:

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

**Cursor** — Settings → MCP → Add server, or create `.cursor/mcp.json` in your project with the same JSON block as Claude Desktop.

**Smoke test (any client):** ask *"What languages does Bluente translation support?"* — a free, read-only call. A language list back means the key and connection both work. The first run takes a few extra seconds while `npx` downloads the package.

### Troubleshooting the API key

The server reads `BLUENTE_API_KEY` from its environment — you never pass it as a tool argument or store it in a file. If the server reports `Missing BLUENTE_API_KEY`, the key is not reaching the server process: check the `env` block for typos and restart your client. When testing from a terminal, prefix the server command itself (`BLUENTE_API_KEY=your_api_key_here npx -y @bluente/translate-mcp-server`); in a shell pipeline the assignment must sit directly before `npx` — placed at the start of the line it applies only to the first command in the pipe.

Optional environment variables:

| Variable | Default | Purpose |
| --- | --- | --- |
| `BLUENTE_API_KEY` | (required) | Your Bluente API key |
| `BLUENTE_API_BASE_URL` | `https://api.bluente.com/api/20250924` | API base URL |
| `BLUENTE_API_TIMEOUT_MS` | `90000` | HTTP timeout in milliseconds |

## Local Development

```bash
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
```

To point an MCP client at your local checkout, use `"command": "node"` with `"args": ["/absolute/path/to/bluente-translate-mcp-server/src/index.js"]` instead of the `npx` config above.

## Operational Notes

- The workflow tool returns as soon as translation starts. Poll `bluente_get_translation_status` until `READY`, then call `bluente_download_file`.
- `auto_download=true` instead blocks until the translation finishes and saves the file(s) to disk. Only safe for small documents — translation often takes minutes and your MCP client may time the request out first.
- `max_poll_attempts` is a single budget shared across the upload and translation phases.
- Timeout is configurable via `BLUENTE_API_TIMEOUT_MS`.
- For production, use separate API keys per environment.

## Data Handling & Privacy

- **Documents you translate are uploaded to Bluente's API** (`api.bluente.com` by default) for processing. Do not translate documents you are not permitted to send to a third-party service.
- **The AI model controls the tools.** When run locally (stdio), `file_path` lets the model read any file your user account can read and upload it to Bluente, and `output_path` lets it write downloaded files to any writable path. Review tool calls in your MCP client before approving them, especially when working with untrusted documents — a malicious document could try to instruct the model to misuse these tools.
- Translated output returned by tools (file contents, status payloads) enters your AI client's context and is therefore visible to your LLM provider.
- Your API key stays on your machine: it is read from the environment and sent only as an `Authorization` header to the configured Bluente API base URL. It is never logged or included in tool responses.

## Security

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

See [SECURITY.md](./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](./CONTRIBUTING.md)
- Security policy: [SECURITY.md](./SECURITY.md)
- Changelog: [CHANGELOG.md](./CHANGELOG.md)
- Code ownership: [.github/CODEOWNERS](./.github/CODEOWNERS)

## About Bluente

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

- Website: [bluente.com](https://www.bluente.com/)
- Product page: [Blu Translate](https://www.bluente.com/translator)
- API documentation: [bluente.com/docs](https://www.bluente.com/docs)

## License

MIT