MCP Sidecar 🐙⚙️💜

C++ code intelligence for Claude, Cursor, and MCP clients. clangd-powered symbol search, references, call hierarchy, build analysis, and data flow. Zero config, SQLite-backed, single binary.

🎯 What It Does

Tool	What
symbol_resolve	Find symbols by name (MainWindow, main, Scanner)
symbol_refs	Find all uses of symbol at file:line:col
symbol_callers	Who calls this function? (incoming hierarchy)
symbol_callees	What does this function call? (outgoing hierarchy)
cpp.build_explain	Full compile command + flags for any file
cpp.include_explain	Used/required/removable includes
symbol_card	Symbol dashboard (decls, refs, callers, effects)
change.impact	What breaks if I change this symbol?

🚀 Quick Start

# Install
dotnet tool install --global mcp-sidecar

# Pre-index (first time only, 5-15min for large projects)
mcp-sidecar --extract --workspace /path/to/cpp/project

# Use with Claude Desktop, Cursor, etc
mcp-sidecar --workspace /path/to/cpp/project

🧠 Features

• Zero config - Finds compile_commands.json automatically
• SQLite - No Postgres required, one file per workspace
• Resume - Interrupted extractions pick up where they left off
• Incremental - Re-indexes only changed files
• 10GB+ indexes - Handles real C++ codebases (Qt, Boost, C++20)
• Progress bar - mcp-sidecar --extract shows live progress

📊 Example

$ mcp-sidecar --extract --workspace ~/LinearScanner-ICS
Extracting: ~/LinearScanner-ICS
Starting clangd... ✓
Starting extraction...

████████████████████████████ 100% | Files: 1742/1742 | Symbols: 35,206 | 12:47
✓ Extraction complete: snapshot_id=1
  Symbols: 35,206
  Files: 1,742
  Time: 12:47

Then in Claude:

> symbol_resolve MainWindow
Found 18 symbols matching 'MainWindow':
  MainWindow (class) @ Applications/Gui/Sources/MainWindow.h:42:8
  MainWindow::MainWindow (constructor) @ Applications/Gui/Sources/MainWindow.cpp:47:5
  ~MainWindow (destructor) @ Applications/Gui/Sources/MainWindow.cpp:57:5

🛠️ Architecture

MCP Client (Claude/Cursor) → MCP Sidecar → clangd (LSP)
                                     ↓
                               SQLite DB (symbols/refs/calls)

1. clangd - Real-time indexing via LSP
2. SQLite - Persistent symbol database
3. MCP - Standard protocol for AI tools

🎪 Why This Exists

Traditional C++ tools (ccls, clangd) are great for editors but terrible for AI. MCP Sidecar bridges the gap:

• AI-ready responses - Structured JSON with file:line:col locations
• Build-aware - Uses your exact compile_commands.json
• Fast queries - Pre-indexed for instant symbol search
• No setup - Just point it at a folder with compile_commands.json

🔧 Native Builds

✅ Available now in v0.1.0!

# Download from GitHub Releases
# Linux/macOS
tar -xzf mcp-sidecar-linux-x64.tar.gz
./mcp-sidecar --extract --workspace ~/project

# Windows
# Extract mcp-sidecar-win-x64.zip
mcp-sidecar.exe --extract --workspace C:\project

Platforms: linux-x64, linux-arm64, osx-x64, osx-arm64, win-x64

📚 MCP Protocol

Full MCP spec: mcp.so

🙏 Thanks

Made by Synthia with 💙

---

⭐ Star on GitHub | 🐙 Issues welcome | 💬 Feedback appreciated

---

🛣️ Development Roadmap

The goal of mcp-sidecar is not just symbol search, but a build-aware fact engine that AI coding agents can trust when working in large C++ codebases.

Below is the working roadmap. Items are intentionally checkable so automated agents (like OpenClaw / Synthia) can execute against them.

---

Phase 1 — Core Stability ✅ COMPLETE (v0.1.0)

Single Binary Deployment

• Complete SQLite migration
• Remove Postgres dependency entirely
• Ensure DB auto‑creation on first run
• Package as single binary build
• Validate Linux / macOS / Windows portability

Indexing Reliability

• Robust incremental indexing
• Resume interrupted indexing jobs
• Detect stale compile_commands entries
• Detect parse failures and report clearly
• Validate symbol identity across re‑index runs (v0.2.0)

Workspace Detection

• Auto‑detect project root
• Auto‑detect compile_commands.json
• Support override flags
• Support multi‑workspace indexing (Phase 2)

---

Phase 2 — Trust & Provenance

Goal: Every fact returned should explain why it is trustworthy.

Provenance Metadata

• Attach provenance metadata to results
• Mark origin: clangd / AST / graph / heuristic
• Return exact file:line:column locations
• Introduce confidence levels:
  • exact
  • high‑confidence
  • inferred
  • speculative

Build Context Awareness

• Track compile flags per file
• Track macro environments
• Track platform/build variants
• Detect symbols hidden behind defines

Parse Context Reporting

• Track files failing AST generation
• Report incomplete analysis conditions

---

Phase 3 — Build Reality Modeling

Goal: reflect the actual compilation environment.

• Persist compile_commands in DB
• Model file → compile flag mapping
• Track include search paths

Tools

• cpp.build_explain
• cpp.include_explain
• cpp.macro_explain

Example:

Symbol active because:

• BUILD_TARGET=Linux
• FEATURE_X enabled
• included via foo.hpp → bar.hpp

---

Phase 4 — Change Impact Engine

Goal: allow agents to safely modify code.

• Build symbol dependency graph
• Track callers / callees
• Track type dependencies
• Track inheritance relationships

Query

• change.impact(symbol)

Returns:

• directly affected symbols
• downstream call chains
• impacted files
• impacted modules

Risk Ranking

• Rank breakage probability
• Highlight API boundaries
• Highlight template propagation

---

Phase 5 — Flow & Effect Analysis (Key Differentiator)

Goal: understand how data and effects propagate through the system.

Call Path Discovery

• Identify shortest call paths
• Identify high‑frequency call paths
• Detect likely entry points

Flow Summaries

• flow_summary(symbol)

Example:

ButtonClick → UIHandler::StartScan → ScanController::Run → MotionPlanner::Execute

Effect Summaries

• effect_summary(symbol)

Classify effects:

• IO
• hardware interaction
• memory mutation
• state transitions

---

Phase 6 — Agent‑Optimized Output

Goal: return minimal safe context for coding agents.

Context Packing

• cpp.context_pack(symbol)

Include:

• symbol definition
• key callers
• related types
• compile environment
• change risk factors

Ranking

• Rank references by importance
• Rank files by change risk
• Rank call paths by likelihood

Token Budget Awareness

• Configurable token limits
• Prefer highest‑value nodes

---

Phase 7 — Performance & Scalability

Goal: support large industrial C++ codebases.

• Validate 100k+ symbol projects
• Validate 10k+ file repositories
• Track memory usage

Index Performance

• Parallel indexing
• Lazy extraction
• Query caching

DB Optimization

• SQLite query tuning
• Precomputed graph tables

---

Phase 8 — Benchmarks & Validation

Goal: prove agents perform better using mcp‑sidecar.

Developer Tasks

Benchmark:

• Trace behavior from UI event
• Trace hardware interaction path
• Safely rename a function
• Remove unused include
• Identify API boundaries

Measure:

• steps required
• tokens consumed
• correctness

Agent Comparison

Compare:

Agent + grep
Agent + embeddings
Agent + mcp‑sidecar

---

Phase 9 — Documentation & Examples

• Example refactor workflow
• Example debugging workflow
• Example API exploration

Tutorials

• Setup guide
• MCP integration guide
• Tool usage examples

---

Long‑Term Vision

mcp‑sidecar becomes a build‑aware fact engine for codebases that AI agents can trust.

Not just:

symbol search

But:

a system that explains how the software actually works.