Logo
BlogPortfolioGadgets

Automatisierte Dokumentation mit doc-gen-mcp: Moderne Doku-Workflows für Entwickler:innen

2025-04-29

Automatisierte Dokumentation mit doc-gen-mcp: Moderne Doku-Workflows für Entwickler:innen

Motivation: Warum Dokumentation automatisieren?

Jede:r Entwickler:in kennt das Problem: Die Dokumentation ist oft veraltet, lückenhaft oder schlicht nicht vorhanden. Dabei ist gute Doku essenziell – für die eigene Arbeit, für Teamkolleg:innen und für die Open-Source-Community. Doch wer hat schon Lust, sie immer manuell zu pflegen?

Hier setzt doc-gen-mcp an: Ein generischer, erweiterbarer Dokumentationsgenerator, der klassische und KI-gestützte Dokumentation automatisiert und nahtlos in moderne Entwicklungsumgebungen wie Cursor AI integriert.

Was ist doc-gen-mcp?

doc-gen-mcp ist ein Open-Source-Tool (Node.js), das verschiedene Eingabeformate (JSON, Rulebases, API-Definitionen, Konfigs, Code mit JSDoc/TypeScript-Kommentaren) in strukturierte Markdown- oder JSON-Dokumentation verwandelt. Es unterstützt klassische Doku-Generierung und kann optional KI-Modelle (OpenAI, Anthropic, Gemini, Cohere, Azure OpenAI) nutzen, um aus Code automatisch verständliche Beschreibungen zu erzeugen.

Die wichtigsten Features im Überblick

  • Flexible Eingabe: JSON, Rulebase, API, Config oder direkt Code-Dateien
  • Automatische Gruppierung: Nach Kategorien, mit klaren Überschriften
  • Markdown oder JSON: Strukturierte Ausgabe, anpassbar nach Bedarf
  • Modulare Export-Plugins: Flexibler Export nach Confluence, Markdown, HTML, PDF oder selbst definierten Zielen
  • Validierung & Diff: Prüft Doku auf Vollständigkeit, zeigt Änderungen zwischen Versionen
  • Mehrsprachig: Deutsch & Englisch, leicht erweiterbar
  • AI-Integration: Nutze GPT, Claude, Gemini, Cohere oder Azure für smarte Doku
  • CLI & MCP-Server: Für lokale Nutzung, CI/CD oder Integration in Tools wie Cursor
  • Umfassende Cursor-Integration: Erweiterte Rules und Befehle für optimierten Workflow
  • Strukturierter Wartungsplan: Klare Roadmap für kurz-, mittel- und langfristige Entwicklung
  • Extensibel: Neue Formate, Sprachen, Ausgabestile und Befehle einfach ergänzbar

So funktioniert's: Ein typischer Workflow

1. Installation

npm install
doc-gen-mcp --help

2. Dokumentation aus JSON, Code oder Verzeichnis generieren

bin/gendoc.js --input ./src --output ./docs/README.md

3. Mit KI-Unterstützung (z.B. OpenAI GPT)

bin/gendoc.js --input ./src --output ./docs/ai-doc.md --ai --ai-provider openai --openai-key $OPENAI_API_KEY

4. Export zu verschiedenen Zielplattformen

bin/gendoc.js --input ./src --export-format confluence --page-title "API Dokumentation"
bin/gendoc.js --input ./src --output ./docs/api.html --export-format html
bin/gendoc.js --input ./src --output ./docs/api.pdf --export-format pdf

5. Integration in Cursor (als Custom Command)

{
  "name": "Generate AI Documentation (OpenAI)",
  "command": "bin/gendoc.js --input ./src --output ./docs/ai-doc.md --ai --ai-provider openai --openai-key $OPENAI_API_KEY",
  "description": "Erzeuge Markdown-Doku mit OpenAI GPT und speichere sie in docs/ai-doc.md"
}

AI-Power: Was bringt die KI-Integration?

Gerade bei großen oder schlecht dokumentierten Codebasen kann die KI-Funktionalität enorm Zeit sparen. doc-gen-mcp schickt den Code an das gewählte Modell (z.B. OpenAI GPT) und erhält daraus automatisch generierte, verständliche Markdown-Dokumentation – inklusive Beschreibung, Parametern und Rückgabewerten.

Vorteile:

  • Spart Zeit und Nerven
  • Hilft, Doku-Lücken zu schließen
  • Einheitlicher Stil, weniger Copy-Paste
  • Unterstützt verschiedene Provider (OpenAI, Anthropic, Gemini, Cohere, Azure)

Ein echter Durchbruch ist die Möglichkeit, verschiedene KI-Modelle flexibel zu nutzen – so kannst du selbst entscheiden, welches Modell für deine spezifischen Anforderungen oder Sicherheitsrichtlinien am besten passt.

Plugin-Architektur: Erweiterbare Export-Ziele

Die Plugin-Architektur ermöglicht es, verschiedene Export-Ziele einfach zu integrieren:

  • BaseExporter: Abstrakte Basisklasse definiert das Interface für alle Exporter
  • ExporterManager: Verwaltet die verfügbaren Exporter-Plugins
  • Eigene Exporter: Einfach durch Erweitern der Basisklasse implementierbar

Diese Architektur macht es möglich, Dokumentation nicht nur als Markdown zu erzeugen, sondern direkt in verschiedene Systeme zu exportieren (Confluence, HTML, PDF, Swagger und mehr).

Besonders beeindruckend ist der PDF-Exporter mit professionellen Features wie Deckblättern, Inhaltsverzeichnissen und Syntax-Highlighting für Codeblöcke – perfekt für den Druck oder die Weitergabe als E-Book.

Erweiterte Cursor-Integration

Die Integration mit dem Cursor Editor wurde stark verbessert:

  • Umfassende Cursor Rules: Definiert Codequalitätsregeln speziell für doc-gen-mcp
  • Wartungsplan-Regeln: Hilft bei der Migration von JavaScript zu TypeScript
  • Vordefinierte Befehle: Über 20 nützliche Befehle für die tägliche Entwicklung
  • Dokumentations-Workflows: Generieren von Markdown, HTML, PDF oder Confluence-Seiten
  • Migrations-Helfer: Befehle für JS zu TS Migration und Fortschritts-Tracking
  • Wartungs-Reports: Automatische Generierung von Statusberichten

Die Cursor Rules sind nach Kategorien organisiert und erleichtern die Einhaltung von Best Practices, insbesondere bei der Plugin-Entwicklung und JavaScript zu TypeScript Migration.

Strukturierter Wartungsplan

Eine der wichtigsten Neuerungen ist der umfassende Wartungsplan:

Kurzfristige Maßnahmen (1-3 Monate)

  • JavaScript zu TypeScript Migration
  • Abhängigkeiten aktualisieren
  • Test-Suite erweitern

Mittelfristige Maßnahmen (3-6 Monate)

  • Sicherheitsverbesserungen
  • Dokumentation erweitern
  • Fehlerbehandlung verbessern

Langfristige Maßnahmen (6-12 Monate)

  • Unterstützung für weitere Programmiersprachen
  • Neue Export-Formate
  • Grafische Benutzeroberfläche
  • Leistungsoptimierungen

Kontinuierliche Aufgaben

  • Codequalität sicherstellen
  • Benutzerfeedback sammeln
  • Versionierung und Release-Management

Der Plan enthält klare Prioritäten, Aufwandschätzungen und messbare Erfolgskriterien.

Praxisbeispiel: Automatisierte Dokumentation in CI/CD

Ein Highlight in der Praxis: Durch den MCP-Server-Modus (stdio) lässt sich doc-gen-mcp nahtlos in CI/CD-Pipelines integrieren:

documentation:
  stage: build
  script:
    - npm install -g doc-gen-mcp
    - doc-gen --input ./src --output ./docs/api.md --export-format html
    - doc-gen --input ./src --ai --ai-provider openai --openai-key $OPENAI_API_KEY --output ./docs/ai-docs.md
  artifacts:
    paths:
      - docs/

So wird die Dokumentation bei jedem Commit oder Pull Request automatisch aktualisiert – ein Traum für jedes Entwicklungsteam!

Erweiterbarkeit & Best Practices

  • Eigene Formate? Einfach in lib/utils.js ergänzen
  • Mehr Sprachen? Textbausteine in generateDocsFromInput erweitern
  • Eigene Befehle? Neue Funktionen in index.js registrieren
  • Exporter hinzufügen? BaseExporter erweitern und in registerExporters.ts registrieren
  • Tests? Jest-basiert, einfach erweiterbar
  • Cursor Rules? Einfach neue Regeln in .cursor/cursorrules.json hinzufügen

Fazit: Moderne Doku, weniger Aufwand, klare Planung

doc-gen-mcp bringt Automatisierung und KI in die Dokumentationswelt. Egal ob für klassische API-Doku, Konfigs oder direkt aus dem Code – das Tool spart Zeit, sorgt für Konsistenz und lässt sich flexibel in bestehende Workflows integrieren. Mit der erweiterten Cursor-Integration und dem strukturierten Wartungsplan ist es nicht nur ein leistungsfähiges Tool für heute, sondern hat auch eine klare Roadmap für die Zukunft. Wer moderne Entwicklung und Automatisierung schätzt, sollte doc-gen-mcp ausprobieren!

Mehr Infos & Source: GitHub-Repo