mdn-translation-ja-mcp

✨ 概要

このツールは、MDN 翻訳作業を支援・自動化することを目的としています。
Cursor から利用し、翻訳の開始・同期・レビューを支援します。

MDN の本文はリポジトリに含めません。手元では mdn/content および mdn/translated-content を GitHub 上で fork し、その fork を clone して参照する想定です。

🎯 目的

• 翻訳開始（原文コピー）の自動化。
• 原文との同期（sourceCommit）の管理。
• glossary マクロの補助。
• ガイドラインに基づくレビュー。

🧱 アーキテクチャ

Cursor
  ↓
MCP Server（stdio または Streamable HTTP）
  ↓
ローカルFS + Git + Skills / shared/data

📦 前提環境

以下の構成が必要です：

.
├── content
├── translated-content
└── mdn-translation-ja-mcp

必須リポジトリ（fork → clone）

翻訳作業で参照する英語原文・日本語訳は、上流の次のリポジトリを自分の GitHub アカウントへ fork してから、手元へ clone します。

• 上流（fork 元）: mdn/content
• 上流（fork 元）: mdn/translated-content

親ディレクトリで、fork したリポジトリを次のように clone します（クローン先ディレクトリ名は任意ですが、content / translated-content とすると後述のディレクトリツリーと一致します）。

mkdir -p mdn-work && cd mdn-work
git clone https://github.com/<あなたのGitHubユーザー名>/content.git # fork した content をclone
git clone https://github.com/<あなたのGitHubユーザー名>/translated-content.git # fork した translated-content をclone
git clone https://github.com/gurezo/mdn-translation-ja-mcp.git

<あなたのGitHubユーザー名> は、fork 先のアカウント名に読み替えてください（上記は mdn/content / mdn/translated-content の fork を clone する例です）。

ランタイム

• Node.js 22 以上（LTS 推奨）
• Cursor（MCP の stdio または Streamable HTTP に対応した版）。HTTP 必須ではありません。

translated-content リポジトリ側で行うこと

翻訳作業では translated-content だけを Cursor のワークスペースとして開くことが多く、この場合の MCP 接続は次のとおりです。

前提: content・translated-content・mdn-translation-ja-mcp の 3 リポジトリを同じ親ディレクトリに並べること（上記ディレクトリツリー）を推奨します。別の場所に置いている場合も、下記 mcp.json の env に両方のルートを絶対パスで書く形は同じです。

1. translated-content リポジトリのルートに、ディレクトリ .cursor を作成します。
2. translated-content/.cursor/mcp.json を、次の 実装例どおりに作成します（ワークスペースのルートが translated-content のとき、このパスに置きます）。
   examples/translated-content-cursor-mcp-example.json は 同一内容のファイルです。コピーしてからパスだけ差し替えても構いません。

{
  "mcpServers": {
    "mdn-translation-ja": {
      "command": "node",
      "args": ["/Users/translator/work/mdn-translation-ja-mcp/dist/index.js"],
      "env": {
        "MDN_CONTENT_ROOT": "/Users/translator/work/content",
        "MDN_TRANSLATED_CONTENT_ROOT": "/Users/translator/work/translated-content"
      }
    }
  }
}

3. 上記の /absolute/path/to/... は、次を指す 実環境でのフルパス（絶対パス） に置き換えます。
   • args[0] — mdn-translation-ja-mcp/dist/index.js の絶対パス（先に「mdn-translation-ja-mcp 側」で npm run build 済みであること）
   • MDN_CONTENT_ROOT — 英語原文リポジトリ（mdn/content）のルート
   • MDN_TRANSLATED_CONTENT_ROOT — 日本語訳リポジトリ（mdn/translated-content）のルート

同一親フォルダに 3 リポジトリを並べる場合も、args と env は 必ず絶対パスで記載してください（プレースホルダのままにしないでください）。

4. （推奨）一括セットアップ — mdn-translation-ja-mcp でビルド済みなら、次で mcp.json と Rules を自動生成できます。

cd mdn-translation-ja-mcp
npm run build
npm run setup:translated-content-cursor
# translated-content のパスが兄弟でない場合:
# node scripts/setup-translated-content-cursor.mjs /path/to/translated-content

手動で置く場合は examples/translated-content-cursor-rules/01-mdn-mcp-tools.mdc を translated-content/.cursor/rules/ にコピー。

5. Cursor をリロード — mcp.json 追加・変更後はウィンドウの再読み込みが必要です。

6. MCP 接続確認 — Cursor の Settings → MCP でサーバー mdn-translation-ja が有効でエラーなく接続されていること。

7. （任意）Skills — 「translated-content で翻訳する場合（任意）」 を参照。

注意（翻訳のコミット・PR）: translated-content/.cursor/ は 手元の Cursor 用のローカル設定です。翻訳作業のコミットや mdn/translated-content へのプルリクエストの差分に含めないでください（絶対パスが入るため、リポジトリにコミットする想定ではありません）。誤ってステージしないよう、必要なら手元の translated-content で .gitignore に .cursor/ を追加してください。

mdn-translation-ja-mcp リポジトリ側で行うこと

MCP サーバーとして使うには、少なくとも次を実行します。

cd mdn-translation-ja-mcp   # clone 済みのディレクトリへ

npm install
npm run build   # dist/index.js / dist/http.js が生成される

ビルド後、stdio の動作確認に npm start または Streamable HTTP に npm run start:http を使えます。

重要: チャットのエージェントが mdn_trans_review を実行するために npm start を手動で走らせる必要はありません。エージェントは Cursor が mcp.json 経由で起動した MCP サーバーのツールを使います。npm start はターミナルでのサーバー単体確認用です。

初めて本リポジトリだけ取得する場合の例:

git clone https://github.com/gurezo/mdn-translation-ja-mcp
cd mdn-translation-ja-mcp
npm install
npm run build
npm start
# または: npm run start:http

📚 API ドキュメント（TypeDoc）

TypeScript API リファレンスを TypeDoc で生成できます（出力先は docs/）。

# 生成済みドキュメントの削除
npm run docs:clean

# API ドキュメント生成
npm run docs:build

# GitHub Pages へ公開（gh-pages ブランチ）
npm run docs:publish

🔗 MCP ツール名の対応

本サーバーが提供する MCP ツール名（Cursor のツール一覧に表示される名前）と主な用途です。
先頭に / は付きません（MCP の登録名は mdn_trans_start のようなスネークケースです）。

翻訳フロー（最短）

一例として、翻訳開始 → 原文コミット同期 → glossary → レビューの順で使えます。

1. 翻訳開始 — 対象の MDN URL を伝え、mdn_trans_start で ja の index.md を用意します。
2. 英語原文との同期 — mdn_trans_commit_get で content の該当ファイルに対する最新コミットを取得し、翻訳ファイルのフロントマターに l10n.sourceCommit を書き込みます。
3. 用語 {{glossary}} — mdn_trans_replace_glossary で、指定した翻訳ファイル内の {{glossary("id")}} を用語データに基づき {{glossary("id", "表示名")}} に置換します。
4. レビュー — mdn_trans_review で .agents/skills 由来のガイドライン機械チェック（表記・文体・l10n メタデータ・glossary マクロ等）を行います（サーバーは対象ファイルを変更しません。意訳の自然さなど未自動の項目は人手確認。エージェントはレビュー結果だけを理由にそのファイルを編集しないよう注意してください）。

MCP ツール名	主な用途
mdn_trans_start	URL を指定し、content の files/en-us/<category>/<slug...>/index.md を translated-content の files/ja/<category>/<slug...>/index.md にコピーするだけ（翻訳・_redirects.txt・他ファイルの修正はしない。URL 側の /docs/ はファイルパスには現れない）
mdn_trans_commit_get	content の git 履歴からコミットハッシュを取得し、l10n.sourceCommit を翻訳ファイルに反映する
mdn_trans_replace_glossary	指定ファイル内の 1 引数 {{glossary}} を第 2 引数付きに置換する
mdn_trans_review	翻訳ファイルのガイドライン機械レビュー（4 スキル分のルール）。読み取りのみ（対象 index.md には書き込まない）

mdn_trans_replace_glossary と mdn_trans_review には、translated-content 内のファイルパスを渡してください（絶対パス、または files/ja/ からの相対パス）。MCP はエディタの「開いているファイル」を知らないため、エージェントがパスを明示する想定です。

🗂️ パスの解決順

各ツールのワークスペース解決で共通です。
環境変数の要否は「translated-content リポジトリ側」の mcp.json（MDN_CONTENT_ROOT / MDN_TRANSLATED_CONTENT_ROOT の指定）と同じ前提です。

1. 環境変数（任意） —
   MDN_CONTENT_ROOT と MDN_TRANSLATED_CONTENT_ROOT を両方指定すると、その絶対パスをそのまま使います。
   片方だけは不可（誤設定防止のためエラー）。
2. 兄弟ディレクトリ — どちらの環境変数も未設定のとき、
   プロセスのカレントディレクトリ（通常は本リポジトリのルート）のひとつ上のディレクトリを親とみなし、
   そこにある content と translated-content を参照します。

リポジトリ実体 — 解決した content 相当のルートには files/en-us が、
translated-content 相当のルートには files/ja がそれぞれディレクトリとして存在する必要があります（上流を fork して clone した状態で、リポジトリ一式が揃っていること）。
名前だけの空フォルダではエラーになります。

環境変数の MCP 設定例は
examples/translated-content-cursor-mcp-example.json を参照してください。

📋 MCP ツールの応答

本サーバーは stdio（npm start → dist/index.js）または
Streamable HTTP（npm run start:http → dist/http.js）のいずれかで起動します。
各ツールの結果は MCP の text コンテンツとして返ります（人間が読める説明文）。

想定外のエラー（パス解決失敗、ファイル未存在、Git 取得失敗など）は ツール実装が例外を投げ、クライアント側でツール呼び出しエラーとして扱われることがあります。

💬 Cursor での利用例（エージェント）

MCP を有効にしたうえで、チャットで対象ページの MDN URL を伝え、主に次のツールをエージェントに実行させます。

• 「https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API を翻訳開始して」→ mdn_trans_start。
• 「この URL の英語原文の最新コミットを sourceCommit に反映して」→ mdn_trans_commit_get。
• 「この index.md の {{glossary}} に第2引数を付けて」→ mdn_trans_replace_glossary（対象ファイルパスを指定）。
• 「この翻訳をルールでざっと確認して」→ mdn_trans_review（対象ファイルパスを指定。レビュー結果を理由にそのファイルを自動編集しない）。

translated-content を Cursor で開いて作業する場合

（MCP の設定は translated-content/.cursor/mcp.json。手順と「翻訳 PR に mcp.json を含めない」旨の注意は「translated-content リポジトリ側で行うこと」を参照してください。）

翻訳作業では translated-content リポジトリだけをワークスペースとして開く運用がよくあります。上記のとおり mcp.json で env を指定していれば、ツールが content を参照する際のパスは一貫します（解決の詳細は「パスの解決順」）。

• 親ディレクトリに content と translated-content が並んでいる（上記「前提環境」のディレクトリツリーと同じ）。
• Cursor で フォルダとして開いているルートが translated-content（例: .../mdn-work/translated-content）。

このとき、エージェントに ツール名と引数が分かるよう、チャットへそのまま貼れる例は次のとおりです（Glossary/Symbol を例にしています。別ページでは URL と files/ja/... を読み替えてください）。

mdn_trans_start で翻訳用ファイルを用意して。
url: https://developer.mozilla.org/en-US/docs/Glossary/Symbol

mdn_trans_commit_get を実行して。
url: https://developer.mozilla.org/en-US/docs/Glossary/Symbol

mdn_trans_replace_glossary を実行して。
jaFile: files/ja/glossary/symbol/index.md

MCP ツール mdn_trans_review を実行して。レビュー結果だけ報告し、files/ja/glossary/symbol/index.md は編集・保存しないで。
jaFile: files/ja/glossary/symbol/index.md

重要: mdn_trans_* は MCP ツール名であり、ターミナルのシェルコマンドではありません。エージェントは Cursor の MCP サーバー mdn-translation-ja から呼び出してください。

パス指定のコツ: MCP はエディタの「開いているファイル」を自動では知らないため、files/ja/... からの相対パス（ワークスペースが translated-content のとき）か、index.md の絶対パスのどちらかを必ず含めます。
親ディレクトリ構成が異なる場合は、MCP 設定の env に MDN_CONTENT_ROOT と MDN_TRANSLATED_CONTENT_ROOT を両方指定してください（examples/translated-content-cursor-mcp-example.json）。

人手レビューでは、本リポジトリの .agents/skills/（表記 / L10N / 用語集 / 文体）を参照してください。

🤖 Cursor AI 設定（Skills / Rules）

本リポジトリには、MDN 日本語翻訳向けの Cursor Agent Skills と Rules が含まれます。

mdn-translation-ja-mcp/
├── .agents/skills/          # mozilla-japan 翻訳ガイドライン（外部ドメイン知識）
│   ├── editorial-guideline/
│   ├── l10n-guideline/
│   ├── mozilla-l10n-glossary/
│   └── japanese-style/
├── .cursor/
│   ├── rules/               # 常時適用の基本制約・MCP 呼び出し制約
│   │   ├── 00-mdn-translation.mdc
│   │   └── 01-mdn-mcp-tools.mdc
│   └── skills/              # MCP 翻訳ワークフロー
│       └── mdn-translation-workflow/
└── examples/
    ├── translated-content-cursor-mcp-example.json
    └── translated-content-cursor-rules/   # translated-content へコピーする Rules 例

translated-content で翻訳する場合（任意）

翻訳作業では translated-content をワークスペースとして開くことが多いです。Skills / Rules を使う場合は、次のいずれかで展開します。

# 例: symlink（mdn-translation-ja-mcp と translated-content が兄弟ディレクトリの場合）
ln -s ../mdn-translation-ja-mcp/.agents translated-content/.agents
ln -s ../mdn-translation-ja-mcp/.cursor/skills translated-content/.cursor/skills

mkdir -p translated-content/.cursor/rules
cp ../mdn-translation-ja-mcp/examples/translated-content-cursor-rules/01-mdn-mcp-tools.mdc translated-content/.cursor/rules/
# または mdn-translation-ja-mcp の .cursor/rules/*.mdc をまとめてコピー

MCP 接続は translated-content/.cursor/mcp.json に設定します（翻訳 PR に含めないでください）。rules-from-mcp のような別名ディレクトリでは Cursor が Rules を読み込めません。 必ず translated-content/.cursor/rules/ に置いてください。

🛠️ トラブルシュート

症状	確認すること
HTTP で Cursor が MCP に接続できない	npm run start:http が起動しているか<br>Cursor の MCP 設定の url（ホスト・ポート・パス /mcp）が<br>一致しているか。
MCP が起動しない / Cannot find module	npm run build 済みか。<br>stdio のときは args のパスが dist/index.js の絶対パスか。
dist/index.js が無い	リポジトリルートで npm install と npm run build。
ワークスペースが解決できない	MDN_CONTENT_ROOT と MDN_TRANSLATED_CONTENT_ROOT は<br>両方セットするか、両方未設定にする。
content / translated-content が見つからない	親ディレクトリに content と translated-content があるか。<br>または上記環境変数で正しい絶対パスを指定。
mdn_trans_commit_get が git 関連で失敗する	content が fork した mdn/content を clone したリポジトリか、対象ファイルが追跡されているか。
Node のバージョンエラー	package.json の engines は node >= 22。
mdn_trans_review がシェルで見つからない	npm start では解決しない（エージェント用ではない）。<br>ワークスペースが translated-content か、translated-content/.cursor/mcp.json があるか。<br>npm run setup:translated-content-cursor 後に Cursor をリロードしたか。<br>Settings → MCP で mdn-translation-ja が接続済みか。<br>フォールバック: mdn-translation-ja-mcp で npm run mdn:trans:review -- --jaFile=files/ja/.../index.md

🔐 ライセンスと第三者表記

• 本リポジトリのソースコード: MIT License。
• MDN 本文・翻訳データ・外部サイトの扱い: THIRD_PARTY.md。

⚠️ 注意

• MDN コンテンツは含まれません。
• content / translated-content は上流を fork したうえで、別途 clone が必要です。
• MDN のライセンスに従って利用してください。