Add next-work dismiss, restore and list tools to kcap mcp workitems

[realtonyyoung]

Closes #1150 — AI-3184

What & why

Adds dismiss_next_work, restore_next_work and list_dismissed_next_work to kcap mcp workitems, so an agent presenting next work can record that the user turned a suggestion down and offer the next one. They call the server's /api/next-work/dismissals routes; the dismiss and restore responses carry the refreshed page one to offer next.

Where to look

A not_presented refusal (409) surfaces as a tool error carrying the code, meaning the item is no longer a current suggestion. The server routes ship in kurrent-io/kcap-server#2055; against an older server the tools get a 404.

Verification

Tool-list schemas, each tool's route and body (with repo_hash included or omitted), the 409 relay and the missing-target_key short-circuit are covered by McpWorkItemsServerTests; an AOT publish showed no trim or AOT warnings.

🤖 Generated with Claude Code

[linear-code]

AI-3184

[qodo-code-review]

PR Summary by Qodo

Add next-work dismissal tools to the workitems MCP server

✨ Enhancement 🧪 Tests 📝 Documentation 🕐 20-40 Minutes

AI Description

• Adds MCP tools to dismiss, restore, and list dismissed next-work suggestions.
• Routes suggestion actions to dismissal APIs with local argument validation.
• Documents behavior and tests schemas, payloads, conflicts, and network short-circuiting.

Diagram

sequenceDiagram
    actor Agent
    participant MCP as Workitems MCP
    participant Validation as Argument Validation
    participant API as Next Work API
    Agent->>MCP: Dismiss or restore
    MCP->>Validation: Require target key
    Validation-->>MCP: Build scoped body
    MCP->>API: POST dismissal route
    alt Request accepted
        API-->>MCP: Refreshed page one
        MCP-->>Agent: Tool result
    else Not presented
        API-->>MCP: 409 not presented
        MCP-->>Agent: Tool error
    end
    Agent->>MCP: List dismissed
    MCP->>API: GET dismissals
    API-->>MCP: Dismissed suggestions
    MCP-->>Agent: Tool result

Loading

High-Level Assessment

The current approach is appropriate because these tools are thin extensions of the existing centralized MCP dispatch and schema model. A dedicated next-work API client or separate MCP server would add abstraction and registration overhead without enough behavior to justify it; the shared payload builder already removes the meaningful duplication.

Files changed (4) +136 / -9

Enhancement (1) +35 / -2

McpWorkItemsServer.csImplement next-work dismissal MCP dispatch +35/-2

Implement next-work dismissal MCP dispatch

• Registers three MCP tools and routes them to the next-work dismissal endpoints. Adds required target-key validation, optional repository scoping, suitable tool annotations, and agent-facing usage guidance.

src/Capacitor.Cli/Commands/McpWorkItemsServer.cs

Tests (1) +84 / -1

McpWorkItemsServerTests.csTest next-work schemas, routes, payloads, and errors +84/-1

Test next-work schemas, routes, payloads, and errors

• Covers tool registration and schemas, POST and GET routing, optional repo_hash serialization, 409 error relay, missing-target short-circuiting, and server instructions.

test/Capacitor.Cli.Tests.Unit/Commands/McpWorkItemsServerTests.cs

Documentation (2) +17 / -6

README.mdDocument next-work dismissal MCP tools +5/-2

Document next-work dismissal MCP tools

• Updates the workitems MCP overview from ten to thirteen tools and documents dismiss, restore, and list behavior, including refreshed suggestions and not-presented refusals.

README.md

help-mcp.txtExpand CLI help with next-work tools +12/-4

Expand CLI help with next-work tools

• Updates the workitems tool count and command help to describe dismissal, restoration, and dismissed-suggestion listing.

src/Capacitor.Cli.Core/Resources/help-mcp.txt

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. The commit fails subject validation ✗ Dismissed 📘 Rule violation ⚙ Maintainability

Description

The commit subject Add next-work dismiss, restore and list tools to kcap mcp workitems does not
end with a GitHub issue reference in the required (#<digits>) form. Automated validation of this
commit metadata therefore rejects the subject when enforcing the repository’s merge format.

Code

README.md[715]

+It provides thirteen tools:

Relevance

●●● Strong

The repository explicitly enforces issue-linked commit subjects; this deterministic metadata
violation is straightforward to correct.

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

PR Compliance ID 2897961 requires every commit subject to end with exactly one GitHub issue
reference. The supplied commit subject has no such reference.

Rule 2897961: Enforce single-clause imperative commit subject with GitHub issue reference and 80-char limit

---

2. The PR lacks required issue links ✗ Dismissed 📘 Rule violation § Compliance

Description

The description’s reference line contains AI-3184 but no GitHub closing keyword and issue
reference. This leaves the required GitHub and Linear references incomplete whenever the PR metadata
is checked for traceability.

Code

README.md[713]

+Stdio MCP server that lets coding agents correlate the current session to the SDLC work item (issue/PR) it belongs to, **declare that work item's structure** — its breakdown into parts and its blocks/blocked-by dependencies — read that structure back, and dismiss or restore next-work suggestions. Registered for every supported harness by `kcap setup` / `kcap plugin install` (Claude Code reads it from the plugin's bundled `.mcp.json`).

Relevance

●●● Strong

Recent accepted precedent confirms required PR reference-line enforcement, including GitHub closing
and Linear references.

PR-#659

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

PR Compliance ID 2897991 requires one reference line containing both a GitHub closing reference and
a Linear issue key. The supplied PR description starts with `AI-3184 (no GitHub issue exists for
this)` and contains no closing GitHub reference.

Rule 2897991: PR description must contain both GitHub and Linear issue references; PR title must not contain issue IDs

---

3. Agents can restore without approval ✓ Resolved 🐞 Bug ⛨ Security

Description

restore_next_work uses the non-destructive Upsert annotation even though it removes an existing
dismissal. When an MCP client derives approval policy from these hints, restoring a user-dismissed
suggestion reaches the mutation route without being classified as destructive.

Code

src/Capacitor.Cli/Commands/McpWorkItemsServer.cs[506]

+            }, ["target_key"]), McpToolAnnotations.Upsert),

Relevance

●●● Strong

A recent accepted finding required destructive annotations for mutation-like MCP operations
affecting existing state.

PR-#1112

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The restore tool explicitly says it undoes a dismissal and dispatches to a mutating restore route,
but its changed declaration selects Upsert. The shared annotation definitions state that Upsert
has DestructiveHint: false, while operations removing existing state must use Destructive; the
same file notes that harnesses may decide approval behavior from these annotations.

src/Capacitor.Cli/Commands/McpWorkItemsServer.cs[180-185]
src/Capacitor.Cli/Commands/McpWorkItemsServer.cs[501-506]
src/Capacitor.Cli/Commands/McpToolAnnotations.cs[3-20]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`restore_next_work` removes an existing dismissal but advertises the non-destructive `Upsert` annotation, allowing MCP approval layers to under-classify the mutation.

## Fix Focus Areas
- src/Capacitor.Cli/Commands/McpWorkItemsServer.cs[501-506]
- src/Capacitor.Cli/Commands/McpToolAnnotations.cs[11-20]

## Recommended Fix
Change `restore_next_work` to use `McpToolAnnotations.Destructive`, and add a tool-list assertion verifying that its destructive hint is true.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Context sources

✅ Compliance rules (platform): 64 rules

✅ Cross-repo context — repo relationships

  Explored: repo: kurrent-io/kcap-server (branch: claude-tyoung/ai-3184-implementation-fe87aa, sha: a1cd614d) — View relationship

Review mode: ⚖️ Balanced: This adds three runtime MCP tools with new routes, request validation, error propagation, and public tool contracts, creating meaningful behavioral and compatibility risk despite focused scope.

Tip of the day

💡 Did you know, you can type 'qodo, fix this' on a finding and the fix lands right on your PR

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[realtonyyoung]

The two open Qodo rule items are stale: the PR description's reference line is Closes #1150 — AI-3184, and both non-merge commits end with (#1150) (Add next-work dismiss, restore and list tools to kcap mcp workitems (#1150), Mark restore_next_work destructive (#1150)). The squash subject gets the PR number appended by GitHub, per this repo's title rule.

🤖 Addressed by Claude Code