Skip to main content
Glama
README.md
## 概要

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

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

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

- [Architecture](https://gurezo.net/mdn-translation-ja-mcp/documents/Architecture.html)
- [Getting Started](https://gurezo.net/mdn-translation-ja-mcp/documents/Getting_Started.html)
- [MCP Tools](https://gurezo.net/mdn-translation-ja-mcp/documents/MCP_Tools.html)
- [MCP Resources](https://gurezo.net/mdn-translation-ja-mcp/documents/MCP_Resources.html)
- [MCP Prompts](https://gurezo.net/mdn-translation-ja-mcp/documents/MCP_Prompts.html)
- [Translation Workflow](https://gurezo.net/mdn-translation-ja-mcp/documents/Translation_Workflow.html)
- [Client Integration](https://gurezo.net/mdn-translation-ja-mcp/documents/Client_Integration.html)
- [Agent Skills](https://gurezo.net/mdn-translation-ja-mcp/documents/Agent_Skills.html)

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

## 目的

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

## アーキテクチャ

```text
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](architecture/mcp-native.md) を参照してください。

## 最小セットアップ

### 前提リポジトリ(fork → clone)

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

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

```bash
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](https://github.com/mdn/content) / [mdn/translated-content](https://github.com/mdn/translated-content) です。

### ランタイム

- [Node.js](https://nodejs.org/) 24 以上(LTS 推奨)
- MCP クライアント(stdio または Streamable HTTP)。HTTP 必須ではありません。Cursor Rules / Skills は任意です。

### サーバーのビルド

```bash
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](examples/README.md) です。

- MCP 共通: [examples/mcp/README.md](examples/mcp/README.md)(Claude Code / VS Code / Inspector)
- Cursor: [examples/cursor/mcp.example.json](examples/cursor/mcp.example.json)

クライアント別の置き場は [Client Integration](https://gurezo.net/mdn-translation-ja-mcp/documents/Client_Integration.html) を参照してください。

### `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](https://gurezo.net/mdn-translation-ja-mcp/documents/MCP_Tools.html) です。

## 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](https://gurezo.net/mdn-translation-ja-mcp/documents/MCP_Resources.html) です。

## MCP Prompts

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

| Prompt | 引数 | 用途 |
| --- | --- | --- |
| `mdn_translate` | `url` | 翻訳開始からレビューまでの標準フロー |
| `mdn_sync` | `url` | 既存訳の `l10n.sourceCommit` 同期 |
| `mdn_review` | `jaFile` | 機械レビューと人手確認項目 |

詳細は [MCP Prompts](https://gurezo.net/mdn-translation-ja-mcp/documents/MCP_Prompts.html) です。

## 翻訳フロー

一例として、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](https://gurezo.net/mdn-translation-ja-mcp/documents/Translation_Workflow.html) です。

## Cursor integration(optional)

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

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

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

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

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

## 他 MCP クライアント

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

```bash
npm run build
npm run inspect
```

検証結果は [architecture/client-verification.md](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/](https://gurezo.net/mdn-translation-ja-mcp/) だけです。

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

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

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

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

公開の主体は [gurezo/portal](https://github.com/gurezo/portal) です。このリポジトリから Firebase Hosting へはデプロイしません。

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

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

検証結果と、旧 GitHub Pages を再公開しない方針は [architecture/docs-migration-validation.md](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](https://github.com/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](LICENSE)。
- MDN 本文・翻訳データ・外部サイトの扱い: [THIRD_PARTY.md](THIRD_PARTY.md)。

## 注意

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

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