ferrograph 1.2.0

Graph-powered Rust code intelligence. Indexes Rust codebases into a queryable knowledge graph with CLI and MCP interfaces.

Status

Implements file discovery, tree-sitter AST extraction (functions, structs, enums, traits, impls, consts, statics, macros, modules), mod/use resolution with Imports edges, call graph construction (same-file and cross-file via imports; includes calls inside macro invocations such as format!() and println!()), type reference edges, trait impl edges, owns/borrows edges (syntactic; struct fields and function parameters), lifetime_scope edges (items with explicit lifetime parameters), macro expansion edges, unsafe usage edges, dead code detection (pub, main, #[test], and #[bench] entry points), CozoDB graph storage, CLI (index, query, search, status, watch), MCP server with 10 tools (reindex, status, search, node_info, dead_code, blast_radius, callers, query, trait_implementors, module_graph), and optional git change-coupling analysis. Node IDs are relative to the project root (e.g. ./src/main.rs#10:1). Full ownership/borrow semantics (move analysis, lifetime validity) are planned for future rust-analyzer integration.

Build

cargo build --release
cargo test
cargo clippy -- -D warnings

Usage

# Index current directory (in-memory)
cargo run -- index .

# Index to a persistent database
cargo run -- index . --output .ferrograph

# Run Datalog queries (requires a persistent database)
cargo run -- query --db .ferrograph "?[id, type, payload] := *nodes[id, type, payload]"
cargo run -- query --db .ferrograph "?[id] := *dead_functions[id]"

# Text search over node payloads (use -c for case-insensitive)
cargo run -- search --db .ferrograph "main"
cargo run -- search --db .ferrograph -c "greet"

# Show graph stats
cargo run -- status .

# Watch for changes and re-index (--output required)
cargo run -- watch . --output .ferrograph

# Run MCP server over stdio (for AI agents / IDEs).
# The server looks for a graph at FERROGRAPH_DB or .ferrograph in the current directory.
# Set FERROGRAPH_DB to the path of your index to use a specific graph.
cargo run -- mcp

Setup with Cursor

Add to .cursor/mcp.json in your project (or global settings):

{
  "mcpServers": {
    "ferrograph": {
      "command": "ferrograph",
      "args": ["mcp"],
      "env": {
        "FERROGRAPH_DB": "/absolute/path/to/your/project/.ferrograph"
      }
    }
  }
}

If building from source instead of installing via cargo install ferrograph:

{
  "mcpServers": {
    "ferrograph": {
      "command": "cargo",
      "args": ["run", "--manifest-path", "/path/to/ferrograph/Cargo.toml", "--", "mcp"],
      "env": {
        "FERROGRAPH_DB": "/absolute/path/to/your/project/.ferrograph"
      }
    }
  }
}

Setup with Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "ferrograph": {
      "command": "ferrograph",
      "args": ["mcp"],
      "env": {
        "FERROGRAPH_DB": "/absolute/path/to/your/project/.ferrograph"
      }
    }
  }
}

First use

You can either pre-index your project or let the MCP reindex tool bootstrap it:

# Option 1: Pre-index from the CLI
cd /path/to/your/rust/project
ferrograph index . --output .ferrograph

# Option 2: Skip this step — use the reindex MCP tool from your AI agent

The FERROGRAPH_DB env var is optional if you run the MCP server from the project root (it defaults to .ferrograph in the current directory).

MCP tools

Node IDs use the format ./path/to/file.rs#line:col (relative to the project root).

Tool	Description
`reindex`	Re-index the project; can bootstrap from scratch (no pre-existing DB needed).
`status`	Node/edge counts, DB path, `indexed_at` timestamp.
`search`	Text search over node payloads; supports limit/offset pagination.
`node_info`	Type, payload, and incoming/outgoing edges for a node ID.
`dead_code`	Functions not reachable from entry points; optional `node_type` and `file_glob` filters.
`blast_radius`	Transitive impact set via calls, references, and changes_with edges.
`callers`	Direct and transitive callers up to a given depth.
`query`	Raw Datalog queries (read-only; mutations rejected).
`trait_implementors`	Find implementations of a named trait (stub; returns empty with note).
`module_graph`	File-to-module containment edges; optional relative path prefix filter (e.g. `./src/`).

Graph schema (edge types)

The schema defines 11 edge types; all 11 are currently populated:

Edge type	v1 populated	Notes
`contains`	Yes	File/module containment.
`imports`	Yes	From `mod`/`use` resolution.
`calls`	Yes	Same-file and cross-file (via imports) calls.
`references`	Yes	Type mentions in fields, params, return types.
`implements_trait`	Yes	Trait impls (`impl Trait for Type`).
`owns`	Yes	Struct fields and fn params; unresolvable types (primitives, generics, external) omitted.
`borrows`	Yes	Struct fields and fn params (`&T`/`&mut T`); same resolution limits as owns.
`expands_to`	Yes	Macro invocation to macro definition.
`uses_unsafe`	Yes	Unsafe blocks and `unsafe fn`/`unsafe impl`.
`lifetime_scope`	Yes	Self-loop on items with explicit lifetime params (tree-sitter only).
`changes_with`	Yes (requires `git` feature)	Git change coupling (optional feature).

Publishing

Published to crates.io. Cargo.toml pins rayon to >=1.5, <1.11 because cozo's transitive graph_builder 0.4.1 is incompatible with rayon 1.11+. This pin does not affect end users.

See CHANGELOG.md for version history.

License

MIT