diff --git a/alfy-mcp/README.md b/alfy-mcp/README.md index cbdb059..c0a719e 100644 --- a/alfy-mcp/README.md +++ b/alfy-mcp/README.md @@ -117,6 +117,7 @@ read -rs ALFY_MCP_TOKEN - `create_project_group` — `title`, необязательные `description`, `color`, `startDate`, `dueDate`. Без `parentId` создаёт эпик; `parentId` (UUID эпика этого проекта) создаёт историю внутри него. Вложенные истории не поддерживаются. Даты `YYYY-MM-DD` допустимы только у эпиков, начало не позже окончания. - `update_project_group` — `id` и изменяемые поля: `title`, `description`, `color`, `status` (`open`/`done`), `parentId`, `startDate`, `dueDate`. Пропущенные поля сохраняются; `null` очищает описание, цвет и даты. `parentId` переносит историю в другой эпик этого проекта; группу с дочерними историями переносить нельзя. `parentId: null` не поддерживается. +- `reorder_project_groups` — `projectId` и непустой `orderedIds`: UUID эпиков проекта либо историй одного эпика **сверху вниз**, без повторов. Полный список задаёт точную перестановку; частичный поднимает указанных соседей наверх, остальных сохраняет следом в прежнем порядке. Чужие группы, смешение эпиков с историями и истории разных эпиков отклоняются без изменений. Родители, задачи, спринты и релизы сохраняются. Ответ: `{ "ok": true }`; новый порядок доступен в `list_project_groups` и на доске. - `delete_project_group` — `id` и `confirm: true`. Удаление эпика удаляет и дочерние истории. Задачи сохраняются в проекте без привязки к удалённым группам; их спринты и релизы сохраняются. Последовательность: создать эпик через `create_project_group({ projectId, title })`, затем историю через `create_project_group({ projectId, parentId: epicId, title })`, затем задачу через `create_task({ projectId, groupId: storyId, title })`. Ответ создания содержит UUID группы. Назначение истории в спринт выполняется отдельным `move_story_to_sprint`. @@ -174,3 +175,14 @@ npm run start # node dist/cli.js npm run test # vitest run npm run lint # eslint . ``` + +### Пример перестановки через MCP + +Сначала вызовите `list_project_groups({ projectId })` и используйте UUID из его ответа: + +```js +reorder_project_groups({ projectId, orderedIds: [epic3.id, epic4.id, epic1.id, epic2.id] }) +reorder_project_groups({ projectId, orderedIds: [story3.id, story4.id, story1.id, story2.id] }) +``` + +Во втором вызове все истории должны принадлежать одному эпику. Повторный `list_project_groups({ projectId })` позволяет проверить сохранённый порядок. Каждый вызов сохраняется отдельно и атомарно. diff --git a/alfy-mcp/src/tools/groups.ts b/alfy-mcp/src/tools/groups.ts index c894cb8..6533bd7 100644 --- a/alfy-mcp/src/tools/groups.ts +++ b/alfy-mcp/src/tools/groups.ts @@ -12,7 +12,7 @@ function toText(data: unknown): { content: [{ type: 'text'; text: string }] } { return { content: [{ type: 'text', text: JSON.stringify(data) }] }; } -/** Регистрирует создание, изменение и удаление эпиков и историй через REST API текущего пользователя. */ +/** Регистрирует создание, изменение, перестановку и удаление эпиков и историй через REST API текущего пользователя. */ export function registerGroupTools(server: McpServer, client: AlfyRestClient): void { server.registerTool('create_project_group', { description: 'Создать эпик или историю в проекте. Без parentId создаётся эпик; с parentId создаётся история внутри указанного эпика. Вложенные истории запрещены. Для задач внутри созданной группы используйте create_task с groupId из ответа. Для назначения истории в спринт используйте move_story_to_sprint.', @@ -40,6 +40,20 @@ export function registerGroupTools(server: McpServer, client: AlfyRestClient): v }, }, async ({ projectId, id, ...body }) => toText(await client.patch(`/projects/${projectId}/groups/${id}`, body))); + server.registerTool('reorder_project_groups', { + description: 'Изменить порядок эпиков проекта или историй внутри одного эпика. orderedIds — UUID соседей сверху вниз, без повторов; получите их через list_project_groups. Полный список задаёт точный порядок. Частичный список помещает указанные группы первыми, остальных соседей оставляет следом в прежнем порядке. Нельзя смешивать эпики с историями, истории разных эпиков или группы разных проектов. Родители, задачи, спринты и релизы не меняются. Сохранение атомарно; возвращает {ok:true}.', + inputSchema: { + projectId, + orderedIds: z.array(z.string().uuid()).min(1) + .refine(ids => new Set(ids).size === ids.length, 'UUID групп не должны повторяться') + .describe('Непустой список UUID эпиков либо историй одного эпика в нужном порядке сверху вниз'), + }, + annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true }, + }, async ({ projectId, orderedIds }) => { + await client.patch(`/projects/${projectId}/groups/reorder`, { orderedIds }); + return toText({ ok: true }); + }); + server.registerTool('delete_project_group', { description: 'Удалить эпик или историю при confirm=true. При удалении эпика удаляются также все его истории. Задачи сохраняются в проекте, их привязка к удалённым группам очищается; назначения спринтов и релизов задач сохраняются.', inputSchema: { projectId, id, confirm: z.literal(true).describe('Подтверждение удаления группы, включая дочерние истории эпика') }, diff --git a/alfy-mcp/src/tools/sprints.ts b/alfy-mcp/src/tools/sprints.ts index 9f33f40..885520b 100644 --- a/alfy-mcp/src/tools/sprints.ts +++ b/alfy-mcp/src/tools/sprints.ts @@ -61,7 +61,7 @@ export function registerSprintTools(server: McpServer, client: AlfyRestClient): }); server.registerTool('list_project_groups', { - description: 'Дерево эпиков и историй проекта с UUID, статусами и назначениями спринтов и релизов. Для создания, изменения и удаления используйте create_project_group, update_project_group и delete_project_group. Используйте UUID истории в move_story_to_sprint.', + description: 'Дерево эпиков и историй проекта с UUID, статусами и назначениями спринтов и релизов. Для создания, изменения и удаления используйте create_project_group, update_project_group и delete_project_group. Для изменения порядка эпиков или историй внутри эпика используйте reorder_project_groups. Используйте UUID истории в move_story_to_sprint.', inputSchema: { projectId }, annotations: { readOnlyHint: true }, }, async ({ projectId }) => toText(await client.get(`/projects/${projectId}/groups`))); diff --git a/alfy-mcp/tests/tools/groups.spec.ts b/alfy-mcp/tests/tools/groups.spec.ts index dd83e7f..d3bd972 100644 --- a/alfy-mcp/tests/tools/groups.spec.ts +++ b/alfy-mcp/tests/tools/groups.spec.ts @@ -37,6 +37,51 @@ describe('эпики и истории через MCP', () => { expect(deletion?.description).toContain('все его истории'); }); + it('публикует перестановку как идемпотентную команду', async () => { + const { tools } = await client.listTools(); + const tool = tools.find(t => t.name === 'reorder_project_groups'); + expect(tool).toBeDefined(); + expect(tool?.annotations).toMatchObject({ readOnlyHint: false, destructiveHint: false, idempotentHint: true }); + }); + + it.each([[STORY, EPIC], [EPIC]])('передаёт порядок %j одним PATCH без изменения списка', async (...orderedIds) => { + for (let i = 0; i < 2; i++) { + const result = await client.callTool({ name: 'reorder_project_groups', arguments: { projectId: PROJECT, orderedIds } }); + expect(result.isError).not.toBe(true); + expect(result.content).toEqual([{ type: 'text', text: '{"ok":true}' }]); + } + expect(rest.patch).toHaveBeenCalledTimes(2); + expect(rest.patch).toHaveBeenLastCalledWith(`/projects/${PROJECT}/groups/reorder`, { orderedIds }); + expect(rest.get).not.toHaveBeenCalled(); + }); + + it.each([ + {}, + { projectId: PROJECT }, + { projectId: 'bad', orderedIds: [EPIC] }, + { projectId: PROJECT, orderedIds: [] }, + { projectId: PROJECT, orderedIds: ['bad'] }, + { projectId: PROJECT, orderedIds: [EPIC, EPIC] }, + { projectId: PROJECT, orderedIds: null }, + ])('отклоняет некорректную перестановку %j до REST', async (args) => { + const result = await client.callTool({ name: 'reorder_project_groups', arguments: args }); + expect(result.isError).toBe(true); + expect(rest.patch).not.toHaveBeenCalled(); + }); + + it.each([ + [400, 'Only sibling groups can be reordered'], + [400, 'All groups must belong to this project'], + [403, 'Project belongs to another user'], + [404, 'Project not found'], + [500, 'Storage failure'], + ] as const)('не сообщает успех при ошибке REST %s: %s', async (status, message) => { + rest.patch.mockRejectedValue(new RestError(status, message)); + const result = await client.callTool({ name: 'reorder_project_groups', arguments: { projectId: PROJECT, orderedIds: [EPIC] } }); + expect(result.isError).toBe(true); + expect(JSON.stringify(result.content)).toContain(message); + }); + it('создаёт эпик без родителя и возвращает UUID для дальнейших действий', async () => { const data = { id: EPIC, projectId: PROJECT, type: 'epic', title: 'Релиз', parentId: null }; rest.post.mockResolvedValue(data); diff --git a/docs/tasks/mcp-group-order.md b/docs/tasks/mcp-group-order.md new file mode 100644 index 0000000..3c747e9 --- /dev/null +++ b/docs/tasks/mcp-group-order.md @@ -0,0 +1,46 @@ +# Порядок эпиков и историй через MCP + +**Status:** done +**Branch:** codex/mcp-group-order +**Worktree:** /Users/v/projects/Alfy/.worktrees/mcp-group-order +**Mode:** interactive +**Goal:** Агент через MCP переставляет эпики проекта и истории внутри эпика; последующее чтение дерева возвращает сохранённый порядок, используемый доской. Useless if: меняется только ответ MCP; перемещаются родители или задачи; смешиваются чужие проекты или истории разных эпиков. + +## Context +- main ea4e243 содержит проверенный атомарный PATCH /projects/:projectId/groups/reorder, используемый стрелками доски. +- MCP умеет читать и изменять группы, но не публикует перестановку. + +## Design +Один инструмент reorder_project_groups(projectId, orderedIds), тонкая обёртка над существующим REST. Список идёт сверху вниз; все UUID принадлежат одному уровню одного проекта. Частичный список поднимает указанных соседей наверх, остальных сохраняет следом в прежнем порядке. Полный список позволяет задать точную перестановку. Возвращать {ok:true} только после успешной записи. Альтернативы — отдельные инструменты для эпиков/историй или команды вверх/вниз — добавляют дублирование и чтения; общий список соответствует существующему API. TDD: yes. + +### Invariants +- IV1 — Один вызов MCP делает один PATCH; projectId не попадает в body. +- IV2 — Пустой список, неверные UUID и дубликаты отклоняются до REST; ограничения уровня и доступа остаются на бэкенде. +- IV3 — Ошибки REST видны агенту, успешная команда не меняет связи групп/задач. +- IV4 — Новый порядок сохраняется и читается через list_project_groups. + +## Plan +### PH1 — Инструмент и контракт +- alfy-mcp/src/tools/groups.ts:15-63 — registerGroupTools: добавить reorder_project_groups с непустым массивом уникальных UUID и возвращаемым подтверждением. +- alfy-mcp/src/tools/sprints.ts:63-68 — описание list_project_groups направляет к перестановке. +- alfy-mcp/tests/tools/groups.spec.ts:1-153 — MCP SDK: регистрация, маршрутизация, валидация, ошибки и повторяемость вызова. +- alfy-mcp/README.md:114-125 — порядок сверху вниз, границы, частичный список, примеры для эпиков/историй. +- Commit: feat(mcp): reorder project epics and stories + +### Validation +RED→GREEN MCP-тесты, build/lint; MCP SDK → настоящий REST → SQLite → повторное чтение дерева для обоих уровней и негативного смешения. Независимое ревью перед PR. + +### Hands-off decisions +- План автоматически одобрен пользователем; PR и слияние разрешены. Изменений REST/клиента и миграций не требуется. + +## Verify +Result: passed +- RED: 8 новых проверок падали из-за отсутствия инструмента; GREEN: все 192 MCP-теста (15 новых), build, lint и diff-check прошли. +- CK1 (IV1, IV2) — SDK проверяет регистрацию, единственный PATCH, сохранение списка, повторный вызов и отказ до REST для пустых/невалидных/повторных UUID. +- CK2 (IV3) — ошибки REST 400/403/404/500 возвращаются агенту как isError. +- CK3 (IV3, IV4) — настоящий MCP SDK → AlfyRestClient → NestJS → SQLite: четыре эпика и четыре истории переставлены 1,2,3,4 → 3,4,1,2; повторное чтение подтвердило сохранение, повторный вызов не меняет итог, привязка задачи сохранена. +- CK4 — смешение уровней, родителей и проектов отклонено без изменения дерева; частичный список поднимает выбранный эпик, сохраняя остальных. +- Стенд использовал неизменённый backend из соседнего worktree epic-story-order (тот же код, что в main ea4e243), временную SQLite и локальный HTTP; данные пользователя не затронуты. Лог /private/tmp/mcp-order-smoke.log. + +## Conclusion +Цель подтверждена полным MCP→REST→SQLite циклом и повторным чтением; IV1–IV4 соблюдены. Независимое ревью c54f934 не выявило замечаний и повторно запустило все 40 тестов groups.spec.ts. Документация MCP обновлена; дополнительных изменений CLAUDE.md или корневого README не требуется.