Void Stack MCP server

Got 10 projects with backends, frontends, workers, and databases — and you can't remember how to start any of them? And your AI agent reads half the repo before it understands one?

Void Stack fixes both:

• One command starts your whole dev stack — backend, frontend, database, Docker, WSL. No memorizing ports or commands, no opening 5 terminals, no reading outdated READMEs.
• A local context engine for AI agents, over MCP — hybrid search (BM25 + exact vector search + a Tree-sitter call graph), project map and entry points. To understand a project at the same depth, your agent reads about 91 % less text than reading the files by hand (measured).

void add my-app F:\projects\my-app    # Auto-detects services
void start my-app                      # Starts everything

That's it. Void Stack scans your project, detects which frameworks you're using (FastAPI, Vite, Express, Django...), generates the right commands, and runs them. If there's a Python venv, it finds it. If node_modules is missing, it tells you.

High Performance — Built with Rust. Zero runtime overhead, instant startup, minimal memory footprint.

Agentic Workflow — MCP server with 75 tools lets Claude Desktop / Claude Code manage your services, search and map your code, check API contracts across projects, and audit security autonomously. Only need code context? void-stack-mcp --tools context exposes the 20 code-context tools and cuts tool definitions per session by 64 % (55,147 → 20,025 characters).

Cloud-Native Roadmap — Deploy to Vercel, DigitalOcean, and more from the same config (coming soon).

Leer en español | void-stack.dev

---

Dogfooding: Void Stack analyzes itself

Void Stack's own analysis and audit tools are used to maintain the quality of its codebase. Here's what running void analyze void-stack --compare and void audit void-stack on the project itself revealed — and how we used those findings to improve the code:

Security audit

void audit void-stack
# Risk Score: 2/100
# 2 low findings (innerHTML usage — already mitigated with DOMPurify)

The initial audit found 6 issues (risk score 25/100), but 4 were false positives — regex patterns and templates in the detection code flagged as "secrets". This led us to add smart false-positive filtering (self-referencing file allowlist, regex metacharacter detection, template line filtering), dropping the false positive rate from 83% to 0%.

Code analysis

void analyze void-stack --compare
# Pattern: Layered (80% confidence)
# 214 modules, 32,453 LOC, 37 external deps
# Max complexity: 152 (i18n en/es — data tables, not logic)
# Anti-patterns: 26 (4 medium God Class, 13 Fat Controller, 8 Excessive Coupling)

Findings that drove refactoring:

Finding	Action taken
God Class: cli/main.rs (1202 LOC, 25 fn)	Split into 6 command modules (~250 LOC main)
God Class: mcp/server.rs (1197 LOC, 35 fn)	Split into 10 tool modules (~340 LOC server)
God Class: manager.rs (30 fn)	Split into 4 submodules (process, state, logs, url)
God Class + Fat Controller: vuln_patterns.rs (789 LOC)	Split into 5 category modules (injection, xss, network, crypto, config)
God Class: db_models.rs (1065 LOC)	Split into 7 submodules by DB format (python, sequelize, gorm, drift, proto, prisma)
God Class: generate_dockerfile.rs (821 LOC)	Split into 6 submodules by language (python, node, rust, go, flutter)
God Class: api_routes.rs (747 LOC)	Split into 5 submodules by protocol (python, node, grpc, swagger)
God Class: architecture.rs (788 LOC)	Split into 4 submodules (externals, crates, infra)
God Class: classifier.rs (759 LOC, 44 fn)	Split into 3 submodules (logic, signals/data tables, tests)
Fat Controller: cli/analysis.rs (580 LOC)	Split into 4 submodules (analyze, diagram, audit, suggest)
CC=42: analyze_best_practices	Table-driven linter registry (CC ~15)
CC=41: cmd_analyze	Extracted 11 helper functions (CC ~10)

Technical debt tracking

void analyze void-stack --compare --label v0.31.0
# Pattern: Layered (80% confidence)
# Coverage: 83.0% (latest lcov snapshot — core at 90.6%)
# Explicit debt: 34 markers (TODO: 11, TEMP: 10, OPTIMIZE: 6, BUG: 3, XXX: 2, FIXME: 1, HACK: 1)
# 2313 tests passing across the workspace (desktop app not included)

New in v0.22.0: explicit debt markers (TODO/FIXME/HACK/XXX/OPTIMIZE/BUG/TEMP/WORKAROUND) are now scanned from source comments and shown in CLI output, markdown reports, and the desktop Debt tab. Complex functions (CC≥10) are cross-referenced with coverage data — uncovered critical functions get [!] warnings in CLI and 🔴 indicators in markdown.

---

Hybrid Context Engine — Semantic + Structural

Most AI tools force you to choose: semantic search (find related concepts) OR structural graphs (trace call chains). Void Stack combines both. Vector embeddings find what is conceptually related. Tree-sitter graphs show what structurally breaks. The result: surgical context that no single-approach tool can match.

Approach	Query	Result
Semantic only	"auth middleware flow"	Conceptually related chunks
Structural only	"callers of validateToken"	Direct call chain
Hybrid (Void Stack)	Both simultaneously	Related chunks + blast radius

Void Stack indexes your codebase locally with BAAI/bge-small-en-v1.5 embeddings and builds a Tree-sitter call graph — so your AI assistant reads only what matters instead of scanning every file.

How it works

# Index once (runs in background, ~30s for 250 files)
void index my-project

# Get the lay of the land first: packages, entry files, key docs; then every entry point
void map my-project
void entrypoints my-project --kind rest,cli

# Search by concept, not by filename
void search my-project "authentication middleware flow"
# Returns the 5 most relevant hits, compact: path:lines, symbol, the matching lines
# (--detail full for whole chunks; MCP agents expand a hit with get_chunk)

# Incremental re-index driven by git, not timestamps
void index my-project --git-base HEAD~1   # only files changed since last commit
void index my-project --force             # full rebuild

# From Claude Desktop / Claude Code via MCP:
#   build_structural_graph my-project          (Tree-sitter, 14 languages)
#   get_impact_radius      my-project          (blast radius BFS)
#   query_graph            my-project callers  (who calls this function)
#   watch_project          my-project          (auto re-index on save)
#   install_index_hook     my-project          (post-commit re-index)

Results are compact by default — location, symbol and the lines that match — and a hit already sent on the same connection comes back compact with a ↺ mark instead of whole (never hidden: subagents sharing one connection still see it). Import-only blocks are skipped; tests, docs and changelogs rank lower unless the query asks for them.

Search is hybrid by default: BM25 (SQLite FTS5, snake_case identifiers kept whole) fused with vector results via Reciprocal Rank Fusion — exact identifiers like stop_unix_process_group hit even when embeddings miss them. Modes: hybrid | vector | lexical.

0.36 vs 0.35 (Windows, 70 registered projects, same queries through the MCP server)

Measure	0.35	0.36	Change
Understanding a project (morrocoy, a 430-file Flutter app): the same 5 questions	10,586 chars	10,556 chars	−91 % vs 114,236 chars reading the 13 needed files by hand
get_api_contracts iunci (Flutter)	410,176 chars	33,222 chars	−92 %
get_api_contracts iunci-backend (Go)	234,464 chars	30,527 chars	−87 %
list_entrypoints iunci	23,139 chars, 41 real routes	4,701 chars, 97 real routes	−80 % (1,475 vendored .proto copies removed)
check_contracts (average of 3 projects)	20.5 s	0.89 s	23× faster
Tool definitions per session (0.36 with --tools context)	55,147 chars	20,025 chars	−64 %
build_structural_graph morrocoy	2.9 s	0.8 s	faster

With project_map + list_entrypoints added to those 5 questions the total is 18,055 characters (−84 % vs by hand), and it lists the app's 70 MCP tools. In 0.33 the same 5 questions returned ~49,000 characters (estimated, on an earlier machine). check_contracts got faster because files whose size and modification time didn't change are skipped without re-reading them, and producers are scanned in parallel.

Indexing on the GPU (new in 0.36; Windows, DirectML, RTX 4070 Ti SUPER):

Project	Chunks	CPU	GPU	Speed-up
iunci	12,206	740–1,003 s	73–75 s	~10–13×
void-stack	6,467	623 s	40 s	~16×
morrocoy	1,371	101–281 s	22 s (38 s the first run of a new binary, while DirectML compiles its shaders)	—

Embeddings are identical to the CPU's (cosine 1.000000 on all 12,206 chunks) and searches return the same results.

0.35 vs 0.34 (11 real projects, same machine, same queries through the MCP server)

Session	0.34 tokens	0.35 tokens	Less
"List every feature" (map + entry points + 8 searches), 8 projects	177,136	48,586	3.6×
140 searches mined from git history (7 projects)	332,233	60,494	5.5×
Same 4 questions asked twice in a session	37,992	4,358	8.7×
Cross-project (3 topics × 3 projects + cross GraphRAG + contracts)	109,391	7,833	14×

Same retrieval quality or better (hit@5 0.679 → 0.686, recall@5 0.514 → 0.538 on the 140 git-history queries), noisy hits in the top 5 (tests, import-only blocks, changelogs) 180 → 54, search latency unchanged (p50 ~10 ms), and project_map found all 21 packages of a 21-crate workspace where the search-only inventory surfaced 8. Indexing time and peak RAM are the same as 0.34. void bench <project> --task queries.txt reproduces the per-query numbers.

Benchmarks (measured on void-stack itself)

Operation	Without index	With void-stack	Reduction
semantic_search (avg)	~170 lines / file	~4 lines / result	97.5 %
Understanding a module	5-10 file reads	1 search query	~10x
Blast radius of a change	Manual, hours	get_impact_radius	instant

97.5 % figure reported by void stats --days 90 across 135 semantic_search operations — 23 868 lines of source that never entered the LLM context.

Footprint (v0.33, Windows, indexing void-stack from scratch, ~3,000 chunks): ~110 s and ~650 MB peak RAM, down from 193 s and 4.2 GB in v0.31. Vector search is exact (int8 vectors, recall 1.0) and the index takes 7.3 MB in memory. Details in the CHANGELOG.

GPU indexing (0.36): on Windows, void index embeds on the GPU through DirectML (any DirectX 12 GPU: NVIDIA, AMD, Intel) with no extra install, and falls back to the CPU if there is none. Searches keep embedding the query on the CPU (a few ms). VOID_STACK_EMBED_DEVICE=cpu forces the CPU. The GPU batch defaults to 32 (VOID_STACK_EMBED_BATCH overrides it; batch 32 used +2.5 GB of video memory, 128 used +8.8 GB for the same speed). macOS and Linux index on the CPU for now. After indexing, the CLI prints embeddings: GPU (DirectML) or embeddings: CPU.

Supported languages

• Semantic index (embeddings): every source extension in CODE_EXTENSIONS — Rust, Python, JS/TS, Go, Dart, Java, PHP, C/C++, C#, Ruby, Swift, Kotlin, Lua, Zig, Elixir, Verse, GDScript, MQL4/MQL5, Vue, Svelte, Astro, plus md/proto/sql/dockerfile.
• Structural graph (Tree-sitter): Rust, Python, JavaScript, TypeScript (+ TSX), Go, Dart, Java, PHP, C, C++, Elixir, C#, Swift, GDScript, MQL4/MQL5 (C++ grammar).
• Dependency graph (imports): Python, JS/TS, Go, Dart, Rust, Verse, C#, Swift, GDScript, C/C++, MQL4/MQL5 — C# links using to the files declaring that namespace, Swift links import to the SwiftPM target, GDScript resolves res:// paths and class_names, C/C++ resolves #include "…" like Unreal's module include paths, MQL resolves #include <…> against the terminal's Include/ folder.
• Game engines: Unity (C#), Unreal Engine (C++ / UEFN Verse) and Godot (GDScript / C#) projects are detected from their markers; their cache/build folders (Library/, Intermediate/, .godot/, …) are skipped by every scanner and offered for cleanup in the Space panel.
• MetaTrader: MQL4/MQL5 projects (.mq4/.mq5/.mqh, or an MQL4/MQL5 data folder) are detected; MetaEditor's UTF-16 sources are read transparently, terminal event handlers (OnInit, OnTick, OnCalculate, …) are never reported as dead code, and compiled .ex4/.ex5 files are excluded.

Structural analysis inspired by code-review-graph (MIT) — AST node mappings and BFS query logic reimplemented natively in Rust.

---

Interfaces

Void Stack has 4 interfaces — use whichever you prefer:

Interface	Description
CLI (void)	Fast commands from terminal
TUI (void-stack-tui)	Interactive terminal dashboard: services, analysis, security audit, debt, space
Desktop (void-stack-desktop)	Desktop app with GUI (Tauri + React) — Windows (.msi), macOS (.dmg), Linux (.deb)
MCP Server (void-stack-mcp)	Integration with Claude Desktop / Claude Code

End-to-end example: FastAPI + React in 30 seconds

Say you have a project with a FastAPI backend and a React frontend:

my-app/
├── backend/       # FastAPI with venv
│   ├── main.py    # from fastapi import FastAPI
│   └── .venv/
├── frontend/      # React with Vite
│   ├── package.json
│   └── src/
└── .env

# 1. Register the project (scans and detects services)
void add my-app F:\projects\my-app

# Void Stack detects:
#   ✓ backend  → uvicorn main:app --host 0.0.0.0 --port 8000
#   ✓ frontend → npm run dev
#   ✓ .venv    → auto-resolves python to virtualenv

# 2. Check dependencies
void check my-app
#   ✅ Python 3.11 (venv detected)
#   ✅ Node 20.x (node_modules up to date)
#   ✅ .env complete vs .env.example

# 3. Start everything
void start my-app
#   [backend]  → http://localhost:8000
#   [frontend] → http://localhost:5173

# 4. Or open the interactive dashboard
void-tui my-app

Installation

Binaries (recommended)

Download pre-built binaries from the Releases page — no Rust required.

Platform	File
Windows	.msi / .exe (NSIS)
macOS	.dmg
Linux	.deb / .AppImage

Claude Desktop Extension — Each release also includes .mcpb files (one per platform). Drop the .mcpb into Claude Desktop to install the MCP server with zero configuration.

Binaries include vector search — Pre-built binaries from Releases include semantic code search powered by BAAI/bge-small-en-v1.5 (local, no API key). The embedding model (~130MB) downloads automatically on first void index use. To build without vector search: cargo build --release -p void-stack-cli

macOS note: If you get "cannot be opened because the developer cannot be verified", run:

xattr -cr /Applications/Void\ Stack.app

From source (Cargo)

# Core CLI (the main tool)
cargo install --git https://github.com/mague/void-stack void-stack-cli

# TUI Dashboard
cargo install --git https://github.com/mague/void-stack void-stack-tui

# MCP Server (for AI integration with Claude Desktop / Claude Code)
cargo install --git https://github.com/mague/void-stack void-stack-mcp

# gRPC Daemon (optional, for persistent management)
cargo install --git https://github.com/mague/void-stack void-stack-daemon

Prerequisites: Rust + Protobuf compiler (winget install Google.Protobuf on Windows)

Build from source

git clone https://github.com/mague/void-stack.git
cd void-stack

# With vector search (recommended):
cargo build --release --features vector

# Minimal build (no ONNX dependency):
cargo build --release

# Binaries in target/release/
#   void              — CLI
#   void-stack-tui    — Terminal dashboard
#   void-stack-daemon — gRPC daemon
#   void-stack-mcp    — MCP server for AI (always includes vector search)

Desktop app (Tauri)

cd crates/void-stack-desktop
cargo tauri build
# Generates installer in target/release/bundle/

Diff-centric workflow: test selection & LLM-ready review

Two tools shorten the implement → test → review loop on large codebases:

suggest_tests_for_diff — run only the tests that cover your diff. A reverse coverage map (test → BFS callees over the structural graph, cached in SQLite) maps changed symbols to covering tests, ranked by call distance, with an explicit uncovered list and ready-to-paste commands:

$ void suggest-tests void-stack
## Suggested tests (3 for 7 changed symbols)
- `test_stop_one_waits_for_child_exit` — crates/void-stack-core/src/manager/process.rs:441 (hop 1)
## Uncovered (1)
- ⚠️ `render_html` — crates/void-stack-core/src/diagram/graph_html.rs:289 has NO covering tests
## Run
cargo test -p void-stack-core test_stop_one_waits_for_child_exit

review_diff — a compact (≤4k tokens) review payload for the current diff, designed as INPUT for an LLM reviewer: summary, audit findings on changed lines only (suppression-aware), blast radius with hop labels, test coverage, and 1-hop call context for the hottest symbols:

$ void review void-stack --git-base main
# Review — void-stack (vs `main`)
## Summary
- 12 files changed, +840 / -95 lines
## Findings on changed lines (1) | Suppressed: 2
- [medium] Use of .unwrap() in production code — `crates/.../db.rs:44` → Replace with '?'
## Blast radius (depth 2)
- `crates/void-stack-mcp/src/tools/search.rs`: semantic_search (hop 1) ...

Workflow: after each batch of edits run the suggested tests (not the full suite); before each commit run review_diff and address Critical/High findings + the uncovered list. The skills/skill-void-stack skill encodes these rules for Claude Code sessions.

Security & trust model

Void Stack is a service launcher: the command strings in void-stack.toml (and in registered services) are executed verbatim through the platform shell (sh -c on Unix, cmd /c on Windows) with your privileges. That is by design — but it means project configs are trusted input.

• Never start services from a repository you haven't reviewed: a malicious void-stack.toml runs arbitrary code.
• The daemon asks for a one-time confirmation before executing the service commands of a newly loaded project. The approval is stored in your user config directory (~/.config/void-stack/trusted-projects.json on Linux, ~/Library/Application Support/void-stack/ on macOS) — never inside the project — and is bound to a hash of the exact command set, so any change to the commands re-prompts. Use void-daemon start --yes to approve non-interactively (CI, scripts).
• Review the listed commands before approving; delete the project entry from trusted-projects.json to be asked again.

Register in your MCP clients

void setup            # detects Claude Desktop/Code, Cursor, Windsurf, Cline, VS Code
void setup --dry-run  # see what would change first

Excluding files from analysis

Create .voidignore in your project root to exclude paths from void analyze:

# Generated code
internal/pb/
vendor/
**/*.pb.go
**/*.pb.gw.go

# Mocks
**/mocks/
**/*_mock.go

Same syntax as .gitignore (simplified). Supports prefix paths, **/ glob suffixes, and directory names.