sdlc-hub/openspec/changes/wiki-history/specs/mcp/spec.md

MODIFIED Requirements

Requirement: MCP вики

sdlc-hub mcp wiki [--project <метка>] SHALL запускать по stdio MCP-сервер модуля wiki с именем sdlc-wiki, ходящий в HTTP API хаба клиентским токеном; хаб недоступен — каждый инструмент отвечает «хаб не запущен: sdlc-hub serve». Привязка к проекту проверяется так же, как у сервера jira («Привязка сессии к проекту»). Инструменты:

Инструмент	Параметры	Ответ
projects	—	таблица: метка, название, корень вики, страниц, последняя синхронизация; текущий проект отмечен
project_create	label, name, wiki_root (необязательно)	POST /projects с автором claude; проект и фрагмент .mcp.json с записью sdlc-wiki
root_set	root	PATCH /projects/<текущий> {wiki_root}; новый корень и id пакета синхронизации
tree	code (необязательно), depth (по умолчанию 2)	дерево от корня или от code: отступ, код, название, размер
page	code или title, offset (по умолчанию 0)	шапка (код, путь в дереве, адрес в Eva, дата синхронизации, строка «изменено: ДД.ММ ЧЧ:ММ <автор> (версий: N)» или «изменено: история не загружена», вложения с id) и Markdown с offset до 20 000 символов, в конце — «продолжение: offset=», если текст длиннее; title ищется точно, иначе — до 10 кандидатов с кодами
search	query, limit (по умолчанию 10)	страницы: код, название, путь, фрагмент
changes	hours, since, until, author (все необязательные)	правки страниц проекта за период (GET /wiki/changes), см. ниже
diff	code, version (необязательно), offset (по умолчанию 0)	шапка (код, название, путь, версия «N из M», автор, время, «+A / −R», предыдущая версия) и unified diff с offset до 20 000 символов, в конце — «продолжение: offset=», если дифф длиннее; без version — последняя правка
attachment	id	ставит скачивание, ждёт до 60 с; готово — путь к копии downloads/wiki-<id>/<имя>; иначе состояние и подсказка повторить
sync	wait (по умолчанию false)	без wait — «поставлено: пакет N» или «уже идёт: пакет N»; с wait — ждёт до 300 с: «ок: синхронизировано ДД.ММ ЧЧ:ММ», «ошибка: <текст>» или «не дождался за 300 с: пакет N»; данных копии в ответе нет
status	—	корень, последняя синхронизация, загрузка истории (history_at или «история не загружена»), ошибка, пакет в работе, агент wiki: онлайн/офлайн, версия, публикация, обновление, запускатель (как agent_status сервера jira)

Инструменты, кроме projects и project_create, SHALL требовать привязки к проекту. В привязанной сессии без корня (кроме root_set, status) ответ SHALL быть «у проекта <метка> нет корня вики: root_set DOC-…»; с корнем, но без синхронизаций — «вики проекта ещё не синхронизирована: sync». Набор инструментов и их описания у сервера sdlc-jira (модуль jira) SHALL остаться прежним. Инструменты page, changes, diff MUST NOT ставить команд: они читают только копию хаба.

changes: период — как у инструмента changes сервера jira («Лента изменений в MCP»): hours и since вместе — ответ «либо hours, либо since»; без обоих — с начала текущих суток по местному времени машины MCP-сервера; с hours — since = сейчас − hours; since/until без смещения — местное время машины MCP-сервера. author передаётся в хаб как есть. Вид ответа: первая строка — период по местному времени («правки вики с 28.10 00:00 по 28.10 14:05»), вторая — «синхронизировано: ДД.ММ ЧЧ:ММ»; затем правки, сгруппированные по странице; страницы — по времени последней правки, новые сверху; у страницы строка «DOC-… <название> — <путь>», под ней правки по времени, новые сверху, каждая — «ЧЧ:ММ <автор>: +A / −R (<версия>)», с датой «ДД.ММ» перед временем, если правка не в текущих сутках. Правок нет — «за период правок нет»; history_at = null — «история ещё не загружена: нужен eva-agent v2 и sync»; truncated — последняя строка «показаны последние N правок, сузьте период». Ошибка 422 хаба — её текст.

Значения из Eva, которые инструменты выводят внутри строки ответа (названия страниц и корня, путь, имя вложения, фрагмент поиска, кандидаты page по названию, имя автора правки), SHALL выводиться одной строкой: переводы строк (\r, \n) и пробелы вокруг них заменяются одним пробелом. Тело страницы (Markdown после шапки page) и дифф после шапки diff выводятся как есть.

Scenario: Поиск из сессии awp-ca

• WHEN сервер запущен с --project AWPCA, копия синхронизирована, вызван search {query: "статус согласован"}
• THEN ответ — страницы с кодами и фрагментами; запрос в хаб — GET /wiki/search?project=AWPCA&q=…

Scenario: Длинная страница

• WHEN page {code: DOC-3}, Markdown 45 000 символов
• THEN первые 20 000 символов и «продолжение: offset=20000»; page {code: DOC-3, offset: 40000} — остаток без строки продолжения

Scenario: Корня нет

• WHEN сессия sfm_kedr без корня, вызван tree
• THEN ответ «у проекта sfm_kedr нет корня вики: root_set DOC-…», запроса GET /wiki/tree нет

Scenario: Сервер jira не изменился

• WHEN запущен sdlc-hub mcp jira --project AWPCA
• THEN имя сервера sdlc-jira, список инструментов и описания совпадают с эталоном до change

Scenario: Перевод строки в названии страницы

• WHEN у DOC-3 название «Статусы\nпуть: поддельный», вызван page {code: DOC-3}
• THEN первая строка ответа — «DOC-3 — Статусы путь: поддельный», строка «путь:» в шапке одна — настоящая

Scenario: Что сделали аналитики сегодня

• WHEN сессия AWPCA, changes {} в 14:05; сегодня Соснов опубликовал две версии DOC-101252 в 11:02 и 12:40
• THEN запрос GET /wiki/changes?project=AWPCA&since=<сегодня 00:00 местного>; в ответе строка DOC-101252 с названием и путём, под ней «12:40 Дмитрий Соснов: +40 / −12 (DOCH-…)» и «11:02 Дмитрий Соснов: …»; команд не поставлено

Scenario: Дифф правки

• WHEN diff {code: DOC-101252}, у страницы 4 версии
• THEN шапка «версия 4 из 4», автор, время, «+A / −R», предыдущая версия; затем unified diff

Scenario: Синхронизация с ожиданием

• WHEN sync {wait: true}, пакет завершился done в 14:05
• THEN ответ — одна строка «ок: синхронизировано 28.10 14:05»

Scenario: История ещё не загружена

• WHEN у агента wiki версия 1, changes {}
• THEN ответ содержит «история ещё не загружена: нужен eva-agent v2 и sync»