CopyTuner Client

CopyTunerClient::Mcp

Es una implementación del servidor MCP (Model Context Protocol) para el servicio de gestión de traducciones i18n de Rails «CopyTuner». Proporciona un conjunto de herramientas para que los asistentes de IA ayuden eficientemente en la internacionalización de aplicaciones Rails.

Resumen

Este gem proporciona un servidor que accede a los datos de traducción del proyecto CopyTuner y permite, a través del protocolo MCP, buscar claves i18n de Rails, gestionar traducciones, crear nuevas claves, etc.

Funcionalidades

Herramientas disponibles

• search_key: Búsqueda de claves i18n de Rails (optimizada para la búsqueda de claves utilizadas en t() y I18n.t()). Además de las claves traducidas, también devuelve claves registradas pero con traducción vacía (representadas por la cadena vacía ""). Las claves devueltas como cadena vacía ya están registradas, por lo que se debe configurar la traducción con update_i18n_key en lugar de create_i18n_key.
• search_translations: Búsqueda por contenido de traducción (búsqueda de traducciones que contengan un texto específico). Solo se incluyen claves traducidas, no claves con traducción vacía.
• create_i18n_key: Creación de nuevas claves i18n (compatible con múltiples idiomas). Dado que registra el borrador de forma síncrona a través de la API v3 de CopyTuner, los errores de validación como duplicados de claves existentes o exceder el límite de locales se devuelven inmediatamente. Es exclusivo para nuevos registros y rechaza claves existentes (para actualizar claves existentes use update_i18n_key). Por defecto, espera hasta 2 minutos para que se refleje en la caché antes de devolver (si se especifica wait: false, devuelve inmediatamente). La publicación se realiza por separado en CopyTuner.
• update_i18n_key: Actualización de traducciones de borrador de claves i18n existentes (compatible con múltiples idiomas). Solo se pueden actualizar traducciones no publicadas (o publicadas pero vacías); intentar actualizar una traducción publicada produce un error. Por defecto, espera hasta 2 minutos para que se refleje en la caché antes de devolver (si se especifica wait: false, devuelve inmediatamente).
• get_locales: Obtener la lista de locales utilizados en el proyecto.
• get_edit_url: Generar la URL de la pantalla de edición para claves registradas.

Plantillas de recursos

• copytuner://projects/{project_id}/translations/{locale}/{key}: Acceso a recursos de traducción individuales.

Instalación

Agregue lo siguiente al Gemfile:

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

Y luego ejecute:

bundle install

Uso

1. Configuración de CopyTunerClient

Primero, copy_tuner_client debe estar configurado correctamente en la aplicación 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. Configuración y uso con asistentes de IA

En asistentes de IA compatibles con el protocolo MCP (Claude Code, VSCode Copilot, etc.), al colocar los siguientes archivos de configuración, el servidor MCP se iniciará automáticamente y las funciones de gestión de traducciones estarán disponibles.

Claude Code

Cree el archivo .mcp.json en el directorio raíz del proyecto:

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

VSCode Copilot

Cree el archivo .vscode/mcp.json:

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

Ejemplo de configuración de CLAUDE.md

Al crear el archivo CLAUDE.yml en el directorio raíz del proyecto, el asistente de IA podrá comprender el mecanismo de internacionalización del proyecto:

# CLAUDE.md

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

Ejemplos de uso

Una vez completada la configuración, el asistente de IA puede realizar operaciones como las siguientes:

Búsqueda de claves

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

Búsqueda de contenido de traducción

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

Creación de nuevas claves

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

Actualización de traducciones de claves existentes

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

3. Inicio manual (para verificación y depuración)

Normalmente se inicia automáticamente a través de los archivos de configuración del asistente de IA, pero si necesita verificar el funcionamiento o depurar, puede iniciarlo manualmente ejecutando lo siguiente en el directorio raíz de la aplicación Rails:

bundle exec copy-tuner-mcp

Licencia

Este gem está disponible como código abierto bajo la MIT License.