Grafeo

Deep code intelligence for AI agents. Give any AI coding assistant persistent, structural understanding of your entire codebase — powered by SpacetimeDB.

Grafeo is a Model Context Protocol (MCP) server that indexes your project into a relational knowledge graph: files, symbols, dependencies, exports, modules, conventions, decisions, tasks, and change history. AI agents query this graph through 29 specialized tools instead of re-reading your code every session.

Grafeo has two parts:

• The MCP server (runs over stdio; used by IDEs/agents).
• The CLI (grafeo) that initializes a project, indexes it, and writes IDE config.

SpacetimeDB is used as Grafeo's persistent storage and query layer: indexing writes to a local database (tables + reducers), and MCP tool calls read from it.

Features

• Universal — Works with any language. Built-in plugins for TypeScript/JavaScript and Python. Generic fallback for Rust, Go, Java, C#, and more.
• Auto-detection — Detects languages, frameworks (Next.js, React, Flask, Django, etc.), and project structure automatically.
• Persistent knowledge — SpacetimeDB stores everything relationally. Conventions, decisions, annotations, and tasks survive across sessions.
• 29 MCP tools — Context, search, blast radius, dependency graphs, conventions, tasks, analytics, and power tools like session_bootstrap and preflight_check.
• Plugin architecture — Add language support by implementing a single LanguagePlugin interface.
• IDE setup — One command configures Windsurf, Cursor, or Claude Desktop.

How it works

1. You run grafeo init to create .grafeo/config.json.
2. You publish the SpacetimeDB module (schema + reducers) to a local database.
3. You run grafeo index to scan files and write structured data into SpacetimeDB.
4. Your IDE starts the MCP server over stdio.
5. Agents call tools (search, file context, dependency graph, blast radius, etc.) which query SpacetimeDB instead of re-reading the whole repo.

Why SpacetimeDB?

• Persistence across sessions (tasks/conventions/decisions/annotations).
• Relational queries over code structure (symbols ↔ files ↔ deps ↔ exports).
• Safe incremental updates via reducers (clear/reindex file, append change history).

For Coding Agents (Repo Setup Prompt)

Use this prompt to let a coding agent set up Grafeo in one pass:

You are setting up Grafeo from scratch in this repository.

Goals:
1) Install dependencies
2) Build project
3) Publish SpacetimeDB module locally
4) Initialize and index this repo with Grafeo
5) Configure MCP for my IDE

Execution requirements:
- Run in this exact order:
  a) npm install
  b) npm run build
  c) (cd spacetimedb && npm install)
  d) spacetime start
  e) spacetime publish grafeo -s local -p ./spacetimedb --no-config -y
  f) npx tsx src/cli.ts init .
  g) SPACETIMEDB_DB=grafeo npx tsx src/cli.ts index .
  h) GRAFEO_SETUP_DEV=1 npx tsx src/cli.ts setup windsurf

Validation (optional but recommended): follow `docs/mcp-validation.md`.

Detailed operational docs for agents are in docs/.

For Coding Agents (npm Package Prompt)

Use this when setting up Grafeo inside another project via npm:

You are setting up Grafeo inside an existing project via npm.

Goals:
1) Install Grafeo
2) Publish SpacetimeDB module locally
3) Initialize and index the target project
4) Configure MCP for my IDE

Execution requirements:
- Run in this exact order (from the project root):
  a) npm install --save-dev grafeo-mcp
  b) npm --prefix node_modules/grafeo-mcp/spacetimedb install
  c) spacetime start
  d) spacetime publish grafeo -s local -p node_modules/grafeo-mcp/spacetimedb --no-config -y
  e) npx grafeo init .
  f) SPACETIMEDB_DB=grafeo npx grafeo index .
  g) npx grafeo setup windsurf

Validation (optional but recommended): follow `docs/mcp-validation.md`.

Quick Start (npm package)

Prerequisites

• Node.js >= 18
• SpacetimeDB CLI — curl -sSf https://install.spacetimedb.com | sh

1. Install

npm install --save-dev grafeo-mcp
# Or globally:
# npm install -g grafeo-mcp

2. Start SpacetimeDB & publish module

spacetime start
npm --prefix node_modules/grafeo-mcp/spacetimedb install
spacetime publish grafeo -s local -p node_modules/grafeo-mcp/spacetimedb --no-config -y

3. Initialize & index your project

npx grafeo init .
SPACETIMEDB_DB=grafeo npx grafeo index .

4. Configure your IDE

npx grafeo setup windsurf

MCP server entry point (npm)

Your IDE configuration should run the MCP server over stdio using:

npx -y grafeo-mcp

If you installed globally, replace npx grafeo with grafeo. If your package manager does not use node_modules, point -p to the actual grafeo-mcp/spacetimedb folder.

Quick Start (from source)

Prerequisites

• Node.js >= 18
• SpacetimeDB CLI — curl -sSf https://install.spacetimedb.com | sh

1. Install

git clone https://github.com/snowarch/grafeo.git
cd grafeo
npm install
npm run build
cd spacetimedb && npm install && cd ..

2. Start SpacetimeDB & publish module

# Start local SpacetimeDB
spacetime start

# Publish the Grafeo module
spacetime publish grafeo -s local -p ./spacetimedb --no-config -y

Or use the helper script:

chmod +x start.sh && ./start.sh

3. Initialize in your project

# From your project directory:
npx tsx /path/to/grafeo/src/cli.ts init .

This auto-detects languages, framework, and creates .grafeo/config.json.

4. Index your project

npx tsx /path/to/grafeo/src/cli.ts index .

5. Configure your IDE

# Windsurf
GRAFEO_SETUP_DEV=1 npx tsx /path/to/grafeo/src/cli.ts setup windsurf

# Cursor
GRAFEO_SETUP_DEV=1 npx tsx /path/to/grafeo/src/cli.ts setup cursor

# Claude Desktop
GRAFEO_SETUP_DEV=1 npx tsx /path/to/grafeo/src/cli.ts setup claude

CLI Commands

| Command | Description | |---------|-------------| | grafeo init [path] | Initialize Grafeo in a project (auto-detects everything) | | grafeo index [path] | Index the project into SpacetimeDB | | grafeo serve | Start MCP server (stdio transport) | | grafeo setup <ide> | Configure MCP for your IDE | | grafeo status [path] | Check index status |

MCP Tools (29)

Full input/behavior reference: docs/tools.md.

Context & Understanding

| Tool | Description | |------|-------------| | get_file_context | Everything about a file: symbols, deps, annotations, dependents | | search_codebase | Fuzzy search across files and symbols | | get_dependency_graph | What a file imports and what depends on it | | get_blast_radius | Risk assessment before editing (LOW/MEDIUM/HIGH/CRITICAL) | | get_export_info | Full info about an exported symbol | | get_module_overview | Module summary: files, entry point, key components | | get_framework_info | Detected framework and project metadata |

Knowledge Management

| Tool | Description | |------|-------------| | save_convention | Record a coding convention | | get_conventions | Retrieve conventions by area | | save_decision | Log an architecture decision record | | annotate_file | Add persistent notes to files | | get_annotations | Retrieve file annotations |

Tasks & Continuity

| Tool | Description | |------|-------------| | create_task | Create a task for multi-session continuity | | update_task | Update task status | | get_active_tasks | List non-completed tasks | | log_change | Record a file change |

Analytics

| Tool | Description | |------|-------------| | get_project_stats | File counts by type/module, symbol counts | | find_hotspots | Most-imported files, most-used exports, high complexity | | get_recent_changes | Recently logged changes |

Indexing

| Tool | Description | |------|-------------| | reindex_file | Re-index a single file | | reindex_all | Full project re-index | | index_status | Current index statistics |

Power Tools

| Tool | Description | |------|-------------| | session_bootstrap | One call to start a session: rules, tasks, conventions, index status, recent changes | | read_file | Read any file with line numbers | | get_project_rules | Inject AGENTS.md / CLAUDE.md / .cursorrules | | preflight_check | Safety gate before editing: blast radius + deps + conventions for all target files | | find_examples | Grep source files for patterns with context | | batch_context | Multi-file + multi-export context in one call | | postchange_audit | Post-edit: reindex + log + validate all changes |

Architecture

grafeo/
├── src/
│   ├── cli.ts              # CLI entry point (init, index, serve, setup, status)
│   ├── mcp-server.ts       # MCP server with 29 tools
│   ├── db.ts               # SpacetimeDB HTTP client
│   ├── config.ts           # Project config management
│   ├── detector.ts         # Auto-detection (languages, frameworks)
│   ├── indexer/
│   │   ├── index.ts        # Main indexer orchestrator
│   │   └── scanner.ts      # File system walker
│   └── plugins/
│       ├── base.ts         # LanguagePlugin interface
│       ├── registry.ts     # Plugin discovery & routing
│       ├── typescript.ts   # TypeScript/JavaScript parser
│       ├── python.ts       # Python parser
│       └── generic.ts      # Fallback parser (Rust, Go, etc.)
├── spacetimedb/
│   └── src/index.ts        # SpacetimeDB schema & reducers
├── test/                   # Unit tests (vitest)
├── start.sh                # Helper to start SpacetimeDB
└── package.json

Data Model (SpacetimeDB)

| Table | Primary Key | Description | |-------|-------------|-------------| | files | path | All indexed files with metadata | | symbols | id (auto) | Functions, classes, imports, types, etc. | | dependencies | id (auto) | File-to-file import relationships | | exports | name | Exported symbols with usage counts | | module_summaries | module_name | Module-level aggregates | | project_meta | key | Key-value project metadata | | custom_entries | id (auto) | Plugin-specific data | | decisions | id (auto) | Architecture decision records | | conventions | id (auto) | Coding conventions | | annotations | id (auto) | File annotations (gotcha, todo, warning) | | tasks | id (auto) | Multi-session task tracking | | change_history | id (auto) | Change log |

Adding Language Plugins

Implement the LanguagePlugin interface:

import type { LanguagePlugin } from './plugins/base.js';

export const rustPlugin: LanguagePlugin = {
  name: 'rust',
  extensions: ['.rs'],

  async detectProject(root) {
    // Check for Cargo.toml
  },

  parseFile(content, path) {
    // Extract symbols, imports, exports
  },

  classifyComplexity(content) {
    // Return 'low' | 'medium' | 'high'
  },
};

Register it in src/plugins/registry.ts:

import { rustPlugin } from './rust.js';
// In constructor:
this.register(rustPlugin);

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | SPACETIMEDB_URL | http://127.0.0.1:3000 | SpacetimeDB server URL | | SPACETIMEDB_DB | auto from project name | Database name | | GRAFEO_PROJECT_ROOT | cwd | Project root override |

Development

# Run tests
npm test

# Type check
npx tsc --noEmit

# Run MCP server directly
npx tsx src/mcp-server.ts

# Run CLI
npx tsx src/cli.ts help

License

MIT — see LICENSE.