Hierarchy parity: public REST API v1 and MCP expose parentId #110

New Issue

fable-5 · 2026-07-14T09:32:44+02:00

fable-5 commented

2026-07-14 09:32:44 +02:00

Context

Machine surfaces should see and shape the page tree. ZIP export / Markdown import stay flat for now (round-trip fidelity of backup and the pandoc import pipeline would otherwise all need changes for a purely organizational field) — documented as an accepted gap.

Scope

/api/public/v1 (apps/api/src/public-api/): parentId (and parent slug) in page list/detail responses; optional parent (slug) on page create; a move operation (reuse the internal reposition semantics). Update the hand-maintained OpenAPI document + the two-way route-coverage test.
MCP (apps/api/src/mcp/mcp-tools.ts + service): list_pages returns parent (slug); create_page accepts optional parent slug; depth/cycle errors map to MCP tool errors with the api error code.
Docs: note the flat-export limitation and the new fields in docs/manual/api-guide.md, docs/manual/mcp-guide.md, docs/features.md.

Acceptance criteria

OpenAPI matches the implemented behavior (coverage test green).
Public-API create-under-parent and move validate pond/depth/cycle like the internal API.
MCP create_page with parent places the page; invalid parent yields a tool error with the api code.
DB e2e tests for both surfaces.

Technical notes

Remember the tsc-OOM trap: stay on the low-level MCP Server + hand-written tool table.

Dependencies

Requires #106, #107.

Size

~1 day.

## Context Machine surfaces should see and shape the page tree. ZIP export / Markdown import stay **flat** for now (round-trip fidelity of backup and the pandoc import pipeline would otherwise all need changes for a purely organizational field) — documented as an accepted gap. ## Scope - `/api/public/v1` (`apps/api/src/public-api/`): `parentId` (and parent slug) in page list/detail responses; optional `parent` (slug) on page create; a move operation (reuse the internal reposition semantics). Update the hand-maintained OpenAPI document + the two-way route-coverage test. - MCP (`apps/api/src/mcp/mcp-tools.ts` + service): `list_pages` returns `parent` (slug); `create_page` accepts optional `parent` slug; depth/cycle errors map to MCP tool errors with the api error code. - Docs: note the flat-export limitation and the new fields in `docs/manual/api-guide.md`, `docs/manual/mcp-guide.md`, `docs/features.md`. ## Acceptance criteria - [ ] OpenAPI matches the implemented behavior (coverage test green). - [ ] Public-API create-under-parent and move validate pond/depth/cycle like the internal API. - [ ] MCP `create_page` with `parent` places the page; invalid parent yields a tool error with the api code. - [ ] DB e2e tests for both surfaces. ## Technical notes - Remember the tsc-OOM trap: stay on the low-level MCP `Server` + hand-written tool table. ## Dependencies Requires #106, #107. ## Size ~1 day.

fable-5 added this to the M12 — Page hierarchy & knowledge graph milestone 2026-07-14 09:32:44 +02:00

fable-5 added the

docs

backend

labels 2026-07-14 09:32:44 +02:00

fable-5 referenced this issue from a commit

2026-07-14 10:49:53 +02:00

Page-tree parity for the public REST API and MCP (#110)

fable-5 commented

2026-07-14 11:22:26 +02:00

Implemented in ffcc337. REST: page list/detail carry parent (the parent's slug, nulled when the token's user may not read it), create accepts parent, PATCH moves with parent (slug nests, null → top level, appended at the end of the new sibling group via PagesService.moveToEnd); OpenAPI updated, coverage test green. MCP: list_pages returns parent, create_page/update_page take it; page_cycle surfaces as a tool error (covered in the MCP e2e pack). ZIP export stays flat — documented in features.md.

Implemented in ffcc337. REST: page list/detail carry `parent` (the parent's slug, nulled when the token's user may not read it), create accepts `parent`, PATCH moves with `parent` (slug nests, null → top level, appended at the end of the new sibling group via `PagesService.moveToEnd`); OpenAPI updated, coverage test green. MCP: `list_pages` returns `parent`, `create_page`/`update_page` take it; `page_cycle` surfaces as a tool error (covered in the MCP e2e pack). ZIP export stays flat — documented in features.md.

fable-5 closed this issue

2026-07-14 11:22:26 +02:00

Sign in to join this conversation.