GitHub Project Management MCP Server

Benutzerdefinierter MCP-Server (Model Context Protocol), der KI-Assistenten ermöglicht, GitHub Project V2-Boards programmatisch über das Model Context Protocol zu verwalten. Entwickelt mit Python 3.12 und FastMCP, kommuniziert über stdio-Transport und läuft in einem eigenständigen Docker-Container.

Speicherort

project/
├── mcp/                    ← This directory (root-level, independent of the app)
│   ├── Dockerfile
│   ├── requirements.txt
│   ├── server.py           # FastMCP entry point
│   ├── config.py
│   ├── auth.py
│   ├── capabilities.py     # Tool → permission mapping
│   ├── profiles.py         # Multi-target profile system
│   ├── tools/              # MCP tool definitions
│   ├── services/           # Business logic
│   ├── clients/            # GraphQL + gh CLI clients
│   ├── models/             # Pydantic models
│   ├── graphql/            # Query/mutation strings
│   ├── tests/              # Unit + contract tests
│   ├── scripts/            # Validation, preflight, secret scanning
│   │   ├── validate.sh     # ← Run before every push
│   │   ├── preflight.sh    # Environment prerequisites
│   │   ├── scan_secrets.sh # Token pattern detection
│   │   └── smoke_build.sh  # Minimal build verification
│   ├── profiles/           # Target config (.env files, no secrets)
│   ├── docs/               # Detailed documentation
│   ├── LICENSE             # MIT
│   ├── CONTRIBUTING.md
│   └── SECURITY.md

Hinweis: Dieser MCP-Server ist eine eigenständige Komponente mit eigenem Dockerfile, eigenen Abhängigkeiten und eigenem Lebenszyklus.

Related MCP server: GitHub Projects MCP Server

So funktioniert es

MCP Client → docker run --rm -i github-project-mcp:latest → stdin/stdout JSON-RPC → GitHub API

1. Der MCP-Client ruft ein Werkzeug auf (z. B. create_project_item)

2. Es wird docker run --rm -i github-project-mcp:latest python server.py ausgeführt

3. Der Server validiert die Authentifizierung und wartet auf Befehle über stdin

4. Der Client sendet JSON-RPC über stdin und erhält Antworten über stdout

5. Nach Abschluss wird der Container automatisch zerstört (--rm)

Docker — Erstellen und Verwalten

Erstellen des Images

# Desde la raíz del proyecto
docker build -t github-project-mcp:latest ./mcp

Docker Compose (lokale Entwicklung)

Der einfachste Weg, den MCP lokal zu konfigurieren und auszuführen:

# 1. Crear tu configuración local (una sola vez)
cp mcp/.env.example mcp/.env
# Editar mcp/.env con tu GITHUB_TOKEN y target (org/repo/project)

# 2. Construir y verificar
cd mcp/
make build
make verify

Makefile-Ziele

Alle Ziele werden innerhalb von Docker ausgeführt — ohne Host-Abhängigkeiten.

cd mcp/
make help         # Mostrar todos los targets disponibles
make build        # Construir imagen Docker
make verify       # Validar auth + scopes + config
make test         # Ejecutar unit tests
make validate     # CI completo (build + syntax + tests + tools + secrets)
make tools        # Contar herramientas registradas (>= 100)
make syntax       # Verificar sintaxis Python
make secrets      # Escanear credenciales en código
make shell        # Shell interactivo dentro del contenedor
make clean        # Eliminar imágenes

Hinweis: Wenn make auf dem Host nicht verfügbar ist, können die Ziele direkt mit Docker aufgerufen werden. Beispiel: docker run --rm --env-file .env github-project-mcp:latest python3 scripts/verify_setup.py

Jeder Mitwirkende klont das Repo, erstellt seine .env, und der MCP funktioniert, ohne dass außer Docker etwas installiert werden muss.

Überprüfen, ob das Image existiert

docker images | grep github-project-mcp

Manuell testen (Smoke-Test)

docker run --rm -i \
  -e GITHUB_TOKEN="<your_token>" \
  github-project-mcp:latest \
  python server.py

Der Server wird auf stderr ausgeben: github-project-management MCP server ready. Authentication validated successfully. Danach wartet er auf JSON-RPC über stdin. Drücken Sie Ctrl+C zum Beenden.

Nach Änderungen neu erstellen

docker build -t github-project-mcp:latest ./mcp --no-cache

Verwaltungsskript

Das Skript ./scripts/dev/start.sh unterstützt ein Argument mcp zur Verwaltung des Images:

./scripts/dev/start.sh mcp build      # Construir/reconstruir la imagen
./scripts/dev/start.sh mcp test       # Ejecutar smoke test
./scripts/dev/start.sh mcp status     # Verificar si la imagen existe

Hinweis: Der MCP ist kein persistenter Dienst. Er benötigt kein up/down/restart. Er wird bei Bedarf jedes Mal gestartet, wenn der Client ein Werkzeug verwendet.

IDE-Integration

Der MCP ist mit jedem Client kompatibel, der das MCP-Protokoll über stdio unterstützt. Die Konfiguration variiert je nach IDE — das allgemeine Muster ist:

{
  "mcpServers": {
    "github-project-management": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "GITHUB_TOKEN",
        "--env-file", "mcp/.env",
        "github-project-mcp:latest",
        "python", "server.py"
      ]
    }
  }
}

Für IDE-spezifische Konfiguration siehe docs/SETUP.md.

Registrierte Werkzeuge (100)

Kernoperationen

Issue-Verwaltung

Board-Operationen

Planung & Arbeitsabläufe

Metadaten

Architektur

Tool Layer (FastMCP tool definitions)
    ↓
Service Layer (business logic, orchestration)
    ↓
Client Layer (GraphQL + gh CLI + caching)
    ↓
GitHub APIs (GraphQL v4 + REST v3)

Delegationsstrategie

Umgebungsvariablen

Fehlerbehebung

MCP verbindet nicht

# Verificar que la imagen existe
docker images | grep github-project-mcp

# Si no existe, construir
docker build -t github-project-mcp:latest ./mcp

# Verificar token
echo $GITHUB_TOKEN | head -c 20

MCP erneut verbinden

Wenn der MCP sich vom IDE trennt, verwenden Sie die Reconnect-Option des entsprechenden MCP-Clients.

Authentifizierungsfehler

• Stellen Sie sicher, dass GITHUB_TOKEN in der Container-Umgebung verfügbar ist

• Tokens github_pat_* (feingranular) benötigen Berechtigungen: Issues (RW), Projects (RW), Metadata (R)

• Klassische Tokens benötigen Scopes: repo, project, read:org

Zugehörige Dokumentation

Quellpfade und Synchronisierung

Dieses Verzeichnis (mcp/) ist die maßgebliche Quelle für das MCP-Paket.

Das Repository enthält eine synchronisierte Kopie unter:

• app/backend/app/mcp/github_project/ — eingebettet in das Backend für Docker-Builds

Synchronisierungsworkflow

1. Nehmen Sie alle Änderungen zuerst hier in mcp/ vor.

2. Kopieren Sie geänderte Dateien in den eingebetteten Pfad:

   cp mcp/<file> app/backend/app/mcp/github_project/<file>

3. Überprüfen Sie mit der automatisierten Prüfung:

   ./mcp/scripts/check_sync.sh

Das Synchronisierungsskript vergleicht alle gemeinsamen .py-Dateien (ausgenommen __init__.py, das in der Backend-Kopie bewusst unterschiedlich ist, sowie reine Infrastrukturdateien wie Dockerfile und requirements.txt). CI führt diese Prüfung bei jedem Push aus — Abweichungen führen zum Fehlschlagen des Builds.

Dateien, die in der Backend-Kopie absichtlich unterschiedlich sind

Die Backend-Testsuite prüft die eingebettete Kopie; die Syntaxvalidierung muss beide Bäume kompilieren.

Abgesichertes Laufzeitverhalten

Alle Einstellungen verwenden das Präfix GH_PROJECT_ und werden beim Start validiert:

Der Metadaten-Cache wird atomar geschrieben, verwendet ausschließlich Eigentümer-Berechtigungen (0600), lehnt zukünftige Zeitstempel ab und wird nicht wiederverwendet, wenn sich Organisation oder Projektnummer unterscheiden. CLI- und GraphQL-Diagnosen maskieren tokenartige Werte und werden begrenzt, bevor sie an den MCP-Client zurückgegeben werden.

Docker-only-Validierung

Führen Sie die Validierung ohne Python-Werkzeuge auf dem Host aus:

# Compile both source copies through a Python container
tar -C . -cf - mcp app/backend/app/mcp \
  | docker run --rm -i python:3.12-slim sh -c \
    'mkdir -p /tmp/factib && tar -xf - -C /tmp/factib && \
     python -m compileall -q /tmp/factib/mcp /tmp/factib/app/backend/app/mcp'

# Run the backend MCP tests using the existing backend image
tar -C . -cf - app/backend/app app/backend/tests/mcp \
  | docker run --rm -i -e PYTHONPATH=/tmp/factib/app/backend backend:latest sh -c \
    'mkdir -p /tmp/factib && tar -xf - -C /tmp/factib && cd /tmp/factib/app/backend && \
     pytest -q --confcutdir=/tmp/factib/app/backend/tests/mcp tests/mcp'

Lokale Validierung (vor dem Push)

Führen Sie dies immer vor dem Erstellen eines PR oder dem Pushen von Änderungen aus. Dies spiegelt die CI-Pipeline lokal wider und erkennt Probleme, bevor sie GitHub Actions erreichen.

Schnellstart

# Full validation (builds image + runs all checks):
./mcp/scripts/validate.sh

# Quick mode (reuses cached image, skips rebuild):
./mcp/scripts/validate.sh --quick

# Auto-fix known issues (e.g., BOM characters):
./mcp/scripts/validate.sh --fix

Was geprüft wird

Verfügbare Skripte

Häufige Probleme und Lösungen

Das vollständige Register mit 200 Einträgen, einschließlich umgesetzter und geplanter Arbeiten, finden Sie in docs/HARDENING_200.md.

Erweiterte Fähigkeitssuite: 60 zusätzliche Tools

Der Server stellt insgesamt über 100 Tools bereit: die ursprünglichen 40 operativen Tools plus 60 fokussierte Fähigkeiten aus tools/capability_suite.py.

Tools, die umfangreiche Änderungen verursachen könnten, geben standardmäßig einen dry_run-Plan zurück. Direkte Kommentar-Tools führen pro Aufruf eine sichtbare Kommentaroperation aus. Der Fähigkeitskatalog bestätigt beim Import 60 eindeutige Ergänzungen, und die Docker-Validierung bestätigt 100 registrierte FastMCP-Tools in beiden Quellkopien.

Distribution

Docker-Image

Der MCP-Server wird als eigenständiges Docker-Image verteilt. Lokal erstellen:

docker build -t github-project-mcp:latest ./mcp

CI/CD-Pipeline

Der Workflow mcp-ci.yaml wird automatisch ausgeführt bei:

• Push auf main, wenn sich Dateien unter mcp/ ändern

• Pull Requests, die mcp/-Pfade betreffen

Pipeline-Stufen:

1. Build — Überprüfung des Docker-Image-Builds

2. Syntaxprüfung — AST-Parsing aller Python-Dateien

3. Unit-Tests — Ausführung der pytest-Suite

4. Tool-Anzahl-Prüfung — Stellt sicher, dass ≥100 Tools registriert sind

Versionierung

Dieser MCP-Server folgt Semantic Versioning. Die Versionshistorie finden Sie in CHANGELOG.md.