Add a list-project-groups tool (sidebar folder groups) #3

New issue

Closed

opened 2026-08-09 19:52:04 -05:00 by mcp-gateway · 0 comments

mcp-gateway commented

2026-08-09 19:52:04 -05:00

Member

Filed from halfst/mpx-engine #120 / #137.

What's needed

A tool that lists the sidebar folder groups — the containers that hold projects — returning at minimum id and name, ideally also sort_order and any closed/archived flag.

To be clear about the level, since the two get conflated: a folder group contains projects; a column is a kanban column inside one project. list-projects already returns each project's group_id, but there is no way to enumerate the groups themselves or learn their names.

Why

Sync Operating Spec §2 defines the Work area as exactly three folder groups — Standing buckets, Efforts, Mirrors — and makes TickTick Registry the SoT for their ids:

All IDs — groups, standing buckets, efforts, mirror projects, mirror columns, and standing cards — live in TickTick Registry, the single queryable SoT.

Those three group ids are currently hand-typed constants in the Registry, and §2's reconcile rule can't verify them:

Registry refresh rule: every run, list_projects → reconcile the Registry against the live groups (add new, mark closed — never delete history, fix renames/regrouping).

The reconcile shipped in mpx-engine #137 maintains the three entry sections but cannot touch the groups: block, because there's no call that returns groups. If a group is renamed, recreated or its id changes, every id resolution downstream silently starts placing projects in the wrong section, and nothing detects it.

That's not hypothetical for this estate — §2 already records one id churning: "the old Areas of Focus id no longer exists" after a board rewrite.

Acceptance

A tool returning all folder groups with id and name.
Included: whether a group is closed/archived, if the API exposes it.
Consistent shape with list-projects (same snake_case flattening).

Unblocks

Full §2 Registry reconcile in halfst/mpx-engine — specifically the groups: block, currently the one part of the Registry the engine has to trust rather than verify.

Filed from `halfst/mpx-engine` #120 / #137. ## What's needed A tool that lists the sidebar **folder groups** — the containers that hold projects — returning at minimum `id` and `name`, ideally also `sort_order` and any closed/archived flag. To be clear about the level, since the two get conflated: a **folder group** contains projects; a **column** is a kanban column inside one project. `list-projects` already returns each project's `group_id`, but there is no way to enumerate the groups themselves or learn their names. ## Why `Sync Operating Spec` §2 defines the Work area as exactly three folder groups — Standing buckets, Efforts, Mirrors — and makes [[TickTick Registry]] the SoT for their ids: > **All IDs — groups, standing buckets, efforts, mirror projects, mirror columns, and standing cards — live in [[TickTick Registry]]**, the single queryable SoT. Those three group ids are currently **hand-typed constants** in the Registry, and §2's reconcile rule can't verify them: > **Registry refresh rule:** every run, `list_projects` → reconcile the Registry against the live groups (add new, mark `closed` — never delete history, fix renames/regrouping). The reconcile shipped in mpx-engine #137 maintains the three *entry* sections but cannot touch the `groups:` block, because there's no call that returns groups. If a group is renamed, recreated or its id changes, every id resolution downstream silently starts placing projects in the wrong section, and nothing detects it. That's not hypothetical for this estate — §2 already records one id churning: *"the old Areas of Focus id no longer exists"* after a board rewrite. ## Acceptance - [ ] A tool returning all folder groups with `id` and `name`. - [ ] Included: whether a group is closed/archived, if the API exposes it. - [ ] Consistent shape with `list-projects` (same snake_case flattening). ## Unblocks Full §2 Registry reconcile in `halfst/mpx-engine` — specifically the `groups:` block, currently the one part of the Registry the engine has to trust rather than verify.