i18n-codelens-mcp

i18n-codelens-mcp

i18n 翻訳ファイル用の Model Context Protocol（MCP）サーバーです。AI エージェント（Claude Code、Cursor、Antigravity、GitHub Copilot、Codex、Gemini CLI、その他の MCP クライアント）が、ロケールファイル全体をモデルコンテキストに読み込むことなく、ロケール JSON ファイルを調査、監査し、安全に編集できます。

• コンパクトな設計。 10 個のツール、1 行の JSON 結果、入力のエコーなし、どこでも limit／includeValues を使用できます。一般的な読み取りで消費するトークン数は 50～200 です。
• 設計による安全性。 ロケールファイルのキーセットを減らす書き込み方法はありません。フラット形式とネスト形式が混在するファイルは形式を変換せず、そのまま編集されます。アップサートでは上書きせず、競合を報告します。
• 最新の MCP。 TypeScript SDK v2 を基盤としており、プロトコルリビジョン 2026-07-28 および 2025 年のリビジョン、サーバー指示、プロンプト（スラッシュコマンド）、キャッシュヒント、破壊的なツールに対するエリシテーションベースの確認に対応しています。
• あらゆるレイアウトに対応。 locales/en.json、locales/en-US.json、messages.en.json、i18next 形式の locales/en/common.json（名前空間ファイル。キーは common:nav.home）に対応します。

このパッケージは、i18n CodeLens VS Code extension の MCP バックエンドでもあります。

要件

• Node.js 20 以降
• JSON ファイル形式のロケールリソース
• stdio サーバーに対応した MCP クライアント

インストール

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

クライアントの設定

以下の各コマンドはすべて、npx -y i18n-codelens-mcp を実行する i18n-codelens という名前の stdio サーバーを登録します。クライアントを選び、1 行のコマンドを実行すれば完了です。

サーバーには、作業対象のプロジェクトを知らせる必要があります。ほとんどのクライアントはプロジェクトディレクトリでサーバーを起動し、Claude Code はプロジェクトルートを明示的に渡すため、それ以外の設定は不要です。クライアントが別の場所からサーバーを起動する場合は、たとえば -e WORKSPACE_ROOT=/absolute/path/to/project のように、クライアントの env フラグを使ってプロジェクトパスを追加してください。

Windows PowerShell： PowerShell が CLI に渡る前に単独の -- を取り除いてしまい、unknown option '-y' と表示されることがあります。その場合は区切り文字を '--' と引用符で囲むか、cmd、Git Bash、または 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 は stdio サーバーに CLAUDE_PROJECT_DIR を設定するため、サーバーは常に適切なプロジェクトを見つけられます。ツール検索機能では MCP ツールの読み込みが遅延されますが、i18n_upsert_translations と i18n_get_translations には anthropic/alwaysLoad が指定されているため、日常的に使う 2 つのツールは検索なしで利用できます。プロンプトは /i18n-codelens:audit、/i18n-codelens:add-key、/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、agy mcp remove i18n-codelens で管理できます。IDE 内では /mcp を実行すると MCP マネージャーが開きます。

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

代わりに -s project を使うと、プロジェクトの設定に書き込めます。Gemini ではコマンドと引数を位置指定で渡すため、-- は不要です。

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 と Copilot Chat

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

これによりユーザープロファイルに書き込まれます。コマンドパレットの MCP: サーバーの追加 からもガイド付きの手順で同じ設定を行え、ワークスペースを対象にすることもできます。

{
  "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
    }
  }
}

Copilot CLI では、シェルからではなく、セッション内でサーバーを追加します。copilot を起動してから、次のように実行します。

/mcp add

フォームに Server Name i18n-codelens、Server Type STDIO、Command npx -y i18n-codelens-mcp を入力します。以降は /mcp、/mcp show i18n-codelens、/mcp delete i18n-codelens で管理できます。

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

Cursor、Windsurf、Claude Desktop、Kiro、Cline、Roo Code

これらのクライアントにはサーバーを追加するコマンドがないため、設定ファイルを使います。形式はどのクライアントでも同じで、パスだけが異なります。

{
  "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": []
    }
  }
}

チームでの共有

プロジェクトレベルの設定をコミットすると、グローバル設定を変更しなくても、すべてのチームメンバーとエージェントが同じサーバーを利用できます。

ワークスペースのルート

解決順序：

1. ツールごとの workspaceDir 引数（設定済みのルート内である必要があります。下記を参照）
2. CLI の --workspaceRoot <path> / --workspace-root <path>
3. WORKSPACE_ROOT
4. CLAUDE_PROJECT_DIR（Claude Code が設定）
5. 現在の作業ディレクトリ
6. サーバーパッケージのディレクトリ

workspaceDir ツール引数で選択できるのは、設定済みのルートのサブディレクトリだけです。サーバーを I18N_ALLOW_ANY_WORKSPACE=1 を指定して起動しない限り、モデルがサーバーにディスク上の別のディレクトリを指定することはできません。

設定

ツール

すべての結果は、1 行にまとめたコンパクトな JSON です。空のセクションは省略され、パスはワークスペース相対のスラッシュ区切りで、すべてのリストに limit（デフォルトは 50）が適用されます。エラーは isError のテキストとして返され、メッセージには修正方法が含まれます（たとえば、利用可能なロケールの一覧）。

破壊的なツールの確認

i18n_delete_keys、i18n_rename_key、i18n_format_resources はデフォルトでプレビューします。モデルが dryRun を省略し、クライアントが MCP のエリシテーションに対応している場合（Claude Code は対応しています）、サーバーは変更内容を説明する質問を 1 つだけ含むダイアログをユーザーに表示し、承認された場合に適用します。ダイアログなしで適用するには dryRun:false、プレビューのみを行うには dryRun:true を渡します。i18n_upsert_translations はキーを削除せず、異なる値の上書きも overwrite:true がない限り拒否するため、確認は不要です。

プロンプト

サーバーは、クライアントがコマンドとして公開する 3 つのプロンプトを提供します：audit（完全な監査と修正案）、add-key <key> [text]（すべてのロケール向けの文言を付けてキーを 1 つ追加）、translate-missing [locale]（不足している翻訳をバッチ処理で補完）。

指示

接続時に、サーバーは使用方法の指示（2 KB 未満）を送信します。Claude Code などのクライアントはこれをシステムプロンプトに追加します。ロケールファイルを直接編集しないこと、i18n_project_info を一度呼び出すこと、1 回の呼び出しですべてのロケールを指定して upsert することなどが含まれます。キーの命名規則、文体、プレースホルダーのスタイルなど、プロジェクト固有のルールは引き続き独自の CLAUDE.md / AGENTS.md に記載してください。

名前空間付きレイアウト

ロケールファイルがロケールごとのディレクトリ（locales/en/common.json、locales/tr/auth.json）にある場合、ディレクトリがロケール、ファイルが名前空間になります。キーは namespace:key（common:nav.home）として指定します。i18n_project_info は keyFormat: "namespace:key" と名前空間を報告します。i18n ライブラリで別の区切り文字を使う場合は I18N_NS_SEPARATOR を、区切り文字なしで記述されたキーに使用するデフォルトの名前空間には I18N_DEFAULT_NS を設定してください。

ロケールタグではない名前のファイル（config.json）は警告を出してスキップされます。また、グロブが同じロケールに複数回一致する場合（src/locales/en.json と public/locales/en.json）、最初のものが使われ、i18n_project_info は I18N_GLOB を絞り込むよう警告します。

構造とキーの安全性

ロケールファイルは、葉の格納方法によって フラット（"nav.home": "Home"）、ネスト（オブジェクト）、または 混在 に分類されます。I18N_STRUCTURE=auto の場合、フラットなファイルはフラットに、ネストされたファイルはネストされた形式で書き込まれ、混在ファイルは決して変換されません。すべてのキーはそのままの場所に保持され、新しいキーはファイル内で優勢な形式で書き込まれます。書き込み時にはファイルのインデント、改行コード、末尾の改行が保持されるため、キーを1つ変更した場合の差分は1行だけです。

構造上、キーの消失を不可能にするガードが2つあります。

• unflattenObject は、値と名前空間が衝突する場合（dashboard.announcement が文字列であると同時に親キーでもある場合）、一方を上書きするのではなくエラーをスローします。
• すべての書き込みでは、新しいドキュメントをディスク上のファイルと比較し、キーが消失する場合は書き込みを拒否します。削除と名前変更では、削除対象を明示します。それ以外の理由でキーが消失した場合は、書き込みを中止して該当するキーを示します。

src/__tests__/tools-write.test.ts と resource-manager.test.ts の回帰テストスイートでは、この仕組みのきっかけとなった事例（3,000キーを含む混在ファイル、名前空間でもある葉）を再現し、すべての書き込み経路で損失がゼロであることと、差分が1行だけであることを検証します。

1.x からの移行

2.0では18個のツールを10個に統合し、デフォルト設定を2つ変更しています。

その他の変更：Node 20 以降、@modelcontextprotocol/sdk は @modelcontextprotocol/server 2.0 に置き換え（2026-07-28 および2025年のプロトコル改訂版の両方に対応）、デフォルトの無視グロブで一般的なビルド出力をスキップ、workspaceDir は設定済みのルート内に限定、パスは posix 形式、コード正規表現は ns:key を受け入れ、ファイルの先頭にある呼び出しにも一致します。

1.x の名前を使用していたプロジェクト向けの、推奨するエージェント指示ブロック：

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 には mcpName: io.github.hepter/i18n-codelens-mcp が含まれ、server.json はパッケージの内容を記述します。次のコマンドで公開します：

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

プログラム 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);

すべてのツールは、(args, ctx) を受け取る通常の非同期関数としてエクスポートされています。あわせて、各構成要素もエクスポートされています：loadProject（キャッシュ済み、名前空間対応）、getCodeIndex（キャッシュ済みのコードスキャン）、createResourceManager（キー消失ガード付きの書き込み状態）、writeFilePretty、flattenObject、unflattenObject、classifyResourceStructure。

変更履歴

2.0.0

• SDK v2／プロトコル 2026-07-28。 @modelcontextprotocol/server と serveStdio、zod 4、Node 20+ を使用します。2026-07-28 版と 2025 版の両方を stdio で提供します。tools/list と prompts/list にはキャッシュヒントが付与されます。
• ツールを18個から10個に削減し、結果をコンパクトな1行にまとめました。structuredContent と引数のエコーはありません。ツール定義は13.5 K文字から9.5 K文字に縮小しました。同じプロジェクトで1.xと比較したところ、約7,600個のキーを持つ2ロケールのコードベースで、50件に一致するキー検索は12.5 K文字から2.3 K文字に、完全な監査は6.7 K文字・1.0秒から2.0 K文字・0.4秒に減少しました。
• Upsert のセマンティクス。 即座に書き込みます。ファイルに触れる前にバッチ全体を検証し（不明なロケールがある場合はすべて拒否）、overwrite:true が指定されていない限り上書きせずに競合を報告します。値がないロケールや、他のロケールにある値とのプレースホルダーの不一致について警告します。
• 確認ダイアログ。 削除、名前変更、フォーマットでは、クライアントが対応している場合は MCP のエリシテーションを使用し、それ以外の場合はヒント付きのプレビューにフォールバックします。
• サーバーの指示とプロンプト（audit、add-key、translate-missing）、サーバーメタデータ（websiteUrl、description）、package.json から読み取るバージョン。
• 名前空間付きレイアウト（{locale}/{namespace}.json、キーは ns:key）、ファイル名またはディレクトリ名からのロケール検出、重複ファイルとロケール以外のファイルに関する警告。
• キャッシュ。 更新日時／サイズが変わらない限り、解析済みのロケールファイルとコードスキャン結果を再利用します。監査時のコードスキャンは1回です。ファイルの読み込み前に .gitignore と一般的なビルドディレクトリを除外します。
• 修正。 コードの正規表現の文字範囲（.-_ が誤って :…^ にまたがっていた問題）とファイル先頭での一致、Windows での posix パス、CLAUDE_PROJECT_DIR の尊重、workspaceDir をルート内に制限、書き込み時のインデントと CRLF の維持、getWorkspaceRoot が呼び出しごとにログを出さないように修正しました。

1.1.0

データ損失の不具合を修正しました。単一の upsert により、値と名前空間の両方として使われている名前のキーが削除される混在ファイルに変換されることがありました。混在ファイルは変換されなくなり、unflattenObject／setNestedValue は衝突時に例外をスローし、すべての書き込みでキーの損失を防止します。

ライセンス

MIT © Mustafa Kuru