MCP GitHub Issue Priority Server

Ein Model Context Protocol (MCP) Server, der es KI-Assistenten ermöglicht, GitHub-Issues mit deterministischer Prioritätsbewertung und nebenläufigkeitssicherer Auswahl zu verwalten.

Schnelleinstieg

# 1. Install from npm (recommended)
npm install -g mcp-git-issue-priority

# 2. Authenticate (if not already using GitHub CLI)
gh auth login

# 3. Add to Claude Code (~/.claude.json)

{
  "mcpServers": {
    "github-issue-priority": {
      "command": "mcp-git-issue-priority"
    }
  }
}

# 4. Restart Claude Code and verify
# The MCP tools should appear when you run /mcp

Related MCP server: Project Manager MCP

Funktionen

• Prioritätsbasierte Issue-Auswahl: Ein deterministischer Bewertungsalgorithmus sorgt für eine konsistente Priorisierung der Issues über Sitzungen hinweg.

• Nebenläufigkeitssichere Sperrung: Dateibasierte atomare Sperren verhindern, dass mehrere KI-Sitzungen dasselbe Issue auswählen.

• Geführter Workflow: 8-Phasen-Workflow (Auswahl → Recherche → Branch → Implementierung → Testen → Commit → PR → Review) mit Übergangsvalidierung.

• Automatische Etikettierung: Erstellt und verwaltet Prioritäts- (P0-P3), Typ- (bug, feature, chore, docs) und Status-Labels.

• Erkennung veralteter Sperren: Erkennt und bereinigt automatisch Sperren von abgestürzten Prozessen.

• Audit-Logging: JSON-Lines-Logging für alle Vorgänge mit 30-tägiger Aufbewahrungsfrist.

Installation

Voraussetzungen

• Node.js 20+ - Download

• GitHub CLI (empfohlen) - Installieren und gh auth login ausführen

  • Oder: ein persönliches GitHub-Zugriffstoken mit repo-Berechtigung

Installation über npm (empfohlen)

npm install -g mcp-git-issue-priority

Spezifische Version installieren

npm install -g mcp-git-issue-priority@1.0.0

Installation aus dem Quellcode

git clone https://github.com/steiner385/mcp-git-issue-priority.git
cd mcp-git-issue-priority
npm install && npm link

Fehlerbehebung

Konfiguration

GitHub-Authentifizierung

Der Server unterstützt zwei Authentifizierungsmethoden:

Empfohlen: GitHub CLI (automatisch)

Wenn Sie die GitHub CLI installiert und authentifiziert haben, ruft der Server Ihr Token automatisch ab:

# One-time setup
gh auth login

Dies ist der empfohlene Ansatz – keine manuelle Token-Verwaltung erforderlich.

Alternative: Umgebungsvariable

Setzen Sie GITHUB_TOKEN mit einem persönlichen Zugriffstoken, das über repo-Berechtigungen verfügt:

export GITHUB_TOKEN="ghp_your_personal_access_token"

Oder konfigurieren Sie es in Ihren MCP-Einstellungen (siehe unten).

Claude Code Konfiguration

Fügen Sie dies zu ~/.claude.json (global) oder .claude/settings.json (Projekt) hinzu:

{
  "mcpServers": {
    "github-issue-priority": {
      "command": "mcp-git-issue-priority"
    }
  }
}

Verwenden Sie ein persönliches Zugriffstoken anstelle der GitHub CLI? Fügen Sie das Token zur Konfiguration hinzu:

{
  "mcpServers": {
    "github-issue-priority": {
      "command": "mcp-git-issue-priority",
      "env": {
        "GITHUB_TOKEN": "ghp_your_personal_access_token"
      }
    }
  }
}

Installation überprüfen

Nach dem Neustart von Claude Code:

1. Führen Sie /mcp aus, um verfügbare MCP-Server anzuzeigen.

2. Der github-issue-priority-Server sollte mit 13 Tools aufgelistet sein.

3. Versuchen Sie list_backlog in einem beliebigen Repository, um zu bestätigen, dass es funktioniert.

Verfügbare Tools

create_issue

Erstellt ein neues GitHub-Issue mit obligatorischen Prioritäts- und Typ-Labels.

Arguments:
  - title (required): Issue title
  - body (optional): Issue description
  - priority (required): P0 (critical) | P1 (high) | P2 (medium) | P3 (low)
  - type (required): bug | feature | chore | docs
  - repository (required): "owner/repo" format

select_next_issue

Wählt das Issue mit der höchsten Priorität aus dem Backlog aus und sperrt es. Verwendet deterministische Bewertung, um eine konsistente Auswahl zu gewährleisten.

Arguments:
  - repository (required): "owner/repo" format
  - type (optional): Filter by issue type
  - maxPriority (optional): Only consider issues at or above this priority

list_backlog

Listet alle offenen Issues in der Reihenfolge ihrer Priorität auf, ohne Sperren zu erwerben (schreibgeschützt).

Arguments:
  - repository (required): "owner/repo" format
  - type (optional): Filter by issue type
  - limit (optional): Maximum issues to return (default: 20)

advance_workflow

Setzt den Workflow für ein gesperrtes Issue in die nächste Phase fort.

Arguments:
  - issueNumber (required): Issue number to advance
  - targetPhase (required): research | branch | implementation | testing | commit | pr | review
  - repository (required): "owner/repo" format
  - testsPassed (optional): Required when advancing to 'commit' phase
  - prTitle (optional): Required for 'pr' phase
  - prBody (optional): Required for 'pr' phase
  - skipJustification (optional): Required if skipping phases

get_workflow_status

Ruft den aktuellen Workflow-Status für gesperrte Issues ab.

Arguments:
  - issueNumber (optional): Specific issue number
  - repository (optional): "owner/repo" format

release_lock

Gibt die Sperre für ein Issue frei (nach Abschluss, Abbruch oder Merge).

Arguments:
  - issueNumber (required): Issue number
  - reason (required): completed | abandoned | merged
  - repository (required): "owner/repo" format

force_claim

Erzwingt die Übernahme eines Issues, das von einer anderen Sitzung gesperrt wurde (erfordert Bestätigung).

Arguments:
  - issueNumber (required): Issue number to claim
  - confirmation (required): Must be exactly "I understand this may cause conflicts"
  - repository (required): "owner/repo" format

sync_backlog_labels

Erkennt und korrigiert optional Issues, denen erforderliche Prioritäts-, Typ- oder Status-Labels fehlen.

Arguments:
  - repository (required): "owner/repo" format
  - mode (optional): "report" (default) to list issues, "update" to apply labels
  - defaultPriority (optional): P0 | P1 | P2 | P3 (defaults to P2)
  - defaultType (optional): bug | feature | chore | docs (defaults to feature)

Im Berichtsmodus wird eine Liste aller Issues ohne Labels zurückgegeben, mit Details dazu, was fehlt.

Im Aktualisierungsmodus werden Standard-Labels auf Issues angewendet:

• Fehlende Priorität → priority:P2 (oder angegebener Standardwert)

• Fehlender Typ → type:feature (oder angegebener Standardwert)

• Fehlender Status → status:backlog

get_pr_status

Überprüft den CI-Status, den Genehmigungsstatus und den Merge-Status eines Pull Requests.

Arguments:
  - repository (required): "owner/repo" format
  - prNumber (required): Pull request number to check

bulk_update_issues

Fügt Labels hinzu/entfernt sie und schließt/öffnet mehrere Issues gleichzeitig.

Arguments:
  - repository (required): "owner/repo" format
  - issues (required): Array of issue numbers (1-50)
  - addLabels (optional): Labels to add
  - removeLabels (optional): Labels to remove
  - state (optional): "open" | "closed"

implement_batch

Startet die Implementierung einer Gruppe von N Issues in der Reihenfolge ihrer Priorität. Gibt das erste zu implementierende Issue zurück.

Arguments:
  - repository (required): "owner/repo" format
  - count (required): Number of issues to implement (1-10)
  - includeTypes (optional): Only include these issue types
  - excludeTypes (optional): Exclude these issue types
  - maxPriority (optional): Only P0, P1, etc.

batch_continue

Setzt die Batch-Implementierung fort. Wartet auf den PR-Merge und gibt dann das nächste Issue oder den Abschluss zurück.

Arguments:
  - batchId (required): Batch ID from implement_batch
  - prNumber (optional): PR number for current issue

get_workflow_analytics

Ruft zeitbasierte Workflow-Analysen ab: Zykluszeit, Phasenaufschlüsselung, Alterungsberichte.

Arguments:
  - repository (required): "owner/repo" format
  - period (optional): "7d" | "30d" | "90d" | "all" (default: 30d)

Prioritäts-Bewertungsalgorithmus

Issues werden mit einer deterministischen Formel bewertet:

score = (basePoints + ageBonus) * blockingMultiplier * blockedPenalty

• Basispunkte: P0=1000, P1=100, P2=10, P3=1

• Alterungsbonus: +1 Punkt pro Tag seit Erstellung (max. 365)

• Blockierender Multiplikator: 1,5x für Issues mit dem Label "blocking"

• Blockierte Strafe: 0,1x für Issues, die durch offene übergeordnete Issues blockiert sind (via GitHub Sub-Issues)

• Entscheidung bei Gleichstand: Das frühere Erstellungsdatum gewinnt (FIFO)

Abhängigkeitserkennung

Issues mit offenen übergeordneten Issues (unter Verwendung der GitHub Sub-Issues-Funktion) werden automatisch mit einer 0,1x-Strafe herabgestuft. Dies stellt sicher, dass blockierte Arbeit ans Ende des Backlogs sinkt, bis ihre Abhängigkeiten gelöst sind. Sobald ein übergeordnetes Issue geschlossen wird, kehrt die Priorität des untergeordneten Issues zum Normalwert zurück.

Workflow-Phasen

1. selection: Issue ausgewählt und gesperrt

2. research: Verständnis des Problems

3. branch: Feature-Branch erstellt

4. implementation: Code-Änderungen in Arbeit

5. testing: Tests und Validierung laufen

6. commit: Änderungen committet

7. pr: Pull Request erstellt

8. review: Warten auf Review/Merge

Datenspeicherung

Alle Daten werden lokal unter ~/.mcp-git-issue-priority/ gespeichert:

~/.mcp-git-issue-priority/
├── locks/          # Active lock files (.lockdata)
├── workflow/       # Workflow state files (.json)
└── logs/           # Audit logs (JSON Lines format)

Entwicklung

Build

npm run build

Test

npm test

Lint

npm run lint

Typ-Prüfung

npm run typecheck

Veröffentlichung (Maintainer)

Einmalige Einrichtung

1. Erstellen Sie ein npm-Konto unter https://www.npmjs.com/

2. Gehen Sie zu https://www.npmjs.com/settings/tokens

3. Erstellen Sie ein "Automation"-Token mit "Publish"-Berechtigung

4. Fügen Sie es zu GitHub hinzu: Settings → Secrets → Actions → Neues Secret namens NPM_TOKEN

Erstellen eines Releases

# Patch release (bug fixes): 1.0.0 → 1.0.1
npm version patch -m "Release v%s"
git push && git push --tags

# Minor release (new features): 1.0.0 → 1.1.0
npm version minor -m "Release v%s"
git push && git push --tags

# Major release (breaking changes): 1.0.0 → 2.0.0
npm version major -m "Release v%s"
git push && git push --tags

Das Pushen eines Tags löst den Release-Workflow aus, der:

• Lint, Build und Tests ausführt

• Ein GitHub-Release mit angehängtem Tarball erstellt

• Auf der npm-Registry veröffentlicht

Download-Tracking

• GitHub: Die Releases-Seite zeigt die Download-Anzahl pro .tgz-Asset

• npm: https://www.npmjs.com/package/mcp-git-issue-priority zeigt wöchentliche Downloads

Lizenz

MIT-Lizenz - siehe LICENSE für Details.

Mitwirken

Beiträge sind willkommen! Bitte lesen Sie CONTRIBUTING.md für Richtlinien.

Feedback & Support

Wir würden uns freuen, von Ihnen zu hören! Ihr Feedback hilft, dieses Tool für alle zu verbessern.

• Fragen oder Ideen? Starten Sie eine Diskussion

• Bug gefunden? Öffnen Sie ein Issue

• Feature-Anfrage? Öffnen Sie ein Issue mit [Feature] im Titel

• Schnelles Feedback? Führen Sie mcp-git-issue-priority --feedback aus, um die Feedback-Seite zu öffnen

Überprüfen Sie bestehende Issues, bevor Sie neue erstellen.