World Model MCP

Die Ereignisuhr für Coding-Agenten. Ein MCP-Server, der einen temporalen Wissensgraphen für Ihre Codebasis erstellt – erfasst Entscheidungsabläufe aus Claude Code-Sitzungen, verknüpft diese mit Testergebnissen, lernt Trajektorien und erzwingt Einschränkungen an der Bearbeitungsgrenze.

Status: Alpha (v0.6.0) – Die Ereignisuhr für Coding-Agenten. 22 MCP-Tools, 186 Tests, PreToolUse-Durchsetzung, Entscheidungsabläufe, Vorhersageschicht. Beiträge sind willkommen.

PyPI Downloads License: MIT Python 3.11+

Was es tut

World Model MCP erstellt einen temporalen Wissensgraphen Ihrer Codebasis, der aus jeder Claude Code-Sitzung lernt, um:

Halluzinationen zu verhindern - Validiert API-/Funktionsreferenzen vor der Verwendung gegen bekannte Entitäten
Wiederholte Fehler zu stoppen - Lernt Einschränkungen aus Korrekturen und wendet sie in zukünftigen Sitzungen an
Regressionen zu reduzieren - Verfolgt Fehlerbehebungen und warnt, wenn Änderungen kritische Bereiche betreffen

Stellen Sie es sich so vor, als würden Sie Claude ein Langzeitgedächtnis für Ihr Projekt geben.

Schnellstart

Installation

# 1. Install the package
pip install world-model-mcp

# 2. Setup in your project (auto-seeds the knowledge graph from existing code)
cd /path/to/your/project
python -m world_model_server.cli setup

# 3. Restart Claude Code
# Done! The world model is pre-populated and active

Sie können das Projekt auch jederzeit neu oder manuell initialisieren:

# Seed from existing codebase
world-model seed

# Re-seed with force (re-processes already seeded files)
world-model seed --force

Was wird installiert

your-project/
├── .mcp.json                    # MCP server configuration
├── .claude/
│   ├── settings.json           # Hook configuration
│   ├── hooks/                  # Compiled TypeScript hooks
│   └── world-model/            # SQLite databases (~155 KB)

Funktionen

1. Verhinderung von Halluzinationen

Vorher:

// Claude invents an API that doesn't exist
const user = await User.findByEmail(email); // This method doesn't exist

Nachher:

// Claude checks the world model first
const user = await User.findOne({ email }); // Verified to exist

Ziel: Reduzierung nicht existierender API-Referenzen durch Validierung gegen den Wissensgraphen

2. Lernen aus Korrekturen

Sitzung 1: Benutzer korrigiert Claude

// Claude writes:
console.log('debug info');

// User corrects to:
logger.debug('debug info');

// World model learns: "Use logger.debug() not console.log()"

Sitzung 2: Claude verwendet das gelernte Muster

// Claude automatically writes:
logger.debug('debug info'); // No correction needed

Ziel: Gelernte Muster bleiben über Sitzungen hinweg bestehen und verhindern wiederholte Verstöße

3. Verhinderung von Regressionen

// Week 1: Bug fixed (null check added)
if (user && user.email) { ... }

// Week 2: Refactoring
// World model warns: "This line preserves a critical bug fix"
// Claude preserves the null check

// Result: Bug not re-introduced

Ziel: Erkennung potenzieller Regressionen vor der Codeausführung

Funktionsweise

Architektur

┌──────────────────────────────────────────────────────────┐
│ Claude Code + Hooks                                      │
│ Captures: file edits, tool calls, user corrections       │
└──────────────────────────────────────────────────────────┘
                         |
                         v
┌──────────────────────────────────────────────────────────┐
│ MCP Server (Python)                                      │
│ - 22 MCP tools for querying/recording/predicting          │
│ - LLM-powered entity extraction (Claude Haiku)           │
│ - External linter integration (ESLint, Pylint, Ruff)     │
└──────────────────────────────────────────────────────────┘
                         |
                         v
┌──────────────────────────────────────────────────────────┐
│ Knowledge Graph (SQLite + FTS5)                          │
│ - entities.db: APIs, functions, classes                  │
│ - facts.db: Temporal assertions with evidence            │
│ - relationships.db: Entity dependency graph              │
│ - constraints.db: Learned rules from corrections         │
│ - sessions.db: Session history and outcomes              │
│ - events.db: Activity log with reasoning chains          │
└──────────────────────────────────────────────────────────┘

Schlüsselkonzepte

Temporale Fakten: Jeder Fakt hat validAt- und invalidAt-Zeitstempel
- "Funktion X existierte vom 15.01.2024 bis zum 20.03.2024"
- Abfrage: "Was war am 1. März wahr?"
Beweisketten: Jede Behauptung lässt sich auf die Quelle zurückverfolgen
- Fakt -> Sitzung -> Ereignis -> Quellcode-Speicherort
Lernen von Einschränkungen: Mustererkennung aus Benutzerkorrekturen
- Automatische Ableitung von Regeltypen (Linting, Architektur, Tests)
- Erkennung des Schweregrads (Fehler, Warnung, Info)
- Beispielgenerierung für zukünftige Referenz
Duale Validierung: Kombiniert zwei Validierungsquellen
- Wissensmodell-Einschränkungen (vom Benutzer gelernt)
- Externe Linter (ESLint, Pylint, Ruff)

MCP-Tools

Zweiundzwanzig MCP-Tools für Claude Code verfügbar:

1. `query_fact`

Überprüfen Sie, ob APIs/Funktionen existieren, bevor Sie sie verwenden

result = query_fact(
    query="Does User.findByEmail exist?",
    entity_type="function"
)
# Returns: {exists: bool, confidence: float, facts: [...]}

2. `record_event`

Erfassen Sie Entwicklungsaktivitäten mit Argumentationsketten

record_event(
    event_type="file_edit",
    file_path="src/api/auth.ts",
    reasoning="Added JWT authentication middleware"
)

3. `validate_change`

Validierung vor der Ausführung gegen Einschränkungen und Linter

result = validate_change(
    file_path="src/api/auth.ts",
    proposed_content="..."
)
# Returns: {safe: bool, violations: [...], suggestions: [...]}

4. `get_constraints`

Abrufen projektspezifischer Regeln für eine Datei

constraints = get_constraints(
    file_path="src/**/*.ts",
    constraint_types=["linting", "architecture"]
)

5. `record_correction`

Aus Benutzereditierungen lernen (HOHE PRIORITÄT)

record_correction(
    claude_action={...},
    user_correction={...},
    reasoning="Use logger.debug instead of console.log"
)

6. `get_related_bugs`

Bewertung des Regressionsrisikos

result = get_related_bugs(
    file_path="src/api/auth.ts",
    change_description="refactoring authentication logic"
)
# Returns: {bugs: [...], risk_score: float, critical_regions: [...]}

7. `seed_project`

Scannen Sie die Codebasis und füllen Sie den Wissensgraphen mit Entitäten und Beziehungen

result = seed_project(
    project_dir=".",
    force=False
)
# Returns: {files_seeded: int, entities_created: int, relationships_created: int}

8. `ingest_pr_reviews`

GitHub PR-Review-Kommentare abrufen und Team-Feedback in Einschränkungen umwandeln

result = ingest_pr_reviews(
    repo="owner/repo",  # Auto-detected from git remote if omitted
    count=10
)
# Returns: {prs_scanned: int, constraints_created: int, constraints_updated: int}

Dokumentation

QUICKSTART.md - 5-Minuten-Einrichtungsanleitung
CONTRIBUTING.md - Richtlinien für Beiträge
RELEASE_NOTES.md - Versionsverlauf und Funktionen

Testen

# Run tests
pytest

# With coverage
pytest --cov=world_model_server --cov-report=html

186 Tests, die Wissensgraph-CRUD, FTS5-Suche, Einschränkungsmanagement, Fehlerverfolgung, automatisches Seeding, PR-Review-Aufnahme, Entscheidungsabläufe, Ergebnisverknüpfung, Trajektorienlernen, Vorhersageschicht, Speicherintegrität, Widerspruchserkennung, Transkriptzeiger, Projektidentität und PreToolUse-Durchsetzung abdecken. Siehe tests/ für Details.

Konfiguration

Umgebungsvariablen

# Database location (default: ./.claude/world-model/)
export WORLD_MODEL_DB_PATH="/custom/path"

# Anthropic API key (optional - enables LLM extraction)
# IMPORTANT: Never commit this! Use .env file (see .env.example)
export ANTHROPIC_API_KEY="your-api-key-here"

# Model selection
export WORLD_MODEL_EXTRACTION_MODEL="claude-3-haiku-20240307"  # Fast
export WORLD_MODEL_REASONING_MODEL="claude-3-5-sonnet-20241022"  # Accurate

# Debug mode
export WORLD_MODEL_DEBUG=1

Hinweis: Erstellen Sie eine .env-Datei in Ihrem Projektstammverzeichnis (siehe .env.example) – sie wird von Git automatisch ignoriert.

Anpassen von Hooks

Bearbeiten Sie .claude/settings.json, um anzupassen, welche Tools Wissensmodell-Hooks auslösen:

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write|Bash",
      "hooks": [...]
    }]
  }
}

Sprachunterstützung

Aktuell unterstützt:

TypeScript / JavaScript
Python

Demnächst verfügbar:

Go, Rust, Java, C++

Erweiterbare Architektur: Einfaches Hinzufügen neuer Sprachparser (siehe CONTRIBUTING.md)

Datenschutz und Sicherheit

Local-First: Alle Daten verbleiben auf Ihrem Computer
Keine Telemetrie: Null Tracking oder externe Datenübertragung
Optionales LLM: Funktioniert ohne API-Schlüssel (verwendet Regex-Muster als Fallback)
Verschlüsselter Speicher: SQLite-Datenbanken sind lokale Dateien (verschlüsseln Sie Ihre Festplatte zur Sicherheit)

API-Schlüssel-Nutzung (nur wenn Sie ANTHROPIC_API_KEY bereitstellen):

Entitätsextraktion aus Codeänderungen
Einschränkungsableitung aus Korrekturen
Sendet niemals: Anmeldeinformationen, Geheimnisse, PII

Sicherheits-Best-Practices:

Committen Sie niemals .env-Dateien
Verwenden Sie .env.example als Vorlage
Speichern Sie API-Schlüssel nur in Umgebungsvariablen oder .env-Dateien
Die .gitignore schließt sensible Dateien automatisch aus

Roadmap

v0.2.x

[x] Auto-Seeding: Wissensgraph füllt sich bei der Einrichtung aus der bestehenden Codebasis
[x] PR-Review-Intelligenz: GitHub-Review-Kommentare als Einschränkungen aufnehmen
[x] Beziehungsverfolgung: Import- und Abhängigkeitsgraph zwischen Entitäten
[x] Mehrsprachige Unterstützung: Python, TypeScript/JavaScript, Solidity, Go, Rust
[x] CLI-Abfragebefehl für Wissensgraph-Lookups
[x] 40 Tests, 8 MCP-Tools

v0.3.0

[x] Abgleich auf Modulebene: Abfrage nach Modulname findet die Datei und ihren Inhalt
[x] Inkrementelles Re-Seeding: Nur Dateien neu verarbeiten, die seit dem letzten Seeding geändert wurden
[x] Fuzzy-Entitätsabgleich: Ungefähre Namenssuche für Tippfehler und Abkürzungen
[x] Abfrage-Caching: In-Memory-Cache mit TTL für wiederholte Lookups
[x] Java-Unterstützung: Vollständige Abdeckung mehrerer Sprachen
[x] MCP-Server-Pipeline-Validierung an realen Projekten

v0.4.0

[x] Ergebnisverknüpfung: Testfehler mit Fakten mit Codeänderungen verknüpft
[x] Trajektorienlernen: Co-Edit-Muster über Sitzungen hinweg verfolgt
[x] Erfassung von Entscheidungsabläufen: Strukturiertes Protokoll von Agentenvorschlägen und menschlichen Korrekturen
[x] Projektübergreifende Entitätssuche mit Projektregistrierung
[x] 5 neue MCP-Tools (insgesamt 13), 104 Tests

v0.5.0

[x] Regressionsvorhersage, "Was-wäre-wenn"-Simulation, Testfehlervorhersage
[x] Projektübergreifender Wissenstransfer, Speicherintegrität, Fakt-TTL/Verfall
[x] get_context_for_action Pre-Edit-Bundle, Verfolgung von Einschränkungsverstößen, find_contradictions
[x] 20 MCP-Tools, 151 Tests

v0.6.0 (Aktuell) — Durchsetzung, Herkunft, Identität

[x] PreToolUse-Einschränkungs-Durchsetzungs-Hook: Verweigern harter Verstöße an der Bearbeitungsgrenze
[x] Indizierte Transkriptzeiger: Jeden Fakt zurück in das Quellgespräch hydrieren
[x] Entkopplung der Projektidentität: Stabile UUID bei Verzeichnisumbenennungen
[x] Content-Hash-Deduplizierung für Fakten und Einschränkungen
[x] Automatische Generierung von CLAUDE.md aus dem Wissensgraphen
[x] BetaAbstractMemoryTool-Unterklasse für Anthropic SDK-Integration
[x] Desktop-Erweiterung (.mcpb) Paketierung für Claude Desktop
[x] 22 MCP-Tools, 13 CLI-Unterbefehle, 186 Tests

v0.7.0 (Nächstes)

[ ] AST-basierte Extraktion via tree-sitter
[ ] Hintergrund-Fakt-Verfallsplaner (Opt-in)
[ ] Konfidenzgewichtete Widersprüche mit automatischer Auflösung
[ ] Organisationsweite Einschränkungsföderation

Mitwirken

Beiträge sind willkommen. Siehe CONTRIBUTING.md für:

Entwicklungseinrichtung
Codierungsstandards
Hinzufügen von Sprachunterstützung
Schreiben von Tests
Einreichen von PRs

Bereiche, in denen Hilfe benötigt wird:

Sprachparser (Go, Rust, Java, C++)
Leistungsoptimierung
Verbesserungen der Dokumentation
Feedback zu realen Tests

Statistiken

Projektgröße:

~4.800 Zeilen Code
13 Python-Module
3 TypeScript-Hook-Implementierungen

Speichereffizienz:

Leere Datenbank: ~155 KB
Pro Entität: ~500 Bytes
Pro Fakt: ~800 Bytes

Lizenz

MIT-Lizenz - Kostenlos für kommerzielle und private Nutzung

Support

Probleme: GitHub Issues
Diskussionen: GitHub Discussions