GitHub Assistant MCP

Ein kleiner, eigenständiger Model Context Protocol (MCP)-Server, der fünf schreibgeschützte Tools für einen KI-Coding-Assistenten (z. B. OpenCode) bereitstellt. Er ermöglicht es dem Assistenten, ein lokales Arbeitsverzeichnis zu durchsuchen und ein öffentliches GitHub-Profil über einen sauberen, sandboxed stdio-Transport abzurufen.

"Ein einfacher GitHub-MCP-Server für OpenCode."

Inhaltsverzeichnis

• Überblick

• So funktioniert es (Architektur)

• Transport & Lebenszyklus

• Tool-Referenz

• Sicherheitsmodell

• Projektübersicht

• Konfiguration

• Erstellen & Ausführen

• Dateistruktur

• Einschränkungen

Related MCP server: chatgpt-codex-local-mcp

Überblick

Der Server ist ein lokaler MCP-Server, der von OpenCode als Kindprozess gestartet wird. Er spricht das MCP-Protokoll über stdio (stdin/stdout) und registriert fünf Tools. Der Assistent ruft diese Tools auf; der Server erledigt die Arbeit (Dateisystemzugriffe, ein git diff oder einen GitHub-API-Aufruf) und gibt strukturierte Textergebnisse zurück.

Alles, was das Dateisystem betrifft, ist auf ein einziges WORKSPACE_ROOT-Verzeichnis beschränkt, sodass der Assistent niemals außerhalb des Projektordners lesen oder entkommen kann.

So funktioniert es (Architektur)

┌─────────────────────────┐         stdio (MCP/JSON-RPC)        ┌──────────────────────────────┐
│                         │  ───────────────────────────────▶  │   github-assistant  (this)   │
│     OpenCode / AI       │  tool call: get_github_profile     │                              │
│     Assistant           │                                    │  ┌────────────────────────┐  │
│                         │  ◀───────────────────────────────  │  │      McpServer          │  │
│  - sees 5 tools         │     result (JSON text)             │  │  (server.ts)            │  │
│  - calls them           │                                    │  └───────────┬────────────┘  │
│  - sandbox enforced     │                                    │              │ registerTools  │
└─────────────────────────┘                                    └──────────────┼──────────────┘
                                                                          ▼
                                                         ┌────────────────────────────────┐
                                                         │  tools.ts  (5 tool handlers)   │
                                                         └───┬──────┬──────┬──────┬─────┬──┘
                                          ┌───────────────┘      │      │      │     │
                                          ▼                      ▼      ▼      ▼     ▼
                                   ┌────────────┐        ┌────────────┐ ┌─────────┐ ┌────────────┐
                                   │ github.ts  │        │ workspace.ts│ │ git.ts │ │ paths.ts   │
                                   │ GitHub API │        │ list/read/  │ │ git diff│ │ resolve    │
                                   │ (fetch)   │        │ search      │ │         │ │ sandbox    │
                                   └─────┬──────┘        └─────┬──────┘ └────┬────┘ └─────┬──────┘
                                         │                    │            │           │
                                         ▼                    ▼            ▼           ▼
                                 api.github.com       WORKSPACE_ROOT/*   git CLI    config.ts
                                                        (files only)   (cwd=root)  WORKSPACE_ROOT

Datenfluss für einen einzelnen Tool-Aufruf:

Assistant ──JSON-RPC request──▶ McpServer
                                     │
                                     ▼
                               tool handler (tools.ts)
                                     │  validates args with zod
                                     ▼
                          business logic (github / workspace / git / paths)
                                     │  resolveWorkspacePath() enforces sandbox
                                     ▼
                          result helper (result.ts) → { content: [{ type:"text", text }] }
                                     │
                                     ▼
Assistant ◀──JSON-RPC response── McpServer

Transport & Lebenszyklus

• Typ: local – OpenCode startet den Server als Kindprozess.

• Transport: stdio über serveStdio() aus @modelcontextprotocol/server/stdio.

• Startsequenz:

  1. node dist/server.js wird ausgeführt (deklariert in opencode.json) mit cwd = ".".

  2. createServer() erstellt einen McpServer namens github-assistant (v1.0.0).

  3. registerTools(server) verdrahtet die fünf Tools.

  4. serveStdio(createServer) beginnt, JSON-RPC-Nachrichten von stdin zu lesen und Ergebnisse nach stdout zu schreiben.

• Herunterfahren: OpenCode beendet den Prozess, wenn die Sitzung endet.

Da der Prozess das Arbeitsverzeichnis von OpenCode erbt, wird WORKSPACE_ROOT zum Projektverzeichnis aufgelöst (path.resolve(process.cwd())).

Tool-Referenz

Alle Tools sind in src/tools.ts registriert und geben MCP-Textergebnisse zurück (JSON oder Klartext).

1. get_github_profile

Ruft das öffentliche GitHub-Profil des fest codierten Benutzers (imshashwatsingh) ab.

• Eingaben: keine

• Backend: fetch() auf https://api.github.com/users/imshashwatsingh mit Accept: application/vnd.github+json und einem User-Agent-Header.

• Gibt zurück: Benutzername, Name, Firma, Standort, Bio, öffentliche Repos/Gists, Follower, Gefolgt, Profil-URL, Erstellungs-/Aktualisierungszeitstempel.

• Datei: src/github.ts

2. list_files

Listet Dateien in einem Arbeitsverzeichnis bis zu einer Tiefe auf.

• Eingaben: path (Standard "."), maxDepth (0–10, Standard 3)

• Backend: rekursives collectFiles() in src/workspace.ts – überspringt symbolische Links (keine Schleifen) und ignoriert konfigurierte Verzeichnisse (node_modules, .git, dist, .next, coverage, .cache). Begrenzt auf MAX_RESULTS (500).

• Gibt zurück: Arbeitsverzeichnis-Wurzel, Dateianzahl und relative Dateipfade.

• Datei: src/workspace.ts

3. read_file

Liest eine UTF-8-Textdatei mit optionalem Zeilenbereich.

• Eingaben: path (erforderlich), startLine (optional), endLine (optional)

• Backend: readWorkspaceFile() – erzwingt die Sandbox, lehnt Nicht-Dateien ab, verweigert Dateien größer als MAX_FILE_SIZE (1 MB) und verweigert Binärerweiterungen. Gibt nummerierte Zeilen zurück.

• Gibt zurück: Dateiinhalt mit Zeile: Text-Präfixen.

• Datei: src/workspace.ts

4. search_context

Stichwortsuche im Arbeitsverzeichnis mit umgebendem Kontext.

• Eingaben: query (erforderlich), path (Standard "."), maxResults (1–100, Standard 50), contextLines (0–10, Standard 2)

• Backend: searchContext() sammelt Dateien, filtert reine Text- und größenbegrenzte Dateien und durchsucht dann jede Zeile (ohne Berücksichtigung der Groß-/Kleinschreibung) und erfasst contextLines ober- und unterhalb jedes Treffers.

• Gibt zurück: Abfrage, Suchpfad, Anzahl der Treffer und Treffer mit Datei/Zeile/Kontext.

• Datei: src/workspace.ts

5. summarize_diff

Untersucht den aktuellen Git-Diff und gibt eine strukturierte Zusammenfassung zurück.

• Eingaben: staged (Standard false), base (optionaler Git-Ref), path (optionaler Datei-/Ordnerpfad), maxDiffChars (1000–200000, Standard 50000)

• Backend: summarizeDiff() führt git diff --no-ext-diff --unified=3 (mit --cached / Basis-Ref / Pfadfiltern) aus WORKSPACE_ROOT aus. Statistiken werden aus dem Unified-Diff selbst geparst (kein zweiter git-Aufruf). Der Diff wird abgeschnitten, wenn er maxDiffChars überschreitet.

• Gibt zurück: geänderte Dateien, Einfügungen, Löschungen, Statistiken pro Datei und den rohen Diff – oder { empty: true }, wenn es keine Änderungen gibt.

• Datei: src/git.ts

Sicherheitsmodell

Der Server ist absichtlich schreibgeschützt und sandboxed:

Die Sandbox-Grenze liegt vollständig in paths.ts. Jedes neue Tool, das auf das Dateisystem zugreift, muss Pfade durch resolveWorkspacePath() leiten.

Projektübersicht

1. Einstiegspunkt – src/server.ts createServer() instanziiert McpServer und ruft registerTools() auf. serveStdio() verbindet es mit stdin/stdout.

2. Tool-Registrierung – src/tools.ts Fünf server.registerTool(...)-Aufrufe. Jeder deklariert eine Beschreibung, ein zod-validiertes inputSchema und einen asynchronen Handler. Handler delegieren an die folgenden Module und verpacken die Ausgabe mit den Helfern aus result.ts.

3. Konfiguration – src/config.ts Zentrale Konstanten: WORKSPACE_ROOT (aus process.cwd() aufgelöst), Größen-/Ergebnislimits, GitHub-Benutzername/-URL und Ignorier-/Binärmengen.

4. Pfadsicherheit – src/paths.ts resolveWorkspacePath() ist das Sandbox-Tor. toWorkspaceRelative() wandelt absolute Pfade zur Anzeige wieder in arbeitsbereichsrelative Zeichenfolgen um. isProbablyTextFile() klassifiziert Dateien anhand der Erweiterung.

5. Arbeitsbereichs-I/O – src/workspace.ts collectFiles() (rekursive Auflistung), readWorkspaceFile() (sicheres Lesen) und searchContext() (Stichwortsuche). Alle laufen über resolveWorkspacePath().

6. GitHub – src/github.ts fetchGitHubProfile() ruft die öffentliche API auf und bildet den rohen GitHubUser auf die benutzerfreundlichere GitHubProfile-Form ab.

7. Git – src/git.ts summarizeDiff() erstellt und führt den git diff-Befehl aus; parseDiffStats() leitet die Einfüge-/Löschzahlen pro Datei direkt aus dem Diff-Text ab.

8. Ergebnisse – src/result.ts Kleine Helfer (textResult, errorResult, errorWithContext) standardisieren den MCP-content-Umschlag und die Fehlerkennzeichnung.

Konfiguration

opencode.json (Projektwurzel) deklariert den Server:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "github-assistant": {
      "type": "local",
      "command": ["node", "dist/server.js"],
      "cwd": ".",
      "enabled": true
    }
  }
}

Innerhalb des Servers wird das Verhalten über Konstanten in src/config.ts eingestellt:

Erstellen & Ausführen

# install dependencies
npm install

# compile TypeScript -> dist/
npm run build

# start the server (used by opencode.json)
npm start

# run directly from source (no build step)
npm run dev

# the workspace must be a git repo for summarize_diff to work
git init

OpenCode erkennt den Server nach dem Erstellen (dist/server.js) automatisch aus opencode.json.

Dateistruktur

github_assistant_mcp/
├── opencode.json          # MCP server declaration for OpenCode
├── package.json           # scripts + dependencies
├── tsconfig.json          # TypeScript config
├── src/
│   ├── server.ts          # Entry point: create + serve McpServer
│   ├── tools.ts           # Registers the 5 tools + handlers
│   ├── config.ts          # Constants, limits, GitHub target
│   ├── paths.ts           # Sandbox path resolution + helpers
│   ├── workspace.ts       # list / read / search filesystem
│   ├── github.ts          # GitHub profile fetch
│   ├── git.ts             # git diff summary + stat parsing
│   └── result.ts          # MCP result/error helpers
└── dist/                  # Compiled output (npm run build)

Einschränkungen

• get_github_profile zielt auf einen einzelnen fest codierten Benutzer; es ist nicht parametrisiert.

• summarize_diff meldet nur Änderungen im Arbeitsverzeichnis – nicht verfolgte Dateien werden von git diff nicht angezeigt.

• Dateisystem-Tools sind auf WORKSPACE_ROOT beschränkt; es gibt keinen projektübergreifenden Zugriff.

• Alle Tools sind schreibgeschützt – keine Bearbeitungen, Löschungen oder Shell-Ausführungen.

• Keine Authentifizierung: Der GitHub-Aufruf verwendet die nicht authentifizierte öffentliche API (auf 60 Anfragen/Std. pro IP begrenzt).