# kiwi-tcms-mcp

MCP-сервер (Model Context Protocol) для **полного доступа к API [Kiwi TCMS](https://kiwitcms.org)** на Node.js + TypeScript.

Работает поверх официального JSON-RPC endpoint'а Kiwi TCMS (`/json-rpc/`) с аутентификацией логин/пароль (`Auth.login`, как в [tcms-api](https://tcms-api.readthedocs.io/en/latest/modules/tcms_api.html)). Подключается к любому 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.

## Установка

```bash
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`](https://www.npmjs.com/package/@kiwi-tcms-ai/kiwi-tcms-client) (ставится автоматически).

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

```bash
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 в закрытом контуре) |

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

```bash
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`):

```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`):

```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:**

```bash
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