Skip to main content

FastAST

High-Performance Model Context Protocol (MCP) Server & Graph Explorer (AST → Graph → Retrieval) for AI Coding Agents

PyPI Version License: Apache-2.0 Python: >= 3.10 Language: Rust + Python Model Context Protocol Database: SQLite WAL

FastAST 2D Architecture Graph Explorer

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

  1. Native Tree-Sitter AST Engine (Rust): High-speed multi-language parsing extracting functions, classes, methods, docstrings, imports, and call sites across 9 languages.
  2. Persistent Relational Code Graph: Stores symbols and typed edges (calls, defines, imports, inherits) in a local SQLite WAL database (.fastast.db).
  3. 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.
  4. 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.
  5. 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).

FastAST Token-Bounded Retrieval vs Traditional File Dumps


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) and DEFINES (Purple solid), with dimmed CALLS to 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)

Source distribution for fastast 0.2.1
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)

Table of built distributions (wheels) for fastast 0.2.1
File Actions
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 log

Release 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 log

Release 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 log

Release 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 log

Release 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 log

Release 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 log

Security 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.

Select from 6 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page