Перейти к содержимому
Verbumia
Начать бесплатно

MCP

API reference

Verbumia поставляется со встроенным MCP сервером, чтобы любой MCP-клиент — Claude Desktop, Cursor, твой собственный агент — мог искать ключи, предлагать переводы, ревьюить PR'ы и смотреть очередь missing-keys. Две строки конфига, твой токен — готово.

1. Получи API-ключ

В дашборде перейди в Org Settings → API Keys → Create. Дай ему scope mcp:* (покрывает все пять инструментов ниже). Секрет показывается один раз; скопируй полную строку vrb_live_<prefix>.<secret>.

Храни в keychain ОС или в локальном .env — никогда не коммить. Ключ привязан к твоей org (и опционально к одному проекту); вызовы вне этого scope возвращают 404. Отозвать можно из дашборда в любой момент; отозванные ключи отдают 401 на следующем вызове.

2. Установка (или пропусти)

MCP server опубликован в npm и Homebrew. С npx ничего ставить не нужно — Claude Desktop тянет последнюю версию при каждом запуске. С brew получаешь зафиксированный локальный бинарник, удобно за строгими firewall'ами.

npx (рекомендуется) 
1// установка не нужна — npx подтягивает свежий @verbumia/mcp по требованию2npx -y @verbumia/mcp --version
Homebrew (альтернатива) Tap публикуется в V1 
1// опционально: установить глобально один раз — будет к запуску V12brew install verbumia/tap/verbumia-mcp

3. Подключи Claude Desktop

Открой конфиг-файл Claude Desktop, добавь запись verbumia под mcpServers, затем закрой и перезапусти приложение.

claude_desktop_config.json 
1// macOS:   ~/Library/Application Support/Claude/claude_desktop_config.json2// Windows: %APPDATA%/Claude/claude_desktop_config.json3{4  "mcpServers": {5    "verbumia": {6      "command": "npx",7      "args": ["-y", "@verbumia/mcp"],8      "env": {9        "VERBUMIA_TOKEN":   "vrb_live_<prefix>.<secret>",10        "VERBUMIA_PROJECT": "<project_uuid>"11      }12    }13  }14}

Всего три env-переменные: VERBUMIA_TOKEN (обязательная), VERBUMIA_PROJECT (опциональная — заранее задаёт проект, чтобы агенту не пришлось сначала вызывать list_projects) и VERBUMIA_API_BASE (опциональная — по умолчанию https://api.verbumia.ca; переопредели для self-hosted или staging).

Cursor (и другие MCP-клиенты)

Тот же JSON, другой файл. В Cursor положи его в .cursor/mcp.json (на проект) или ~/.cursor/mcp.json (на пользователя). Для других клиентов следуй их документации по MCP-конфигу — запись mcpServers.verbumia идентична.

.cursor/mcp.json 
1// .cursor/mcp.json (project-scoped) or ~/.cursor/mcp.json (user-scoped)2{3  "mcpServers": {4    "verbumia": {5      "command": "npx",6      "args": ["-y", "@verbumia/mcp"],7      "env": { "VERBUMIA_TOKEN": "vrb_live_<prefix>.<secret>" }8    }9  }10}

5 инструментов V1

После настройки агент получает доступ к этим инструментам. По именам ты их не вызываешь — опиши намерение в чате, и агент сам выберет. Имена ниже — канонические идентификаторы, полезны при чтении трасс агента или при построении кастомных агентов поверх того же сервера.

list_projects Перечисляет проекты, доступные текущему API-ключу. Удобно для выбора workspace в начале чата.

Аргументы

  • limit number опциональный лимит на число возвращаемых проектов

Пример промпта

«List my Verbumia projects.»

get_project_info Получает метаданные проекта: исходный язык, целевые языки, namespace'ы, общее число ключей.

Аргументы

  • project_uuid string required

Пример промпта

«Какие языки и namespace'ы у проекта Checkout?»

list_missing_keys Возвращает накопленные события missing-keys, собранные runtime SDK (cursor-пагинация). Фильтруется по namespace или языку.

Аргументы

  • project_uuid string required
  • namespace string сузить до одного namespace (например, "checkout")
  • language_code string сузить до одного языка (например, "ja")
  • cursor string cursor пагинации, возвращённый предыдущим вызовом
  • limit number размер страницы (по умолчанию 20)

Пример промпта

«Какие ключи переводов отсутствуют для ja в namespace checkout?»

propose_translation Отправляет вариант перевода ключа на целевой язык. Всегда пишется как draft; повышает до approved человек-ревьюер — Verbumia это менеджер, а не движок.

Аргументы

  • project_uuid string required
  • key string required
  • namespace string required
  • language_code string required
  • value string required

Пример промпта

«Propose \"Confirmer la commande\" for checkout.review.confirm in fr-CA.»

validate_translations Линтит JSON i18next payload перед push'ем: парность ICU-плейсхолдеров, отсутствующие/лишние ключи, расхождение типов между локалями.

Аргументы

  • project_uuid string required
  • language_code string required
  • payload object required карта переводов в формате JSON i18next

Пример промпта

«Validate this translation file against the project's English source.»

Как проверить

  1. 1 Полностью перезапусти Claude Desktop (выйди и запусти снова — конфиг читается при старте).
  2. 2 Открой новый чат. Иконка молотка должна показывать verbumia с пятью доступными инструментами.
  3. 3 Напиши «List my Verbumia projects.» Агент должен вызвать list_projects и вернуть твои workspace'ы.

Застрял? Смотри логи Claude Desktop в ~/Library/Logs/Claude/mcp*.log (macOS). 90% проблем — опечатки в JSON или просроченный токен.

Дальше

Быстрый старт
React + i18next
Сквозной захват пропущенных ключей в рантайме.
Справка
Вся документация
CLI, API reference (в работе).