Blocks Translation MCP

An MCP server that finds new UI translation keys in your codebase, dedup-checks them against a Blocks/UILM tenant, and generates the JSON the Blocks portal expects for import — for any project, framework, or language set, driven by a single per-project config file.

It never guesses tenant IDs, module names, or supported languages — those are resolved live from your config and the tenant itself. Translation text is inferred/authored by the agent; this server does the deterministic parts (diff scanning, dedupe, exact JSON stamping) in code so they're fast, cheap, and reliable.

• Works in any MCP client — Claude Code, Cursor, Codex, Google Antigravity, Pi, Windsurf, Cline, VS Code, Zed, …
• Any frontend framework — built-in ngx-translate and react-i18next extractors, plus a generic regex mode for anything else.
• Zero hardcoded languages — cultures come from the tenant's own Language/Gets API and are cached per project.
• Per-project config — one .env.blocks-translation file at each consuming repo's root; no secrets ever live in this server.

Contents

• Quick start
• Tools
• Install
• Add to your AI tool — Claude Code · Cursor · Codex · Antigravity · Pi · Windsurf · Cline · VS Code · Zed · generic
• Configure your project
• How it works
• How the server finds your project
• Troubleshooting

Quick start

# 1. Build the server (once)
git clone <repo-url> blocks-translation-mcp
cd blocks-translation-mcp && npm install && npm run build

# 2. Configure a project that uses Blocks
cp .env.blocks-translation.example /path/to/your/project/.env.blocks-translation
#    …then fill in BLOCKS_TENANT_ID, BLOCKS_PORTAL_KEY, BLOCKS_USERNAME, BLOCKS_PASSWORD

# 3. Register the server in your AI tool (see "Add to your AI tool"), then just ask:
#    "sync the translation keys"

Tools

Tool	What it does
prepare_sync	The one prep call. Scans the project diff (working-tree + staged + untracked), groups keys by their own module, fetches the tenant cultures, and exact-dedupes — all in code. Returns { cultures, modules: [{ module, newKeys, existingSkip }] }. Replaces find_keys+list_modules+list_cultures+search_keys.
sync_keys	Dedup-check + build + write the upload JSON in one call (one file per module). Reports skippedExisting and duplicateWarnings (same English under a different key).
find_keys	Standalone: extract translation keys from the git diff for the configured framework (ngx-translate | react-i18next | generic).
list_cultures	The tenant's supported cultures (from the Blocks Language API, cached). refresh:true re-fetches.
list_modules	Modules in the tenant (name + id).
search_keys	Dedup-check keys against a module (+ any BLOCKS_DEDUP_MODULES) — both exact-key and same-text.
build_upload_entries	Pure JSON assembly of already-translated keys into the portal's import shape.

Most of the time the agent only needs prepare_sync → sync_keys; the rest are composable building blocks.

Install

Recommended: one command (auto-detects your AI tools)

npx -y github:mahmudul006/blocks-translation-mcp install

This detects the AI tools installed on your machine (Claude Code, Cursor, Codex, Antigravity, Pi, Windsurf, Cline, VS Code, Zed…), asks global vs project, and registers the server into each — using each tool's own CLI or config format. It backs up any file before editing and only ever touches its own blocks-translation entry.

Flags (all optional — omit them to be prompted):

Flag	Effect
--print	Dry run: show every planned change, write nothing.
--scope global|project	Skip the scope prompt.
--root <path>	Project root for a project install (default: current dir).
--clients all|1,3,5	Skip the client picker.
--yes	Accept all defaults (non-interactive).

Requires Node ≥ 18; no clone or build. Then configure your project (the .env.blocks-translation) and restart your tool.

Uninstall / re-try

npx -y github:mahmudul006/blocks-translation-mcp uninstall           # prompts for scope
npx -y github:mahmudul006/blocks-translation-mcp uninstall --scope global --yes

Removes only the blocks-translation entry from each tool (via its remove-CLI or by editing its config, backing up first), and lists any you must remove by hand. Accepts the same --scope / --root / --print flags.

Re-fetching a new version: npx github: caches the cloned repo, so after the server is updated on GitHub, clear the cache before re-running: rm -rf ~/.npm/_npx.

Manual / from source

If you'd rather not use npx github:, clone and build, then use the per-client blocks below with node /abs/path/to/dist/index.js instead of the npx command:

git clone https://github.com/mahmudul006/blocks-translation-mcp
cd blocks-translation-mcp && npm install && npm run build

Add to your AI tool

The installer above does this for you. To do it by hand, every client runs the same stdio command:

npx -y github:mahmudul006/blocks-translation-mcp

Only two things differ per client: where the config lives and its wrapper key (mcpServers JSON, VS Code's servers, Zed's context_servers, or Codex's TOML). If your client doesn't start the server with its working directory set to your project root, add "BLOCKS_PROJECT_ROOT": "/abs/path/to/your/project" to the server's env (see How the server finds your project).

GUI clients + nvm: the one-command installer handles this, but if you configure a GUI client (Antigravity, Cursor, Windsurf, VS Code) by hand and Node is installed via nvm, use an absolute command (full path to npx) and add your Node bin dir to env.PATH — otherwise the tool can't find npx/node. See Troubleshooting. Command-line clients (Claude Code, Codex) don't need it.

Claude Code

claude mcp add blocks-translation -- npx -y github:mahmudul006/blocks-translation-mcp

or in .mcp.json (project) / ~/.claude.json (global):

{ "mcpServers": { "blocks-translation": {
  "command": "npx",
  "args": ["-y", "github:mahmudul006/blocks-translation-mcp"]
} } }

Claude Code sets the server's cwd to your project root, so .env.blocks-translation is found automatically — no BLOCKS_PROJECT_ROOT needed.

Cursor

.cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{ "mcpServers": { "blocks-translation": {
  "command": "npx",
  "args": ["-y", "github:mahmudul006/blocks-translation-mcp"],
  "env": { "BLOCKS_PROJECT_ROOT": "/abs/path/to/your/project" }
} } }

Codex (OpenAI Codex CLI)

~/.codex/config.toml (or a project .codex/config.toml):

[mcp_servers.blocks-translation]
command = "npx"
args = ["-y", "github:mahmudul006/blocks-translation-mcp"]

[mcp_servers.blocks-translation.env]
BLOCKS_PROJECT_ROOT = "/abs/path/to/your/project"

or via CLI:

codex mcp add blocks-translation --env BLOCKS_PROJECT_ROOT=/abs/path/to/your/project -- npx -y github:mahmudul006/blocks-translation-mcp

Google Antigravity

In the IDE: Manage MCP Servers → View raw config, or edit .agents/mcp_config.json (workspace) / ~/.gemini/config/mcp_config.json (global):

{ "mcpServers": { "blocks-translation": {
  "command": "npx",
  "args": ["-y", "github:mahmudul006/blocks-translation-mcp"],
  "env": { "BLOCKS_PROJECT_ROOT": "/abs/path/to/your/project" }
} } }

Pi (pi coding agent)

.mcp.json in your project (or the pi agent directory). Pi supports a cwd field, so you can point the server at your repo directly:

{ "mcpServers": { "blocks-translation": {
  "command": "npx",
  "args": ["-y", "github:mahmudul006/blocks-translation-mcp"],
  "cwd": "/abs/path/to/your/project"
} } }

Because Pi loads .mcp.json from the project cwd, a project-local config also finds .env.blocks-translation automatically.

Windsurf

~/.codeium/windsurf/mcp_config.json:

{ "mcpServers": { "blocks-translation": {
  "command": "npx",
  "args": ["-y", "github:mahmudul006/blocks-translation-mcp"],
  "env": { "BLOCKS_PROJECT_ROOT": "/abs/path/to/your/project" }
} } }

Cline (VS Code extension)

Cline → MCP Servers → Configure (cline_mcp_settings.json):

{ "mcpServers": { "blocks-translation": {
  "command": "npx",
  "args": ["-y", "github:mahmudul006/blocks-translation-mcp"],
  "env": { "BLOCKS_PROJECT_ROOT": "/abs/path/to/your/project" }
} } }

VS Code (Copilot agent mode)

.vscode/mcp.json — note VS Code uses servers (not mcpServers) and an explicit type:

{ "servers": { "blocks-translation": {
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "github:mahmudul006/blocks-translation-mcp"],
  "env": { "BLOCKS_PROJECT_ROOT": "${workspaceFolder}" }
} } }

Zed

settings.json — Zed uses context_servers:

{ "context_servers": { "blocks-translation": {
  "source": "custom",
  "command": "npx",
  "args": ["-y", "github:mahmudul006/blocks-translation-mcp"],
  "env": { "BLOCKS_PROJECT_ROOT": "/abs/path/to/your/project" }
} } }

Any other MCP client (generic stdio)

Any client that speaks MCP over stdio works. Register a stdio server with:

• command: npx
• args: ["-y", "github:mahmudul006/blocks-translation-mcp"]
• env (optional): BLOCKS_PROJECT_ROOT (if the client doesn't set cwd to your repo), or the full BLOCKS_* set instead of a .env file.

Configure your project

Copy the example into your project's repo root (not this server's directory) and fill it in:

cp /abs/path/to/blocks-translation-mcp/.env.blocks-translation.example \
   /abs/path/to/your/project/.env.blocks-translation

Add .env.blocks-translation (and .blocks-translation-cache.json) to your project's .gitignore — the config holds credentials.

Config is read lazily, only when a tool runs, with this precedence per key: explicit BLOCKS_* env vars (e.g. from your client's env block) win over values in .env.blocks-translation.

Variable	Required?	Default	Meaning
BLOCKS_TENANT_ID	Yes	—	Your tenant GUID. Required for every tool.
BLOCKS_PORTAL_KEY	For login / modules / languages	—	Portal app key used to authenticate the admin surface.
BLOCKS_USERNAME	For login / modules / languages	—	Admin username for the login-required endpoints.
BLOCKS_PASSWORD	For login / modules / languages	—	Admin password. If it contains #, wrap the value in double quotes.
BLOCKS_BASE_URL	No	https://api.seliseblocks.com	Blocks API base URL.
BLOCKS_ORIGIN	No	https://cloud.seliseblocks.com	Origin/Referer the admin surface requires. Override only for a non-cloud Blocks deployment.
BLOCKS_FRAMEWORK	No	ngx-translate	Key extraction: ngx-translate | react-i18next | generic.
BLOCKS_KEY_REGEX	Only if BLOCKS_FRAMEWORK=generic	—	Regex whose first capture group is the key.
BLOCKS_OUTPUT_PATH_PATTERN	No	blocks-translation-helper/blocks-upload.{module}.generated.json	Output path template; {module} is substituted.
BLOCKS_DEDUP_MODULES	No	(empty)	Comma-separated shared modules to also dedup-check alongside the target (e.g. root,generic-app if your tenant has them). Missing modules are tolerated.
BLOCKS_PROJECT_ROOT	Only if your client doesn't set cwd to your repo	current working directory	Points the server at your project's root.

How it works

The lean, token-cheap flow for adding or syncing translation keys — usually two tool calls:

1. prepare_sync — one call. Scans the diff (working-tree + staged + untracked), groups keys by their own module, fetches the tenant's cultures, and exact-dedupes each module's keys. Returns { cultures, modules: [{ module, newKeys, existingSkip }] }.
2. Translate — for each module's newKeys only, the agent infers English from the key name and translates into the returned cultures. (This server does not translate for you, and does not read your local i18n files — the portal is the source of truth.)
3. sync_keys — once per module, writes blocks-translation-helper/blocks-upload.<module>.generated.json (path configurable) and reports any duplicateWarnings (same English under a different existing key) for you to decide on.
4. Manual portal import — importing the generated JSON into the Blocks portal is a step you do yourself; this server never calls a write/import endpoint.

In clients that surface MCP server instructions (e.g. Claude Code), this workflow is injected automatically. In clients that don't, just ask for a tool by name (e.g. "run prepare_sync").

Languages: on first use the server logs in, calls Language/Gets for your tenant, and caches the result to .blocks-translation-cache.json at your project root (with a module-name → id cache). Pass refresh:true to prepare_sync/list_cultures if the tenant later adds a language.

How the server finds your project

The server needs your project's root to read .env.blocks-translation, run git diff, and place the cache. It resolves it with this precedence:

1. Explicit BLOCKS_* env vars set in your client's server config (highest priority).
2. BLOCKS_PROJECT_ROOT/.env.blocks-translation if BLOCKS_PROJECT_ROOT is set.
3. <cwd>/.env.blocks-translation — the zero-config default when the client sets cwd to your project (Claude Code, project-local Pi).

So: on Claude Code (and project-local Pi) it just works; on other clients, set BLOCKS_PROJECT_ROOT (or put the BLOCKS_* vars straight in the env block).

Troubleshooting

"No Blocks config found for this project" — BLOCKS_TENANT_ID isn't set. Create .env.blocks-translation at your project root (copy the example) or set BLOCKS_PROJECT_ROOT / the BLOCKS_* vars in your client's env block.

Missing admin credentials (BLOCKS_USERNAME/BLOCKS_PASSWORD/BLOCKS_PORTAL_KEY not set) — prepare_sync, list_modules, and language lookups use the admin surface. Set all three.

406 Invalid_Origin_Or_Referer — your Blocks deployment isn't the default cloud host. Set BLOCKS_ORIGIN to your portal's origin.

exec: "npx": executable file not found in $PATH / /usr/bin/env: 'node': No such file or directory — a GUI-launched client (Antigravity, Cursor, Windsurf, VS Code) spawned the server without your shell's PATH, so node/npx aren't found. Common when Node is installed via nvm (its bin dir is only on PATH inside a shell that sourced nvm). The one-command installer fixes this automatically. If you configured the client by hand, you need both an absolute command (the host resolves it against its own stripped PATH, before env) and an env.PATH (for npx's node shebang and child node/git). Find your Node bin dir with dirname $(readlink -f $(which npx)):

"blocks-translation": {
  "command": "/home/you/.nvm/versions/node/vX.Y.Z/bin/npx",
  "args": ["-y", "github:mahmudul006/blocks-translation-mcp"],
  "env": { "PATH": "/home/you/.nvm/versions/node/vX.Y.Z/bin:/usr/local/bin:/usr/bin:/bin" }
}

CLI-installed clients (Claude Code, Codex) don't need this — they inherit your shell PATH.

find_keys/prepare_sync git error — they run git in the project root. Ensure the project is a git repo and git is on PATH; if your client doesn't set cwd, set BLOCKS_PROJECT_ROOT.

Admin vs. public surface — the admin surface (prepare_sync language/module lookups, list_modules, list_cultures) requires the login vars. The public surface (search_keys, the dedupe fetches) needs only BLOCKS_TENANT_ID.

Cultures look stale (a newly-added tenant language is missing) — call prepare_sync/list_cultures with refresh:true, or delete .blocks-translation-cache.json.