feat: iterations CRUD — create_iteration & update_iteration tools

[Hakihiro]

Context

The MCP currently exposes only list_iterations (read-only) for GitLab iterations. Sprint planning workflows (e.g. the wana-gitlab:sprint skill in wanadev-marketplace) need to create new iterations and publish their description (Sprint Goal + Capacity table) — currently both fall back to raw glab api calls because there is no MCP coverage.

Needs

Endpoint	Method	Scope	Purpose
groups/{group}/iterations	POST	group	Create a new iteration when no current one exists
groups/{group}/iterations/{iid}	PUT	group	Publish iteration description (Sprint Goal + Capacity table)

Both endpoints are documented as needs in the consumer's API registry:

{
  "endpoint": "groups/{group}/iterations",
  "method": "POST",
  "scope": "group",
  "used_by": ["wana-gitlab/skills/sprint/SKILL.md"],
  "purpose": "Create a new iteration when no current one exists (no MCP coverage)"
},
{
  "endpoint": "groups/{group}/iterations/{iid}",
  "method": "PUT",
  "scope": "group",
  "used_by": ["wana-gitlab/skills/sprint/SKILL.md"],
  "purpose": "Publish iteration description (Sprint Goal + Capacity table — no MCP coverage)"
}

Proposed tools

create_iteration

Param	Type	Description
group_id	string	GitLab group ID or full path (existing groupIdSchema)
title	string?	Iteration title (optional — GitLab can auto-generate from cadence)
description	string?	Iteration description (markdown)
start_date	string	ISO date YYYY-MM-DD
due_date	string	ISO date YYYY-MM-DD
dry_run	boolean	Preview-only (default true, project convention)

update_iteration

Param	Type	Description
group_id	string	GitLab group ID or full path
iteration_iid	number	Per-group iteration iid (REST path uses iid, not global id — the two are not interchangeable)
title	string?	New title
description	string?	New description (markdown)
start_date	string?	New start date
due_date	string?	New due date
dry_run	boolean	Preview-only (default true)

Implementation notes

• The existing setEpicIteration (src/client.ts:371) uses the GraphQL Work Items API and is unrelated — it links an iteration to an epic, it does not mutate the iteration itself.
• REST POST /groups/:id/iterations and PUT /groups/:id/iterations/:iid exist on GitLab 18.x (verified in production at git.wanadev.org). They are partially undocumented but stable; older instances may 404, in which case a fallback to the GraphQL iterationCreate mutation should be considered.
• The id ↔ iid distinction matters: GraphQL mutations and mcp__gitlab__update_issue expect the global iteration_id, while REST paths take the per-group iid. The new tools should follow the REST convention (iid in path) and document this clearly.
• Group path must be URL-encoded in the path segment (slashes become %2F).
• Both tools are write operations → must follow the project's dry_run=true default and readOnlyHint: false annotation.

Smoke-test impact

test/smoke.test.mjs should be updated:

• EXPECTED_TOOLS: add create_iteration, update_iteration (count goes from 56 → 58).
• WRITE_TOOLS: add both.
• GROUP_SCOPED_TOOLS: add both.

README impact

The "Iterations" section currently lists 1 tool (list_iterations). It should grow to 3 tools.

Why upstream this

This is the second consumer-side workaround that calls glab api directly for iteration mutation (the first being iteration assignment, tracked in #44). Closing the gap in the MCP removes the glab shell dependency from the sprint planning flow and makes the skill portable to any MCP-only host (Claude Desktop, etc.).

[Hakihiro]

Implemented — create_iteration and update_iteration tools now exist in src/tools/utils.ts, along with list_iterations.