FastAST
High-Performance Model Context Protocol (MCP) Server & Graph Explorer (AST → Graph → Retrieval) for AI Coding Agents
FastAST equips AI coding agents (Claude Code, Cursor, Windsurf, Codex, and SWE-bench harnesses) with a fast, deterministic, token-budgeted Model Context Protocol (MCP) server. Powered by compiled Rust Tree-Sitter grammars, an embedded SQLite symbol graph, and hybrid retrieval, FastAST eliminates the need for agents to grep entire directories or dump massive raw files into context.
Key Features
- Native Tree-Sitter AST Engine (Rust): High-speed multi-language parsing extracting functions, classes, methods, docstrings, imports, and call sites across 9 languages.
- Persistent Relational Code Graph: Stores symbols and typed edges (
calls,defines,imports,inherits) in a local SQLite WAL database (.fastast.db). - Token-Bounded Evidence Retrieval: Combines BM25 full-text search, dense embeddings, and 1-hop graph expansion into concise evidence bundles bounded by strict token budgets.
- Zero-Setup Graph Explorer (
fastast ui): An interactive 2D architecture canvas pre-bundled inside the PyPI package—zero Node.js or npm dependencies required at runtime. - Agent-Native MCP Server: Standards-compliant Model Context Protocol (MCP) server for instant integration with Claude, Cursor, and VS Code.
Token Efficiency
When AI coding agents investigate bugs or explore repositories without FastAST, they typically read entire files (cat/read_file) or dump wide grep matches into context. This exhausts token limits, inflates API bills, and causes "lost in the middle" hallucinations.
FastAST replaces raw file ingestion with AST-bounded symbol slices and precomputed 1-hop graph neighborhoods, enforcing strict programmatic budgets (max_tokens: 1024 or 2048).
Multi-Language Support (9 Languages)
FastAST parses source code using compiled Tree-Sitter grammars in Rust, extracting rich syntax constructs without external runtime dependencies:
| Language | Extensions | Extracted Entities & Syntax Features |
|---|---|---|
| Python | .py, .pyi, .pyw |
Classes, async/sync functions, methods, decorators, docstrings, imports, call sites |
| TypeScript / TSX | .ts, .tsx, .mts, .cts |
Interfaces, type aliases, enums, classes, methods, React components, imports, calls |
| JavaScript / JSX | .js, .jsx, .mjs, .cjs |
Classes, functions, arrow functions, methods, React components, JSDoc, calls |
| Rust | .rs |
Structs, enums, traits, impl blocks, functions, modules, macro calls, use statements |
| Java | .java |
Packages, classes, interfaces, enums, records, constructors, methods, imports |
| HTML | .html, .htm, .xhtml |
Semantic elements, IDs, classes, embedded <script> and <link> stylesheet tags |
| CSS | .css |
Selectors, rule sets, media queries, keyframes, @import rules |
| JSON | .json, .jsonc |
Top-level object keys, structured hierarchy, dependency manifests |
| TOML | .toml |
Section tables, array of tables, configuration keys, package dependencies |
Quick Start
1. Installation
Install pre-built binary wheels directly from PyPI (no Rust compiler required):
pip install fastast
Or install from source with Python >= 3.10 and Rust >= 1.70:
git clone https://github.com/iabdullaheqbal/fastAST.git
cd fastAST
pip install .
Verify the installation:
fastast --version
fastast-mcp --version
2. Index a Repository
Index any repository into a persistent local .fastast.db SQLite database:
# Index current directory:
fastast index .
# Or scan without indexing to preview file and token counts:
fastast scan .
3. Launch the Interactive Graph Explorer (fastast ui)
FastAST comes with a 2D/3D Architecture Graph Explorer pre-bundled inside the package. No Node.js or npm is required:
# Starts local engine and automatically opens Graph Explorer in your browser:
fastast ui
# Or specify a custom port / host:
fastast ui --port 4200 --host 127.0.0.1
Graph Explorer Capabilities:
- Radial Galaxy Clusters: Louvain community clusters spaced cleanly in non-overlapping orbits.
- Architectural Hierarchy (Tiered): Visualizes entry points $\rightarrow$ domain classes $\rightarrow$ functions $\rightarrow$ external storage.
- Topological Role Filters: Filter by Root Drivers (in-degree = 0), Core Hubs (in-degree $\ge$ 2), Orchestrators (out-degree $\ge$ 2), or Leaf Nodes (out-degree = 0).
- Edge Priorities: Primary focus on
IMPORTS(Emerald dashed) andDEFINES(Purple solid), with dimmedCALLSto prevent visual hairballs. - Dynamic Color Modes: Color nodes by Subsystem, Kind, Language, or Degree intensity.
4. Retrieve Token-Budgeted Evidence
Retrieve ranked symbols, exact code snippets, and 1-hop graph context within a strict token budget:
# Query evidence bounded to 1,024 tokens:
fastast evidence "database connection pool" --max-tokens 1024
# Extract file outline (classes, methods, signatures) in ~300 tokens:
fastast outline python/fastast/indexer.py
# Trace call graph for a symbol:
fastast calls get_call_graph --depth 2
Model Context Protocol (MCP) Setup
FastAST exposes native tools for AI coding agents via the Model Context Protocol (MCP).
1. Cursor (.cursor/mcp.json)
Add to your project's .cursor/mcp.json:
{
"mcpServers": {
"fastast": {
"command": "fastast-mcp",
"args": ["--transport", "stdio"]
}
}
}
2. Claude Desktop (claude_desktop_config.json)
Add to your claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Linux: ~/.config/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json):
{
"mcpServers": {
"fastast": {
"command": "fastast-mcp",
"args": ["--transport", "stdio"],
"cwd": "/path/to/your/repository"
}
}
}
3. VS Code / Continue (~/.continue/config.json)
{
"experimental": {
"modelContextProtocolServers": [
{
"transport": {
"type": "stdio",
"command": "fastast-mcp",
"args": ["--transport", "stdio"]
}
}
]
}
}
Core MCP Tools Reference
| MCP Tool | Inputs | Description |
|---|---|---|
fastast_get_evidence |
query?: string, symbol?: string, file_path?: string, max_tokens?: int |
Returns a compact, token-bounded evidence bundle or code slices (never dumps whole files). |
fastast_search_symbols |
query: string, kind?: string, path?: string, limit?: int |
Searches symbols with filters for function, class, method, or file path. |
fastast_get_call_graph |
symbol: string, depth?: int |
Traces inbound callers, outbound callees, and imported dependencies. |
fastast_file_outline |
file_path: string |
Returns a compact skeleton outline of classes, methods, and signatures (~300 tokens). |
fastast_graph_neighbors |
symbol: string, depth?: int, limit?: int |
Returns multi-hop relational graph nodes and confidence-weighted edges. |
fastast_list_communities |
limit?: int |
Returns Louvain modularity clusters grouping symbols into architectural subsystems. |
fastast_similar_symbols |
symbol: string, min_similarity?: float |
Detects near-duplicate structural code clones using MinHash + LSH. |
fastast_index_status |
directory_path?: string |
Reports current index health, total files, symbols, and edge counts. |
fastast_trigger_index |
directory_path?: string, force?: bool |
Triggers incremental or full repository indexing into .fastast.db. |
CLI Reference
| Command | Arguments | Description |
|---|---|---|
fastast index |
[DIR] [--force] [--json] |
Index repository into .fastast.db with incremental change detection. |
fastast scan |
[DIR] [--json] |
Fast repository survey reporting file counts, languages, and token estimates. |
fastast symbols |
QUERY [-k KIND] [-l LANG] [-n LIMIT] |
Search symbols by name, kind (function, class), or language. |
fastast calls |
SYMBOL [-d DEPTH] [--json] |
Trace inbound callers and outbound invocations across the repository. |
fastast evidence |
QUERY [--max-tokens N] [--ranking R] |
Retrieve hybrid BM25 + Graph evidence bundle within a strict token budget. |
fastast outline |
FILE [--snippets] [--json] |
Extract structural class/method outline and signatures from a file. |
fastast snippet |
SYMBOL [--window N] [--max-lines M] |
Extract syntax-bounded code snippet for a specific symbol. |
fastast ui |
[-p PORT] [-H HOST] [--no-open] |
Launch the interactive Graph Explorer web UI in your default browser. |
fastast serve |
[-p PORT] [-H HOST] [--open] |
Start the local REST API server and static UI host. |
fastast mcp |
[--transport stdio|sse] [-p PORT] |
Start the Model Context Protocol (MCP) server for coding agents. |
fastast watch |
[-d DIR] [--poll SEC] [--debounce MS] |
Live file-watcher that automatically updates the index on file edits. |
fastast doctor |
[DIR] [--json] |
Run automated database integrity checks (PRAGMA quick_check) and diagnostics. |
fastast stats |
[DIR] [--json] |
Display repository statistics, language distributions, and symbol kinds. |
Python API
FastAST can also be embedded directly in Python workflows:
import fastast
# 1. Index a repository
stats = fastast.index_repository(".")
# 2. Retrieve token-bounded evidence bundle for an agent query
bundle = fastast.retrieve_bundle(
query="handle_graph",
repo_root=".",
limit=5,
max_tokens=1024,
ranking_method="hybrid",
)
# 3. Inspect structural file outline (compact signatures)
outline = fastast.get_file_outline("python/fastast/api_server.py", repo_root=".")
# 4. Extract syntax-bounded symbol snippet
snippet = fastast.get_snippet("run_api_server", repo_root=".")
print(snippet.snippet)
Architecture
FastAST combines a native Rust Tree-Sitter parsing core with an embedded SQLite WAL store and Python retrieval layers:
[AI Agent: Claude Code / Cursor / Windsurf / CLI]
│
▼ (CLI or MCP JSON-RPC)
┌─────────────────────────┐
│ fastast / fastast-mcp │
└────────────┬────────────┘
│
┌──────────┴──────────┐
▼ (Index) ▼ (Query & Evidence)
┌───────────────┐ ┌───────────────────────────────┐
│ Discovery & │ │ Hybrid Retrieval Engine │
│ Rust AST Core │ │ • FTS5 BM25 + Dense Vectors │
│ (Tree-Sitter) │ │ • Graph Centrality & RRF │
└───────┬───────┘ │ • MinHash/LSH & Louvain │
│ │ • Token-Bounded Materializer │
▼ └───────────────┬───────────────┘
┌─────────────────────────────────────┴───────────────┐
│ Local SQLite WAL Store (.fastast.db) │
│ files · symbols · edges · calls · imports │
│ symbols_fts · symbol_embeddings · symbol_similarity │
│ symbol_communities · schema_migrations │
└─────────────────────────────────────────────────────┘
Development & Testing
# Run unit tests across all 9 languages
PYTHONPATH=python python3 -m unittest discover tests
# Build frontend UI assets and bundle into Python package
npm run bundle:ui
# Verify CLI
python3 -m fastast.cli doctor
License
Licensed under the Apache License, Version 2.0.
Disclaimer
This project was developed as part of the Devpost Build with AI: Basics hackathon and was built with the assistance of AI .
Metadata
Release files for fastast 0.2.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| fastast-0.2.1.tar.gz | 624.5 kB | With provenance | Details for fastast-0.2.1.tar.gz |
Built distributions (wheels)
| File | Actions Reset | |||
|---|---|---|---|---|
| fastast-0.2.1-cp310-abi3-win_amd64.whl | CPython 3.10 | abi3 | Windows x86-64 | Details for fastast-0.2.1-cp310-abi3-win_amd64.whl |
| fastast-0.2.1-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl | CPython 3.10 | abi3 | Linux glibc 2.17+ x86-64 | Details for fastast-0.2.1-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
| fastast-0.2.1-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl | CPython 3.10 | abi3 | Linux glibc 2.17+ ARM64 | Details for fastast-0.2.1-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl |
| fastast-0.2.1-cp310-abi3-macosx_11_0_arm64.whl | CPython 3.10 | abi3 | macOS 11.0+ ARM64 | Details for fastast-0.2.1-cp310-abi3-macosx_11_0_arm64.whl |
| fastast-0.2.1-cp310-abi3-macosx_10_12_x86_64.whl | CPython 3.10 | abi3 | macOS 10.12+ x86-64 | Details for fastast-0.2.1-cp310-abi3-macosx_10_12_x86_64.whl |
Total release size: 14.8 MB
Release files / fastast-0.2.1.tar.gz
| Download URL | fastast-0.2.1.tar.gz |
|---|---|
| Size | 624.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a0402fd84e7cbda4d3d300086bed8058fd3643bfcdce3d6e44d9f703564c783d
|
|
BLAKE2b-256 checksum How to use checksums |
912d53f5d9ab3cfd238e1b645ff87135f26e9edc0bbf1f0a0afe3abeeb14d836
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 25, 2026.
Transparency logRelease files / fastast-0.2.1-cp310-abi3-win_amd64.whl
| Download URL | fastast-0.2.1-cp310-abi3-win_amd64.whl |
|---|---|
| Size | 2.8 MB |
| Tags | CPython 3.10 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
9250575e2285e87ca4ce71d07f197bb2f9e203e6bfb4541cd268e7d386b07726
|
|
BLAKE2b-256 checksum How to use checksums |
2d7ff67f2ddede57a0b664713c7beaa8995fd4704311620f6c304864c5f5abbc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 25, 2026.
Transparency logRelease files / fastast-0.2.1-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | fastast-0.2.1-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 2.9 MB |
| Tags | CPython 3.10 Linux glibc 2.17+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
b9464eedb913df2233aa48e1e9d05982b54510d5852086f6ab42573b44f7cbd0
|
|
BLAKE2b-256 checksum How to use checksums |
e79fd71208c42f4ea08fd7484f7a7b8d9e2baa7be39260bdafe62e38bf184c0d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 25, 2026.
Transparency logRelease files / fastast-0.2.1-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | fastast-0.2.1-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl |
|---|---|
| Size | 2.8 MB |
| Tags | CPython 3.10 Linux glibc 2.17+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
e83b835ba290a49dba09088a1181f8964095ea336d70c754740f904a1fa217df
|
|
BLAKE2b-256 checksum How to use checksums |
4d48258e5c9333934b03e308079807dd89bc167f3713186cbbb9ec3dcc57a7de
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 25, 2026.
Transparency logRelease files / fastast-0.2.1-cp310-abi3-macosx_11_0_arm64.whl
| Download URL | fastast-0.2.1-cp310-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 2.8 MB |
| Tags | CPython 3.10 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
931dc61e16959e45721b4fd62aafe09c3834233892848ee08a5d58c3c3a89bb9
|
|
BLAKE2b-256 checksum How to use checksums |
4f77c48ad9471a2c1e4e221c2646e1c9b1ffe92b61fc594facf067330c2bca94
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 25, 2026.
Transparency logRelease files / fastast-0.2.1-cp310-abi3-macosx_10_12_x86_64.whl
| Download URL | fastast-0.2.1-cp310-abi3-macosx_10_12_x86_64.whl |
|---|---|
| Size | 2.8 MB |
| Tags | CPython 3.10 abi3 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
84da2e8b18888f860b4a1c0e634cb410b410194f2b480c4efb5feaa537f26da1
|
|
BLAKE2b-256 checksum How to use checksums |
7b05632030297111cd33dbf32f6b3d6d16aba7fbfcf8d2e77a8e904bd74cedee
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 25, 2026.
Transparency logSecurity for fastast 0.2.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 6 files in this release have been uploaded with provenance metadata.
Attestation for fastast-0.2.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 25, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.