backlog-mcp MCP server

backlog-mcp

Ein MCP-Server, der KI-Agenten strukturierten Lese-/Schreibzugriff auf ein storybasiertes Projekt-Backlog ermöglicht. Agenten können Stories auflisten, Inhalte lesen, den Status aktualisieren und Notizen hinzufügen – alles basierend auf einfachen Markdown-Dateien, die sich in Ihrem Projekt-Repository befinden.

Wie die Zusammenarbeit funktioniert

Es gibt keinen gemeinsam genutzten Server. Die Backlog-Dateien liegen in Ihrem Repo unter requirements/, werden dort committet und zusammen mit Ihrem Code versioniert. Die Zusammenarbeit zwischen Agenten oder zwischen einem Agenten und einem Menschen funktioniert genau so wie der Rest Ihrer Codebasis: über git. Wenn zwei Agenten gleichzeitig unterschiedliche Stories aktualisieren, führt git sie zusammen. Wenn sie dieselbe Zeile bearbeiten, lösen Sie dies wie jeden anderen Merge-Konflikt.

Der MCP-Server ist ein lokaler Prozess, den jeder Agent für sich selbst ausführt. Er liest und schreibt Dateien; git erledigt den Rest.

Installation

Laden Sie das neueste Binary für Ihre Plattform von der Releases-Seite herunter und legen Sie es irgendwo in Ihren $PATH.

Oder, falls Sie Go installiert haben:

go install github.com/corbym/backlog-mcp@latest

Aus dem Quellcode bauen

go mod tidy
go build -o backlog-mcp .

Einrichtung

Initialisieren Sie einen requirements/-Ordner in Ihrem Projekt-Root:

./backlog-mcp init /path/to/your/project/requirements

Dies erstellt:

requirements/
  requirements-index.md   # master index — source of truth for epics and story status
  backlog.md              # priority-ordered list of not-done stories
  epic-001-example/
    story-001.md          # example story file

Committen Sie den requirements/-Ordner in Ihr Repo. Bearbeiten Sie die Dateien, um Ihre eigenen Epics und Stories hinzuzufügen.

Ausführung

./backlog-mcp

Der Server sucht nach einem requirements/-Verzeichnis relativ zum Arbeitsverzeichnis, aus dem er gestartet wird. Claude Code setzt das Arbeitsverzeichnis auf das Projekt-Root, daher ist keine Konfiguration erforderlich.

Claude Code Konfiguration (.claude/settings.json in Ihrem Projekt oder ~/.claude/settings.json global):

{
  "mcpServers": {
    "backlog-mcp": {
      "command": "/path/to/backlog-mcp"
    }
  }
}

Tools

Tool	Beschreibung
`list_stories`	Stories auflisten, optional gefiltert nach `epic_id` oder `status`
`get_story`	Vollständigen Markdown-Inhalt und Metadaten für eine Story abrufen
`set_story_status`	Story-Status im Index und Backlog aktualisieren
`add_story_note`	Eine mit Zeitstempel versehene Notiz an eine Story-Datei anhängen
`complete_story`	Eine Story als erledigt markieren und in einem Aufruf eine obligatorische Abschlusszusammenfassung anhängen
`create_epic`	Ein neues Epic erstellen — weist die nächste EPIC-NNN ID zu, schreibt die Epic-Datei, registriert sie im Index
`create_story`	Eine neue Story unter einem Epic erstellen — weist die nächste STORY-NNN ID zu, registriert sie im Index und Backlog
`set_acceptance_criteria`	Den Abschnitt für Akzeptanzkriterien einer Story ersetzen (idempotent)
`get_index_summary`	Zusammenfassung der Epic-/Story-Anzahl nach Status

Umgebungsvariablen

Variable	Erforderlich	Standard	Beschreibung
`BACKLOG_ROOT`	nein	`requirements`	Pfad zum requirements-Verzeichnis überschreiben
`BACKLOG_TRANSPORT`	nein	`stdio`	Auf `http` für HTTP/SSE-Modus setzen
`BACKLOG_HTTP_ADDR`	nein	`0.0.0.0:8080`	Listen-Adresse für den HTTP-Modus

Dateiformat

requirements-index.md — ein Epic-Abschnitt pro Überschrift, eine Story pro Tabellenzeile:

## EPIC-001: Combat System — `draft`

| Story | Title | Status |
|-------|-------|--------|
| [STORY-001](./epic-001-combat-system/story-001.md) | Basic combat | draft |

backlog.md — nach Priorität sortierte nummerierte Liste:

1. **STORY-001** — Basic combat
2. **STORY-002** — Enemy AI *(in-progress)*

Story-Dateien liegen unter epic-NNN-slug/story-NNN.md innerhalb von BACKLOG_ROOT.

Statuswerte: draft, in-progress, done, blocked

Hinweise

Dateischreibvorgänge sind atomar (temporäre Datei + Umbenennung) — ein Absturz während des Schreibvorgangs kann Ihre Dateien nicht beschädigen.
Das Dateisystem ist die Quelle der Wahrheit. Der MCP-Server besitzt niemals die Daten.