Codevira MCP Server

Codevira MCP

Persistent memory and project context for AI coding agents — across every session, every tool, every file.

Works with: Claude Code · Cursor · Windsurf · Google Antigravity · any MCP-compatible AI tool

The Problem

Every time you start a new AI coding session, your agent starts from zero.

It re-reads files it has seen before. It re-discovers patterns already established. It makes decisions that contradict last week's decisions. It has no idea what phase the project is in, what's already been tried, or why certain files are off-limits.

You end up spending thousands of tokens on re-discovery — every single session.

Codevira fixes this.

What It Does

Codevira is a Model Context Protocol server you drop into any project. It gives every AI agent that works on your codebase a shared, persistent memory:

The result: ~1,400 tokens of overhead per session instead of 15,000+ tokens of re-discovery.

How It Works

Agent Session Lifecycle

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 Intelligence Model

flowchart TB

A[Source Code]

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

subgraph Knowledge Stores
E[(Semantic IndexChromaDB)]
F[(Context GraphYAML Nodes)]
end

subgraph Runtime Access
G[MCP Query Layersearch_codebase • get_node • get_impact]
end

H[AI Coding AgentClaude Code • Cursor]

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

B --> D
D --> F

E --> G
F --> G

G --> H

Quick Start

1. Install

pip install codevira-mcp

2. Initialize in your project

cd your-project
codevira-mcp init

This single command:

• Creates .codevira/ with config, graph, and log directories
• Adds .codevira/ to .gitignore (index is auto-regenerated, no need to commit)
• Prompts for project name, language, source directories (comma-separated), and file extensions
• Builds the full code index
• Auto-generates graph stubs for all source files
• Bootstraps .codevira/roadmap.yaml from git history
• Installs a post-commit git hook for automatic reindexing
• Prints the MCP config block to paste into your AI tool

3. Connect to your AI tool

Depending on your IDE and environment, codevira-mcp may not automatically be in your PATH. You can use uvx (the easiest option) or provide the absolute path to your Python virtual environment.

Option A: Using uvx (Recommended for all IDEs without local install) If you use `uv`, you can run the MCP server seamlessly without managing virtual environments per project.

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

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

Option B: Using Local Venv (Recommended, works everywhere) Point your AI tool directly to the Python runtime inside your .venv where codevira-mcp is installed.

Claude Code (.claude/settings.json) or Cursor / Windsurf (Settings → MCP):

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