i18n-file-replace-mcp

English | 中文

MCP (Model Context Protocol) server built on the external API of the i18n resource management platform (https://i18n.codeini.com). Exposes the i18n file replacement capability to MCP clients such as Claude Desktop and Qoder.

Requirements: Node.js >= 20.

Installation

cd i18n-file-replace-mcp
npm install

Stateless: every tool call talks directly to the remote platform API, no data is stored locally.

Related MCP server: @langapi/mcp-server

Configuration (MCP clients)

Generic (stdio)

{
  "mcpServers": {
    "i18n-file-replace": {
      "command": "npx",
      "args": ["--yes", "--package", "@codeini/i18n-file-replace-mcp", "i18n-file-replace-mcp"],
      "env": {
        "I18N_API_KEY": "your platform API key"
      }
    }
  }
}

Local directory (recommended, debuggable)

{
  "mcpServers": {
    "i18n-file-replace": {
      "command": "node",
      "args": ["C:/projects/codeini_playground/common/backend/Globalization/General/i18n-file-replace-mcp/src/index.js"],
      "env": {
        "I18N_API_KEY": "your platform API key",
        "I18N_BASE_URL": "https://i18n.codeini.com"
      }
    }
  }
}

Environment variables

Tools

(* = required; provide at least one of configJson / profileName, configJson takes precedence.)

resourceSetByDir mirrors the CLI's --resource-set-by-dir: when fileName carries a directory prefix (e.g. member/list.vue), the actual resource set becomes <resourceSet>.<first-level dir> (e.g. portal.member).

download_resources returns file contents as text — writing them to disk is up to the caller.

Usage examples

1. List the available profiles:

   list_profiles

2. Preview a replacement (no database write):

   preview_replace { fileName: "Home.vue", content: "<template>...</template>", profileName: "vue-home" }

3. Replace and write the keys into a resource set:

   replace_file { fileName: "Home.vue", content: "<template>...</template>", configJson: "{...}", resourceSet: "home" }
   // also produce English alongside zh in one call:
   replace_file { fileName: "Home.vue", content: "...", profileName: "vue", resourceSet: "home", translateTo: ["en"] }

Debugging

Validate the tools with MCP Inspector:

npx @modelcontextprotocol/inspector node src/index.js

Common errors

Publishing to npm

A release is cut from a git tag: push vX.Y.Z (the same version as package.json) and the Release workflow runs the tests, then submits this version with npm stage publish.

Staged publishing means the workflow can only queue the package in npm's staging area — nobody installs it from there. Making it live requires a maintainer to approve it on https://www.npmjs.com under the Staged Packages tab (or npm stage approve <stage-id> in the CLI), and that step needs 2FA. CI structurally cannot publish on its own. The workflow reads the NPM_TOKEN repository secret, which must carry @codeini publish rights.

npm test                                       # what CI runs, on your machine
npm run publish:npm                            # stage this working copy by hand (needs NPM_TOKEN)
npm stage list @codeini/i18n-file-replace-mcp  # find the stage-id
npm stage approve <stage-id>                   # make it live (your own npm login + 2FA)