GitHub MCP Server

MCP-Server in Node.js und TypeScript, der es einem kompatiblen Agenten ermöglicht, Operationen auf GitHub über natürliche Sprache auszuführen.

Architektur

Usuario -> Antigravity (Host) -> MCP Client -> MCP Server -> Octokit -> GitHub API

Ein Chatbot führt hauptsächlich ein Gespräch. Ein KI-Assistent hilft mithilfe zusätzlicher Fähigkeiten. Ein KI-Agent interpretiert ein Ziel, entscheidet, welche Aktionen er benötigt, und nutzt Tools, um es zu erreichen.

MCP (Model Context Protocol) standardisiert die Kommunikation zwischen einem KI-Host, einem MCP-Client und Servern, die Tools oder Datenquellen bereitstellen. In diesem Projekt ist der Transport stdio: Die Protokollnachrichten verwenden stdin/stdout und die Logs verwenden stderr.

Related MCP server: GitHub MCP Server

Technologien

• Node.js 18 oder höher

• TypeScript mit strict: true

• @modelcontextprotocol/sdk

• @octokit/rest

• zod

• dotenv

• Vitest

Installation

npm install
npm run build

Konfiguration

Kopiere .env.example als .env und fülle das Token lokal aus:

GITHUB_TOKEN=tu_token_de_github

.env ist durch .gitignore ausgeschlossen und darf niemals committet werden.

Das Token sollte nur die erforderlichen Berechtigungen besitzen. Für private Repositories müssen feingranulare Tokens je nach Operation den Zugriff auf das Repository und Contents/Issues erlauben. Ein klassisches PAT kann repo erfordern. Die Berechtigung user ist nur für zusätzliche Benutzeroperationen erforderlich und admin:org ist für die fünf aktuellen Tools nicht notwendig, es sei denn, die Organisation erzwingt dieses Szenario. Es werden keine Tokens in Beispielen, Tests, Logs oder MCP-Antworten aufgenommen.

Skripte

npm run dev       # Ejecuta TypeScript directamente
npm run build     # Compila a dist/
npm start         # Ejecuta el JavaScript compilado
npm test          # Ejecuta los tests unitarios

MCP-Tools

create_repository

Erstellt ein neues Repository im authentifizierten Konto.

Eingaben: name, description.

Gibt den vollständigen Namen und die URL des Repositories zurück.

create_issue

Erstellt ein Issue in einem vorhandenen Repository.

Eingaben: owner, repo, title, body.

Gibt Nummer, Titel und URL des Issues zurück.

list_repositories

Listet die Repositories des authentifizierten Benutzers auf.

Optionale Eingaben: page, per_page.

Gibt eine zusammengefasste Liste mit vollständigem Namen und URL zurück.

create_commit

Erstellt oder aktualisiert eine Datei und erzeugt den Commit über die Contents API.

Eingaben: owner, repo, path, message, content; branch ist optional.

Das Tool fragt zuerst die Datei ab. Wenn sie existiert, verwendet es ihren SHA; wenn GitHub mit 404 antwortet, erstellt es die Datei ohne SHA.

list_issues

Listet die offenen Issues eines Repositories auf und schließt Pull Requests aus.

Eingaben: owner, repo; page und per_page sind optional.

Fehlerbehandlung

Fehler werden als ValidationError, AuthenticationError, GitHubAPIError oder NetworkError klassifiziert. MCP-Antworten enthalten umsetzbare Meldungen und leiten keine technischen Meldungen weiter, die Anmeldeinformationen offenlegen könnten.

Operationen werden nur bei Rate-Limiting, 5xx-Fehlern oder behebbaren Netzwerkfehlern bis zu dreimal wiederholt. Validierungs-, Authentifizierungs- und Fehler bei nicht vorhandenen Ressourcen werden nicht wiederholt.

Tests

Die Tests rufen kein echtes GitHub auf. Sie verwenden simulierte Octokit-Clients und decken ab:

• Gültige und ungültige Schemas für Repositories und Issues.

• Erstellung von Repositories und Issues.

• Auflistung von Repositories und offenen Issues.

• Erstellung neuer Dateien.

• Aktualisierung vorhandener Dateien mithilfe des SHA.

• Fehlertransformation.

• Retry mit Backoff.

Führe npm test aus, um die gesamte Suite auszuführen.

MCP Inspector

Kompiliere das Projekt und führe den Server über den Inspector aus:

npm run build
npx @modelcontextprotocol/inspector node dist/index.js

Konfiguriere GITHUB_TOKEN in der Umgebung, bevor du den Inspector startest. Überprüfe, ob die fünf Tools, ihre Beschreibungen und Schemas erscheinen. Für einen echten Test verwende ein Test-Repository und vermeide destruktive Operationen.

Antigravity und VS Code

Die Datei .vscode/mcp.json enthält eine stdio-Konfiguration ohne versionierte Anmeldeinformationen. Verwende npm run build, bevor du den Server vom Host aus startest. Die Konfiguration führt dist/index.js aus und bezieht GITHUB_TOKEN aus der lokalen Umgebung.

Für einen anderen MCP-kompatiblen Host registriere den entsprechenden Befehl:

{
  "type": "stdio",
  "command": "node",
  "args": ["dist/index.js"],
  "env": { "GITHUB_TOKEN": "${env:GITHUB_TOKEN}" }
}

Stelle sicher, dass der Host create_repository, create_issue, list_repositories, create_commit und list_issues erkennt.

Struktur

src/
  errors/       Errores clasificados y sanitizacion
  github/       Cliente Octokit y operaciones GitHub
  schemas/      Schemas Zod y tipos inferidos
  tools/        Handlers MCP individuales
  utils/        Retry, logging, respuestas y ensamblado del servidor
  index.ts      Entrada y transporte stdio
tests/          Tests unitarios con mocks

Sicherheit

• Keine Tokens hartcodieren.

• .env nicht committen.

• Keine Tokens oder Autorisierungs-Header ausgeben.

• Logs in stderr halten, um das Protokoll nicht zu verunreinigen.

• Das Prinzip der geringsten Rechte auf das PAT anwenden.

• Änderungen überprüfen, bevor Tools ausgeführt werden, die in GitHub schreiben.