kiwi-tcms-mcp

MCP-сервер (Model Context Protocol) для полного доступа к API Kiwi TCMS на Node.js + TypeScript.

Работает поверх официального JSON-RPC endpoint'а Kiwi TCMS (/json-rpc/) с аутентификацией логин/пароль (Auth.login, как в tcms-api). Подключается к любому MCP-клиенту (Claude Desktop, VS Code, Cline, Cursor, MCP Inspector) по stdio.

Возможности

• 68 инструментов: планы, кейсы, раны, исполнения, справочники (версии, теги, статусы, пользователи), вложения, properties + сквозной kiwi_rpc.
• Именованные аргументы: приоритеты, категории, статусы, сборки, типы планов и пользователи принимаются по имени — сервер сам резолвит их в id.
• Проект по умолчанию: KIWI_PROJECT (Product в терминах Kiwi) автоматически подставляется в фильтры и создание объектов.
• Ресурс kiwi://status и промпт run-summary (сводка по тест-рану).
• Понятные ошибки: HTTP-коды, JSON-RPC-ошибки, таймауты (KIWI_TIMEOUT), подсказки что проверить.
• Безопасность: пароль не логируется, весь диагностический вывод — только в stderr.

Установка

npm install -g @kiwi-tcms-ai/kiwi-tcms-mcp
kiwi-tcms-mcp --help

Или без глобальной установки: npx -y @kiwi-tcms-ai/kiwi-tcms-mcp --help.

Клиент API — @kiwi-tcms-ai/kiwi-tcms-client (ставится автоматически).

Локальная сборка из исходников:

cd kiwi-tcms-mcp
npm install
npm run build        # tsc -> dist/
node dist/index.js --help

Требования: Node.js ≥ 18 (используется глобальный fetch).

Конфигурация

Параметры задаются переменными окружения или CLI-флагами (флаги приоритетнее).

Env	Флаг	Обязат.	Описание
KIWI_URL	--url	да	Базовый URL инстанса, например https://tcms.example.com
KIWI_USERNAME	--username	да	Логин Kiwi TCMS (Auth.login)
KIWI_PASSWORD	--password	да	Пароль Kiwi TCMS
KIWI_PROJECT	--project	нет	Проект/Product по умолчанию (имя или id)
KIWI_TIMEOUT	--timeout	нет	Таймаут JSON-RPC запроса, мс (по умолчанию 30000)
KIWI_DEFAULT_LIMIT	--limit	нет	Лимит строк в list/filter-инструментах (по умолчанию 20)
KIWI_INSECURE=1	--insecure	нет	Не проверять TLS-сертификат (только self-signed в закрытом контуре)

Пример прямого запуска:

npx -y @kiwi-tcms-ai/kiwi-tcms-mcp \
  --url https://tcms.example.com \
  --username api-bot \
  --password keep-me-secret \
  --project "Payments"

Подключение к MCP-клиентам

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "kiwi-tcms": {
      "command": "npx",
      "args": ["-y", "@kiwi-tcms-ai/kiwi-tcms-mcp"],
      "env": {
        "KIWI_URL": "https://tcms.example.com",
        "KIWI_USERNAME": "api-bot",
        "KIWI_PASSWORD": "keep-me-secret",
        "KIWI_PROJECT": "Payments"
      }
    }
  }
}

После npm install -g @kiwi-tcms-ai/kiwi-tcms-mcp можно писать "command": "kiwi-tcms-mcp" без args.

VS Code (.vscode/mcp.json):

{
  "servers": {
    "kiwi-tcms": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@kiwi-tcms-ai/kiwi-tcms-mcp"],
      "env": {
        "KIWI_URL": "https://tcms.example.com",
        "KIWI_USERNAME": "api-bot",
        "KIWI_PASSWORD": "keep-me-secret",
        "KIWI_PROJECT": "Payments"
      }
    }
  }
}

Cline / Cursor (mcp_settings.json) — как Claude Desktop (mcpServers).

Отладка через MCP Inspector:

KIWI_URL=https://tcms.example.com KIWI_USERNAME=api-bot KIWI_PASSWORD=... KIWI_PROJECT=Payments \
  npx @modelcontextprotocol/inspector npx -y @kiwi-tcms-ai/kiwi-tcms-mcp

Инструменты

Инструмент	Метод Kiwi TCMS	Назначение
kiwi_ping	Product.filter	Проверка соединения и логина
kiwi_list_projects	Product.filter	Список проектов
kiwi_list_builds	Build.filter	Сборки продукта
kiwi_list_components	Component.filter	Компоненты продукта
kiwi_list_priorities	Priority.filter	Приоритеты
kiwi_list_categories	Category.filter	Категории кейсов
kiwi_list_plans	TestPlan.filter	Поиск тест-планов
kiwi_create_plan	TestPlan.create	Создание плана
kiwi_plan_add_case	TestPlan.add_case	Привязка кейса к плану
kiwi_search_cases	TestCase.filter	Гибкий поиск кейсов
kiwi_get_case	TestCase.filter	Карточка кейса; text возвращается как есть
kiwi_create_case	TestCase.create + add_tag	Создание кейса; тело кейса — в text
kiwi_update_case	TestCase.update	Обновление полей; text заменяется целиком
kiwi_case_add_comment	TestCase.add_comment	Комментарий к кейсу
kiwi_case_history	TestCase.history	История изменений кейса
kiwi_list_runs	TestRun.filter	Поиск тест-ранов
kiwi_create_run	TestRun.create	Создание рана
kiwi_run_add_case	TestRun.add_case	Добавление кейсов в ран
kiwi_run_status	TestRun.filter + TestExecution.filter	Сводка по рану, упавшие кейсы
kiwi_list_executions	TestExecution.filter	Поиск исполнений
kiwi_update_execution	TestExecution.update + add_comment	Смена статуса/сборки/исполнителя
kiwi_create_project	Product.create	Создать продукт
kiwi_create_build	Build.create	Создать сборку (через Version)
kiwi_list_versions / kiwi_create_version	Version.*	Версии продукта
kiwi_list_plan_types / kiwi_create_plan_type	PlanType.*	Типы планов
kiwi_list_case_statuses	TestCaseStatus.filter	Статусы кейсов
kiwi_list_execution_statuses	TestExecutionStatus.filter	Статусы исполнений
kiwi_list_users / kiwi_me	User.filter	Пользователи / текущий логин
kiwi_list_tags / kiwi_create_tag	Tag.*	Теги
kiwi_list_classifications	Classification.filter	Классификации продуктов
kiwi_update_plan	TestPlan.update	Обновить план
kiwi_plan_remove_case	TestPlan.remove_case	Убрать кейс из плана
kiwi_plan_tree	TestPlan.tree	Дерево плана
kiwi_plan_add_tag / kiwi_plan_remove_tag	TestPlan.*_tag	Теги плана
kiwi_update_run	TestRun.update	Обновить/закрыть ран
kiwi_run_get_cases	TestRun.get_cases	Кейсы рана + execution_id
kiwi_case_add_tag / kiwi_case_remove_tag	TestCase.*_tag	Теги кейса
kiwi_case_add_component / kiwi_case_remove_component	TestCase.*_component	Компоненты кейса
kiwi_execution_add_link / get_links / remove_link	TestExecution.*_link	Ссылки/баги на исполнение
kiwi_*_list_attachments / kiwi_*_add_attachment	*.list_attachments / add_attachment	Вложения кейса/плана/рана/исполнения
kiwi_remove_attachment	Attachment.remove_attachment	Удалить вложение
kiwi_*_properties / kiwi_*_add_property	*.properties / add_property	Properties кейса/рана/исполнения
kiwi_rpc	любой	Сквозной вызов оставшихся методов

Плюс ресурс kiwi://status (конфиг + live-проверка) и промпт run-summary.

Структура

kiwi-tcms-mcp/
├── package.json           # зависит от @kiwi-tcms-ai/kiwi-tcms-client из npm
├── tsconfig.json
└── src/
    ├── index.ts           # входная точка: stdio-транспорт, сборка сервера
    ├── config.ts          # env + CLI-флаги, валидация
    └── tools.ts           # MCP-схемы; логика — в kiwi-tcms-client

Лицензия

MIT