Codevira MCP

Persistenter adaptiver Speicher für KI-Coding-Agenten — lernt aus jeder Sitzung, funktioniert mit jedem Tool, erinnert sich über jedes Projekt hinweg.

Funktioniert mit: Claude Code · Cursor · Windsurf · Google Antigravity · jedem MCP-kompatiblen KI-Tool

Das Problem

Jedes Mal, wenn Sie eine neue KI-Coding-Sitzung starten, beginnt Ihr Agent bei Null.

Er liest Dateien erneut, die er bereits gesehen hat. Er entdeckt Muster wieder, die bereits etabliert wurden. Er trifft Entscheidungen, die den Entscheidungen der letzten Woche widersprechen. Er hat keine Ahnung, in welcher Phase sich das Projekt befindet, was bereits ausprobiert wurde oder warum bestimmte Dateien tabu sind.

Sie verbringen Tausende von Token mit der Wiederentdeckung — in jeder einzelnen Sitzung.

Codevira behebt das.

Was es tut

Codevira ist ein Model Context Protocol-Server, den Sie in jedes Projekt einbinden können. Er gibt jedem KI-Agenten, der an Ihrer Codebasis arbeitet, einen gemeinsamen, persistenten Speicher:

Das Ergebnis: ca. 1.400 Token Overhead pro Sitzung statt 15.000+ Token für die Wiederentdeckung.

Wie es funktioniert

Agenten-Sitzungslebenszyklus

flowchart TB

Start([Start Session])

subgraph Orientation
A[Check Open Changesets]
B[Get Project Roadmap]
C[Search Past Decisions]
D[Load Graph Context\nget_node • get_impact]
end

subgraph Execution
E[Plan Task]
F[Implement Code]
G[Run Tests / Validation]
end

subgraph Completion
H[Update Graph Metadata]
I[Write Session Log]
J[Complete Changeset]
end

Start --> A
A --> B
B --> C
C --> D
D --> E
E --> F
F --> G
G --> H
H --> I
I --> J

Code-Intelligenz-Modell

flowchart TB

A[Source Code]

subgraph Structural Analysis
B[AST Parser]
C[Function / Class Extraction]
D[Dependency Analysis]
end

subgraph Knowledge Stores
E[(Semantic Index<br/>ChromaDB)]
F[(Context Graph<br/>SQLite DB)]
end

subgraph Runtime Access
G[MCP Query Layer<br/>search_codebase • get_node • get_impact]
end

H[AI Coding Agent<br/>Claude Code • Cursor]

A --> B
B --> C
C --> E

B --> D
D --> F

E --> G
F --> G

G --> H

Schnellstart

1. Installation

pip install codevira-mcp

2. Initialisierung in Ihrem Projekt

cd your-project
codevira init

Dieser einzelne Befehl:

• Erstellt .codevira/ mit Konfigurations-, Graph- und Protokollverzeichnissen

• Fügt .codevira/ zu .gitignore hinzu (Index wird automatisch neu generiert, kein Commit erforderlich)

• Fragt nach Projektname, Sprache, Quellverzeichnissen (durch Kommas getrennt) und Dateierweiterungen

• Erstellt den vollständigen Code-Index mittels SHA-256-Content-Hashing (nur geänderte Dateien werden neu indiziert)

• Generiert automatisch Graph-Stubs für alle Quelldateien

• Bootstrappt .codevira/roadmap.yaml aus der Git-Historie

• Installiert einen post-commit Git-Hook für die automatische Neuindizierung

• Gibt den MCP-Konfigurationsblock aus, den Sie in Ihr KI-Tool einfügen können

Live-Auto-Überwachung: Wenn der MCP-Server startet, startet er automatisch eine Hintergrund-Dateiüberwachung. Jedes Mal, wenn Sie eine Quelldatei speichern, wird der Index innerhalb von 2 Sekunden aktualisiert — keine manuellen Befehle erforderlich. Der post-commit-Hook und das codevira index CLI bleiben als Alternativen verfügbar.

3. Verbindung zu Ihrem KI-Tool herstellen

Je nach IDE und Umgebung befindet sich codevira-mcp möglicherweise nicht automatisch in Ihrem PATH. Sie können uvx (die einfachste Option) verwenden oder den absoluten Pfad zu Ihrer Python-virtuellen Umgebung angeben.

Option A: Verwendung von uvx (Empfohlen für alle IDEs ohne lokale Installation) Wenn Sie uv verwenden, können Sie den MCP-Server nahtlos ausführen, ohne virtuelle Umgebungen pro Projekt verwalten zu müssen.

Claude Code (.claude/settings.json), Cursor / Windsurf (Einstellungen → MCP):

{
  "mcpServers": {
    "codevira": {
      "command": "uvx",
      "args": ["codevira-mcp", "--project-dir", "/path/to/your-project"]
    }
  }
}

Option B: Verwendung einer lokalen Venv (Empfohlen, funktioniert überall) Verweisen Sie Ihr KI-Tool direkt auf die Python-Laufzeitumgebung in Ihrer .venv, in der codevira-mcp installiert ist.

Claude Code (.claude/settings.json) oder Cursor / Windsurf (Einstellungen → MCP):

{
  "mcpServers": {
    "codevira": {
      "command": "/path/to/your-project/.venv/bin/python",
      "args": ["-m", "mcp_server", "--project-dir", "/path/to/your-project"]
    }
  }
}

Google Antigravity — hinzufügen zu ~/.gemini/antigravity/mcp_config.json:

{
  "mcpServers": {
    "codevira": {
      "$typeName": "exa.cascade_plugins_pb.CascadePluginCommandTemplate",
      "command": "/path/to/your-project/.venv/bin/python",
      "args": ["-m", "mcp_server", "--project-dir", "/path/to/your-project"]
    }
  }
}

⚠️ WICHTIG: Verwendung globaler Clients (Antigravity / Claude Desktop) mit mehreren Projekten

Im Gegensatz zu Cursor, das automatisch isolierte MCP-Server pro Projekt startet, teilen globale Clients wie Antigravity eine einzige mcp_config.json über alle Ihre offenen Projekte hinweg.

Wenn Sie codevira einmal für Projekt A konfigurieren und dann eine Frage zu Projekt B stellen, liest der Agent den Graphen und die Roadmap von Projekt A.

Um dies zu beheben: Sie müssen für jedes Projekt eindeutig benannte Server in Ihrer globalen Konfiguration registrieren. Die KI wählt dynamisch das richtige Tool-Präfix basierend auf Ihrem Gesprächskontext:

{
  "mcpServers": {
    "codevira-project-a": {
      "$typeName": "exa.cascade_plugins_pb.CascadePluginCommandTemplate",
      "command": "uvx",
      "args": ["codevira-mcp", "--project-dir", "/path/to/project-a"]
    },
    "codevira-project-b": {
      "$typeName": "exa.cascade_plugins_pb.CascadePluginCommandTemplate",
      "command": "uvx",
      "args": ["codevira-mcp", "--project-dir", "/path/to/project-b"]
    }
  }
}

4. Überprüfung

Bitten Sie Ihren Agenten, get_roadmap() aufzurufen — es sollte Ihre aktuelle Phase und die nächste Aktion zurückgeben.

Projektstruktur nach der Initialisierung

your-project/
├── src/                   ← your code (indexed)
├── .codevira/             ← Codevira data directory (git-ignored)
│   ├── config.yaml        ← project configuration
│   ├── roadmap.yaml       ← project roadmap (auto-generated, human-enrichable)
│   ├── codeindex/         ← ChromaDB index (auto-regenerated)
│   └── graph/             ← context graph and session memory
│       ├── graph.db       ← SQLite database for nodes, edges, logs, and decisions
│       └── changesets/    ← active multi-file change records
└── requirements.txt       ← add: codevira-mcp>=1.0.0

Roadmap-Lebenszyklus: Die Roadmap wird während der Initialisierung automatisch generiert und vom Agenten durch MCP-Tool-Aufrufe aktualisiert. Siehe docs/roadmap.md für den vollständigen Leitfaden zum Lebenszyklus, manuelle Bearbeitungsschritte und Fehlerbehebung.

Sitzungsprotokoll

Jede Agentensitzung folgt einem einfachen Protokoll. Richten Sie es einmal im System-Prompt Ihres Agenten ein — dann erledigen Ihre Agenten den Rest.

Sitzungsstart (obligatorisch):

list_open_changesets()      → resume any unfinished work first
get_roadmap()               → current phase, next action
search_decisions("topic")   → check what's already been decided
get_node("src/service.py")  → read rules before touching a file
get_impact("src/service.py") → check blast radius

Sitzungsende (obligatorisch):

complete_changeset(id, decisions=[...])
update_node(file_path, changes)
update_next_action("what the next agent should do")
write_session_log(...)

Diese Schleife hält jede Sitzung schnell, fokussiert und fortsetzbar.

33 MCP-Tools

Graph-Tools

Roadmap-Tools

Änderungssatz-Tools

Such-Tools

Adaptive Lern-Tools (v1.4)

Code-Reader-Tools

Playbook-Tool

Agenten-Personas

Sieben Rollendefinitionen in agents/ sagen jedem Agenten genau, was er tun soll und wann:

Projektstruktur

.agents/
├── PROTOCOL.md              # Session protocol — read this first
├── config.example.yaml      # Config template
├── config.yaml              # Your config (git-ignored)
├── roadmap.yaml             # Phase tracker (auto-created, git-ignored)
├── mcp-server/
│   ├── server.py            # MCP server entry point
│   └── tools/
│       ├── graph.py
│       ├── roadmap.py
│       ├── changesets.py
│       ├── search.py
│       ├── playbook.py
│       └── code_reader.py
├── indexer/
│   ├── index_codebase.py    # Build/update ChromaDB index + background file watcher
│   ├── chunker.py           # AST-based code chunker
│   ├── treesitter_parser.py # Multi-language AST parsing (16+ languages)
│   ├── sqlite_graph.py      # SQLite graph database backend
│   └── graph_generator.py   # Auto-generate graph stubs
├── requirements.txt         # Python dependencies
├── agents/                  # Role definitions
│   ├── orchestrator.md
│   ├── planner.md
│   ├── developer.md
│   ├── reviewer.md
│   ├── tester.md
│   ├── builder.md
│   └── documenter.md
├── rules/                   # Engineering standards
│   ├── master_rule.md
│   ├── coding-standards.md
│   ├── testing-standards.md
│   └── ...13 more
├── graph/
│   ├── graph.db             # SQLite Context Graph and Session Memory (git-ignored)
│   └── changesets/
├── hooks/
│   └── install-hooks.sh
└── codeindex/               # ChromaDB files (git-ignored)

Sprachunterstützung

Alle Sitzungsverwaltungs-, Graph-, Roadmap- und Suchfunktionen funktionieren für jede Sprache. Code-Parsing und -Extraktion (Suche, Graph-Generierung, Signatur-Lesevorgänge) werden durch robuste AST- und Tree-Sitter-Integrationen unterstützt.

Anforderungen

• Python 3.10+

• ChromaDB

• sentence-transformers

• PyYAML

pip install -r .agents/requirements.txt

Hintergrund

Möchten Sie die ganze Geschichte darüber verstehen, warum dies gebaut wurde, die Designentscheidungen, was nicht funktioniert hat und wie es im Vergleich zu anderen Tools im Ökosystem abschneidet?

Lesen Sie den vollständigen Bericht: How We Cut AI Coding Agent Token Usage by 92%

Mitwirken

Beiträge sind willkommen — dies ist ein Open-Source-Projekt im Frühstadium und es gibt viel Raum für Wachstum.

Lesen Sie CONTRIBUTING.md für den vollständigen Leitfaden: Forking, Branch-Benennung, Commit-Format und PR-Prozess.

Gute erste Bereiche: