{"_id":"@bluente/translate-mcp-server","_rev":"2-8721dfc5628e63e635b85f010779add3","name":"@bluente/translate-mcp-server","dist-tags":{"latest":"0.4.0"},"versions":{"0.2.0":{"name":"@bluente/translate-mcp-server","version":"0.2.0","keywords":["mcp","model-context-protocol","translation","bluente"],"author":{"name":"Bluente"},"license":"MIT","_id":"@bluente/translate-mcp-server@0.2.0","maintainers":[{"name":"jack89757","email":"jack.feng@bluente.com"},{"name":"euzintan_bluente","email":"euzin.tan@bluente.com"}],"homepage":"https://www.bluente.com/translator","bugs":{"url":"https://github.com/Bluente/bluente-translate-mcp-server/issues"},"bin":{"bluente-translate-mcp":"src/index.js"},"dist":{"shasum":"1c1153dd16206bcd2fee130f8d5934fa470ed04a","tarball":"https://registry.npmjs.org/@bluente/translate-mcp-server/-/translate-mcp-server-0.2.0.tgz","fileCount":19,"integrity":"sha512-Scl9blTaSeOG3WwL79dE6esZAhWZW4cBeNUwe1u9dVisAI/xpRuPCrmklCv9BDbzZlsKlJAfmWhthoL6+Dl+MA==","signatures":[{"sig":"MEQCIFMfNCq6gGcFDv04Lpj07KiOSCZXzw8PU9vtmE+0facEAiBwuUY/6zWRR9ngbvwnIsQbGXSb+n7rt2qfALXXl3jbsQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":27716},"main":"src/index.js","type":"module","engines":{"node":">=20.0.0"},"gitHead":"04fb73bc77abd338970acd98ff0c62ae579f9eb5","scripts":{"test":"node --test","check":"node scripts/check-syntax.mjs","start":"node src/index.js"},"_npmUser":{"name":"euzintan_bluente","email":"euzin.tan@bluente.com"},"repository":{"url":"git+https://github.com/Bluente/bluente-translate-mcp-server.git","type":"git"},"_npmVersion":"11.17.0","description":"Open-source MCP server for Bluente translation APIs","directories":{},"_nodeVersion":"26.5.0","dependencies":{"zod":"^3.25.76","dotenv":"^16.6.1","zod-to-json-schema":"^3.25.0","@modelcontextprotocol/sdk":"^1.17.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/translate-mcp-server_0.2.0_1786810504642_0.19385490356216462","host":"s3://npm-registry-packages-npm-production"}},"0.4.0":{"name":"@bluente/translate-mcp-server","version":"0.4.0","description":"Open-source MCP server for Bluente translation APIs","type":"module","main":"src/index.js","bin":{"bluente-translate-mcp":"src/index.js"},"publishConfig":{"access":"public"},"scripts":{"start":"node src/index.js","check":"node scripts/check-syntax.mjs","test":"node --test","prepublishOnly":"npm run check && npm test"},"keywords":["mcp","model-context-protocol","translation","bluente"],"author":{"name":"Bluente"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/Bluente/bluente-translate-mcp-server.git"},"homepage":"https://www.bluente.com/translator","bugs":{"url":"https://github.com/Bluente/bluente-translate-mcp-server/issues"},"dependencies":{"@modelcontextprotocol/sdk":"^1.17.0","dotenv":"^16.6.1","zod":"^3.25.76"},"engines":{"node":">=20.0.0"},"gitHead":"364a8a65b672fc2032a4b078d57eb70b16a557db","_id":"@bluente/translate-mcp-server@0.4.0","_nodeVersion":"26.5.0","_npmVersion":"11.17.0","dist":{"integrity":"sha512-j3rQadFBB74m6k7XsZlhJJgweCeYr5gIgmARzvROh9fTD1lY4OcdSN/At7+5feaHn5aJnxsXP7F48nsen2hv/w==","shasum":"ac618094eb8b9ed8dd4eb69c4e75a9b89aeb739e","tarball":"https://registry.npmjs.org/@bluente/translate-mcp-server/-/translate-mcp-server-0.4.0.tgz","fileCount":21,"unpackedSize":72145,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIFjNPn6FBKi4ni862XjIA56jVyDm2KRNTefpgPIJwVnRAiEA2AQinpGkTaw0MBhDnzN6+KW1dy97M+j+znIOwZ7yh4A="}]},"_npmUser":{"name":"euzintan_bluente","email":"euzin.tan@bluente.com"},"directories":{},"maintainers":[{"name":"jack89757","email":"jack.feng@bluente.com"},{"name":"euzintan_bluente","email":"euzin.tan@bluente.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/translate-mcp-server_0.4.0_1787996109841_0.547329163627869"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-15T16:15:04.517Z","modified":"2026-08-29T09:35:10.144Z","0.2.0":"2026-08-15T16:15:04.777Z","0.4.0":"2026-08-29T09:35:09.988Z"},"bugs":{"url":"https://github.com/Bluente/bluente-translate-mcp-server/issues"},"author":{"name":"Bluente"},"license":"MIT","homepage":"https://www.bluente.com/translator","keywords":["mcp","model-context-protocol","translation","bluente"],"repository":{"type":"git","url":"git+https://github.com/Bluente/bluente-translate-mcp-server.git"},"description":"Open-source MCP server for Bluente translation APIs","maintainers":[{"name":"jack89757","email":"jack.feng@bluente.com"},{"name":"euzintan_bluente","email":"euzin.tan@bluente.com"}],"readme":"<div align=\"center\">\n\n<a href=\"https://www.bluente.com/\" target=\"_blank\" rel=\"noopener noreferrer\">\n  <img src=\"https://translate.bluente.com/_next/static/media/singleLogo.c3edb4ba.svg\" alt=\"Bluente Logo\" width=\"72\" height=\"72\" />\n</a>\n\n# Bluente Translate MCP Server\n\n**AI-powered. Format-preserving. Built for professional document translation workflows.**\n\n[![CI](https://img.shields.io/github/actions/workflow/status/bluente/bluente-translate-mcp-server/ci.yml?branch=main&label=CI)](./.github/workflows/ci.yml)\n[![Node.js >=20](https://img.shields.io/badge/node-%3E%3D20-339933?logo=node.js&logoColor=white)](https://nodejs.org/)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)\n[![MCP](https://img.shields.io/badge/protocol-MCP-111111)](https://modelcontextprotocol.io/)\n\n</div>\n\n`bluente-translate-mcp-server` is the official open-source MCP server for exposing Bluente translation capabilities to AI clients.\n\nIt wraps Bluente APIs into production-ready MCP tools so teams can automate multilingual document workflows from Claude Desktop, Cursor, and other MCP-compatible runtimes.\n\n## Why Bluente\n\nBluente focuses on enterprise-grade document translation where **accuracy, formatting integrity, and speed** matter.\n\nFrom [Bluente.com](https://www.bluente.com/) and [Blu Translate](https://www.bluente.com/translator), the core product positioning is:\n\n- AI-powered translation for professional use cases\n- Original layout retention for document-centric workflows\n- Broad language and file-type support\n- Security-first handling for sensitive content\n\nThis MCP server brings those capabilities into agent workflows through a standard protocol interface.\n\n## Brand Identity\n\nThis repository is maintained by **Bluente** and is part of Bluente's public developer ecosystem.\n\n- Company website: [https://www.bluente.com](https://www.bluente.com)\n- Product page: [https://www.bluente.com/translator](https://www.bluente.com/translator)\n- API docs: [https://www.bluente.com/docs](https://www.bluente.com/docs)\n\n## Table of Contents\n\n- [What You Get](#what-you-get)\n- [Architecture](#architecture)\n- [Supported Bluente APIs](#supported-bluente-apis)\n- [MCP Tools](#mcp-tools)\n- [Quick Start](#quick-start)\n- [Local Development](#local-development)\n- [Operational Notes](#operational-notes)\n- [Data Handling & Privacy](#data-handling--privacy)\n- [Security](#security)\n- [Roadmap](#roadmap)\n- [Contributing and Governance](#contributing-and-governance)\n- [License](#license)\n\n## What You Get\n\n- Modular Node.js MCP server with clear layering (`config`, `client`, `service`, `tools`)\n- One-file-per-tool implementation for maintainability\n- Unified tool response envelope (`ok/tool/data` and structured errors)\n- End-to-end translation workflow tool (upload -> start -> poll -> download)\n- CI checks and local smoke tests\n\n## Architecture\n\n```text\nAI Client (Claude / Cursor / Agents)\n            |\n            | MCP (stdio)\n            v\n+---------------------------------------+\n| Bluente Translate MCP Server          |\n|                                       |\n|  tools/  -> MCP tool handlers         |\n|  services/ -> workflow orchestration  |\n|  clients/ -> Bluente HTTP API client  |\n|  config/ + lib/ -> env/errors/results |\n+---------------------------------------+\n            |\n            | HTTPS\n            v\n      Bluente Translation APIs\n```\n\nProject layout:\n\n```text\nsrc/\n  clients/bluente-http-client.js\n  config/env.js\n  constants/api.js\n  lib/errors.js\n  lib/mcp-result.js\n  services/translation-workflow-service.js\n  tools/*.tool.js\n  tools/schemas.js\n  tools/register-tools.js\n  server.js\n  index.js\ntests/smoke/core-smoke.test.js\n```\n\n## Supported Bluente APIs\n\n- `GET /blu_translate/supported_languages`\n- `POST /blu_translate/upload`\n- `GET /blu_translate/check`\n- `POST /blu_translate/translate`\n- `GET /blu_translate/download`\n\nReference: [Bluente API Docs](https://www.bluente.com/docs)\n\n## MCP Tools\n\n- `bluente_get_supported_languages`\n- `bluente_upload_file`\n- `bluente_get_translation_status`\n- `bluente_translate_file`\n- `bluente_download_file`\n- `bluente_translate_document_workflow`\n\nThese match the tools exposed by Bluente's hosted MCP server, so a prompt or\nagent written against one works against the other. The differences are the two\nthings only a local server can do: `file_path` as a source, and `output_path`\nfor saving results to disk (the hosted server hands out download links instead).\n\nTool behavior notes:\n\n- **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**. 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.\n- **File sources**: `file_path` (a file on this machine), `file_url` (a public link), or `file_content_base64` (under 2MB).\n- `bluente_translate_file`: `from` and `to` are required when `action=\"start\"` and optional when `action=\"cancel\"`.\n- **`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.\n- **`entry` / `status_entry`**: `get_status` (translation progress, the default) or `get_page_count` (the uploaded file's page count).\n- **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.\n- **`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.\n- **`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; costs more per page). The numeric `scanned` 0–3 flag is a deprecated alias.\n- **`page_range`** (e.g. `\"1-3,5\"`): translate only selected pages; credits are charged only for those pages.\n- **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`.\n\nSuccess envelope:\n\n```json\n{\n  \"ok\": true,\n  \"tool\": \"bluente_upload_file\",\n  \"data\": {\n    \"code\": 0,\n    \"message\": \"success\",\n    \"data\": { \"id\": \"task_xxx\" }\n  }\n}\n```\n\nError envelope:\n\n```json\n{\n  \"isError\": true,\n  \"ok\": false,\n  \"tool\": \"bluente_translate_file\",\n  \"error\": {\n    \"name\": \"BluenteApiError\",\n    \"message\": \"Bluente API request failed.\",\n    \"details\": { \"status\": 401 }\n  }\n}\n```\n\n## Quick Start\n\nRequirements: Node.js `>= 20` (check with `node --version`; install from [nodejs.org](https://nodejs.org)) and a Bluente API key.\n\n**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.\n\n### Option 1: Just let your coding agent do it\n\nThe 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:\n\n> 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\n\nThe agent finds the right config file for its client, writes the block, and proves the install works by showing you the supported-language list.\n\nPrefer 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.\n\n### Option 2: Install manually\n\n**Claude Desktop**\n\n1. Open **Settings → Developer → Edit Config** (opens `claude_desktop_config.json`).\n2. Add this block (merge into `mcpServers` if it already exists), inserting your API key:\n\n   ```json\n   {\n     \"mcpServers\": {\n       \"bluente-translate\": {\n         \"command\": \"npx\",\n         \"args\": [\"-y\", \"@bluente/translate-mcp-server\"],\n         \"env\": {\n           \"BLUENTE_API_KEY\": \"your_api_key_here\"\n         }\n       }\n     }\n   }\n   ```\n\n3. Quit and reopen Claude Desktop. The tools icon should list six `bluente_*` tools.\n\n**Claude Code** — one command, then restart your session and verify with `/mcp`:\n\n```bash\nclaude mcp add bluente-translate -e BLUENTE_API_KEY=your_api_key_here -- npx -y @bluente/translate-mcp-server\n```\n\n**Cursor** — Settings → MCP → Add server, or create `.cursor/mcp.json` in your project with the same JSON block as Claude Desktop.\n\n**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.\n\n### Troubleshooting the API key\n\nThe 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.\n\nOptional environment variables:\n\n| Variable | Default | Purpose |\n| --- | --- | --- |\n| `BLUENTE_API_KEY` | (required) | Your Bluente API key |\n| `BLUENTE_API_BASE_URL` | `https://api.bluente.com/api/20250924` | API base URL |\n| `BLUENTE_API_TIMEOUT_MS` | `90000` | HTTP timeout in milliseconds |\n\n## Local Development\n\n```bash\ngit clone https://github.com/bluente/bluente-translate-mcp-server.git\ncd bluente-translate-mcp-server\nnpm install\ncp .env.example .env   # then set BLUENTE_API_KEY\nnpm start              # run the server on stdio\nnpm run check          # syntax check\nnpm test               # run tests\n```\n\nTo 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.\n\n## Operational Notes\n\n- The workflow tool returns as soon as translation starts. Poll `bluente_get_translation_status` until `READY`, then call `bluente_download_file`.\n- `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.\n- `max_poll_attempts` is a single budget shared across the upload and translation phases.\n- Timeout is configurable via `BLUENTE_API_TIMEOUT_MS`.\n- For production, use separate API keys per environment.\n\n## Data Handling & Privacy\n\n- **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.\n- **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.\n- Translated output returned by tools (file contents, status payloads) enters your AI client's context and is therefore visible to your LLM provider.\n- 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.\n\n## Security\n\n- Do not commit API keys or `.env` files.\n- Rotate leaked keys immediately.\n- Use repository private vulnerability reporting.\n\nSee [SECURITY.md](./SECURITY.md) for disclosure policy.\n\n## Roadmap\n\n- Add text translation tools if exposed in public API docs\n- Add richer integration tests with API mocking\n- Add container image and one-command local launch profile\n\n## Contributing and Governance\n\n- Contribution guide: [CONTRIBUTING.md](./CONTRIBUTING.md)\n- Security policy: [SECURITY.md](./SECURITY.md)\n- Changelog: [CHANGELOG.md](./CHANGELOG.md)\n- Code ownership: [.github/CODEOWNERS](./.github/CODEOWNERS)\n\n## About Bluente\n\nBluente builds AI translation and business communication solutions for professional teams.\n\n- Website: [bluente.com](https://www.bluente.com/)\n- Product page: [Blu Translate](https://www.bluente.com/translator)\n- API documentation: [bluente.com/docs](https://www.bluente.com/docs)\n\n## License\n\nMIT\n","readmeFilename":"README.md"}