Scrum4Me/docs/plans/sprint-mcp-tools.md

title	status	audience	language	last_updated	applies_to
Sprint MCP-tools — create_sprint & update_sprint	draft	maintainer ai-agent	nl	2026-05-11	scrum4me-mcp

Plan — create_sprint + update_sprint in scrum4me-mcp

Context

Het runbook docs/runbooks/plan-to-pbi-flow.md (draft) beschrijft een sprint-lifecycle als onderdeel van de plan→PBI→story→task workflow:

• Bij plan-goedkeuring opent Claude een nieuwe sprint (status: OPEN)
• Na PR-merge + verify groen sluit Claude die sprint (status: CLOSED)
• Cron mag stale/falende sprints later op FAILED zetten

Hiervoor zijn twee MCP-tools nodig die nog niet bestaan in ~/Development/scrum4me-mcp/:

Tool	Wat	Wie roept aan
create_sprint	Maakt nieuwe sprint, status OPEN	Claude bij plan-goedkeuring
update_sprint	Wijzigt status / dates / sprint_goal	Claude bij PR-close & cron bij stale-detect

Door één generieke update_sprint te bouwen (i.p.v. losse close_sprint/fail_sprint) is de tool-oppervlakte minimaal en zijn alle transities tussen OPEN | CLOSED | ARCHIVED | FAILED mogelijk.

Bestaande conventies (te respecteren)

• Toolpattern: elk tool is één bestand onder ~/Development/scrum4me-mcp/src/tools/, registreert via register{ToolName}Tool(server: McpServer) in src/index.ts. Voorbeeld-template: scrum4me-mcp/src/tools/create-pbi.ts
• DB-toegang: direct via import { prisma } from '../prisma.js' — geen REST-tussenstap, geen Next-deps
• Auth: requireWriteAccess(token) + userCanAccessProduct(userId, productId) zoals in create-pbi.ts
• Error-pad: withToolErrors(...), toolError(...), toolJson(...) uit ../errors.js
• Zod-input apart gedefinieerd, status-enum gespiegeld uit Prisma
• Schema-sync: Prisma-schema is een git-submodule in vendor/scrum4me; geen schema-wijzigingen nodig (Sprint-model heeft alle statussen al)

Scope

A. create_sprint

Bestand: ~/Development/scrum4me-mcp/src/tools/create-sprint.ts

Input-schema:

const inputSchema = z.object({
  product_id: z.string().min(1),
  code: z.string().min(1).max(30).optional(),     // auto-generate als leeg
  sprint_goal: z.string().min(1).max(500),
  start_date: z.string().date().optional(),       // ISO YYYY-MM-DD; default = today
})

Gedrag:

1. requireWriteAccess(token) → user_id
2. userCanAccessProduct(user_id, product_id)
3. Code-generatie (als niet meegegeven): S-{YYYY-MM-DD}-{N} waarbij N = count(sprints van product op datum) + 1. Dezelfde retry-on-unique-conflict pattern als generateNextPbiCode().
4. prisma.sprint.create({ data: { product_id, code, sprint_goal, status: 'OPEN', start_date } })
5. Return: { id, code, status, start_date }

Niet doen: géén check op bestaande OPEN-sprints (per runbook-beslissing: "altijd nieuwe sprint").

B. update_sprint

Bestand: ~/Development/scrum4me-mcp/src/tools/update-sprint.ts

Input-schema:

const inputSchema = z.object({
  sprint_id: z.string().min(1),
  status: z.enum(['OPEN', 'CLOSED', 'ARCHIVED', 'FAILED']).optional(),
  sprint_goal: z.string().min(1).max(500).optional(),
  end_date: z.string().date().optional(),
  start_date: z.string().date().optional(),
}).refine(d =>
  d.status !== undefined || d.sprint_goal !== undefined ||
  d.end_date !== undefined || d.start_date !== undefined,
  { message: 'Minstens één veld vereist' }
)

Gedrag:

1. requireWriteAccess(token) → user_id
2. Laad sprint → check userCanAccessProduct(user_id, sprint.product_id)
3. Geen state-machine validatie in deze tool — elke status-transitie is toegestaan. Het resubmit/heropen-pad wordt elders (buiten deze MCP-tool) afgehandeld.
4. Auto-end_date: als status naar CLOSED/FAILED/ARCHIVED gaat en end_date is niet meegegeven → set op today().
5. prisma.sprint.update({ where: { id }, data: {...} })
6. Return: { id, code, status, start_date, end_date }

C. index.ts — tool-registratie

Twee regels toevoegen aan ~/Development/scrum4me-mcp/src/index.ts:

import { registerCreateSprintTool } from './tools/create-sprint.js'
import { registerUpdateSprintTool } from './tools/update-sprint.js'
// …
registerCreateSprintTool(server)
registerUpdateSprintTool(server)

Out-of-scope (apart op te pakken)

• Cron auto-close/fail: een Vercel cron-route (/api/cron/sprint-lifecycle) die OPEN-sprints scant, PR-status + verify check, en update_sprint aanroept met CLOSED of FAILED. Drempels: PR mergedAt → CLOSED, PR closed && !merged → FAILED, PR stale > 14d → FAILED. Apart PBI want vereist GitHub-API-koppeling en threshold-policy-besluiten.
• Sprint-koppeling bij create_story: runbook merkt op dat als er meerdere OPEN-sprints zijn de gebruiker moet bevestigen welke. Schoner is create_story uitbreiden met optionele sprint_id-param. Klein patch in create-story.ts, maar niet in deze PBI — eerst de basis-tools werkend hebben.
• Sprint-events / SSE: elke status-transitie zou een NOTIFY moeten emiteren zodat de UI live update. Bestaande pattern in docs/patterns/realtime-notify-payload.md. Niet in v1 van deze PBI — handmatige refresh acceptabel tot cron-flow er is.
• REST-endpoints: POST /api/sprints en PATCH /api/sprints/[id] in de Scrum4Me-app voor UI-pariteit. Niet in deze PBI — MCP gaat direct via Prisma, UI kan dat later naadloos volgen.

Testen

In scrum4me-mcp zelf (Vitest):

• create-sprint.test.ts: happy-path (alle velden + minimal), code-auto-generatie, code-conflict-retry, user-access-denied
• update-sprint.test.ts: legal transities (×3), illegal transities (×3), auto-end_date bij CLOSE/FAIL/ARCHIVE, multi-field update, access-denied

In Scrum4Me-app: één integration-test in __tests__/sprint-lifecycle.test.ts die via een geseed token de MCP-tools aanroept en het Prisma-record verifieert.

Implementatie-stappen (volgorde)

1. create-sprint.ts schrijven + registreren in index.ts
2. update-sprint.ts schrijven + registreren in index.ts
3. Unit-tests in scrum4me-mcp
4. npm run verify in scrum4me-mcp (typecheck + tests)
5. Sync naar Scrum4Me-app: sync-schema.sh is voor Prisma-schema; voor tool-discovery hoeft niets — MCP is een aparte service en de Scrum4Me-app importeert niets uit scrum4me-mcp/src/tools/
6. Update docs/runbooks/mcp-integration.md: voeg de twee tools toe aan de tool-lijst
7. Update docs/runbooks/plan-to-pbi-flow.md: verwijder de ⚠️-tooling-banner; status van draft → active
8. PR-flow zoals gewend (branch-and-commit-runbook)

Open vragen — uitgesteld tot later

Bewust pas later beslissen (niet blokkerend voor de eerste implementatie):

• code-conventie — voor v1 default S-{YYYY-MM-DD}-{N}; later evalueren of S-{N} doorlopend per product (zoals PBI-N) beter past
• Cron-drempels — pas relevant in de vervolg-PBI voor de cron zelf
• update_sprint zonder status-wijziging — toegestaan (alle velden optioneel; refine eist minstens één)

Risico's

• Multi-sprint-context bij create_story: nu impliciet (server resolveert "active sprint"). Met meerdere OPEN-sprints kan dit fout gaan. Mitigatie: korte termijn → het runbook waarschuwt, gebruiker bevestigt; lange termijn → expliciete sprint_id param in create_story.
• Cron racet met handmatige close: als gebruiker update_sprint(CLOSED) doet vóór de cron, en cron daarna FAILED zet, overschrijft cron de eerdere status. Acceptabel voor v1 — last-write-wins. Het externe resubmit-mechanisme bepaalt of een sprint überhaupt nog door cron geraakt mag worden.
• Demo-modus: demo-users mogen geen schrijfacties; requireWriteAccess checkt al op isDemo, dus geen extra werk.

Klaar wanneer

• Beide tools live in scrum4me-mcp main
• Tests groen
• mcp-integration.md tool-lijst bijgewerkt
• plan-to-pbi-flow.md banner weg + status active
• Eén end-to-end smoke-test gedraaid: create_sprint → create_pbi → ... → update_sprint(CLOSED) op een lokale dev-DB