Update sprint MCP tools for points field + new boards/column #11

New issue

Closed

opened 2026-03-06 13:04:43 +00:00 by forgejo_admin · 1 comment

forgejo_admin commented

2026-03-06 13:04:43 +00:00

Owner

Plan

plan-2026-03-01-pal-e-sprints -- Phase: Schema Expansion (phase-sprints-schema-expansion)

Repo

forgejo_admin/pal-e-docs-mcp

User Story

As Betty Sue
I want MCP tools that support the expanded sprint schema
So that I can assign points, use repo/project boards, and the needs_approval column from the main session

Context

The pal-e-docs API is being expanded with: repo/project item_types (PR #67), needs_approval column (PR #67), and a points field (separate PR). The MCP tools need to match. Existing issue #10 covers boards/column — this issue extends scope to include points. This issue should be worked AFTER both pal-e-docs PRs are merged.

File Targets

Files the agent should modify or create:

src/pal_e_docs_mcp/tools/sprints.py -- Update add_sprint_item to accept optional points param. Update item move/update to accept points. Ensure repo and project item_types work. Ensure needs_approval column works. get_sprint_board should return points.

Files the agent should NOT touch:

Non-sprint tool files -- this is sprint-only

Acceptance Criteria

add_sprint_item accepts optional points integer parameter
Item update/move accepts optional points integer parameter
get_sprint_board returns points in each item's output
repo and project item_types work in all sprint tools
needs_approval column works in all sprint tools
Tool descriptions updated to mention points, new boards, new column

Test Expectations

Manual test: add item with points via MCP tool
Manual test: update item points via MCP tool
Manual test: get_sprint_board shows points
Run command: test against running pal-e-docs instance

Constraints

Must match pal-e-docs API schema exactly
Do not break existing tool signatures — points is additive/optional
Depends on BOTH pal-e-docs PRs merging first (PR #67 + points PR)

Checklist

PR opened
Tests pass
No unrelated changes

project-pal-e-sprints -- project this affects
Existing issue #10 on this repo -- overlapping scope (boards/column)
phase-sprints-schema-expansion -- parent phase

### Plan `plan-2026-03-01-pal-e-sprints` -- Phase: Schema Expansion (`phase-sprints-schema-expansion`) ### Repo `forgejo_admin/pal-e-docs-mcp` ### User Story As Betty Sue I want MCP tools that support the expanded sprint schema So that I can assign points, use repo/project boards, and the needs_approval column from the main session ### Context The pal-e-docs API is being expanded with: repo/project item_types (PR #67), needs_approval column (PR #67), and a points field (separate PR). The MCP tools need to match. Existing issue #10 covers boards/column — this issue extends scope to include points. This issue should be worked AFTER both pal-e-docs PRs are merged. ### File Targets Files the agent should modify or create: - `src/pal_e_docs_mcp/tools/sprints.py` -- Update add_sprint_item to accept optional `points` param. Update item move/update to accept `points`. Ensure `repo` and `project` item_types work. Ensure `needs_approval` column works. get_sprint_board should return points. Files the agent should NOT touch: - Non-sprint tool files -- this is sprint-only ### Acceptance Criteria - [ ] `add_sprint_item` accepts optional `points` integer parameter - [ ] Item update/move accepts optional `points` integer parameter - [ ] `get_sprint_board` returns points in each item's output - [ ] `repo` and `project` item_types work in all sprint tools - [ ] `needs_approval` column works in all sprint tools - [ ] Tool descriptions updated to mention points, new boards, new column ### Test Expectations - [ ] Manual test: add item with points via MCP tool - [ ] Manual test: update item points via MCP tool - [ ] Manual test: get_sprint_board shows points - Run command: test against running pal-e-docs instance ### Constraints - Must match pal-e-docs API schema exactly - Do not break existing tool signatures — points is additive/optional - Depends on BOTH pal-e-docs PRs merging first (PR #67 + points PR) ### Checklist - [ ] PR opened - [ ] Tests pass - [ ] No unrelated changes ### Related - `project-pal-e-sprints` -- project this affects - Existing issue #10 on this repo -- overlapping scope (boards/column) - `phase-sprints-schema-expansion` -- parent phase

forgejo_admin referenced this issue

2026-03-06 13:40:02 +00:00

feat: add labels param and todo item_type to sprint MCP tools #13

forgejo_admin referenced this issue from a commit

2026-03-13 06:44:56 +00:00

Update sprint MCP tools for points field, repo/project boards, and needs_approval column

forgejo_admin referenced this issue from a pull request that will close it,

2026-03-13 06:45:16 +00:00

Update sprint MCP tools for points, repo/project boards, needs_approval #32

forgejo_admin commented

2026-03-13 06:47:10 +00:00

Author

Owner

PR #32 Review

BLOCKERS

None.

NITS

Cannot clear points via MCP -- move_sprint_item maps None to _UNSET (don't send), so there is no way for an MCP caller to explicitly clear points back to null. This is the same known limitation that exists for labels and is documented in the update_sprint comment block (lines 88-92). Not a regression -- just a design constraint inherited from the MCP-to-SDK mapping pattern. Worth a follow-up issue if clearing points becomes a real workflow need.
bulk_move_items passthrough assumption -- The description now advertises points as a valid key in the JSON array, but the MCP tool passes the parsed JSON list directly to the SDK, which passes it directly to the API. If the backend API's bulk endpoint does not support points in its schema, callers will get a silent drop or a validation error. Not a blocker since this is a documentation-level concern and the backend likely supports it, but worth verifying.

SOP COMPLIANCE

Branch named after issue (11-update-sprint-mcp-tools-points-boards-column)
PR body follows template (Summary, Changes, Test Plan, Review Checklist, Related)
Related references Closes #11
No secrets committed
Single file changed -- no scope creep
Commit messages are descriptive (PR title is clear)

Code Review

points in add_sprint_item: Correctly passed as points=points to SDK. SDK's add_sprint_item(points: int | None = None) only includes it in the request body when not None. No sentinel needed for creation -- correct.
points in move_sprint_item: Correctly uses _UNSET sentinel (points_val = points if points is not None else _UNSET). SDK's update_sprint_item(points: Any = _UNSET) only includes it when not _UNSET. Matches the existing labels pattern exactly.
Six boards: plan, phase, issue, todo, repo, project -- consistently listed across add_sprint_item, get_sprint_board, get_backlog, create_sprint, and bulk_move_items docstrings.
Seven columns: backlog, todo, next_up, in_progress, needs_approval, qa, done -- consistently listed across add_sprint_item, move_sprint_item, get_sprint_board, create_sprint, and bulk_move_items docstrings.
note_slug description: Correctly expanded to include repo and project alongside plan and phase.
No breaking changes: All new parameters (points) default to None. Existing signatures unchanged.
Unchanged tools correctly excluded: get_sprint, list_sprints, update_sprint, delete_sprint, remove_sprint_item -- none of these reference board types or columns, so no updates needed.

VERDICT: APPROVED

## PR #32 Review ### BLOCKERS None. ### NITS 1. **Cannot clear `points` via MCP** -- `move_sprint_item` maps `None` to `_UNSET` (don't send), so there is no way for an MCP caller to explicitly clear points back to null. This is the same known limitation that exists for `labels` and is documented in the `update_sprint` comment block (lines 88-92). Not a regression -- just a design constraint inherited from the MCP-to-SDK mapping pattern. Worth a follow-up issue if clearing points becomes a real workflow need. 2. **`bulk_move_items` passthrough assumption** -- The description now advertises `points` as a valid key in the JSON array, but the MCP tool passes the parsed JSON list directly to the SDK, which passes it directly to the API. If the backend API's bulk endpoint does not support `points` in its schema, callers will get a silent drop or a validation error. Not a blocker since this is a documentation-level concern and the backend likely supports it, but worth verifying. ### SOP COMPLIANCE - [x] Branch named after issue (`11-update-sprint-mcp-tools-points-boards-column`) - [x] PR body follows template (Summary, Changes, Test Plan, Review Checklist, Related) - [x] Related references `Closes #11` - [x] No secrets committed - [x] Single file changed -- no scope creep - [x] Commit messages are descriptive (PR title is clear) ### Code Review - **`points` in `add_sprint_item`**: Correctly passed as `points=points` to SDK. SDK's `add_sprint_item(points: int | None = None)` only includes it in the request body when not None. No sentinel needed for creation -- correct. - **`points` in `move_sprint_item`**: Correctly uses `_UNSET` sentinel (`points_val = points if points is not None else _UNSET`). SDK's `update_sprint_item(points: Any = _UNSET)` only includes it when not `_UNSET`. Matches the existing `labels` pattern exactly. - **Six boards**: `plan`, `phase`, `issue`, `todo`, `repo`, `project` -- consistently listed across `add_sprint_item`, `get_sprint_board`, `get_backlog`, `create_sprint`, and `bulk_move_items` docstrings. - **Seven columns**: `backlog`, `todo`, `next_up`, `in_progress`, `needs_approval`, `qa`, `done` -- consistently listed across `add_sprint_item`, `move_sprint_item`, `get_sprint_board`, `create_sprint`, and `bulk_move_items` docstrings. - **`note_slug` description**: Correctly expanded to include `repo` and `project` alongside `plan` and `phase`. - **No breaking changes**: All new parameters (`points`) default to `None`. Existing signatures unchanged. - **Unchanged tools correctly excluded**: `get_sprint`, `list_sprints`, `update_sprint`, `delete_sprint`, `remove_sprint_item` -- none of these reference board types or columns, so no updates needed. ### VERDICT: APPROVED

forgejo_admin closed this issue

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