pygraph

AST-based Python/Flask codebase indexer for AI coding agents.

pygraph parses your Python project into a queryable graph (graph.json) using static analysis (AST). It detects Flask routes, blueprints, templates, CLI commands, decorators, dependencies, and more — with zero network calls and no telemetry.

Designed as a companion tool for AI agents (opencode, Cline, etc.) via MCP, or for direct CLI use during development.

Quick Start

pip install pygraph-mcp

# Or with uv:
uv pip install pygraph-mcp

Index your project and start querying:

cd my-python-project
pygraph build
pygraph public
pygraph node "my_function"
pygraph callers "my_function"

Commands

MCP Integration

Start the MCP server and connect your AI agent:

pygraph mcp --root /path/to/project

All query commands are exposed as MCP tools, making them callable from opencode, Cline, and any MCP-compatible client.

Flask Support

pygraph detects Flask-specific constructs out of the box:

• Route decorators (@app.route) with HTTP methods and URL parameters
• Blueprint creation and registration (register_blueprint)
• Template rendering (render_template, render_template_string)
• Error handlers (@app.errorhandler)
• CLI commands (@app.cli.command)
• Flask extension usage

Architecture Enforcement

Create .pygraph/boundaries.json:

{
  "layers": [
    {"name": "views",     "pattern": "src/views/",     "allowed": ["services"]},
    {"name": "services",  "pattern": "src/services/",  "allowed": ["models", "repos"]},
    {"name": "models",    "pattern": "src/models/",    "allowed": []},
    {"name": "repos",     "pattern": "src/repos/",     "allowed": ["models"]}
  ]
}

Then run:

pygraph boundaries

Requirements

• Python 3.11+
• uv (recommended) or pip

Development

git clone https://github.com/shvmgyl15/pygraph.git
cd pygraph
uv sync
uv run pytest
uv run mypy src
uv run ruff check

How It Works

┌──────────┐    ┌──────────────┐    ┌───────────┐
│  Scanner  │ → │  Extractors  │ → │   Graph   │
│ (walker)  │   │ (AST, Flask) │   │  (JSON)   │
└──────────┘    └──────────────┘    └───────────┘
                                          ↓
                                   ┌──────────┐
                                   │  Query   │
                                   │  Engine  │
                                   └──────────┘

1. Scan — walks the project tree, respects .gitignore, classifies files
2. Extract — parses Python source with ast, extracts symbols, calls, imports, Flask decorators, dependencies
3. Graph — serializes everything to .pygraph/graph.json (incremental builds supported)
4. Query — CLI or MCP tools query the graph for callers, callees, impact, paths, orphans, complexity, coupling, etc.

Inspiration

pygraph was inspired by and follows the same design philosophy as:

• tsgraph — TypeScript codebase indexer
• gograph — Go codebase indexer

Both projects use AST-based static analysis to create queryable code graphs for AI coding agents. pygraph adapts the same concept to Python and Flask.