i18n-codelens-mcp

Model Context Protocol (MCP) server for i18n translation files. It lets AI agents (Claude Code, Cursor, Antigravity, GitHub Copilot, Codex, Gemini CLI and any other MCP client) inspect, audit and safely edit locale JSON files without ever loading a whole locale file into the model context.

• Compact by design. Ten tools, single-line JSON results, no echoed input, limit/includeValues everywhere. A typical read costs 50-200 tokens.
• Safe by construction. No write path can reduce a locale file's key set; mixed flat/nested files are edited in place, never converted; upserts report conflicts instead of overwriting.
• Current MCP. Built on the TypeScript SDK v2: protocol revision 2026-07-28 and the 2025 revisions, server instructions, prompts (slash commands), cache hints and elicitation-based confirmation for destructive tools.
• Any layout. locales/en.json, locales/en-US.json, messages.en.json and i18next-style locales/en/common.json (namespace files, keys as common:nav.home).

This package is also the MCP backend of the i18n CodeLens VS Code extension.

Requirements

• Node.js 20 or newer
• Locale resources as JSON files
• An MCP client that supports stdio servers

Install

npx -y i18n-codelens-mcp
# or
npm install -g i18n-codelens-mcp

Client setup

Every command below registers the same thing: a stdio server named i18n-codelens running npx -y i18n-codelens-mcp. Pick your client, run one line, done.

The server needs to know which project to work on. Most clients start it in the project directory, and Claude Code passes the project root explicitly, so nothing else is needed. When your client starts the server from somewhere else, add the project path with the client's env flag, for example -e WORKSPACE_ROOT=/absolute/path/to/project.

Windows PowerShell: PowerShell can swallow a bare -- before it reaches the CLI, which then reports unknown option '-y'. If that happens, quote the separator as '--', or run the command from cmd, Git Bash or WSL.

Claude Code

# for the whole team: writes .mcp.json in the repo
claude mcp add --scope project i18n-codelens -- npx -y i18n-codelens-mcp

# just for you, in every project
claude mcp add --scope user i18n-codelens -- npx -y i18n-codelens-mcp

Claude Code sets CLAUDE_PROJECT_DIR for stdio servers, so the server always finds the right project. Its tool-search feature defers MCP tools; i18n_upsert_translations and i18n_get_translations are marked anthropic/alwaysLoad so the two everyday tools need no lookup. The prompts show up as /i18n-codelens:audit, /i18n-codelens:add-key and /i18n-codelens:translate-missing.

{
  "mcpServers": {
    "i18n-codelens": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "i18n-codelens-mcp"]
    }
  }
}

Google Antigravity

agy mcp add i18n-codelens -- npx -y i18n-codelens-mcp

agy mcp list, agy mcp disable i18n-codelens and agy mcp remove i18n-codelens manage it afterwards. Inside the IDE, /mcp opens the MCP manager.

{
  "mcpServers": {
    "i18n-codelens": {
      "command": "npx",
      "args": ["-y", "i18n-codelens-mcp"],
      "cwd": "/absolute/path/to/project",
      "env": { "WORKSPACE_ROOT": "/absolute/path/to/project" }
    }
  }
}

Gemini CLI

gemini mcp add -s user i18n-codelens npx -y i18n-codelens-mcp

Use -s project to write the project's settings instead. Gemini takes the command and its arguments positionally, so no -- is needed.

OpenAI Codex CLI

codex mcp add i18n-codelens -- npx -y i18n-codelens-mcp

[mcp_servers.i18n-codelens]
command = "npx"
args = ["-y", "i18n-codelens-mcp"]

VS Code and Copilot Chat

code --add-mcp "{\"name\":\"i18n-codelens\",\"command\":\"npx\",\"args\":[\"-y\",\"i18n-codelens-mcp\"]}"

That writes the user profile. MCP: Add Server in the Command Palette does the same through a guided flow and can target the workspace.

{
  "servers": {
    "i18n-codelens": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "i18n-codelens-mcp"],
      "env": { "WORKSPACE_ROOT": "${workspaceFolder}" }
    }
  }
}

OpenCode

opencode mcp add i18n-codelens -- npx -y i18n-codelens-mcp

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "i18n-codelens": {
      "type": "local",
      "command": ["npx", "-y", "i18n-codelens-mcp"],
      "enabled": true
    }
  }
}

GitHub Copilot CLI

Copilot CLI adds servers from inside a session rather than from the shell. Start copilot, then:

/mcp add

Fill in the form: Server Name i18n-codelens, Server Type STDIO, Command npx -y i18n-codelens-mcp. /mcp, /mcp show i18n-codelens and /mcp delete i18n-codelens manage it afterwards.

{
  "mcpServers": {
    "i18n-codelens": {
      "type": "local",
      "command": "npx",
      "args": ["-y", "i18n-codelens-mcp"],
      "env": {},
      "tools": ["*"]
    }
  }
}

Cursor, Windsurf, Claude Desktop, Kiro, Cline and Roo Code

These clients have no command to add a server, so the configuration file is the way in. The shape is the same everywhere; only the path differs.

{
  "mcpServers": {
    "i18n-codelens": {
      "command": "npx",
      "args": ["-y", "i18n-codelens-mcp"],
      "env": { "WORKSPACE_ROOT": "/absolute/path/to/project" }
    }
  }
}

{
  "mcpServers": {
    "i18n-codelens": {
      "command": "npx",
      "args": ["-y", "i18n-codelens-mcp"],
      "env": { "WORKSPACE_ROOT": "/absolute/path/to/project" }
    }
  }
}

{
  "mcpServers": {
    "i18n-codelens": {
      "command": "npx",
      "args": ["-y", "i18n-codelens-mcp"],
      "env": { "WORKSPACE_ROOT": "/absolute/path/to/project" },
      "disabled": false,
      "autoApprove": ["i18n_project_info", "i18n_get_translations", "i18n_search_keys", "i18n_file_keys", "i18n_key_references", "i18n_audit"]
    }
  }
}

{
  "context_servers": {
    "i18n-codelens": {
      "source": "custom",
      "command": "npx",
      "args": ["-y", "i18n-codelens-mcp"],
      "env": { "WORKSPACE_ROOT": "/absolute/path/to/project" }
    }
  }
}

{
  "mcpServers": {
    "i18n-codelens": {
      "command": "npx",
      "args": ["-y", "i18n-codelens-mcp"],
      "env": { "WORKSPACE_ROOT": "/absolute/path/to/project" },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Sharing with a team

Commit a project-level configuration so every teammate and every agent picks up the same server without touching global settings.

Workspace root

Resolution order:

1. Per-tool workspaceDir argument (must be inside the configured root, see below)
2. CLI --workspaceRoot <path> / --workspace-root <path>
3. WORKSPACE_ROOT
4. CLAUDE_PROJECT_DIR (set by Claude Code)
5. Current working directory
6. Server package directory

The workspaceDir tool argument can only select a sub-directory of the configured root. A model cannot point the server at another directory on disk unless the server is started with I18N_ALLOW_ANY_WORKSPACE=1.

Configuration

Tools

All results are compact single-line JSON. Empty sections are omitted, paths are workspace-relative with forward slashes, and every list honours limit (default 50). Errors come back as isError text with the fix in the message (for example the list of available locales).

Confirmation for destructive tools

i18n_delete_keys, i18n_rename_key and i18n_format_resources preview by default. When the model omits dryRun and the client supports MCP elicitation (Claude Code does), the server shows the user a one-question dialog describing the change and applies it on accept. Pass dryRun:false to apply without a dialog, dryRun:true to only preview. i18n_upsert_translations needs no confirmation: it cannot remove keys and refuses to overwrite a differing value unless overwrite:true.

Prompts

The server publishes three prompts that clients expose as commands: audit (full audit and fix proposals), add-key <key> [text] (add one key with copy for every locale) and translate-missing [locale] (fill missing translations in batches).

Instructions

On connect the server sends usage instructions (under 2 KB) that clients such as Claude Code add to the system prompt: never edit locale files directly, call i18n_project_info once, upsert with every locale in one call, and so on. Project-specific rules (key naming, tone, placeholder style) still belong in your own CLAUDE.md / AGENTS.md.

Namespaced layouts

If locale files live in per-locale directories (locales/en/common.json, locales/tr/auth.json), the directory is the locale and the file is the namespace. Keys are addressed as namespace:key (common:nav.home); i18n_project_info reports keyFormat: "namespace:key" and the namespaces. Set I18N_NS_SEPARATOR if your i18n library uses another separator and I18N_DEFAULT_NS for keys written without one.

Files whose name is not a locale tag (config.json) are skipped with a warning, and when a glob matches the same locale twice (src/locales/en.json and public/locales/en.json) the first is used and i18n_project_info warns you to narrow I18N_GLOB.

Structure and key safety

A locale file is classified by how its leaves are stored: flat ("nav.home": "Home"), nested (objects) or mixed. Under I18N_STRUCTURE=auto a flat file is written flat, a nested file nested, and a mixed file is never converted: every key stays where it is and a new key is written in the file's dominant style. Writes preserve the file's indentation, line endings and trailing newline, so a single-key change is a single-line diff.

Two guards make key loss structurally impossible:

• unflattenObject throws on a value/namespace collision (dashboard.announcement both a string and a parent) instead of overwriting one side.
• Every write compares the new document against the file on disk and refuses when a key would disappear. Deletes and renames declare their removals; anything else that goes missing aborts the write and names the keys.

The regression suite in src/__tests__/tools-write.test.ts and resource-manager.test.ts reproduces the incident that motivated this (a 3,000-key mixed file, a leaf that is also a namespace) and asserts zero loss and one-line diffs on every write path.

Migrating from 1.x

2.0 consolidates 18 tools into 10 and changes two defaults.

Other changes: Node 20+; @modelcontextprotocol/sdk replaced by @modelcontextprotocol/server 2.0 (protocol 2026-07-28 and 2025 revisions, both served); default ignore globs now skip common build output; workspaceDir is confined to the configured root; paths are posix; the code regex accepts ns:key and matches a call at the start of a file.

Suggested agent instruction block for projects that used the 1.x names:

i18n: never edit src/locales/*.json by hand. Call i18n_project_info once, then
i18n_upsert_translations with values for every locale (en and tr) in one call; it
reports conflicts and placeholder mismatches. Use i18n_get_translations to read,
i18n_audit for QA, i18n_rename_key / i18n_delete_keys with dryRun:false to apply.

MCP Registry

package.json carries mcpName: io.github.hepter/i18n-codelens-mcp and server.json describes the package. Publish with:

npm publish --access public
mcp-publisher login github
mcp-publisher publish

Programmatic API

import { createI18nMcpServer, loadProject, createResourceManager, toolUpsertTranslations, createToolContext } from 'i18n-codelens-mcp';

const ctx = createToolContext({ workspaceRoot: '/path/to/project' });
const result = await toolUpsertTranslations({ entries: [{ key: 'nav.home', values: { en: 'Home', tr: 'Ana Sayfa' } }] }, ctx);

Every tool is exported as a plain async function taking (args, ctx), alongside the building blocks: loadProject (cached, namespace-aware), getCodeIndex (cached code scan), createResourceManager (write states with the key-loss guard), writeFilePretty, flattenObject, unflattenObject, classifyResourceStructure.

Changelog

2.0.0

• SDK v2 / protocol 2026-07-28. @modelcontextprotocol/server with serveStdio, zod 4, Node 20+. Both the 2026-07-28 and 2025 revisions are served on stdio. tools/list and prompts/list carry cache hints.
• Ten tools instead of eighteen, compact single-line results, no structuredContent, no echoed arguments. Tool definitions shrank from 13.5 K to 9.5 K characters. Measured against 1.x on the same project, a two-locale code base of about 7,600 keys, a 50-hit key search dropped from 12.5 K to 2.3 K characters and a full audit from 6.7 K characters and 1.0 s to 2.0 K characters and 0.4 s.
• Upsert semantics. Writes immediately, validates the whole batch before touching a file (an unknown locale rejects everything), reports conflicts instead of overwriting unless overwrite:true, warns about locales without a value and about placeholder mismatches against the values other locales hold.
• Confirmation dialogs. Delete, rename and format use MCP elicitation when the client supports it and fall back to a preview with a hint otherwise.
• Server instructions and prompts (audit, add-key, translate-missing), server metadata (websiteUrl, description), version read from package.json.
• Namespaced layouts ({locale}/{namespace}.json, keys as ns:key), locale detection from file or directory names, duplicate and non-locale file warnings.
• Caches. Parsed locale files and code scans are reused while mtime/size are unchanged; the audit scans code once. .gitignore and common build directories are excluded before files are read.
• Fixes. Code regex character range (.-_ accidentally spanned :…^) and start-of-file matches; posix paths on Windows; CLAUDE_PROJECT_DIR respected; workspaceDir confined to the root; writes preserve indentation and CRLF; getWorkspaceRoot no longer logs on every call.

1.1.0

Fixed a data-loss defect: a single upsert could convert a mixed file and drop keys whose name was both a value and a namespace. Mixed files are no longer converted, unflattenObject/setNestedValue throw on collisions, and every write is guarded against key loss.

License

MIT © Mustafa Kuru