rw-ast-tools — Documentation Portal

Structural Code Intelligence

An open-source MCP server giving AI agents deep structural understanding of any codebase — hybrid search, AST editing, dependency analysis, and LSP integration in one unified platform.

943 Tests 77 MCP Tools v0.2.0 Release MIT License

Source Files

Lines of Code

Tests Passing

MCP Tools

System Health

Tool Distribution by Category

Project Growth

🔧

77 MCP Tools

Structural search, AST editing, LSP integration, knowledge graphs, and more across 10 categories.

⌨️

11 CLI Commands

Terminal-first workflows: search, navigate, analyze dependencies, detect dead code, and more.

🏗️

System Architecture

Three-server mode architecture with agent-agnostic integration, hybrid search engine, and plugin system.

System Architecture

rw-ast-tools is built on a modular, three-server-mode architecture with an agent-agnostic core, pluggable integration layer, and hybrid search engine powered by 6-factor RRF fusion.

Three Server Modes

Default

Timeout Mode

Per-connection stdio with idle TTL. Best for desktop CLI agents and single-session use.

Daemon

Daemon Mode

Persistent systemd service with auto-restart and file watcher. Best for multi-agent workstations.

Remote

Remote Mode

Streamable HTTP with auth. Persistent server deployment for team/enterprise use.

Tech Stack

ParserTree-sitter (20+ langs)

Python ASTlibcst (structural editing)

Vector DBsqlite-vec (384-dim)

SearchFTS5 + 6-factor RRF

Embeddingsbge-small-en-v1.5 (CPU)

RerankerCross-Encoder MiniLM

ProtocolMCP (Model Context Protocol)

Schemav5 (symbols + edges + KNN + audit)

Component Architecture

graph TB subgraph Clients["AI Agents"] H["Hermes Agent"] CC["Claude Code"] GC["Gemini CLI"] QC["Qwen Code"] end subgraph MCP["MCP Protocol Layer"] T["Timeout Mode
(stdio + idle TTL)"] D["Daemon Mode
(systemd + watcher)"] R["Remote Mode
(Streamable HTTP + Auth)"] end subgraph Core["Core Engine"] TS["Tree-sitter Parser
20+ Languages"] LC["libcst AST Editor
Python Structural Edits"] S["Hybrid Search
FTS5 + sqlite-vec"] RRF["6-Factor RRF
Semantic+Recency+Usage+Kind+Proximity+Callgraph"] CR["Cross-Encoder
MiniLM Reranker"] end subgraph Index["Index Layer"] IDX["Symbol Index
FTS5 + Embeddings"] KG["Knowledge Graph
KNN + Call Graph"] DM["Dependency Metrics
Fan-in/Fan-out/SPOF"] AL["Audit Log
Schema v5"] end subgraph Ext["Extensions"] LSP["LSP Integration
Definition/Completion/Refactor"] FX["Fix Pipeline
Ruff/ESLint/gofmt/clippy"] AG["Agent Integration
Context Builder/Tokens/Error Correction"] WD["Watchdog
Inotify File Watcher"] end Clients --> MCP MCP --> Core Core --> IDX Core --> KG Core --> DM Core --> AL Core --> LSP Core --> FX Core --> AG Core --> WD style H fill:#6366f1,stroke:#4338ca,color:#fff style CC fill:#06b6d4,stroke:#0891b2,color:#fff style GC fill:#10b981,stroke:#059669,color:#fff style QC fill:#f59e0b,stroke:#d97706,color:#fff style MCP fill:#1e293b,stroke:#475569,color:#e2e8f0 style Core fill:#0f172a,stroke:#6366f1,color:#e2e8f0 style IDX fill:#0f172a,stroke:#22d3ee,color:#e2e8f0 style KG fill:#0f172a,stroke:#34d399,color:#e2e8f0 style DM fill:#0f172a,stroke:#fbbf24,color:#e2e8f0 style AL fill:#0f172a,stroke:#fb7185,color:#e2e8f0

Data Flow — Query Path

sequenceDiagram participant A as AI Agent participant M as MCP Server participant P as Parser participant I as Index participant R as Reranker A->>M: semantic_search(query) M->>P: Parse query tokens M->>I: FTS5 + Vector Search I-->>M: Candidate Symbols M->>R: Rerank (Cross-Encoder) R-->>M: Scored Results M->>A: Ranked Context

Data Flow — Index Pipeline

Quick Deploy

# Desktop (timeout)
ast-tools-server
# --mode timeout (default)

# Server (daemon)
ast-tools-server --mode daemon
# systemd + file watcher

# Remote (HTTP)
ast-tools-server --mode remote
# --port 8080 --auth-token ...

CLI Reference

Complete ast command reference — 11 commands for terminal-first code intelligence workflows.

Commands

Output Formats

Languages

Available Commands

Command	Description	Example
ast search	Semantic search across codebase	ast search "auth handler"
ast navigate	Jump to symbol definition	ast navigate SessionManager
ast blast-radius	Impact analysis for any symbol	ast blast-radius src/auth.py:42
ast find-dead	Enhanced dead code detection	ast find-dead --format table
ast summary	Codebase overview & stats	ast summary --format markdown
ast symbols	List symbols in a file	ast symbols src/auth.py
ast refs	Find all references	ast refs authenticate
ast callers	Who calls this symbol	ast callers process_payment
ast callees	What does this symbol call	ast callees main --file-path main.py
ast deps	Import dependency analysis	ast deps src/api/handlers.py
ast browse	Browse all symbols by kind	ast browse --kind function -n 20

📋table

Default. Human-readable tabular format with aligned columns and headers.

📄json

Machine-readable JSON output. Perfect for scripting, piping, and automation.

📝markdown

Markdown tables. Great for embedding in documentation and reports.

Workflow Examples

# Find all authentication-related code
ast search "token validation middleware" --format json -n 20


      # Check impact before refactoring
ast blast-radius src/api/handlers.py:process_payment --max-hops 3 --format table

      # Find dead code (6 false-positive reductions)
ast find-dead --format json --exclude tests/ | jq '.items | length'

      # Trace full dependency chain
ast deps src/main.py --graph --format mermaid





  Performance & Benchmarks
  Real-world performance characteristics of the ast-tools engine across indexing, search, analysis, and LSP operations.

  
  
    
      <10ms
      FTS5 Keyword Search
      BM25-ranked full-text search over indexed symbols
    
    
      <50ms
      Vector Semantic Search
      384-dim cosine similarity via sqlite-vec (CPU)
    
    
      <100ms
      Hybrid RRF Fusion
      FTS5 + vector + 4 additional ranking signals
    
    
      ~10K/min
      Symbol Indexing Speed
      Parse + embed + store (CPU-only, no GPU)
    
    
      0.074s
      Import Time
      Lazy-loaded model weights — no startup delay
    
    
      98.7s
      Full Test Suite
      943 tests across 71 test files
    
  

  
  
    
      Search Latency Comparison (ms)
      
    
    
      Index Size by Schema Version
      
    
  

  
  
    Competitive Positioning
    
      
        Feature ast-tools Semble CodeGraph CodeSight jMunch
        
          Hybrid Search (FTS5+Vector) ✅ ✅ ✅ ⚠️ ❌
          Structural Editing ✅ ❌ ❌ ❌ ❌
          6-Factor RRF Fusion ✅ ❌ ❌ ❌ ❌
          Cross-Encoder Reranker ✅ ❌ ❌ ❌ ❌
          Hermes Plugins (Hooks) ✅ ❌ ❌ ❌ ❌
          LSP Integration ✅ ❌ ❌ ✅ ✅
          Knowledge Graph ✅ ❌ ✅ ✅ ❌
          Languages Supported 20+ 19 21 66 70+
          License MIT Apache 2.0 Proprietary MIT Apache 2.0
          Agent-First Design ✅ ❌ ❌ ❌ ❌
        
      
    
  




  Development Roadmap
  From v0.1.0 to v1.0.0 — the complete path from functional MCP server to self-sustaining code intelligence platform.

  
  
    

    
      
        
        
          Donev0.1.0 - v0.2.0
          Foundation Complete
          MCP server with 77 tools, 3-server-mode architecture, hybrid search engine, LSP integration, auto-fix pipeline, spectral clustering, knowledge graph, Hermes plugins. 943 tests passing.
        
      

      
        
        
          In ProgressPhase A — Ship
          PyPI Publishing & Distribution
          PyPI publish v0.1.0. GitHub Actions CI/CD. Pre-commit hooks configured. Wheel + sdist build pipeline complete.
          
            PyPI Release
            CI/CD Pipeline
            Documentation
          
        
      

      
        
        
          Phase BData Lifecycle Management
          Infrastructure Hardening
          Config directory (~/.ast-tools/), first-time setup wizard, doctor command, maintenance commands (vacuum, curation, pruning), data backup/restore, uninstall logic.
        
      

      
        
        
          Phase CDistribution & Ecosystem
          SDK + Docker + Marketplace
          Python SDK for programmatic access. Docker images for all three modes. Plugin marketplace with tiered monetization (Free/Team/Enterprise).
        
      

      
        
        
          Phase DWeb Dashboard
          Visualization & Administration
          Web dashboard for configuration, insights, search visualization, index management, and administration. Multi-machine deployment dashboard.
        
      

      
        
        
          Phase EMonetization
          Revenue Generation
          Team subscriptions ($29/mo), Enterprise tier ($49/mo), API licensing. Market projection: $250-500K ARR Year 2.
        
      
    
  

  
  
    
      Market Sizing ($M)
      
    
    
      Revenue Projections ($K ARR)
      
    
  




  Developer Guide
  Complete integration guide — from installation to advanced usage across agents, CLI, and API.

  
  
    Quick Install
    
      
        From Source
        # Clone & install
git clone https://github.com/stephanos8926-lgtm/ast-tools.git
cd ast-tools
uv sync --all-extras
      
      
        From PyPI
        # Install from PyPI
pip install rw-ast-tools

# Verify install
ast-tools-server --help
      
    
  

  
  
    Hermes Agent Integration
    # ~/.hermes/config.yaml
mcp_servers:
  rw-ast-tools:
    command: ast-tools-server
    args: [--mode, timeout]
    
      semantic_search"auth handler login"
      impact_analysissrc/auth.py:42
      class_hierarchySessionManager
    
  

  
  
    CLI Quick Reference
    
      ast search "auth handler"
ast search "db connection" --format json -n 5
      ast blast-radius src/auth.py:42
ast blast-radius --max-hops 3
      ast find-dead --format table
ast find-dead --exclude tests/
      ast callers process_payment
ast callees main --file-path src/main.py
      ast deps src/api/handlers.py
ast deps --graph --format mermaid
      ast summary --format markdown
ast browse --kind function -n 20
    
  

  
  
    Claude Code Integration
    # ~/.claude/settings.json
{
  "mcpServers": {
    "rw-ast-tools": {
      "command": "ast-tools-server",
      "args": ["--mode", "timeout"]
    }
  }
}
  

  
  
    Gemini CLI Integration
    # ~/.gemini/settings.yaml
mcp_servers:
  rw-ast-tools:
    command: ast-tools-server
    args: [--mode, daemon]
  

  
  
    Environment Reference
    
      
        Variable Default Description
        
          AST_TOOLS_MODE timeout Server mode: timeout, daemon, or remote
          AST_TOOLS_PORT 8080 Port for remote mode
          AST_TOOLS_HOST 0.0.0.0 Host for remote mode
          AST_TOOLS_AUTH_TOKEN — Auth token for remote mode
          AST_TOOLS_TIMEOUT 300 Idle TTL in seconds
          AST_TOOLS_INDEX_PATH .ast-tools/ Index storage directory
          AST_TOOLS_LOG_LEVEL info Logging level: debug/info/warn/error
        
      
    
  




  MCP Tools Reference
  77 tools across 10 categories — structural search, semantic analysis, code editing, LSP integration, and more. Search and filter below.

Feature	ast-tools	Semble	CodeGraph	CodeSight	jMunch
Hybrid Search (FTS5+Vector)	✅	✅	✅	⚠️	❌
Structural Editing	✅	❌	❌	❌	❌
6-Factor RRF Fusion	✅	❌	❌	❌	❌
Cross-Encoder Reranker	✅	❌	❌	❌	❌
Hermes Plugins (Hooks)	✅	❌	❌	❌	❌
LSP Integration	✅	❌	❌	✅	✅
Knowledge Graph	✅	❌	✅	✅	❌
Languages Supported	20+	19	21	66	70+
License	MIT	Apache 2.0	Proprietary	MIT	Apache 2.0
Agent-First Design	✅	❌	❌	❌	❌

Variable	Default	Description
AST_TOOLS_MODE	timeout	Server mode: timeout, daemon, or remote
AST_TOOLS_PORT	8080	Port for remote mode
AST_TOOLS_HOST	0.0.0.0	Host for remote mode
AST_TOOLS_AUTH_TOKEN	—	Auth token for remote mode
AST_TOOLS_TIMEOUT	300	Idle TTL in seconds
AST_TOOLS_INDEX_PATH	.ast-tools/	Index storage directory
AST_TOOLS_LOG_LEVEL	info	Logging level: debug/info/warn/error