Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions alfy-mcp/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
Expand Down Expand Up @@ -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 })` позволяет проверить сохранённый порядок. Каждый вызов сохраняется отдельно и атомарно.
16 changes: 15 additions & 1 deletion alfy-mcp/src/tools/groups.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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.',
Expand Down Expand Up @@ -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('Подтверждение удаления группы, включая дочерние истории эпика') },
Expand Down
2 changes: 1 addition & 1 deletion alfy-mcp/src/tools/sprints.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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`)));
Expand Down
45 changes: 45 additions & 0 deletions alfy-mcp/tests/tools/groups.spec.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down
46 changes: 46 additions & 0 deletions docs/tasks/mcp-group-order.md
Original file line number Diff line number Diff line change
@@ -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 не требуется.
Loading