faststack-mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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]" # bothAlready 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 changesStep 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 averagesRelated MCP server: code-index
Tools reference (12 tools)
Tool | Purpose | Key params |
| Scan & cache a project |
|
| Browse cached projects | — |
| Primary nav — ranked FTS symbol search |
|
| Read exact code snippet by symbol_id |
|
| New — import graph + text scan for a symbol |
|
| New — read N lines around a line number |
|
| Full-text search across all files |
|
| Grouped structure overview |
|
| Directory tree of indexed files | — |
| All symbols in one file |
|
| Remove cached index |
|
| Session cost + tool breakdown |
|
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.
Value | Default | When to use |
| Yes | Local dev, any project size. Single |
| No | Shared team index, large projects, or when you want the index in your project DB. Requires |
| No | Backward compat with pre-v0.2 caches. No FTS or reference graph. |
SQLite (default)
No configuration needed. Features:
FTS5 virtual table on symbol name + qualified_name + signature
Combined FTS5 + LIKE fallback (handles
get_db,create_userunderscore names)refstable forfind_referenceslookupsWAL mode — concurrent reads while indexing
PostgreSQL
export FASTSTACK_STORAGE=postgres
export DATABASE_URL=postgresql://user:pass@localhost:5433/mydbFeatures:
GENERATED ALWAYS AStsvector column + GIN index (zero-maintenance FTS)ts_rankrelevance ordering + ILIKE supplementTables prefixed
faststack_*(no conflicts with your app tables)Batch inserts via
execute_values(500 rows/page)faststack_referencestable forfind_references
psycopg2-binarymust be installed (pip install psycopg2-binaryorpip install faststack-mcp[postgres]).
File watcher (auto-reindex)
# Start watcher alongside indexing
index_folder("/path/to/project", watch=True)Uses
watchfiles(install:pip install watchfilesorpip 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
watchfilesis 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:
Query kind | Default |
| Shown (fields are useful) |
| Shown |
Everything else | Hidden |
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
Language | Parser | Extracts |
Python / FastAPI |
| functions, classes, routes, pydantic models, services, repos, decorators, Depends() |
TypeScript / React |
| components, hooks, types, interfaces, backend routes/services/repos |
SQL | regex | tables, views, indexes, functions, procedures, triggers |
JSON / JSONL |
| root keys, RAG chunk fields, manifest metadata |
Config |
| package scripts/deps, tsconfig, vite, eslint, alembic |
Env | regex (masked) | variable names — values stored as |
Tailwind | heuristics | config keys, className usage |
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]" # bothEnvironment variables
Variable | Default | Description |
|
| Storage backend: |
| — | PostgreSQL DSN (required when |
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.exampleindexed by default with masked values (***MASKED***).envand.env.*skipped unlessinclude_env_files=TrueRaw values never persisted
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Agent-native MCP server over the public saagarpatel.dev corpus. Read-only, stateless.
Zotero MCP server for Claude and ChatGPT: search, citations, safe writes, PDF passages and pages.
An MCP server for search and retrieval over a local LanceDB database
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceLocal MCP server that provides semantic search (RAG) over code repositories, enabling AI clients like Claude and Gemini to access project context without manual re-upload.-
- AlicenseNot gradedqualityDmaintenanceA local, SQLite-backed code index for Claude Code, exposed over MCP, enabling targeted code retrieval without external APIs.131 PyPI1MIT
- AlicenseNot gradedqualityDmaintenanceLocal MCP server that indexes folders of documents into a hybrid vector + keyword search index for Claude Desktop, with support for PDFs, Office files, and images via OCR.MIT
- AlicenseAqualityCmaintenanceA local MCP server that indexes and searches your past Claude sessions using SQLite FTS5. No cloud, runs entirely on your machine.3MIT