@transglot/mcp

MCP (Model Context Protocol) server for transglot. It exposes the public REST API as typed MCP tools, so any MCP-capable agent (Claude Desktop, Claude Code, Cursor, or your own) can read and write translations, pull/push localization files, trigger AI translation batches, run QA, and manage the glossary.

One server instance serves one project: the access token is project-scoped (the token is the project), and the abilities on the token (read, write, pull, push, manage) gate which tools succeed.

Setup

Create a project access token in the transglot web UI (project settings → access tokens), then configure your client:

Claude Code

claude mcp add transglot --env TRANSGLOT_TOKEN=tgl_xxx -- npx -y @transglot/mcp

Claude Desktop

claude_desktop_config.json:

{
  "mcpServers": {
    "transglot": {
      "command": "npx",
      "args": ["-y", "@transglot/mcp"],
      "env": { "TRANSGLOT_TOKEN": "tgl_xxx" }
    }
  }
}

Cursor

.cursor/mcp.json:

{
  "mcpServers": {
    "transglot": {
      "command": "npx",
      "args": ["-y", "@transglot/mcp"],
      "env": { "TRANSGLOT_TOKEN": "tgl_xxx" }
    }
  }
}

Environment

| Variable | Required | Meaning | | --- | --- | --- | | TRANSGLOT_TOKEN | yes | Project access token (Bearer). Never logged; redacted from every error message. | | TRANSGLOT_BASE_URL | no | Server base URL for self-hosted installs. Defaults to https://api.transglot.ai (the API host; the web UI on https://app.transglot.ai serves no /v1 paths). Plain http:// is allowed for loopback hosts only. TRANSGLOT_URL (the CLI's variable) is honored as a fallback. |

Tools

Read tools are free and side-effect-less; mutating tools state their effects in their descriptions so the agent (and you, via your client's approval flow) can decide. Tools marked AI spend consume the organization's AI word quota.

| Tool | Effect | | --- | --- | | get_project | Read project identity, configured locales, key count. | | list_languages | Read the locale inventory (the API cannot add locales). | | get_translation | Read one key in one locale: value, workflow state, staleness, QA verdict. | | upsert_translation | Create/overwrite one value (or plural forms) as a human edit. A source-locale edit may auto-queue an AI batch (AI spend). | | translate_missing | Queue an AI batch filling missing target values; never overwrites human edits (AI spend). | | get_batch_status | Poll a batch by id, optionally with its failed items. | | list_batches | List recent batches; active_only finds the one blocking a new run. | | retry_failed_batch | Re-queue a finished batch's failed items (AI spend). | | cancel_batch | Stop a running batch; unspent reserved words return to the allowance. | | run_qa | Run the agentic QA pass; findings land on each row (AI spend, plan-gated). | | glossary_list_terms | List glossary terms, keyset-paginated via next_cursor. | | glossary_add_term | Add an active term (do-not-translate / forbidden / required translations). | | glossary_update_term | Full-replace a term by id. | | glossary_delete_term | Permanently delete a term by id. | | pull_file | Export one locale as a file (8 formats, optional min_state filter). | | push_file | Import file content; sync_removals also deletes keys absent from a source file. |

Formats for pull_file/push_file: json_flat, json_nested, android_xml, ios_strings, ios_stringsdict, flutter_arb, laravel_php, laravel_json.

Behavior

• Transport: stdio only. stdout is reserved for the protocol; diagnostics go to stderr. npx @transglot/mcp --help prints usage.
• Errors: RFC 7807 problems from the API surface as in-band tool errors, slug (HTTP status): detail plus a what-to-do-next hint (e.g. quota exceeded reports used/limit and says to raise the word limit).
• Rate limits: the API allows 60 requests/minute per token; transient 429s are retried automatically (honoring Retry-After, capped, max 2 retries) before an error is surfaced.
• Security: the token is sent only as the Authorization header and is redacted from any error text, even if a server echoes it back.

Not covered (API surface, not server choices)

The public API has no endpoints for listing/searching keys, creating/deleting individual keys (keys are managed by pushing source files), adding languages, or managing webhooks, so there are deliberately no tools for those.

Development

npm ci
npm run typecheck
npm test        # vitest; builds dist/ once for the stdio ring
npm run build