CopyTunerClient::Mcp

Rails i18nの翻訳管理サービス「CopyTuner」のMCP（Model Context Protocol）サーバー実装です。AIアシスタントがRailsアプリケーションの多言語化対応を効率的に支援するためのツールセットを提供します。

概要

このgemは、CopyTunerプロジェクトの翻訳データにアクセスし、Rails i18nキーの検索、翻訳の管理、新しいキーの作成などをMCPプロトコル経由で実行できるサーバーを提供します。

機能

利用可能なツール

• search_key: Rails i18nキーの検索（`t()`や`I18n.t()`で使用されるキーの検索に最適化）。翻訳済みのキーに加え、登録済みだが訳が空のキーも返す（空文字列 `""` で表現）。空文字列で返ってきたキーはすでに登録済みなので、`create_i18n_key` ではなく `update_i18n_key` で翻訳を設定する
• search_translations: 翻訳内容による検索（特定のテキストを含む翻訳の検索）。翻訳済みキーのみが対象で、訳が空のキーは含まない
• create_i18n_key: 新しいi18nキーの作成（複数言語対応）。CopyTuner API v3経由でdraftを同期登録するため、既存キーの重複やロケール数上限超過などのバリデーションエラーは即座に返る。新規登録専用で既存キーは拒否する（既存キーの更新は `update_i18n_key` を使う）。デフォルトではキャッシュへの反映を最大2分待ってから返る（`wait: false` を指定すると即時返却）。公開は別途CopyTuner側で行われる
• update_i18n_key: 既存i18nキーのdraft翻訳の更新（複数言語対応）。未公開（または公開済みでも空）の訳のみ更新可能で、公開済みの訳を更新しようとするとエラーになる。デフォルトではキャッシュへの反映を最大2分待ってから返る（`wait: false` を指定すると即時返却）
• get_locales: プロジェクトで使用中のロケール一覧の取得
• get_edit_url: 登録済みキーの編集画面URLの生成

リソーステンプレート

• `copytuner://projects/{project_id}/translations/{locale}/{key}`: 個別の翻訳リソースへのアクセス

インストール

Gemfileに以下を追加：

group :development do
  gem 'copy_tuner_client-mcp', github: 'SonicGarden/copy_tuner_client-mcp', require: false
end

そして実行：

bundle install

使用方法

1. CopyTunerClientの設定

まず、Railsアプリケーションでcopy_tuner_clientが適切に設定されている必要があります：

# config/initializers/copy_tuner_client.rb
CopyTunerClient.configure do |config|
  config.api_key = "your-api-key"
  config.project_id = "your-project-id"
  config.locales = ["ja", "en"]
end

2. AIアシスタントでの設定と利用

MCPプロトコルに対応したAIアシスタント（Claude Code、VSCode Copilot等）で、以下の設定ファイルを配置するとMCPサーバーが自動的に起動され、翻訳管理機能が利用可能になります。

Claude Code

プロジェクトのルートディレクトリに `.mcp.json` ファイルを作成：

{
  "mcpServers": {
    "copy-tuner": {
      "command": "bundle",
      "args": ["exec", "copy-tuner-mcp"]
    }
  }
}

VSCode Copilot

`.vscode/mcp.json` ファイルを作成：

{
  "servers": {
    "copy-tuner": {
      "type": "stdio",
      "command": "bundle",
      "args": ["exec", "copy-tuner-mcp"],
      "cwd": "${workspaceFolder}"
    }
  }
}

CLAUDE.md設定例

プロジェクトのルートディレクトリに `CLAUDE.yml` ファイルを作成することで、AIアシスタントがプロジェクトの国際化の仕組みを理解できるようになります：

# CLAUDE.md

## 国際化（i18n）について
- i18nのバックエンドには**copy_tuner**というサーバでi18nデータを管理する仕組みを利用
- i18nのキーや内容を参照する場合は、copy_tunerから取得する必要がある
- `config/locales` 配下のファイルは利用していません
- copy_tunerサーバと連携してローカライズデータを管理

使用例

設定完了後、AIアシスタントで以下のような操作が可能になります：

キーの検索

user.nameに関連するi18nキーを検索してください

翻訳内容の検索

「ログイン」という文字を含む翻訳を検索してください

新しいキーの作成

user.profile.bioというキーで「プロフィール」（日本語）と「Profile」（英語）の翻訳を作成してください

既存キーの翻訳の更新

user.profile.bioの日本語訳を「自己紹介」に更新してください

3. 手動起動（動作確認・デバッグ用）

通常はAIアシスタントの設定ファイルを通じて自動的に起動されますが、動作確認やデバッグが必要な場合は、Railsアプリケーションのルートディレクトリで以下を実行して手動起動できます：

bundle exec copy-tuner-mcp

ライセンス

このgemはMIT Licenseの下でオープンソースとして利用可能です。