para-graph 🧠

Structural code analysis tool powered by Tree-sitter AST parsing.

🇺🇸 English • 🇻🇳 Tiếng Việt

Table of Contents

• Overview
• Features
• Quick Start
• Usage
• Output Format
• Architecture
• Development
• Roadmap
• License

🎯 Overview

para-graph is a deterministic code analysis tool that extracts structural information from multi-language codebases and produces a knowledge graph in JSONL format.

It uses Tree-sitter for fast, accurate AST parsing — no compiler pipeline required. The output graph captures:

• Entities — classes, functions, interfaces, arrow functions, methods
• Relationships — imports, function calls, inheritance (future)

Part of the PARA Workspace ecosystem.

🛠 Requirements / Tech Stack

• Node.js >= 18.0.0
• TypeScript 5.x
• Tree-sitter (native bindings compiled automatically via node-gyp-build)

✨ Features

• Multi-Language Support — TypeScript, TSX, Python 🐍, Bash 🐚, Go 🐹, PHP 🐘
• Deterministic parsing — Tree-sitter AST & Pure SSEC Queries, no LLM heuristics
• JSONL output — one entity/relation per line, easy to stream and process
• Global Workspace Server — Serve multiple project graphs simultaneously via MCP
• Semantic Enrichment — Agent-driven context tagging (summary, complexity, domain concepts)
• Fast In-Memory Query Engine — Indexed lookups with LRU cache (Max=3 projects)
• Impact Analysis — BFS traversal to find all affected nodes when changing a code entity
• Context Bundle — Get source code, callers, callees, imports, and tests in one MCP call
• Agentic Edge Resolution — Inject missing relationships (e.g., dynamic Bash imports) directly via MCP
• MCP Auto-Setup — Manifest-declared mcp: block enables automatic IDE configuration via ./para mcp-setup

🚀 Quick Start

# Clone
git clone https://github.com/pageel/para-graph.git
cd para-graph

# Install
npm install

# Build
npm run build

# Scan any supported project
npx para-graph build /path/to/your/ts/project ./output

Or run directly without cloning:

npx para-graph build ./src ./output

📖 Usage

CLI Commands

# Scan source code and export graph
para-graph build <target-dir> [output-dir] [--import]

# Start MCP server for AI Agent integration
para-graph serve <workspace-root>

# Show help
para-graph --help

Build Command

# Basic usage
para-graph build ./src                       # Output to ./output/
para-graph build ./src ./my-graph            # Custom output directory
para-graph build ./src ./out --import        # Preserve semantic data on re-scan

Argument	Required	Default	Description
target-dir	✅	—	Directory containing supported source files
output-dir	—	./output	Where to write the graph output
--import	—	—	Load existing graph, preserve semantic enrichment data

Serve Command

# Start MCP server (stdio transport)
para-graph serve /path/to/workspace

🤖 MCP Server Setup

To connect para-graph to an AI Agent editor (like Claude Desktop, Cursor, or Google Antigravity), you need to configure their respective MCP settings.

Auto-Setup (Recommended)

If you are using PARA Workspace v1.8.2+, you can automatically configure the MCP server in your IDE by running:

./para mcp-setup

This will safely detect your active IDE and inject the para-graph MCP server configuration.

Manual Setup (Fallback)

If you prefer to configure the server manually:

Claude Desktop / Antigravity

Edit your claude_desktop_config.json (or mcp_config.json for Antigravity) and add the following:

{
  "mcpServers": {
    "para-graph": {
      "command": "<ABSOLUTE_WORKSPACE_PATH>/cli/para",
      "args": [
        "graph",
        "serve",
        "<ABSOLUTE_WORKSPACE_PATH>"
      ]
    }
  }
}

Note: Replace <ABSOLUTE_WORKSPACE_PATH> with the absolute path to your PARA Workspace root directory.

Cursor

Go to Cursor Settings > Features > MCP Servers > Add New MCP Server:

• Name: para-graph
• Type: command
• Command: <ABSOLUTE_WORKSPACE_PATH>/cli/para graph serve <ABSOLUTE_WORKSPACE_PATH>

Available MCP Tools

Once connected, your AI Agent gains access to the following tools:

• graph_query: Search entities by name or semantic type.
• graph_edges: Find function callers and imports.
• graph_enrich: Automatically save documentation and complexity data into the graph.
• graph_impact_analysis: Discover upstream/downstream impacted files when changing code.
• graph_context_bundle: Get the entire context of a code snippet in one call.

Library Usage

// Import as a library
import { CodeGraph } from 'para-graph';

// Import MCP server factory
import { createServer } from 'para-graph/mcp';

📊 Output Format

Three files are generated in the output directory:

entities.jsonl

One code entity per line, sorted by file path:

{"id":"src/graph/code-graph.ts::CodeGraph","type":"class","name":"CodeGraph","filePath":"src/graph/code-graph.ts","startLine":10,"endLine":81,"exportType":"named","signature":"export class CodeGraph {"}

relations.jsonl

One relationship per line, sorted by source file:

{"sourceId":"src/index.ts","targetId":"./parser/file-walker.js","relation":"IMPORTS_FROM","sourceFile":"src/index.ts","sourceLine":3}

metadata.json

Summary statistics:

{
  "version": "0.1.0",
  "nodeCount": 31,
  "edgeCount": 47,
  "fileCount": 6,
  "createdAt": "2026-04-21T03:35:33.508Z"
}

Entity Types

Type	Description
file	Source file
class	Class declaration
function	Function, method, or arrow function
interface	Interface declaration
variable	Variable declaration (future)

Relation Types

Relation	Description
IMPORTS_FROM	File imports from another module
CALLS	Function/method calls another function
INHERITS	Class extends another (future)
IMPLEMENTS	Class implements interface (future)

🏗️ Architecture

src/
├── cli.ts                    # Subcommand router (shebang entrypoint)
├── commands/
│   ├── build.ts              # Build command — scan, parse, export graph
│   └── serve.ts              # Serve command — MCP server lifecycle
├── graph/
│   ├── models.ts             # GraphNode, GraphEdge type definitions
│   ├── code-graph.ts         # In-memory graph with dual indexing
│   ├── jsonl-exporter.ts     # Serialize graph → JSONL files
│   ├── jsonl-importer.ts     # Load graph from JSONL files
│   └── graph-store.ts        # LRU cache manager for multi-project graphs
├── mcp/
│   ├── server.ts             # MCP server factory (pure library export)
│   ├── tools.ts              # MCP tools: query, edges, enrich, impact_analysis, context_bundle, add_edges
│   └── resources.ts          # MCP resources: JSONL file access
├── parser/
│   ├── registry.ts           # Language Registry (lazy-loads parsers by extension)
│   ├── tree-sitter-parser.ts # AST parsing and SSEC mapping engine
│   └── file-walker.ts        # Recursive multi-language file scanner
└── queries/
    ├── typescript.scm        # SSEC query patterns for TS/TSX
    ├── python.scm            # SSEC query patterns for Python
    ├── go.scm                # SSEC query patterns for Go
    ├── php.scm               # SSEC query patterns for PHP
    └── bash.scm              # SSEC query patterns for Bash

Data Flow

Source files → File Walker → Registry Lookup → Tree-sitter Parser + SSEC Query → CodeGraph (in-memory) → JSONL Export
                                                                                       │
                                                                                 GraphStore (LRU)
                                                                                       │
                                                                                 MCP Server → AI Agent

🛠️ Development

# Install dependencies
npm install

# Run in development
npm run dev

# Build TypeScript
npm run build

# Run tests
npm run test

Tech Stack

Component	Technology
Runtime	Node.js ≥ 18
Language	TypeScript 5.x (strict mode)
AST Parser	tree-sitter + tree-sitter-typescript
Test Runner	Vitest
Dev Runner	tsx

🧠 AI Intelligence (PARA Workspace)

This tool bundles AI intelligence artifacts that enhance the PARA Workspace agent experience. When installed via ./para install-tool para-graph, these artifacts are automatically installed into your workspace's .agents/ directory:

Type	Name	Version	Description & Usage
Workflow	/para-graph	1.8.0	Type @[/para-graph] to instruct the AI to re-scan and update the graph memory.
Skill	graph-enrichment	1.0.0	Loaded on-demand when the agent reads graph data. Guides the agent to semantically enrich graph nodes (add summaries, complexity scores).
Rule	graph-first-policy	1.0.0	Enforces graph-first development practices. The agent will proactively query the MCP server before making architecture decisions.

Requires PARA Workspace v1.8.2+ for automatic MCP auto-setup detection.

🗺️ Roadmap

Phase	Description	Status
P1	Structural Base (Tree-sitter AST)	✅ Done
P2	Semantic Enrichment (Agent-Driven)	✅ Done
P3	Storage & Query Engine	✅ Done
P4	CLI Integration & NPM Package	✅ Done
P5	Multi-language Support & Query Refactor	✅ Done
P6	Impact & Context Queries	✅ Done
P7	Agentic Bash Edge Resolution	✅ Done
P8	Deep CALLS + Pattern Detection	📋 Planned
P9	Documentation & Stable Release (v1.0.0)	📋 Planned

📄 License

MIT