ticket-writer MCP

Ein MCP-Server für MagOneAI. Ein Reporter gibt eine Feature-Anfrage als Freitext ein; der Workflow stellt die wenigen Fragen, die nötig sind, um sie umsetzbar zu machen, und legt dann ein Ticket an, das das Problem, die erforderlichen Schritte, die Akzeptanzkriterien und etwaige Architekturentscheidungen beschreibt.

Jira, GitHub, GitLab und Linear kommen aus demselben Codepfad.

Der Server ruft niemals einen Tracker auf. Er rendert die Create-Issue-Anfrage und gibt sie zurück; der eigene HTTP-Knoten des Workflows sendet sie.

So läuft der Workflow ab

free text  ──▶  check_request  ──"needs_clarification"──▶  ask the reporter ──┐
                     │                                                        │
                     │◀──────────────────── answers ─────────────────────────┘
                  "ready"
                     │
                     ▼
                render_ticket  ──"possible_duplicate"──▶  human confirms ──┐
                     │                                                     │
                     │◀────────── confirm_not_duplicate ───────────────────┘
              "ready_to_send"
                     │
                     ▼
          HTTP node: POST request.url  ◀── the only write in the workflow
                     │
                     ▼
              issue key + url back to the reporter

WORKFLOW.md enthält den Knoten-für-Knoten-Vertrag: exaktes Eingabe- und Ausgabe-JSON und jedes Feld, das auf dem Ticket landet.

Related MCP server: ProduckAI MCP Server

Warum er sich nicht selbst mit Jira verbindet

Der erste Entwurf enthielt einen Jira-REST-Client. Diese Version benötigte Anmeldedaten auf diesem Rechner, bekam einen Fehlermodus, bei dem das Ticket korrekt gerendert wurde und der POST fehlschlug, und band den Workflow an einen einzigen Tracker.

Stattdessen eine Anfrage zu rendern bedeutet:

• keine Anmeldedaten hier — Header tragen {{PLACEHOLDER}}-Namen, die der API-Knoten aus dem Secret-Store von MagOne einsetzt

• beliebiger Tracker — ein neuer ist ein Dict-Eintrag in src/targets.py

• Wiederverwendung dessen, was MagOne bereits hat — wenn ein Tracker-MCP verbunden ist, target="generic" verwenden und die Felder an dessen Create-Tool übergeben

• ein Genehmigungsschritt passt hinein — nichts wird geschrieben, bis nach dem Render-Aufruf

• mit pytest und sonst nichts testbar — kein Netzwerk im gesamten Repository

Er schreibt auch nicht den Ticket-Text. Der Workflow-Agent ist ein Sprachmodell und besser darin, eine weitschweifige Slack-Nachricht in eine Problembeschreibung zu verwandeln, als es jede Rubrik in diesem Repository könnte. Was dieser Server besitzt, ist der Teil, der bei jedem Lauf identisch funktionieren muss: die Checkliste, die Formulierung der Fragen, das Body-Format und der Duplikatschutz.

Tools

Alle vier sind schreibgeschützt. Jede Antwort trägt einen status, auf den die Canvas umschaltet:

Was ein Ticket vollständig macht

check_request blockiert bei vier Feldern, die in dieser Reihenfolge abgefragt werden, höchstens drei pro Runde:

1. problem — was heute wehtut, wer betroffen ist

2. goal — was existieren soll, wenn es fertig ist, als Verhalten

3. acceptance_criteria — wie ein Prüfer es annimmt oder ablehnt

4. architecture_notes — getroffene Entscheidungen, zu beachtende Einschränkungen ("none known" ist gültig, wenn das Design noch offen ist)

affected_users und out_of_scope werden gesammelt, wenn sie angeboten werden, blockieren aber nie. Eine Antwort unter 25 Zeichen oder eine, die die Frage zurückspiegelt, gilt nicht als beantwortet.

Um die Checkliste zu ändern, SLOTS in src/ticket.py bearbeiten — die Fragen, die Rangfolge und die Obergrenze folgen alle aus dieser Liste.

Ziele

Unterschiede, die der Renderer absorbiert, sodass der Agent sich nie darum kümmern muss:

• Jira möchte ADF, nicht Markdown, in description. Eine Markdown-Zeichenkette zu übergeben, ist der häufigste Grund, warum ein handverdrahteter Jira-Knoten fehlschlägt.

• GitLab möchte Labels als Komma-Zeichenkette; GitHub und Jira möchten eine Liste.

• GitHub hat kein Prioritätsfeld, daher wird Priorität zu einem priority-*-Label.

• Linear ist GraphQL — ein Endpunkt, Mutation im Body.

Einen Tracker hinzufügen: ein TARGETS-Eintrag mit einem build(), das (url, headers, body) zurückgibt. Das ist die gesamte Änderung.

Duplikatschutz

Dieser Server kann nicht suchen, daher füttert der Workflow ihn: duplicate_search_query erstellt die Abfrage, ein Suchknoten führt sie aus, die Treffer gehen zurück in render_ticket als existing_issues=[{key, summary, url}]. Zusammenfassungen mit einer Token-Überlappung von ≥ 0,6 kommen als possible_duplicate zurück.

Kein Suchknoten, keine Prüfung — das Ticket wird trotzdem gerendert. Das ist der Preis dafür, keinen eigenen Suchclient pro Tracker zu besitzen.

Ausführen

python -m venv .venv && .venv/bin/pip install -r requirements-dev.txt
.venv/bin/python -m pytest -q          # 47 tests, no network, no account

Lokales MCP über stdio, für Claude Desktop:

MCP_TRANSPORT=stdio .venv/bin/python -m src.server

Bereitstellen:

docker build -t ticket-writer .
docker run -p 8000:8000 -e TICKET_WRITER_TOKEN=$(openssl rand -hex 32) ticket-writer
curl localhost:8000/health

https://your-host/mcp in MagOneAI mit dem Header Authorization: Bearer $TICKET_WRITER_TOKEN registrieren, genau wie das Outlook-MCP konfiguriert ist. TICKET_WRITER_TOKEN ist die einzige Umgebungsvariable, die der Server benötigt; MCP_TRANSPORT, HOST, PORT und LOG_LEVEL haben funktionierende Standardwerte. max_iterations auf etwa 12 setzen.

Ein echtes Ticket anlegen, um es zu prüfen

scripts/send.py macht genau das, was der API-Knoten tut — rendern, den Platzhalter aus der gleichnamigen Umgebungsvariable einsetzen, POST:

.venv/bin/python scripts/send.py --target jira \
  --config base_url=https://you.atlassian.net project_key=KAN --dry   # payload only

export JIRA_BASIC_AUTH=$(printf '%s' 'you@mail.com:API_TOKEN' | base64)
.venv/bin/python scripts/send.py --target jira \
  --config base_url=https://you.atlassian.net project_key=KAN         # 201 + issue key

TESTING.md behandelt, was jede Suite beweist, den Live-Lauf gegen Jira Cloud und die Fehlertabelle.

Sicherheit

• Bearer-Token aus einer Umgebungsvariable, niemals über einen Workflow-Knoten — ein Token, das die Canvas durchläuft, landet in Ausführungsprotokollen.

• Keine Tracker-Anmeldedaten erreichen jemals diesen Server. Header sind Platzhalter; config nimmt Orte, keine Geheimnisse. Ein Test stellt das sicher.

• /health ist für Plattform-Probes unauthentifiziert; alles andere nicht. Der Server weigert sich, ohne gesetztes Token über HTTP zu starten.

• Nicht-Root-Container-Benutzer.

• Reporter-Text ist Daten, keine Anweisungen. Er wird wörtlich in einem Blockzitat gespeichert und niemals interpretiert. Die Tool-Docstrings sagen das, weil das ist, was der Agent liest.

• Der Duplikatschutz und die Vollständigkeitsprüfung sind das, was zwischen einem geschwätzigen Slack-Kanal und hundert Junk-Tickets steht. Fügen Sie kein Flag hinzu, das beide überspringt.

Aufbau

src/server.py    MCP surface: tool defs, transport, auth
src/ticket.py    pure: rubric, questions, body in markdown + ADF, dup scoring
src/targets.py   pure: what each tracker's API wants — one entry per tracker
tests/           47 tests: the rules, the tool surface, HTTP and auth
scripts/send.py  stands in for the API node, for end-to-end checks
WORKFLOW.md      node-by-node input/output contract
TESTING.md       what is covered, what is not

ticket.py weiß nichts über irgendeinen Tracker; targets.py weiß nichts darüber, was ein Ticket gut macht. Wenn das Hinzufügen eines Pflichtfelds bedeutet, targets.py zu bearbeiten, ist die Trennung ausgelaufen.