CopyTuner Client

CopyTunerClient::Mcp

Implementação do servidor MCP (Model Context Protocol) para o serviço de gerenciamento de tradução i18n do Rails "CopyTuner". Fornece um conjunto de ferramentas para que assistentes de IA auxiliem eficientemente na internacionalização de aplicações Rails.

Visão geral

Esta gem fornece um servidor que acessa os dados de tradução de projetos CopyTuner e executa, via protocolo MCP, buscas de chaves i18n do Rails, gerenciamento de traduções, criação de novas chaves e outras operações.

Funcionalidades

Ferramentas disponíveis

• search_key: Busca de chaves i18n do Rails (otimizada para busca de chaves usadas em t() e I18n.t()). Além de chaves traduzidas, também retorna chaves registradas com tradução vazia (representadas pela string vazia ""). Chaves retornadas como string vazia já estão registradas, portanto use update_i18n_key em vez de create_i18n_key para configurar a tradução
• search_translations: Busca pelo conteúdo da tradução (busca de traduções que contenham texto específico). Apenas chaves traduzidas são consideradas; chaves com tradução vazia não são incluídas
• create_i18n_key: Criação de novas chaves i18n (com suporte a múltiplos idiomas). Como o registro do draft é sincronizado via API v3 do CopyTuner, erros de validação como duplicidade de chaves existentes ou excedente do limite de locales são retornados imediatamente. Exclusivo para novos registros; chaves existentes são rejeitadas (para atualizar chaves existentes, use update_i18n_key). Por padrão, aguarda até 2 minutos para refletir no cache antes de retornar (especifique wait: false para retorno imediato). A publicação é feita separadamente no CopyTuner
• update_i18n_key: Atualização de traduções draft de chaves i18n existentes (com suporte a múltiplos idiomas). Apenas traduções não publicadas (ou publicadas, porém vazias) podem ser atualizadas; tentar atualizar uma tradução publicada gera erro. Por padrão, aguarda até 2 minutos para refletir no cache antes de retornar (especifique wait: false para retorno imediato)
• get_locales: Obtenção da lista de locales em uso no projeto
• get_edit_url: Geração de URL da tela de edição de chaves registradas

Modelos de recursos

• copytuner://projects/{project_id}/translations/{locale}/{key}: Acesso a recursos de tradução individuais

Instalação

Adicione ao Gemfile:

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

E execute:

bundle install

Como usar

1. Configuração do CopyTunerClient

Primeiro, o copy_tuner_client deve estar configurado adequadamente na aplicação Rails:

# 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. Configuração e uso com assistentes de IA

Em assistentes de IA compatíveis com o protocolo MCP (Claude Code, VSCode Copilot etc.), ao colocar o arquivo de configuração abaixo, o servidor MCP é iniciado automaticamente e as funcionalidades de gerenciamento de tradução ficam disponíveis.

Claude Code

Crie o arquivo .mcp.json no diretório raiz do projeto:

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

VSCode Copilot

Crie o arquivo .vscode/mcp.json:

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

Exemplo de configuração do CLAUDE.md

Ao criar o arquivo CLAUDE.yml no diretório raiz do projeto, o assistente de IA poderá compreender o mecanismo de internacionalização do projeto:

# CLAUDE.md

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

Exemplos de uso

Após a configuração, as seguintes operações ficam disponíveis no assistente de IA:

Busca de chaves

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

Busca de conteúdo de tradução

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

Criação de novas chaves

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

Atualização de traduções de chaves existentes

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

3. Inicialização manual (para verificação e depuração)

Normalmente, o servidor é iniciado automaticamente por meio do arquivo de configuração do assistente de IA, mas, se for necessário verificar o funcionamento ou depurar, execute o comando abaixo no diretório raiz da aplicação Rails para iniciar manualmente:

bundle exec copy-tuner-mcp

Licença

Esta gem está disponível como código aberto sob a Licença MIT.