mdgraph

Scannt das Markdown eines Repos in einen Graphen, visualisiert ihn im Browser und exponiert ihn für Claude (oder jeden MCP-Host) als Navigationsindex.

Ein Datenmodell — { nodes, edges } — mit drei Konsumenten:

              scan  (the only hard part)
                 │  emits { nodes, edges }
      ┌──────────┼───────────┐
      ▼          ▼           ▼
   graph.json  browser     MCP server
   (a file)   (viewer)   (agents read it)

Einblicke, Erreichbarkeit und verwaiste Knoten werden zur Lesezeit aus dem Modell abgeleitet. Knoten und Kanten bleiben dumm.

Das Modell

node = { id, label, path, type, cluster, content }   // type: root | ai | doc
edge = { source, target, sourceLine, context }        // context = the line the link lives on

type wird per Dateinamenskonvention vergeben (README.md → root, CLAUDE.md/AGENTS.md/*.mdc → ai, sonst → doc). Kanten entstehen aus tatsächlichen Links im Text — standard [x](./y.md) und [[wikilinks]] — nicht aus Ordnerzugehörigkeit, sodass eine Datei in docs/, die über die Baumstruktur hinweg verlinkt, auch tatsächlich verbunden ist. Ordner steuern nur cluster (Einfärbung/Gruppierung).

Related MCP server: mcp-server-markdown

Installation & Ausführung

Keine Installation nötig — einfach direkt mit npx ausführen:

npx @emmd474/mdgraph scan .            # print the graph as JSON
npx @emmd474/mdgraph view .            # open the interactive graph in a browser
npx @emmd474/mdgraph scan . --out graph.json

Oder global installieren, um einen einfachen mdgraph-Befehl zu erhalten:

npm install -g @emmd474/mdgraph
mdgraph view ./my-repo
mdgraph scan ./my-repo --out graph.json

dir standardmäßig das aktuelle Verzeichnis. view akzeptiert --port (Standard: 4173).

Befehle

Für Claude exponieren (MCP)

Claude Desktop — in claude_desktop_config.json eintragen:

{
  "mcpServers": {
    "mdgraph": {
      "command": "npx",
      "args": ["-y", "@emmd474/mdgraph", "mcp", "/abs/path/to/your/repo"]
    }
  }
}

Claude Code:

claude mcp add mdgraph -- npx -y @emmd474/mdgraph mcp /abs/path/to/your/repo

Host neu starten und Claude erhält vier Werkzeuge:

Der Punkt: Ein Agent ruft get_project_map zur Orientierung auf, dann get_context("README.md"), um nur die Dokumente zu laden, die die Aufgabe braucht — statt jedes .md in den Kontext zu kippen.

Veröffentlichung (für Maintainer)

Der Name mdgraph ist auf npm vergeben, daher wird scoped unter deinem Konto veröffentlicht:

# 1. set the scope to YOUR npm username (edit "name" in package.json if not @emmd474)
npm whoami          # confirm you're logged in; else: npm login
npm publish --access public

Scoped-Pakete sind standardmäßig privat, daher ist --access public beim ersten Mal erforderlich. Für ein Update die Version erhöhen und erneut veröffentlichen:

npm version patch   # 0.1.0 -> 0.1.1, also creates a git tag
npm publish

npm pack --dry-run zeigt genau, was veröffentlicht wird (derzeit 7 Dateien, ~16 kB — kein node_modules, kein Test-Repo, dank der files-Allowlist).

Am Beispiel ausprobieren

git clone <this repo> && cd mdgraph && npm install
node cli.mjs view testrepo
node cli.mjs scan testrepo

Was real ist vs. was als Nächstes kommt

Getestet und funktionsfähig: der Scanner (md + Wikilink-Erkennung, Codefence-Überspringen, Konventions-Typisierung, Erkennung verwaister Knoten), der Browser-Viewer und alle vier MCP-Werkzeuge über einen echten stdio-Handshake.

Als Nächstes, in etwa der Reihenfolge:

• Link-Parsing härten — der Scanner arbeitet zeilenbasiert und überspringt Codeblöcke, aber ein Inline-Code-Span (`[x](y)`) kann noch einen falschen Link erzeugen. Einen echten Markdown-AST (remark + unist-util-visit) einbauen, wenn du Präzision willst; die ausgegebene Form bleibt identisch.

• Manuelle Kanten — dem Viewer erlauben, related: in die Frontmatter einer Datei zu schreiben, die als dritte Kantenquelle gelesen wird.

• Frontmatter-Tags als Clusterquelle neben den Ordnern.

• --watch bei view, um Graph-Updates per Server-Sent Events zu pushen.

MIT-lizenziert.