42 lines
3.3 KiB
Markdown
42 lines
3.3 KiB
Markdown
# mcp Specification
|
||
|
||
## Purpose
|
||
TBD - created by archiving change bridge-core. Update Purpose after archive.
|
||
|
||
## Requirements
|
||
|
||
### Requirement: Сервер и регистрация
|
||
`jira-hub mcp` SHALL запускать MCP-сервер по stdio (пакет `mcp`), ходящий в HTTP API хаба клиентским токеном из
|
||
настроек. Регистрация — в `~/.claude.json` для проекта `awp-ca` как `jira-hub` (`uv run --project <путь> jira-hub mcp`).
|
||
Если хаб недоступен, каждый инструмент SHALL вернуть текст «хаб не запущен: jira-hub serve», а не исключение.
|
||
|
||
#### Scenario: Хаб выключен
|
||
- **WHEN** вызван `issues` при остановленном хабе
|
||
- **THEN** ответ инструмента — одна строка с подсказкой, сервер MCP продолжает работать
|
||
|
||
### Requirement: Инструменты
|
||
| Инструмент | Параметры | Результат |
|
||
|---|---|---|
|
||
| `issues` | фильтры как у `GET /issues`, `limit` (по умолчанию 50) | таблица: ключ, тема (до 80 символов), статус, срок, исполнитель, спринт, статус по факту |
|
||
| `issue` | `key` | поля, связи (обе стороны, с типом и направлением), заметки, последние команды |
|
||
| `notes_set` | `key`, подмножество полей заметок | обновлённые заметки |
|
||
| `batch_create` | `title`, `commands` (список объектов по контракту `commands`) | `id`, `estimate_seconds`, число команд; 422 — текст ошибки валидации |
|
||
| `batch_status` | `id` | статусы команд, ошибки, оценка остатка |
|
||
| `batch_wait` | `id`, `timeout_minutes` (≤ 60) | как `batch_status`, возвращается по завершении или по таймауту |
|
||
| `batches` | `limit` | последние пакеты со статусом |
|
||
| `command_retry`, `batch_cancel` | `id` | новый пакет / результат отмены |
|
||
| `refresh` | `keys` или `full`, `wait` (bool) | `sync_run` или id пакета |
|
||
| `agent_status` | — | онлайн/офлайн, версия, текущая команда, 429 за сутки, версия настроек |
|
||
| `sync_log` | `limit` | последние `sync_run` |
|
||
| `settings_get`, `settings_set` | ключ, значение | текущее значение / новая `settings_version` |
|
||
|
||
Автор команд из MCP SHALL быть `claude`; из API без автора — `api`.
|
||
|
||
#### Scenario: Пакет из чата
|
||
- **WHEN** `batch_create {title: "1538 в спринт 2", commands: [ensure_fields{…}, ensure_link{…}, ensure_sprint{…}]}`
|
||
- **THEN** пакет создан с четырьмя командами (три + `refresh`), ответ содержит оценку в минутах
|
||
|
||
#### Scenario: Ожидание результата
|
||
- **WHEN** `batch_wait {id, timeout_minutes: 10}` и пакет завершился через 6 минут
|
||
- **THEN** ответ через 6 минут со статусами всех команд
|