grapulone

Local code knowledge graph + MCP server for AI coding assistants. Index your repo once; let agents query the structure (callers, callees, imports, dead code, cycles) instead of re-reading source on every turn.

• Languages: TypeScript / TSX, JavaScript / JSX (incl. CommonJS), Python, Rust.
• No cloud, no auth. Everything stays in <repo>/.grapulone/graph.db.
• 16 MCP tools for Claude Code, Cursor, or any MCP-compatible client.

Install

Requires Bun ≥ 1.1.

npm install -g grapulone
# or
bun add -g grapulone

Quick start

# Index any repo
grapulone index /path/to/your/repo

# Browse the graph in your browser
grapulone ui /path/to/your/repo

Plug into Claude Code

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "grapulone": {
      "command": "grapulone",
      "args": [
        "mcp",
        "--db", "/absolute/path/to/repo/.grapulone/graph.db",
        "--repo-root", "/absolute/path/to/repo"
      ]
    }
  }
}

Restart Claude Code. Run /mcp to confirm 16 tools are connected. For Cursor, the same block goes in ~/.cursor/mcp.json.

Pair with grapulone watch /path/to/repo in a side terminal to keep the index fresh as you edit.

What the agent gets

| Tool | Use when... | |------|-------------| | list_files | Need a directory overview | | find_symbol | Looking for a name across the project | | get_symbol_detail | Want full info on one symbol | | get_symbol_source | Need the actual source code of a symbol | | get_file_imports / get_file_importers / get_file_exports | File-level deps | | get_class_hierarchy | Tracing inheritance | | get_project_overview | Sanity-checking project size | | get_callers / get_callees | One-hop call edges | | get_call_chain | Recursive blast-radius walk N levels | | get_module_graph | Render IMPORTS as Mermaid/DOT | | find_dead_code | Exported symbols with no callers | | find_circular_deps | Cycles in IMPORTS or CALLS graph | | find_unused_imports | Imports where nothing is referenced |

All tools are read-only. The agent cannot modify your code.

Supported languages

| Language | Files | Cross-file edges | |-------------|------------------------------------|-------------------------------------------------------------| | TypeScript | .ts, .tsx | IMPORTS, EXPORTS, EXTENDS, IMPLEMENTS, CALLS, JSX usage | | JavaScript | .js, .jsx, .mjs, .cjs | ES modules + CommonJS (require, module.exports) | | Python | .py | IMPORTS, EXPORTS, EXTENDS, CALLS (incl. singletons) | | Rust | .rs | IMPORTS, EXPORTS, EXTENDS, CALLS (regex-based) |

Python adapter requires python (or py / python3) on PATH. Standard library only — no pip install.

CLI commands

grapulone index <path> [--force] [--include <subdir>]...  # one-time index
grapulone watch <path>           [--include <subdir>]...  # live re-index
grapulone query <path> <symbol-name>                      # debug search
grapulone ui <path> [--port N] [--no-open]                # browser UI
grapulone mcp --db <db-path> --repo-root <repo-path>      # MCP server (stdio)

Scoping the index to specific subfolders

Pass --include one or more times to limit indexing to a subset of the repo (useful for monorepos where you only want certain workspaces):

grapulone index ~/work/big-monorepo \
  --include packages/api \
  --include packages/web \
  --include shared

The DB still lives at <path>/.grapulone/graph.db, and the MCP server sees only the included files. Without --include, the entire repo is indexed (respecting .gitignore).

License

MIT. v0.5.4.