# ASTra MCP

> MCP server giving Claude Code, Cursor & Codex permanent AST code memory. 98.9% token reduction. 100% local.

- **Type:** MCP server
- **Install:** `agentstack add mcp-charan-place-astra-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Charan-place](https://agentstack.voostack.com/s/charan-place)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [Charan-place](https://github.com/Charan-place)
- **Source:** https://github.com/Charan-place/ASTra-MCP
- **Website:** https://ast-ra-mcp.vercel.app

## Install

```sh
agentstack add mcp-charan-place-astra-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](https://ast-ra-mcp.vercel.app/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 →](https://ast-ra-mcp.vercel.app/demo)**

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

---

## 🚀 Quickstart

```bash
# 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:
```json
{
  "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:

```json
{
  "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:

```json
{
  "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"
      }
    }
  }
}
```

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

---

### Windsurf (Codeium)

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

```json
{
  "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"
      }
    }
  }
}
```

3. 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:

```bash
# 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:
```bash
astra query "task description" --no-tokens | jq '.context'
```

---

### Continue.dev

Edit `~/.continue/config.json`:

```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](https://modelcontextprotocol.io) over **stdio**. If your tool supports MCP, this config works:

```json
{
  "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):
```bash
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

```bash
# 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

```bash
# 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

```bash
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](https://tree-sitter.github.io) — AST parsing (Python, JS, TS, JSX, TSX)
- 🤖 [sentence-transformers](https://sbert.net) — local embeddings (`all-MiniLM-L6-v2`, 384-dim)
- 🕸 [NetworkX](https://networkx.org) — Personalized PageRank over call graph
- 💾 SQLite — zero-dependency knowledge graph storage
- 🛰 [MCP protocol](https://modelcontextprotocol.io) — 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](CODE_OF_CONDUCT.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](https://github.com/Charan-place)

If ASTra saves you tokens, [**⭐ star the repo**](https://github.com/Charan-place/ASTra-MCP) — 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](https://github.com/Charan-place)
- **Source:** [Charan-place/ASTra-MCP](https://github.com/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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-charan-place-astra-mcp
- Seller: https://agentstack.voostack.com/s/charan-place
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.