Skip to main content
Glama

概要

このリポジトリは、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-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 です。

クライアント別の置き場は 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 のようなスネークケースです)。シェルコマンドではありません。

MCP ツール名

主な引数

用途

mdn_trans_start

url

content の原文 index.md を translated-content の対応パスへコピーするだけ(翻訳・_redirects.txt・他ファイルの修正はしない)

mdn_trans_commit_get

url

content の git 履歴からコミットハッシュを取得し、l10n.sourceCommit を翻訳ファイルに反映する

mdn_trans_replace_glossary

jaFile

1 引数 {{glossary}} を第 2 引数付きに置換する

mdn_trans_review

jaFile

ガイドライン機械レビュー(mdn://data/review-rules と同じ JSON)。読み取りのみ

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

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

詳細は MCP Tools です。

MCP Resources

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

URI

内容

mdn://guidelines/editorial

表記ガイドライン

mdn://guidelines/l10n

L10N ガイドライン

mdn://guidelines/japanese-style

文体ルール

mdn://glossary

用語抜粋と Wiki 参照手順

mdn://data/glossary-terms

機械用 glossary(mdn_trans_replace_glossary と同一)

mdn://data/review-rules

機械チェックルール(mdn_trans_review と同一)

mdn://data/prohibited-expressions

禁止・注意表現

詳細は MCP Resources です。

MCP Prompts

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

Prompt

引数

用途

mdn_translate

url

翻訳開始からレビューまでの標準フロー

mdn_sync

url

既存訳の l10n.sourceCommit 同期

mdn_review

jaFile

機械レビューと人手確認項目

詳細は 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 です。

トラブルシュート

症状

確認すること

HTTP で MCP に接続できない

npm run start:http が起動しているか。クライアントの url(ホスト・ポート・パス /mcp)が一致しているか。

MCP が起動しない / Cannot find module

npm run build 済みか。stdio のときは args のパスが dist/index.js の絶対パスか。

dist/index.js が無い

リポジトリルートで npm install と npm run build。

ワークスペースが解決できない

MDN_CONTENT_ROOT と MDN_TRANSLATED_CONTENT_ROOT は 両方セットするか、両方未設定にする。

content / translated-content が見つからない

親ディレクトリに両方があるか。または上記環境変数で正しい絶対パスを指定。

mdn_trans_commit_get が git 関連で失敗する

content が fork した mdn/content を clone したリポジトリか、対象ファイルが追跡されているか。

Node のバージョンエラー

package.json の engines は node >= 24。

mdn_trans_review がシェルで見つからない

MCP ツールとして呼ぶ(npm start では解決しない)。クライアントにサーバーが接続済みか。フォールバック: npm run mdn:trans:review -- --jaFile=files/ja/.../index.md

ライセンスと第三者表記

  • 本リポジトリのソースコード: MIT License。

  • MDN 本文・翻訳データ・外部サイトの扱い: THIRD_PARTY.md。

注意

  • MDN コンテンツは含まれません。

  • content / translated-content は上流を fork したうえで、別途 clone が必要です。

  • MDN のライセンスに従って利用してください。

Available Tools

4 tools
mdn_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翻訳のガイドライン機械レビュー(読み取りのみ)A
Read-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

    A4/5.0

    Scored across 4 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • -
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables 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.
      -
    • A
      license
      A
      quality
      D
      maintenance
      Enforces 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.
      4
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables surgical markdown edits across GitHub repositories through a claude.ai custom connector, batching multiple changes into exactly one commit.
      3
      -