Grapuco Documentation

Everything you need to set up, index, and query your codebase.

rocket_launch

Getting Started

1. Get your API Key

2. Install the CLI

Grapuco CLI is the engine that parses your AST locally. Run the following command securely on your machine:

npm install -g @bitsness/grapuco-cli

3. Ingest Data

At the root of your project database, run the ingest command below. The engine will scan logic networks and map them onto the Cloud securely in a few seconds.

grapuco ingest

account_tree

Architecture Graph

The moment ingestion completes, your codebase is transformed into a visual Knowledge Graph. Here's how to read it:

Filters

Tailor the graph to your exact needs. Toggle visibility by node types (API Endpoints, DB Models, Functions) or filter out noisy utility directories dynamically.

Explorer

Navigate through your entire codebase organically. Select any node to expand its surrounding ecosystem, inspecting properties, outgoing calls, and dependencies locally.

Flows

Discover auto-detected execution lifecycles. Click any HTTP Endpoint flow to trigger a luminous trace that highlights the exact path from Router to Database.

hub

3. MCP Server Integration

MCP (Model Context Protocol) is an open standard that allows AI coding assistants like Claude, Cursor, and Windsurf to connect directly to external tools and data sources. When you connect Grapuco as an MCP server, your AI assistant gains full access to your codebase's architecture graph - enabling it to understand call chains, trace data flows, and analyze impact before writing a single line of code.

Connect Your AI Agent

terminalQuick Setup

One command to configure MCP for all AI coding agents on your machine:

grapuco setup

The CLI will ask for your API key, auto-detect installed AI tools (Claude Code, Cursor, Windsurf, Antigravity, etc.), and write the correct MCP config for each one.

Available MCP Tools

Once connected, your AI assistant can call these tools automatically. You don't need to invoke them manually - just ask your AI a question about your codebase and it will pick the right tool.

folder_open

list_repositories

Lists all repositories you've indexed on Grapuco. This is the starting point - your AI will call this first to find the correct Repository ID before running any other tool.

manage_search

search_code

Finds functions, classes, or methods by their exact name in the code graph. Think of it like a smart IDE search, but across your entire architecture map - not just text files.

psychology

semantic_search

Search your codebase using plain English instead of exact keywords. For example, ask "where do we validate JWT tokens?" and Grapuco will find the most relevant symbols using vector similarity (cosine distance).

device_hub

get_dependencies

Given a specific function or class, this tool returns its full dependency tree: what it CALLS, what it IMPORTS, and what it EXTENDS. Perfect for understanding how deeply connected a piece of code is.

account_tree

get_architecture

Returns the complete architecture map of a repository - every node (function, class, endpoint) and every edge (call, import, extend). Your AI uses this to understand the big picture before making changes.

auto_awesome

get_context

AI-powered contextual retrieval. Give it a feature name like "user authentication flow" and it returns related symbols, call chains, and documentation. Costs 5 AI credits per query. Best for onboarding to unfamiliar codebases.

route

get_data_flows

Traces end-to-end execution paths: from HTTP API endpoints through services down to database operations. Shows exactly how a request travels through your system - ideal for debugging and understanding business logic.

warning

get_impact_analysis

The "Blast Radius" detector. Point it at any file and it reveals every API endpoint, database operation, and workflow that would be affected if that file changes. Essential before refactoring or deploying risky changes.

hub

get_symbol_context

360° view of any symbol: callers, callees, processes, heritage, DB access, routes, and overrides. Your go-to tool for understanding how a function fits into the bigger picture.

radar

blast_radius

Compute the upstream and downstream impact of changing a symbol. Returns risk level (LOW to CRITICAL), affected routes, and impacted business processes.

difference

detect_changes

Feed it a git diff and get back: which symbols changed, what's impacted downstream, affected routes, and overall risk level. Perfect for pre-commit safety checks.

edit_note

rename_symbol

Safe multi-file rename. Preview all edits (declaration, call sites, imports, exports), detect naming conflicts, and optionally apply.

update

check_staleness

Check if your code graph is up-to-date with the latest commit. Returns recommendation: none, incremental, or full reindex needed.

build

detect_tools

Scan the codebase for MCP tools, gRPC services, and JSON-RPC methods. Useful for discovering API surface area.

help_center

grapuco_help

Get guidance on which tool to use. Returns the full skill and tool catalog, with optional topic filtering.

bolt

bootstrap

One-shot onboarding: returns repos, tool catalog, skill manifest, and recommended first moves. Call once at session start. Pass workspaceId to auto-resolve linked repos and spec projects.

school

5. AI Skill Packs

downloadDownload All

Grapuco ships with built-in Skill Packs — step-by-step playbooks that teach your AI agent how to use Grapuco tools effectively. Each skill describes when to use it, what inputs are needed, and how to interpret the output.

explore

Onboard a new/unfamiliar codebase — discover structure, entry points, and key flows in minutes.

download

shield

safe-edit

Check impact before editing code — get context, blast radius, and suggest tests to validate changes.

download

check_circle

pre-commit

Run impact analysis on your git diff before committing — catch risky changes early.

download

edit_note

rename

Safely rename a symbol across multiple files — preview all edits and conflicts before applying.

download

timeline

trace

Trace a request from API route through service layer to database — understand the full data flow.

download

bug_report

bug

Investigate a bug using stack trace — trace each frame, find upstream causes, and scope the fix.

download

construction

refactor

Plan a refactor by mapping blast radius, grouping by module, and scoping safe incremental steps.

download

description

spec-coding

Implement a feature using Spec Agent business specifications — requirements, acceptance criteria, and domain rules.

download

fact_check

review-uc

Review a Use Case's full scope — requirements, steps, rules, actors, and dependencies — before writing code.

download

gavel

validate-rules

Search and validate business rules, constraints, and schemas relevant to your current implementation.

download

terminal

4. CLI Deep Dive

The Grapuco CLI runs entirely on your local machine. It parses your codebase's AST (Abstract Syntax Tree) and extracts only structural metadata - function names, call relationships, import maps. Zero source code ever leaves your machine.

key

grapuco login

Authenticate your CLI with the Grapuco cloud. You can pass your API key directly via flag, or run the command without flags for an interactive prompt. Credentials are stored securely at ~/.grapuco/credentials.json.

grapuco login --api-key YOUR_API_KEY

--api-key <key> - Pass API key directly (skip interactive prompt)

--server <url> - Custom server URL (default: https://api.grapuco.com)

folder_open

grapuco init

Initialize a new Grapuco project in the current directory. The CLI auto-detects your programming language and framework (NestJS, Next.js, Django, Spring Boot, etc.), creates a .grapuco/config.json file, and registers a new repository on the server.

grapuco init

--name <name>Custom repository name (default: folder name)

--link <repoId>Link to an existing repository instead of creating new

--workspace <id>Add repo to a workspace during init

--server <url>Custom server URL

cloud_upload

grapuco ingest

The core command. Scans every file in your project, builds a full AST parse locally, then uploads only the metadata (nodes + edges) to the Grapuco cloud. This is a full re-sync - use it for the first run or when you want a complete refresh.

grapuco ingest

--embeddings - Enable vector embeddings for semantic search

--flows - Enable data flow analysis (API → Service → DB tracing)

--all - Enable all features

--dry-run - Parse locally but don't upload to server

sync

grapuco push

Smart incremental sync. Compares file hashes against the last push and only re-parses files that have changed (added, modified, or deleted). Dramatically faster than a full ingest - ideal for daily development workflows.

grapuco push

--force - Ignore delta cache, re-ingest everything

--enrich-flows - Re-run data flow analysis on changed files

visibility

grapuco watch

Real-time file watcher. Monitors your project directory using chokidar and automatically triggers a delta push whenever you save a file. Configure the debounce interval to control how frequently syncs happen. Press Ctrl+C to stop.

grapuco watch

--debounce <ms> - Debounce interval in milliseconds (default: 2000)

preview

grapuco inspect

Transparency tool. Parses your project locally and shows exactly what data would be sent to the server - without actually sending it. Perfect for security audits or verifying that no source code is included in the payload.

grapuco inspect --json

--json - Output full machine-readable JSON instead of summary

info

grapuco status

Dashboard in your terminal. Shows your project config, detected language/framework, feature flags (embeddings, data flows), last push timestamp, cached file count, and remote repository status (node/edge counts).

grapuco status

settings_suggest

grapuco setup

Auto-configure MCP for your AI editor. Detects installed editors (Claude Code, Cursor, Windsurf, Codex, Antigravity), writes the MCP config, and verifies the connection.

grapuco setup