mdn-translation-ja-mcp

概要

このリポジトリは、MDN 日本語翻訳を支援する MCP サーバーです。
MCP クライアント（Cursor / Claude / VS Code など）からサーバーを登録するだけで、翻訳の開始・同期・レビューとガイドライン参照ができます。Cursor Rules / Skills は必須ではありません。

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

利用者向けの詳細は https://gurezo.net/mdn-translation-ja-mcp/ の次のページです。

• Architecture
• Getting Started
• MCP Tools
• MCP Resources
• MCP Prompts
• Translation Workflow
• Client Integration
• Agent Skills

公開先はこの URL だけです。移行前の https://gurezo.github.io/mdn-translation-ja-mcp/ は非公開です。リダイレクトは無く、再公開しません。

目的

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

アーキテクチャ

MCP Client（Cursor / Claude / VS Code / other）
    │  stdio または Streamable HTTP
    ▼
mdn-translation-ja-mcp
├─ Tools
├─ Resources
├─ Prompts
└─ content + translated-content

integrations/cursor/   … optional UX

設計の詳細は architecture/mcp-native.md を参照してください。

最小セットアップ

前提リポジトリ（fork → clone）

同じ親ディレクトリに次を並べます（ディレクトリ名は任意ですが、この名前だと後述の兄弟ディレクトリ解決と一致します）。

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

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

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

ランタイム

• Node.js 24 以上（LTS 推奨）
• MCP クライアント（stdio または Streamable HTTP）。HTTP 必須ではありません。Cursor Rules / Skills は任意です。

サーバーのビルド

cd mdn-translation-ja-mcp
npm install
npm run build

dist/index.js（stdio）と dist/http.js（Streamable HTTP）が生成されます。チャットのエージェントのために npm start を手動で走らせる必要はありません。クライアントが MCP 設定経由でサーバーを起動します。npm start / npm run start:http は単体確認用です。

サーバー登録

どのクライアントでも次を渡します。パスは 絶対パス に置き換えてください。

• command: node
• args: /absolute/path/to/mdn-translation-ja-mcp/dist/index.js
• env.MDN_CONTENT_ROOT: content のルート
• env.MDN_TRANSLATED_CONTENT_ROOT: translated-content のルート

設定ファイルの例は examples/README.md です。

• MCP 共通: examples/mcp/README.md（Claude Code / VS Code / Inspector）
• Cursor: examples/cursor/mcp.example.json

クライアント別の置き場は Client Integration を参照してください。

content / translated-content のパス解決

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

解決した content 相当のルートには files/en-us が、translated-content 相当のルートには files/ja がディレクトリとして存在する必要があります。名前だけの空フォルダではエラーになります。

MCP Tools

先頭に / は付きません（登録名は mdn_trans_start のようなスネークケースです）。シェルコマンドではありません。

url は https://developer.mozilla.org/en-US/docs/... 形式です。URL 側の /docs/ はファイルパスに現れません。

jaFile は translated-content 内の絶対パス、または files/ja/ からの相対パスです。MCP はエディタの「開いているファイル」を知りません。

詳細は MCP Tools です。

MCP Resources

人手翻訳ではガイドラインを Resource から読んでください。.agents/skills のコピーは不要です。

詳細は MCP Resources です。

MCP Prompts

標準手順は Prompt です。サーバー内では LLM を実行しません。

詳細は MCP Prompts です。

翻訳フロー

一例として、Prompt mdn_translate は次の順で Tools / Resources を使います。

1. mdn_trans_start — ja の index.md を用意する
2. mdn_trans_commit_get — l10n.sourceCommit を書き込む
3. Resources — ガイドラインを読む
4. クライアント LLM — 本文を翻訳する
5. mdn_trans_replace_glossary — {{glossary}} 第 2 引数を補完する
6. mdn_trans_review — 機械チェックする（対象ファイルは変更しない）

既存訳の同期は mdn_sync、レビューだけなら mdn_review です。手順の全体は Translation Workflow です。

Cursor integration（optional）

Cursor で必要なのは MCP 接続設定だけです。Rules / Skills は任意です。

• 手動: examples/cursor/mcp.example.json を translated-content/.cursor/mcp.json にコピーし、絶対パスを書き換える
• 一括: npm run setup:translated-content-cursor（既定は mcp.json のみ。薄い Rule は --with-rules）

cd mdn-translation-ja-mcp
npm run build
npm run setup:translated-content-cursor

translated-content/.cursor/ は手元のローカル設定です。翻訳 PR に含めないでください。

入れると便利な点（エージェントがツール名をシェルと誤認しにくくなる等）は integrations/cursor/README.md にまとめています。

他 MCP クライアント

Cursor 以外では examples/mcp/README.md の JSON を使います。MCP Inspector なら .cursor は不要です。

npm run build
npm run inspect

検証結果は architecture/client-verification.md を参照してください。

ツールの応答

本サーバーは stdio（npm start → dist/index.js）または Streamable HTTP（npm run start:http → dist/http.js）で起動します。各ツールの結果は MCP の text コンテンツとして返ります。想定外のエラーはクライアント側でツール呼び出しエラーとして扱われることがあります。

API ドキュメント（TypeDoc）

TypeScript API リファレンスと上記の利用者向けページを TypeDoc で生成します（出力先は docs/）。公開先は https://gurezo.net/mdn-translation-ja-mcp/ だけです。

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

# ドキュメント生成（docs/ を再生成）
npm run docs:build

# 必須ファイルの確認
npm run docs:verify

# docs:publish は docs:build と同じ（ローカルで docs/ を更新する。リモートへは送らない）
npm run docs:publish

公開の主体は gurezo/portal です。このリポジトリから Firebase Hosting へはデプロイしません。

ドキュメントを更新するときは、portal の scripts/mdn-translation-ja-mcp.sha を 40 文字のコミット SHA に差し替え、portal の main へマージします。ブランチ名は書きません。生成と配置の詳細は architecture/docs-supply.md と portal の README です。

本番で問題が起きたときの戻しは、Firebase コンソールの Hosting でサイト gurezo-portal を開き、Release history から以前のリリースへ戻します。hosting:clone は、プレビューチャネルの現行リリースを live へコピーする用途です。過去リリースの選択には使いません。戻しは Angular サイトと、取り込んでいる静的ドキュメント一式を含むサイト全体の差し替えです。

検証結果と、旧 GitHub Pages を再公開しない方針は architecture/docs-migration-validation.md です。

トラブルシュート

ライセンスと第三者表記

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

注意

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