Grapuco Documentation

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

rocket_launch

Getting Started

1. Get your API Key

Sign up and create a new project. You'll receive a unique Repository ID and an API Key to authenticate your CLI or MCP tool.

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

codeAntigravity / Cursor / Windsurf

Add this JSON block to your MCP Server Raw Config file (Settings → MCP Servers):

{
  "mcpServers": {
    "grapuco": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.grapuco.com/mcp",
        "--header",
        "X-Api-Key: YOUR_API_KEY"
      ],
      "env": {},
      "disabled": false
    }
  }
}
terminalClaude Code (CLI)

Run this single command in your terminal to register Grapuco as an MCP source:

claude mcp add grapuco --transport http "https://api.grapuco.com/mcp?apiKey=YOUR_API_KEY"

Replace YOUR_API_KEY with the key from your API Keys page in the Grapuco Dashboard.

Video walkthrough: Setting up Grapuco MCP with your AI coding assistant

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.

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
--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
--embeddingsEnable vector embeddings for semantic search
--flowsEnable data flow analysis (API → Service → DB tracing)
--allEnable all features
--dry-runParse 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
--forceIgnore delta cache, re-ingest everything
--enrich-flowsRe-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
--jsonOutput 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