ASTra MCP

ASTra MCP — Permanent Code Memory for AI Coding Assistants

MCP server that gives Claude Code, Cursor, Codex and Windsurf structural memory of your codebase

AST parsing · Knowledge graph · PageRank · Semantic embeddings · 100% local · 98.9% token reduction

[](https://ast-ra-mcp.vercel.app/demo) [](LICENSE) [](https://python.org) [](https://modelcontextprotocol.io)

[](benchmarks/) [](#) [](#-privacy--security) [](#-privacy--security) [](#-installation)

[Quickstart](#-quickstart) · [Integrate](#-integrate-with-your-ai-assistant) · [How It Works](#-how-it-works) · [All Commands](#-command-reference) · [Architecture](ARCHITECTURE.md) · Live Demo

---

ASTra MCP is an open-source MCP server that builds a permanent AST knowledge graph of your codebase, so AI coding assistants like Claude Code, Cursor, and Codex get surgical context — not entire files. 98.9% fewer tokens. Zero cloud. Runs fully local.

---

🔥 The Problem

Your AI assistant reads entire files to understand your codebase. On a 100k-line repo that's 500k+ tokens per session.

• ⏱️ Slow, expensive responses
• 💸 Burns API credits fast
• 🚫 Hits context window limits
• 🎯 Misses cross-file connections
• 🔁 Re-reads the same code every session

⚡ The Fix

ASTra builds a permanent knowledge graph of your codebase. Every AI task gets only the 5–25 most relevant functions — not 50 whole files.

• 🚀 Sub-second context injection
• 💰 ~99% reduction in tokens
• ♾️ Never hits context limits
• 🧠 Understands cross-file structure
• 💾 Memory persists across sessions

---

📊 Real Numbers

| Metric | ❌ Without ASTra | ✅ With ASTra | Saved | |--------|-----------------|--------------|-------| | Tokens per task | ~112,000 | ~1,250 | 98.9% | | Cost per task (Claude Sonnet) | $0.34 | $0.004 | $0.336 | | Time to context | 12–18 s | `

> 💡 50 AI tasks/day × 10 engineers = roughly $5,000/month saved.

---

🎬 See It In Action

A function migrates between code clusters. Edges re-wire live. Loops every 6s.

🎮 Open Interactive Demo →

Drag nodes · Click to inspect callers/callees · Watch live migration

---

🚀 Quickstart

# 1. Install
pip install astra-mcp

# 2. Index your project (one-time, ~60s)
cd ~/your-project
astra init

# 3. Start live daemon (keeps graph hot in memory)
astra daemon start

# 4. Connect your AI assistant (2 min setup)
# → Claude Code:  add to ~/.claude/mcp.json  (or use Plugin)
# → Cursor:       Settings → Features → MCP Servers
# → Windsurf:     Settings → MCP
# → Continue.dev: ~/.continue/config.json
# Full per-assistant instructions: see "Integrate With Your AI Assistant" below

# 5. Optional: open the visual dashboard
astra dashboard
# → http://localhost:7865

That's it. Your AI assistant now has permanent structural memory of your codebase.

---

🧠 How It Works

YOUR CODEBASE
      │
      ▼
┌─────────────────────────────────────────────────────────────┐
│  PHASE 1 — INDEX  (one-time, ~60s)                          │
│                                                             │
│  tree-sitter  →  AST parse every .py / .js / .ts file      │
│       ↓                                                     │
│  Extract symbols: functions, classes, methods, imports      │
│       ↓                                                     │
│  all-MiniLM-L6-v2  →  embed each symbol → 384-dim vector   │
│       ↓                                                     │
│  SQLite  →  store nodes + edges + embeddings                │
└─────────────────────────────────────────────────────────────┘
      │
      ▼
┌─────────────────────────────────────────────────────────────┐
│  PHASE 2 — LIVE DAEMON  (background process)                │
│                                                             │
│  watchdog  →  detects file saves → re-index changed file    │
│  Unix socket  →  any tool queries the live in-memory graph  │
│  Incremental PageRank  →  updates subgraph only (10× faster)│
└─────────────────────────────────────────────────────────────┘
      │
      ▼
┌─────────────────────────────────────────────────────────────┐
│  PHASE 3 — QUERY  (per AI task,  Pick your assistant below. Each takes under 2 minutes.

---

## 🔌 Integrate With Your AI Assistant

### Claude Code

**Option A — Plugin (zero config, recommended)**

Claude Code → Settings → Manage Plugins → search "astra" → Install

Done. ASTra activates automatically for every project.

**Option B — Manual MCP config**

Find your Claude Code config file:
```bash
# macOS / Linux
~/.claude/mcp.json

# Or per-project (takes priority)
/your-project/.mcp.json

Add ASTra:

{
  "mcpServers": {
    "astra": {
      "command": "python3",
      "args": ["-m", "astra.mcp.server"],
      "env": {
        "ASTRA_PROJECT": "/absolute/path/to/your-project",
        "ASTRA_DATA_DIR": "/absolute/path/to/your-project/.astra"
      }
    }
  }
}

Restart Claude Code. You'll see astra in the MCP server list (green dot = connected).

Verify it's working:

/mcp                         ← shows all connected servers
astra_index_status           ← call this tool to check node count

---

Cursor

1. Open Cursor → Settings → Features → MCP Servers
2. Click + Add Server
3. Fill in:

| Field | Value | |---|---| | Name | astra | | Command | python3 | | Args | -m astra.mcp.server |

Or edit ~/.cursor/mcp.json directly:

{
  "mcpServers": {
    "astra": {
      "command": "python3",
      "args": ["-m", "astra.mcp.server"],
      "env": {
        "ASTRA_PROJECT": "/absolute/path/to/your-project",
        "ASTRA_DATA_DIR": "/absolute/path/to/your-project/.astra"
      }
    }
  }
}

Restart Cursor. The ASTra tools appear in Cursor's tool list automatically.

---

GitHub Copilot (VS Code)

Copilot supports MCP via the VS Code MCP extension.

1. Install: VS Code → Extensions → search "MCP Client" → install MCP Client for VS Code
2. Open settings.json (Cmd+Shift+P → Preferences: Open User Settings JSON)
3. Add:

{
  "mcp.servers": {
    "astra": {
      "command": "python3",
      "args": ["-m", "astra.mcp.server"],
      "env": {
        "ASTRA_PROJECT": "/absolute/path/to/your-project",
        "ASTRA_DATA_DIR": "/absolute/path/to/your-project/.astra"
      }
    }
  }
}

1. Restart VS Code → Copilot Chat will now call ASTra tools automatically.

---

Windsurf (Codeium)

1. Open Windsurf → Settings → MCP
2. Add a new server entry:

{
  "mcpServers": {
    "astra": {
      "command": "python3",
      "args": ["-m", "astra.mcp.server"],
      "env": {
        "ASTRA_PROJECT": "/absolute/path/to/your-project",
        "ASTRA_DATA_DIR": "/absolute/path/to/your-project/.astra"
      }
    }
  }
}

1. Click Reload. ASTra appears in Windsurf's connected tools.

---

OpenAI Codex / ChatGPT with Code Interpreter

Codex doesn't support MCP natively yet. Use the CLI bridge instead:

# Query ASTra from any terminal, pipe output to Codex
astra query "add rate limiting to auth middleware"
# Copy the output → paste into Codex chat as context

# Or use daemon for fast repeated queries
astra daemon start
astra daemon query "fix the payment flow"

For automation, use the JSON output flag:

astra query "task description" --no-tokens | jq '.context'

---

Continue.dev

Edit ~/.continue/config.json:

{
  "mcpServers": [
    {
      "name": "astra",
      "command": "python3",
      "args": ["-m", "astra.mcp.server"],
      "env": {
        "ASTRA_PROJECT": "/absolute/path/to/your-project",
        "ASTRA_DATA_DIR": "/absolute/path/to/your-project/.astra"
      }
    }
  ]
}

Restart Continue. Tools appear under @astra in chat.

---

Any MCP-Compatible Client

ASTra uses the standard Model Context Protocol over stdio. If your tool supports MCP, this config works:

{
  "mcpServers": {
    "astra": {
      "command": "python3",
      "args": ["-m", "astra.mcp.server"],
      "env": {
        "ASTRA_PROJECT": "/absolute/path/to/your-project",
        "ASTRA_DATA_DIR": "/absolute/path/to/your-project/.astra"
      }
    }
  }
}

Finding the right Python path (if python3 doesn't work):

which python3           # use this full path in "command"
# e.g. /usr/local/bin/python3  or  /opt/homebrew/bin/python3

---

🔧 Troubleshooting Connection Issues

Server shows red / not connected

# 1. Verify astra is installed
python3 -m astra.mcp.server --help

# 2. Check paths are absolute (relative paths fail in MCP configs)
# ✅  /Users/you/project/.astra
# ❌  .astra

# 3. Check the crash log
cat ~/.astra-mcp/crash.log

Tools not appearing in assistant

# Confirm server starts successfully
python3 -m astra.mcp.server
# Should print: ASTra MCP server starting. project=...
# (Ctrl+C to stop)

Index is empty / no context returned

cd /your-project
astra init          # re-index
astra status        # should show nodes > 0

Wrong project being indexed

Set ASTRA_PROJECT explicitly in the MCP config env block to the absolute path of your repo root.

---

🏗 Architecture

Full deep-dive → [ARCHITECTURE.md](ARCHITECTURE.md)

astra/
├── daemon/         ← Live background process + Unix socket server
├── indexer/        ← tree-sitter parser + sentence-transformer embedder
├── graph/          ← SQLite store + NetworkX PageRank
├── query/          ← Semantic search + context serializer
├── impact/         ← Blast radius analyzer
├── semantics/      ← Drift detector
├── temporal/       ← Git history replay + volatility scoring
├── federation/     ← Cross-repo graph linker
├── mcp/            ← MCP stdio server + 11 tools
├── dashboard/      ← FastAPI + D3.js real-time dashboard
├── memory/         ← Session memory store
├── watcher/        ← watchdog file monitor
└── cli/            ← typer CLI

Stack:

• 🌳 tree-sitter — AST parsing (Python, JS, TS, JSX, TSX)
• 🤖 sentence-transformers — local embeddings (all-MiniLM-L6-v2, 384-dim)
• 🕸 NetworkX — Personalized PageRank over call graph
• 💾 SQLite — zero-dependency knowledge graph storage
• 🛰 MCP protocol — stdio interface for AI assistants
• 🌐 FastAPI + D3.js v7 — real-time knowledge graph dashboard

---

🔐 Privacy & Security

| | | |---|---| | ✅ | Local-first — code never leaves your machine | | ✅ | No telemetry — ASTra doesn't phone home | | ✅ | No API keys — embeddings model runs 100% locally | | ✅ | Self-hosted dashboard — localhost only | | ✅ | Open source — Apache 2.0, audit everything | | ✅ | Delete anytime — rm -rf .astra removes all data |

Safe for confidential codebases: medical, financial, defense, enterprise.

---

🆚 vs. Alternatives

| | ASTra | grep | Copilot RAG | Chroma RAG | tree-sitter | |---|:---:|:---:|:---:|:---:|:---:| | Semantic search | ✅ | ❌ | ✅ | ✅ | ❌ | | Structural (AST) | ✅ | ❌ | ❌ | ❌ | ✅ | | Call graph / PageRank | ✅ | ❌ | ❌ | ❌ | ❌ | | Local / no cloud | ✅ | ✅ | ❌ | partial | ✅ | | Auto-injects to AI | ✅ | ❌ | partial | manual | ❌ | | Persistent memory | ✅ | ❌ | ❌ | ❌ | ❌ | | Impact analysis | ✅ | ❌ | ❌ | ❌ | ❌ | | Cross-repo tracing | ✅ | ❌ | ❌ | ❌ | ❌ |

---

❓ FAQ

Does this slow down my AI assistant?

No. Daemon queries take ~10ms. You save 10–15 seconds of file-reading per task.

How big is the index?

Roughly 1–3% of source size. A 50,000-line codebase produces a ~2MB SQLite file.

Languages supported?

Python, JavaScript, TypeScript, JSX, TSX. Go, Rust, Java planned.

What if my code changes constantly?

File watcher re-indexes changed files in

Does it work offline?

Yes. After first install, the embeddings model (~80MB) is cached locally. No internet needed.

How is this different from RAG?

RAG embeds raw text chunks. ASTra embeds parsed symbols with structural context — function signatures, docstrings, call relationships. Far higher signal density per token.

Does ASTra train on my code?

No. All computation is local. Nothing sent anywhere. Embeddings stored in .astra/graph.db.

Can I delete the index?

rm -rf .astra — rebuild with astra init.

---

🗺 Roadmap

• [x] Python, JS, TS parser
• [x] Personalized PageRank
• [x] MCP stdio protocol (11 tools)
• [x] Real-time dashboard
• [x] Live daemon + Unix socket
• [x] Impact analyzer
• [x] Semantic drift detector
• [x] Temporal knowledge graph
• [x] Cross-repo federation
• [ ] Go, Rust, Java parsers
• [ ] VS Code inline graph extension
• [ ] Team-shared index (S3/GCS backend)
• [ ] HNSW indexing for 100k+ symbol corpora
• [ ] Pre-commit hook installer

---

🤝 Contributing

Read [CONTRIBUTING.md](CONTRIBUTING.md) for full setup instructions and guidelines.

PRs welcome. High-value areas:

• 🌐 New language parsers (Go, Rust, Java) — [astra/indexer/parser.py](astra/indexer/parser.py)
• 📊 Benchmarks on diverse codebases — [benchmarks/](benchmarks/)
• 🎨 Dashboard UX — [astra/dashboard/](astra/dashboard/)
• 🧪 Test coverage — [tests/](tests/)

Please read our [Code of Conduct](CODEOFCONDUCT.md) before contributing.

---

📜 License

Apache License 2.0 · Copyright © 2026 Narra Satya Sai Charan

[](LICENSE)

| | Apache 2.0 allows | |---|---| | ✅ | Commercial use, modification, distribution | | ✅ | Patent grant from all contributors | | ✅ | Private use without releasing changes | | 📌 | Must: include LICENSE + NOTICE, state changes, keep copyright |

Full text → [LICENSE](LICENSE)

---

🕸 ASTra MCP — Code memory that thinks like an engineer.

Built by Narra Satya Sai Charan

If ASTra saves you tokens, ⭐ star the repo — it helps others find it.

Made with ☕ and a deep grudge against context window limits.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Charan-place
• Source: Charan-place/ASTra-MCP
• License: Apache-2.0
• Homepage: https://ast-ra-mcp.vercel.app

Install and usage instructions live in the source repository linked above.