@deepsoul/agentic-planning-mcp

MCP-Server für Cursor: holt agent-ready Ticket-Kontext aus GitHub Issues (DoR-Gate, Arbeitsauftrag Branch → Code → PR). Optional hängt er Design-Screenshots als Bild-Content an.

Tickets werden im Agentic Sprint Planning Dashboard angelegt und durchlaufen dort den gesamten Workflow von Refinement und Definition of Ready bis zum Sprint-Commitment. Der MCP-Server liest dieselben Issues und liefert Cursor den Arbeitsauftrag — unabhängig vom Dashboard-Clone.

Überblick

1. Board-Account + Workspace auf https://flow-agt.run
2. GitHub-Repo + PAT im Admin hinterlegen
3. Ein Setup-Befehl erzeugt `.cursor/mcp.json` + Cursor Skill im Code-Repo
4. Agent-ready Ticket → /agentic-planning PREFIX-123

Code-Repo (bei jedem Entwickler)
  ├── .cursor/mcp.json     ← lokal, Secrets; startet npx @deepsoul/agentic-planning-mcp
  └── .cursor/skills/…     ← commitbar

Cursor → MCP get_ticket_context → GitHub Issues API
Dashboard (https://flow-agt.run) → dieselbe Issue-Source of Truth

Quick start (Cursor)

Im Code-Repo ausführen:

npx -y @deepsoul/agentic-planning-mcp init

Der Befehl erzeugt:

• .cursor/skills/agentic-planning/SKILL.md — sichtbarer, commitbarer Workflow für Cursor
• .cursor/mcp.json — lokale MCP-Konfiguration mit Platzhaltern für Secrets
• den Eintrag .cursor/mcp.json in .gitignore

Anschließend GITHUB_TOKEN und GITHUB_REPO in .cursor/mcp.json eintragen.

Kein npm install nötig: Das Paket ist ein ausführbares MCP-Tool, keine Library-Dependency des Zielprojekts. npx lädt und startet es bei Bedarf; dadurch entsteht kein Eintrag in package.json und keine dauerhafte Kopie im lokalen node_modules.

Bestehende Dateien werden nicht überschrieben. Ein bewusstes Zurücksetzen auf die Paketvorlagen ist möglich mit:

npx -y @deepsoul/agentic-planning-mcp init --force

Danach Cursor neu laden (Reload Window) → Settings → MCP → agentic-planning sollte verbunden sein. Dann zum Beispiel:

/agentic-planning AGT-102

Environment

| Variable | Pflicht | Bedeutung | |---|---|---| | GITHUB_TOKEN | ja | Fine-grained PAT mit mindestens Issues: Read (Board braucht Read/Write + Discussions) | | GITHUB_REPO | ja | owner/repo mit den Ticket-Issues | | DASHBOARD_URL | nein | Board-URL für optionalen Gemini-Prompt (Prod: https://flow-agt.run) | | MCP_API_TOKEN | nein | Bearer für die Prompt-API des Boards |

PAT-Empfehlung

Fine-grained PAT, nur Ziel-Repo:

• Issues → Read and write (MCP: mindestens Read)
• Discussions → Read and write (Board-Chat)
• Metadata → Read

Im Dashboard unter /admin speichern. Denselben (oder einen Read-only) Token in .cursor/mcp.json eintragen.

Tool

get_ticket_context

| Input | Beschreibung | |---|---| | ticketId | z. B. AGT-102 | | locale | optional de | en | | includeGeneratedPrompt | optional; Gemini-Prompt über Board-API (braucht MCP_API_TOKEN) |

Verhalten:

• Liest das Issue mit Titel [TICKET-ID] …
• Prüft Definition of Ready (6 Kriterien) — bei Lücken: Fehler mit missingDoR, keine Implementierung
• Liefert Markdown-Arbeitsauftrag inkl. Branch-Name und strikter Code-Pfade
• Design-Screenshots aus dem Issue-Frontmatter als MCP-Image-Parts

Issue-Format

Titel:

[AGT-102] Kurzer Ticket-Titel

Body: YAML-Frontmatter + Markdown-DoR-Sektionen (schreibt das Board automatisch bei Hybrid-Sync):

---
ticket_id: AGT-102
type: feat          # fix | feat | refac | chore
scope: M            # S | M | L
risk: low           # low | med | high
craft: frontend     # frontend | backend (optional)
figma_url: null
mitigation_plan: ""
dor:
  goal: true
  acceptance: true
  contracts: true
  design: true
  testStrategy: true
  dependencies: true
design_screenshots: []   # optional: [{ id, url, path, contentType }]
---

DoR-Sektionen im Markdown (alle 6 müssen erfüllt sein → agent-ready):

| Key | Überschrift | Checkliste | |---|---|---| | goal | ## Ziel | Ziel klar definiert | | acceptance | ## Akzeptanzkriterien | Akzeptanzkriterien testbar | | contracts | ## Betroffene Code-Pfade | Betroffene Code-Pfade benannt | | design | ## Design | API/Design festgelegt | | testStrategy | ## Teststrategie | Teststrategie definiert | | dependencies | ## Abhängigkeiten | Keine blockierenden Abhängigkeiten |

Branch-Konvention aus dem Auftrag: {type}/{TICKET-ID}/{slug} (z. B. feat/AGT-102/onboarding-status-ux).

Erstes Ticket

1. Auf flow-agt.run Ticket anlegen und DoR 6/6 setzen (Issue [PREFIX-n] …).
2. Im Code-Repo-Chat: /agentic-planning PREFIX-n
3. Erwartung: MCP liefert Arbeitsauftrag → Branch → Code nur in erlaubten Pfaden → Draft-PR

Checkliste

• [ ] Workspace + Prefix + Lead-Rolle auf dem Board
• [ ] Admin: githubRepo + PAT
• [ ] npx -y @deepsoul/agentic-planning-mcp init im Zielrepo ausgeführt
• [ ] Token + GITHUB_REPO in der erzeugten .cursor/mcp.json
• [ ] Erzeugten Skill unter .cursor/skills/agentic-planning/ committen
• [ ] Issue [PREFIX-n] DoR 6/6
• [ ] Reload → /agentic-planning PREFIX-n

Häufige Fehler

| Symptom | Ursache | Fix | |---|---|---| | Paket liegt in node_modules / package.json | npm install statt Setup-Befehl verwendet | Dependency entfernen und npx -y @deepsoul/agentic-planning-mcp init ausführen | | MCP startet nicht / Package not found | Netzwerk / Cache | npx -y @deepsoul/agentic-planning-mcp@latest bzw. Cursor neu laden | | GITHUB_TOKEN ist nicht gesetzt | Env fehlt in mcp.json | Token in env eintragen | | Kein GitHub-Issue … | Falsches Repo / Titel | GITHUB_REPO + Titel [PREFIX-123] | | DoR-Fehler trotz Board grün | MCP liest Issue | Issue-YAML dor: prüfen, kurz warten (Sync) |

Requirements

• Node.js ≥ 20
• GitHub Issues mit Ticket-Prefix im Titel und erfülltem DoR
• Cursor mit MCP-Support

License

Teil des Agentic Sprint Planning Projekts. Nutzung im Team-Kontext des Boards (flow-agt.run).