faststack-mcp

Local-first, read-only MCP server for Claude Code. Indexes and searches full-stack projects (FastAPI + React + PostgreSQL) with SQLite-backed FTS, cross-reference graph, and file-watcher auto-reload — so Claude reads only what it needs instead of entire files.

Quick Start

Step 1 — Install

# From local source (development)
cd C:\path\to\faststack-mcp
pip install -e .

# From GitHub
pip install "git+https://github.com/Evaan-devlops/faststack-mcp.git"

# With optional extras
pip install -e ".[watch]"     # file watcher (watchfiles)
pip install -e ".[postgres]"  # PostgreSQL backend (psycopg2-binary)
pip install -e ".[all]"       # both

Already have watchfiles / psycopg2 globally? Nothing extra to install — they're picked up automatically.

Step 2 — Add to Claude Code

{
  "mcpServers": {
    "faststack": {
      "command": ".venv\\Scripts\\python.exe",
      "args": ["-m", "faststack_mcp"]
    }
  }
}

Step 3 — Index your project

index_folder("/path/to/your/project")          → project_id + counts
index_folder("/path/to/project", watch=True)   → + auto-reindex on file changes

Step 4 — Explore

get_project_outline(project_id)                → structure at a glance (~17 tokens)
search_symbols(project_id, "createUser")       → find functions, routes, hooks, models
get_symbol(project_id, symbol_id)              → exact code snippet only
find_references(project_id, "get_db")          → all files that import / call a symbol
get_file_context(project_id, "db.py", 120)     → 80 lines around line 120
get_file_outline(project_id, "main.py")        → all symbols in one file
search_text(project_id, "HTTPException")       → fallback full-text search
get_file_tree(project_id)                      → directory tree
list_projects()                                → all indexed projects
invalidate_cache(project_id)                   → force full re-index
get_token_usage()                              → cost + per-session averages

Related MCP server: code-index

Tools reference (12 tools)

find_references — dependency impact analysis

find_references(project_id, "get_db")
→ {
    symbol_name: "get_db",
    files_found: 3,
    total_usages: 3,
    references: [
      { file_path: "users.py",  usages: [{ line: 5,  context: "from db import get_db" }] },
      { file_path: "auth.py",   usages: [{ line: 12, context: "db = get_db()" }] },
      { file_path: "orders.py", usages: [{ line: 8,  context: "from db import get_db" }] }
    ]
  }

Use before modifying a shared symbol to understand blast radius. Uses the import graph built during index_folder (fast path) with a whole-word regex scan as fallback.

get_file_context — surrounding code window

get_file_context(project_id, "src/db.py", around_line=120, radius=40)
→ lines 80–160, line 120 marked with >>>

Use when get_symbol is too narrow — e.g. understanding the code around a symbol boundary, inspecting a migration function, or reading error-handling context.

Storage backends

Controlled by FASTSTACK_STORAGE environment variable.

SQLite (default)

No configuration needed. Features:

• FTS5 virtual table on symbol name + qualified_name + signature

• Combined FTS5 + LIKE fallback (handles get_db, create_user underscore names)

• refs table for find_references lookups

• WAL mode — concurrent reads while indexing

PostgreSQL

export FASTSTACK_STORAGE=postgres
export DATABASE_URL=postgresql://user:pass@localhost:5433/mydb

Features:

• GENERATED ALWAYS AS tsvector column + GIN index (zero-maintenance FTS)

• ts_rank relevance ordering + ILIKE supplement

• Tables prefixed faststack_* (no conflicts with your app tables)

• Batch inserts via execute_values (500 rows/page)

• faststack_references table for find_references

psycopg2-binary must be installed (pip install psycopg2-binary or pip install faststack-mcp[postgres]).

File watcher (auto-reindex)

# Start watcher alongside indexing
index_folder("/path/to/project", watch=True)

• Uses watchfiles (install: pip install watchfiles or pip install faststack-mcp[watch])

• 1.5 s debounce — rapid saves are batched before re-index fires

• Background daemon thread — does not block Claude

• Falls back silently if watchfiles is not installed

Cross-reference graph

Built automatically during index_folder. Tracks every import and from X import Y statement across Python and TypeScript/JavaScript files.

The graph is stored in the index and queried by find_references. It enables:

• "What calls / imports this symbol?" in one tool call

• Impact analysis before refactoring shared utilities

• Understanding FastAPI dependency injection (Depends(get_db))

Search — include_synthetic behaviour

Synthetic symbols (auto-generated model fields, config keys) are shown or hidden depending on context:

Override explicitly: search_symbols(project_id, "User", include_synthetic=True)

Token usage analytics

get_token_usage(last_n=20)
→ {
    totals: { input_tokens, output_tokens, estimated_cost_usd },
    averages: { input_tokens_per_session, cost_usd_per_session },
    tool_breakdown: { get_symbol: { calls: 18, est_saved: 136800 }, ... },
    estimated_tokens_saved_by_mcp: 209000
  }

Requires the Stop hook in ~/.claude/settings.json to log session data.

Supported file types

Source: .py .ts .tsx .js .jsx .sql

Config / meta: .json .jsonl .toml .yaml .yml .ini

Named files: package.json pyproject.toml tsconfig.json tsconfig.app.json tsconfig.node.json vite.config.* alembic.ini eslint.config.js tailwind.config.js tailwind.config.ts manifest.json chunks.jsonl index.faiss bunfig.toml .env.example

Skipped dirs: .git node_modules .next dist build coverage .venv venv __pycache__ .mypy_cache .pytest_cache .idea .vscode .claude

Sensitive files skipped: .env .env.* *.pem *.key *.p12 id_rsa id_ed25519 (.env* files opt-in via include_env_files=True)

Parsers

Security

• All file reads path-confined to the indexed project root

• Symlink escape checks on every lookup

• Binary file detection (null-byte scan)

• File size cap (default 2 MB)

• Sensitive file patterns skipped by default

• No write or shell operations on project files

• SQLite cache isolated at ~/.faststack-mcp/

Installation options

# Local dev
pip install -e "C:\path\to\faststack-mcp"

# GitHub
pip install "git+https://github.com/Evaan-devlops/faststack-mcp.git"

# With extras
pip install -e ".[watch]"       # watchfiles — file watcher
pip install -e ".[postgres]"    # psycopg2-binary — PostgreSQL backend
pip install -e ".[all]"         # both

Environment variables

Development

python -m venv .venv
.venv\Scripts\python -m pip install -e .
python -m py_compile src/faststack_mcp/server.py  # syntax check
pytest tests/

Env parsing

• .env.example indexed by default with masked values (***MASKED***)

• .env and .env.* skipped unless include_env_files=True

• Raw values never persisted