mdn-translation-ja-mcp
This MCP server automates and supports MDN Japanese translation tasks: starting a translation from the original content, syncing source commits, completing glossary macros, and running guideline-based mechanical reviews.
mdn_trans_start: copies an English
index.mdfromcontentto the correspondingtranslated-contentpath for a given MDN URL; can overwrite an existing file, and does not translate or edit other files.mdn_trans_commit_get: fetches the latest commit hash for the source page from the
contentrepo and writes it asl10n.sourceCommitin the translation file's frontmatter.mdn_trans_replace_glossary: replaces
{{glossary("id")}}macros in a Japanese file with the second display argument using glossary data.mdn_trans_review: runs a read-only mechanical review of a Japanese translation file against editorial, l10n, Japanese style, glossary, and prohibited-expression rules, returning findings without modifying the file.
The server also provides MCP Resources (guidelines, glossary terms, review rules, prohibited expressions) and MCP Prompts (
mdn_translate,mdn_sync,mdn_review) that orchestrate the standard translation, sync, and review workflows.
Provides tools for interacting with Git repositories, such as retrieving commit hashes from the mdn/content repository to synchronize translations.
Integrates with GitHub by allowing users to fork and clone the mdn/content and mdn/translated-content repositories, enabling collaborative translation workflows.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mdn-translation-ja-mcp Copy Web/API/Window/focus from en to ja"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
概要
このリポジトリは、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/ の次のページです。
公開先はこの URL だけです。移行前の https://gurezo.github.io/mdn-translation-ja-mcp/ は非公開です。リダイレクトは無く、再公開しません。
Related MCP server: Note Post 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-mcpmkdir -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 builddist/index.js(stdio)と dist/http.js(Streamable HTTP)が生成されます。チャットのエージェントのために npm start を手動で走らせる必要はありません。クライアントが MCP 設定経由でサーバーを起動します。npm start / npm run start:http は単体確認用です。
サーバー登録
どのクライアントでも次を渡します。パスは 絶対パス に置き換えてください。
command:nodeargs:/absolute/path/to/mdn-translation-ja-mcp/dist/index.jsenv.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 のパス解決
環境変数(任意) —
MDN_CONTENT_ROOTとMDN_TRANSLATED_CONTENT_ROOTを両方指定すると、その絶対パスを使います。片方だけは不可です。兄弟ディレクトリ — どちらも未設定のとき、プロセスのカレントディレクトリのひとつ上を親とみなし、そこにある
contentとtranslated-contentを参照します。
解決した content 相当のルートには files/en-us が、translated-content 相当のルートには files/ja がディレクトリとして存在する必要があります。名前だけの空フォルダではエラーになります。
MCP Tools
先頭に / は付きません(登録名は mdn_trans_start のようなスネークケースです)。シェルコマンドではありません。
MCP ツール名 | 主な引数 | 用途 |
|
|
|
|
| content の git 履歴からコミットハッシュを取得し、 |
|
| 1 引数 |
|
| ガイドライン機械レビュー( |
url は https://developer.mozilla.org/en-US/docs/... 形式です。URL 側の /docs/ はファイルパスに現れません。
jaFile は translated-content 内の絶対パス、または files/ja/ からの相対パスです。MCP はエディタの「開いているファイル」を知りません。
詳細は MCP Tools です。
MCP Resources
人手翻訳ではガイドラインを Resource から読んでください。.agents/skills のコピーは不要です。
URI | 内容 |
| 表記ガイドライン |
| L10N ガイドライン |
| 文体ルール |
| 用語抜粋と Wiki 参照手順 |
| 機械用 glossary( |
| 機械チェックルール( |
| 禁止・注意表現 |
詳細は MCP Resources です。
MCP Prompts
標準手順は Prompt です。サーバー内では LLM を実行しません。
Prompt | 引数 | 用途 |
|
| 翻訳開始からレビューまでの標準フロー |
|
| 既存訳の |
|
| 機械レビューと人手確認項目 |
詳細は MCP Prompts です。
翻訳フロー
一例として、Prompt mdn_translate は次の順で Tools / Resources を使います。
mdn_trans_start—jaのindex.mdを用意するmdn_trans_commit_get—l10n.sourceCommitを書き込むResources — ガイドラインを読む
クライアント LLM — 本文を翻訳する
mdn_trans_replace_glossary—{{glossary}}第 2 引数を補完する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-cursortranslated-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 です。
トラブルシュート
症状 | 確認すること |
HTTP で MCP に接続できない |
|
MCP が起動しない / |
|
| リポジトリルートで |
ワークスペースが解決できない |
|
| 親ディレクトリに両方があるか。または上記環境変数で正しい絶対パスを指定。 |
|
|
Node のバージョンエラー |
|
| MCP ツールとして呼ぶ( |
ライセンスと第三者表記
本リポジトリのソースコード: MIT License。
MDN 本文・翻訳データ・外部サイトの扱い: THIRD_PARTY.md。
注意
MDN コンテンツは含まれません。
content/translated-contentは上流を fork したうえで、別途 clone が必要です。MDN のライセンスに従って利用してください。
Available Tools
4 toolsmdn_trans_commit_getsourceCommit の取得と反映A
content リポジトリで該当原文の最新コミットを取得し、翻訳ファイルのフロントマターに l10n.sourceCommit を書き込みます。
Inputs: url (required).
mdn_trans_replace_glossaryglossary マクロの第2引数補完A
指定した翻訳ファイル内の {{glossary("id")}} を、用語データに基づき {{glossary("id", "表示")}} に置換します。
Inputs: jaFile (required).
mdn_trans_review翻訳のガイドライン機械レビュー(読み取りのみ)ARead-only
.agents/skills 由来の機械チェック(表記・文体・l10n メタデータ・glossary マクロ等)を翻訳ファイルに対して実行します。サーバーは対象ファイルへ一切書き込みません(readOnlyHint)。エージェントはレビュー結果を理由に当該ファイルを編集・整形・追記してはならない。ユーザーが「修正して」等と明示した場合のみ編集してよい。
Inputs: jaFile (required).
mdn_trans_start翻訳開始(原文コピーのみ)A
Wiki 定義: content の files/en-us//<slug...>/index.md を、同じ階層の translated-content 側 files/ja//<slug...>/index.md にコピーするのみ(URL 側の /docs/ セグメントはファイルパスには現れない)。翻訳・_redirects・他ファイル編集は行わない。
Inputs: url (required), overwrite.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a distinct purpose: start copies files, commit_get updates metadata, replace_glossary edits glossary macros, and review runs checks. There is no overlap or ambiguity between them.
All tools share the 'mdn_trans_' prefix and mostly use verb-like names (start, replace_glossary, review). However, 'commit_get' reverses the verb_noun order, making it inconsistent with the others.
With only 4 tools, the server is well-scoped for the specific MDN translation workflow it supports. Each tool serves a necessary step without unnecessary bulk.
The tools cover the full intended workflow: starting a translation, syncing the source commit, replacing glossary terms, and running reviews. The server is deliberately limited to these helper actions, and no obvious gaps exist within that scope.
Maintenance
Related MCP Connectors
Manage product translations from Claude and ship reviewed changes as GitHub pull requests.
Estimates automation time savings, drafts automation specs, and checks Japanese ad copy. Read-only.
Diff gatekeeper, pre-merge review, unicode safety, SMT prover, dependency advisor.
AI-native translation management: push translation files, translate, review and audit strings.
Related MCP Servers
- -licenseNot gradedqualityNot gradedmaintenanceEnables automatic creation and management of weekly work reports in Korean through structured templates. Organizes work tasks and issues with automatic file management, backup/rollback, and 100% template compliance through JSON Schema validation.-
- AlicenseBqualityDmaintenanceEnables automated publishing and draft saving to note.com platform using Playwright automation. Reads Markdown files with titles, body text, and tags to publish content directly to your note.com account.225 npm58MIT
- AlicenseAqualityDmaintenanceEnforces team engineering standards across Git, code review, Rails, frontend, deployment, incidents, observability, API design, database, ADRs, and technical debt, with tools for branch name and commit message validation.4MIT
- FlicenseNot gradedqualityCmaintenanceEnables surgical markdown edits across GitHub repositories through a claude.ai custom connector, batching multiple changes into exactly one commit.3-