# i18n-file-replace-mcp

**English** | [中文](README.zh-CN.md)

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

```bash
cd i18n-file-replace-mcp
npm install
```

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

## Configuration (MCP clients)

### Generic (stdio)

```json
{
  "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)

```json
{
  "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

| Variable | Description | Default |
|---|---|---|
| `I18N_API_KEY` | Platform API key (required, get it from the i18n platform) | none |
| `I18N_BASE_URL` | API base URL | `https://i18n.codeini.com` |
| `I18N_ACCOUNT_ID` | Dev-mode tenant override (sends `X-Dev-Account-Id`; only honored by a Development server) | none |

## Tools

| Tool | Parameters | Returns |
|---|---|---|
| `replace_file` | `fileName`*, `content`*, `configJson`?, `profileName`?, `resourceSet`?, `resourceSetByDir`?, `translateTo`? (`["en","ja"]`), `translateProvider`? | `{ fileName, content, generatedKeys, keyCount, translatedCount? }` — with `resourceSet` + `translateTo`, each generated key is also machine-translated into the target locales and saved to the same resource set |
| `preview_replace` | Same as above (no resourceSet write) | `{ fileName, originalContent, content, generatedKeys, keyCount }` |
| `list_profiles` | none | List of profiles (without configJson) |
| `get_profile` | `name`* | `{ id, name, configJson, createdAt, updatedAt }` |
| `save_profile` | `name`*, `configJson`* | `{ message, profile }` (create or update) |
| `list_projects` | none | List of projects (id, name, locales, resourceSetCount) |
| `list_resource_sets` | none | List of resource set names |
| `list_resource_keys` | `resourceSet`*, `projectId`? | List of `{ resourceId, hasValue }` |
| `download_resources` | `resourceSet`*, `format`? (`.json`/`.resx`/`.po`/`.yaml`/`.yml`), `locale`? | Single file: `{ fileName, contentType, content }`; ZIP (multi-locale / .resx): `{ fileName, files: [{ name, content }] }` |

(`*` = 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:

```bash
npx @modelcontextprotocol/inspector node src/index.js
```

## Common errors

| Symptom | Fix |
|---|---|
| `Authentication failed (401)` | Check `I18N_API_KEY` in the MCP client config and whether the key is enabled |
| `Cannot connect to ...` | Check the network and that `I18N_BASE_URL` is reachable |
| `Resource not found (404)` | The profile name passed to `get_profile` / `preview_replace` does not exist |

## 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.

```bash
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)
```