MCP sprint tools cannot clear points/labels back to null

### Lineage `todo-mcp-clear-points-labels` (no plan ancestry) ### Repo `forgejo_admin/pal-e-docs-mcp` ### User Story As a sprint manager using MCP tools I want to clear points or labels back to null on a sprint item So that I can correct mistakes or remove stale data without direct DB access ### Context PR #32 added `points` to `move_sprint_item` and `add_sprint_item`. QA nit #1: `move_sprint_item` maps `None` to `_UNSET` (don't send), so MCP callers cannot explicitly clear points or labels back to null once set. This is a gap in the MCP-to-SDK mapping pattern — `None` means "omitted" and there's no way to say "clear this field." The SDK already distinguishes `None` from `_UNSET` internally, but the MCP layer has no way to express "clear" vs "don't touch." ### File Targets Files the agent should modify: - `src/pal_e_docs_mcp/tools/sprints.py` — `move_sprint_item` function, add clear convention Files the agent may need to verify: - `pal-e-docs-sdk/src/pal_e_docs_sdk/sprints.py` — confirm SDK `update_sprint_item` accepts `None` for clearing ### Acceptance Criteria - [ ] MCP caller can set `points` to a value (existing, works today) - [ ] MCP caller can clear `points` back to null (e.g. `points=0` or `clear_points=true`) - [ ] MCP caller can clear `labels` back to null/empty - [ ] Omitting `points`/`labels` still means "don't touch" (no regression) ### Test Expectations - [ ] Manual test: set points=3, then clear points, verify null in DB - [ ] Manual test: set labels, then clear labels, verify empty - [ ] `ruff check` and `ruff format --check` pass ### Constraints - Must not break existing callers — clearing must be opt-in (new param or sentinel value) - Follow whichever convention the SDK uses for clear vs omit - Keep it simple — prefer `points=0` means clear over adding boolean flags ### Checklist - [ ] PR opened - [ ] Tests pass - [ ] No unrelated changes ### Related - `pal-e-sprints` — project - PR #32 — QA nit #1 - `todo-mcp-clear-points-labels` — discovery note

forgejo_admin commented

2026-03-13 06:54:26 +00:00

Owner

Lineage

todo-mcp-clear-points-labels (no plan ancestry)

Repo

forgejo_admin/pal-e-docs-mcp

User Story

As a sprint manager using MCP tools
I want to clear points or labels back to null on a sprint item
So that I can correct mistakes or remove stale data without direct DB access

Context

PR #32 added points to move_sprint_item and add_sprint_item. QA nit #1: move_sprint_item maps None to _UNSET (don't send), so MCP callers cannot explicitly clear points or labels back to null once set. This is a gap in the MCP-to-SDK mapping pattern — None means "omitted" and there's no way to say "clear this field."

The SDK already distinguishes None from _UNSET internally, but the MCP layer has no way to express "clear" vs "don't touch."

File Targets

Files the agent should modify:

src/pal_e_docs_mcp/tools/sprints.py — move_sprint_item function, add clear convention

Files the agent may need to verify:

pal-e-docs-sdk/src/pal_e_docs_sdk/sprints.py — confirm SDK update_sprint_item accepts None for clearing

Acceptance Criteria

MCP caller can set points to a value (existing, works today)
MCP caller can clear points back to null (e.g. points=0 or clear_points=true)
MCP caller can clear labels back to null/empty
Omitting points/labels still means "don't touch" (no regression)

Test Expectations

Manual test: set points=3, then clear points, verify null in DB
Manual test: set labels, then clear labels, verify empty
ruff check and ruff format --check pass

Constraints

Must not break existing callers — clearing must be opt-in (new param or sentinel value)
Follow whichever convention the SDK uses for clear vs omit
Keep it simple — prefer points=0 means clear over adding boolean flags