MCP für Code-Dokumentation: Ein Nachschlagewerk für Legacy-Projekte

from pathlib import Path

PROJECT_ROOT = Path("/path/to/project")
DOCS_ROOT = Path.home() / "Documents" / "project-docs"

@mcp.tool()
def read_module(module_name: str) -> str:
    """Liest ein Perl-Modul und gibt den Inhalt zurück."""
    # Module::Name -> Module/Name.pm
    path = module_name.replace("::", "/") + ".pm"
    full_path = PROJECT_ROOT / "lib" / path

    if not full_path.exists():
        return f"Modul nicht gefunden: {module_name}"

    content = full_path.read_text()

    # Bei sehr langen Dateien kürzen
    if len(content) > 15000:
        content = content[:15000] + "\n\n... (gekürzt, Datei hat {len(content)} Zeichen)"

    return content


@mcp.tool()
def find_modules(pattern: str) -> str:
    """Findet Module die einem Muster entsprechen."""
    lib_path = PROJECT_ROOT / "lib"
    matches = list(lib_path.rglob(f"*{pattern}*.pm"))

    if not matches:
        return f"Keine Module gefunden für: {pattern}"

    # Pfade zu Modulnamen konvertieren
    modules = []
    for m in sorted(matches)[:30]:
        rel = m.relative_to(lib_path)
        name = str(rel.with_suffix("")).replace("/", "::")
        modules.append(name)

    return "\n".join(modules)


@mcp.tool()
def module_dependencies(module_name: str) -> str:
    """Zeigt welche Module ein Modul verwendet (use/require)."""
    path = module_name.replace("::", "/") + ".pm"
    full_path = PROJECT_ROOT / "lib" / path

    if not full_path.exists():
        return f"Modul nicht gefunden: {module_name}"

    content = full_path.read_text()

    # Einfaches Regex für use/require Statements
    import re
    uses = re.findall(r'^use\s+([\w:]+)', content, re.MULTILINE)
    requires = re.findall(r'^require\s+([\w:]+)', content, re.MULTILINE)

    deps = sorted(set(uses + requires))

    if not deps:
        return "Keine Abhängigkeiten gefunden"

    return "\n".join(deps)

@mcp.tool()
def write_doc(doc_type: str, name: str, content: str) -> str:
    """Schreibt eine Dokumentations-Datei.

    doc_type: 'module', 'table', 'flow' oder 'note'
    name: Name der Datei (ohne .md)
    content: Markdown-Inhalt
    """
    valid_types = ["module", "table", "flow", "note"]
    if doc_type not in valid_types:
        return f"Ungültiger Typ. Erlaubt: {valid_types}"

    folder = DOCS_ROOT / f"{doc_type}s"
    folder.mkdir(parents=True, exist_ok=True)

    # Dateiname bereinigen
    safe_name = name.replace("::", "_").replace("/", "_")
    filepath = folder / f"{safe_name}.md"

    filepath.write_text(content)
    return f"Geschrieben: {filepath}"


@mcp.tool()
def read_doc(doc_type: str, name: str) -> str:
    """Liest eine existierende Dokumentations-Datei."""
    safe_name = name.replace("::", "_").replace("/", "_")
    filepath = DOCS_ROOT / f"{doc_type}s" / f"{safe_name}.md"

    if not filepath.exists():
        return f"Dokumentation nicht gefunden: {filepath}"

    return filepath.read_text()


@mcp.tool()
def list_docs(doc_type: str = None) -> str:
    """Listet vorhandene Dokumentation auf."""
    if doc_type:
        folder = DOCS_ROOT / f"{doc_type}s"
        if not folder.exists():
            return f"Keine Dokumentation vom Typ: {doc_type}"
        files = sorted(folder.glob("*.md"))
    else:
        files = sorted(DOCS_ROOT.rglob("*.md"))

    if not files:
        return "Keine Dokumentation vorhanden"

    return "\n".join(f.stem for f in files[:50])

import hashlib
import json

HASH_FILE = DOCS_ROOT / ".module_hashes.json"

@mcp.tool()
def check_changes(module_name: str) -> str:
    """Prüft ob sich ein Modul seit der letzten Dokumentation geändert hat."""
    path = module_name.replace("::", "/") + ".pm"
    full_path = PROJECT_ROOT / "lib" / path

    if not full_path.exists():
        return f"Modul nicht gefunden: {module_name}"

    # Aktuellen Hash berechnen
    content = full_path.read_text()
    current_hash = hashlib.md5(content.encode()).hexdigest()

    # Gespeicherten Hash laden
    hashes = {}
    if HASH_FILE.exists():
        hashes = json.loads(HASH_FILE.read_text())

    stored_hash = hashes.get(module_name)

    if stored_hash is None:
        return f"{module_name}: Noch nie dokumentiert"
    elif stored_hash != current_hash:
        return f"{module_name}: GEÄNDERT seit letzter Dokumentation"
    else:
        return f"{module_name}: Unverändert"


@mcp.tool()
def mark_documented(module_name: str) -> str:
    """Markiert ein Modul als dokumentiert (speichert Hash)."""
    path = module_name.replace("::", "/") + ".pm"
    full_path = PROJECT_ROOT / "lib" / path

    if not full_path.exists():
        return f"Modul nicht gefunden: {module_name}"

    content = full_path.read_text()
    current_hash = hashlib.md5(content.encode()).hexdigest()

    hashes = {}
    if HASH_FILE.exists():
        hashes = json.loads(HASH_FILE.read_text())

    hashes[module_name] = current_hash
    HASH_FILE.write_text(json.dumps(hashes, indent=2))

    return f"{module_name}: Als dokumentiert markiert"

# {Modulname}

**Pfad:** `lib/Order/Validation.pm`
**Letzte Dokumentation:** 2025-12-29
**Status:** Aktuell

## Zweck

Kurze Beschreibung, was das Modul macht.

## Wichtige Funktionen

### `validate_order($order)`

Validiert eine Bestellung vor dem Checkout.

- **Parameter:** `$order` - Order-Objekt
- **Rückgabe:** `1` bei Erfolg, `0` bei Fehlern
- **Seiteneffekte:** Setzt `$order->errors` bei Validierungsfehlern

### `validate_payment($payment_data)`

...

## Abhängigkeiten

- [[Order::Base]] - Basisklasse
- [[Payment::Gateway]] - Zahlungsanbindung
- [[Database::Orders]] - Datenbankzugriff

## Verwendet von

- [[Checkout::Process]]
- [[API::Orders]]

## Notizen

- Achtung: Validierung für Sonderfälle (Gutscheine > Warenwert) ist in `_handle_edge_cases`
- Die Funktion `_legacy_validate` wird noch für alte API-Clients gebraucht