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

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.3
File Size Uploaded Provenance Actions
fastast-0.2.3.tar.gz 626.7 kB With provenance Details for fastast-0.2.3.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for fastast 0.2.3
File Actions
fastast-0.2.3-cp310-abi3-win_amd64.whl CPython 3.10 abi3 Windows x86-64 Details for fastast-0.2.3-cp310-abi3-win_amd64.whl
fastast-0.2.3-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.3-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
fastast-0.2.3-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl CPython 3.10 abi3 Linux glibc 2.17+ ARM64 Details for fastast-0.2.3-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
fastast-0.2.3-cp310-abi3-macosx_11_0_arm64.whl CPython 3.10 abi3 macOS 11.0+ ARM64 Details for fastast-0.2.3-cp310-abi3-macosx_11_0_arm64.whl
fastast-0.2.3-cp310-abi3-macosx_10_12_x86_64.whl CPython 3.10 abi3 macOS 10.12+ x86-64 Details for fastast-0.2.3-cp310-abi3-macosx_10_12_x86_64.whl

Total release size: 14.9 MB

Release files / fastast-0.2.3.tar.gz

Download URL fastast-0.2.3.tar.gz
Size 626.7 kB
Tags Source
SHA-256 checksum
How to use checksums
f99832335b6d1f01cd7cd83af5b8333fd4474cf7972004a74515c224924df841
BLAKE2b-256 checksum
How to use checksums
f634b1a2acf56d8a088ac04a49e7bb689b9f35fc9703d8f40e35e3c9e0c60d28
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 26, 2026.

Transparency log

Release files / fastast-0.2.3-cp310-abi3-win_amd64.whl

Download URL fastast-0.2.3-cp310-abi3-win_amd64.whl
Size 2.8 MB
Tags CPython 3.10 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
40130d91628a4c950bfe0f2f182ddaafc92fc15e2f09470c697ca156a110b522
BLAKE2b-256 checksum
How to use checksums
5490e2823ffc6de2059490a8e6c6f88d171780cc5c356cdf84612b13f59bc67a
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 26, 2026.

Transparency log

Release files / fastast-0.2.3-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL fastast-0.2.3-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
39fc097d7232067da20b2abc3f5a0ca8b0a5df31604f7007b98b282627c40304
BLAKE2b-256 checksum
How to use checksums
d0e166cc7dd30188619bbf01e9a23ebc8a428268a956a5bcb4118a3f301656a0
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 26, 2026.

Transparency log

Release files / fastast-0.2.3-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

Download URL fastast-0.2.3-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
ab8f658fc7bc6b7753e775a448708394f25b21a7300975c45733798fca63b23f
BLAKE2b-256 checksum
How to use checksums
9c16dd959675d8c7509cf5496003b482723c3ee101327c6c20186ee09b33306e
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 26, 2026.

Transparency log

Release files / fastast-0.2.3-cp310-abi3-macosx_11_0_arm64.whl

Download URL fastast-0.2.3-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
83f0f6375b68753ed9d3da5a950f1e2fb70f3a0c9faac2fc59acef3ffeb6f707
BLAKE2b-256 checksum
How to use checksums
8a18b97ce0a5d18e24e8bb6ebe7ff54495d5266ab11b70031e7429175d40f0b5
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 26, 2026.

Transparency log

Release files / fastast-0.2.3-cp310-abi3-macosx_10_12_x86_64.whl

Download URL fastast-0.2.3-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
0fd130c36fb19823b0cdd261f71e904f4e3c7537c9e1e12322d04f66d783342a
BLAKE2b-256 checksum
How to use checksums
ad9c7401ba9b2f17ee08d78eaff15fae90d9215dc8c774bd5d721a22b07efbd4
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 26, 2026.

Transparency log

Security for fastast 0.2.3

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.3.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 26, 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