Repository avatar
Databases
v0.3.0
active

sqlite-graph-mcp

io.github.developjik/sqlite-graph-mcp

Zero-embedding code & spec graph over SQLite with file:line citations for every answer.

Documentation

sqlite-graph-mcp

한국어 문서: README.ko.md · English documentation

A code & spec graph your AI agent can actually cite — no embeddings, no Docker, no Neo4j, no API key. One SQLite file, five operators, file:line evidence for every answer.

npx -y @developjik/sqlite-graph-mcp index
npx -y @developjik/sqlite-graph-mcp plan 'find "walker" kind=symbol | walk type=defines dir=in depth=1 | filter kind=file'
# → src/graph/walker.ts:1

Most "code graph" tools ask you to run an embedding pipeline, push your source to a vector database, and then return semantically similar chunks you still have to verify. This one builds a small, deterministic graph in a local SQLite file during index, and answers structural questions with recursive CTEs. When the agent says "this file defines walkGraph, and index.ts imports it", the claim comes with a path and a line number.


Why a graph in SQLite

  • Deterministic. The same workspace produces the same graph. Nothing depends on a model, a chunking strategy, or a similarity threshold.
  • Zero infrastructure. node:sqlite-class storage via better-sqlite3, one file at .sqlite-graph/index.db, .gitignore-friendly. No daemon, no container, no account.
  • Fast enough to re-index on every commit. A few thousand files index in well under a second.
  • Auditable. Every node is a row, every edge is a row. You can open the database with sqlite3 and check the agent's reasoning yourself.
  • Citations by construction. Nodes carry path and line; edges carry the line of the import/definition/link that created them.

What it indexes

Node kindSourceExample key
file.ts .tsx .js .jsx .mts .cts .mjs .cjs .md .mdx .markdown package.jsonfile:src/index.ts
symboltop-level function / class / `constlet
headingMarkdown # headings, GitHub-style slugsheading:docs/spec.md#usage
packagepackage.json name + dependencies, plus bare importspackage:left-pad
Edge typeMeaning
importsfile → file (static import, export … from, require, dynamic import()), including tsconfig paths aliases and workspace-local package entries
exportsfile → symbol (declaration is exported)
definesfile → symbol, file → heading, package.json → its package
links_toMarkdown link/reference → file or heading, including #anchors
depends_onfile → package, package → dependency from the manifest
referencesfile → symbol: the file actually uses that symbol (named/default/namespace/require bindings; unused imports produce no edge)

Files are tagged (code, ts, doc, test, entry, manifest, exported, …), and tags are filterable — that is how graph_orphans can skip test and entry files without extra arguments.

Extraction engines

The default ast engine parses TypeScript/TSX (and plain JS) with tree-sitter WASM grammars vendored in the package — no native build, no network. Imports, symbols and exports come from the parse tree, and references edges cite the first line where an imported binding is actually used. If the WASM files cannot load, indexing falls back to the heuristic engine (comment-masked regexes, import-clause-based references). Force it explicitly with graph_index { engine: "heuristic" } or --engine heuristic; the index report says which engine ran (engine: "ast").

Install

The package is published as @developjik/sqlite-graph-mcp (the unscoped name on npm is an unrelated project, so always use the scope). Requires Node.js 20+ (tested on 20 and 22); better-sqlite3 ships prebuilt binaries. After installing, the binary is sqlite-graph-mcp (or the alias sqlite-graph).

# run without installing
npx -y @developjik/sqlite-graph-mcp --help

# or install globally
npm install -g @developjik/sqlite-graph-mcp

# or as a dependency
npm install @developjik/sqlite-graph-mcp

MCP setup

The server speaks MCP over stdio. --root is the workspace to index; it defaults to the process's current directory, which is usually what an MCP client gives you.

Claude Code

claude mcp add sqlite-graph -- npx -y @developjik/sqlite-graph-mcp serve --root /absolute/path/to/repo

Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "sqlite-graph": {
      "command": "npx",
      "args": ["-y", "@developjik/sqlite-graph-mcp", "serve", "--root", "/absolute/path/to/repo"]
    }
  }
}

Codex (~/.codex/config.toml)

[mcp_servers.sqlite-graph]
command = "npx"
args = ["-y", "@developjik/sqlite-graph-mcp", "serve", "--root", "/absolute/path/to/repo"]

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "sqlite-graph": {
      "command": "npx",
      "args": ["-y", "@developjik/sqlite-graph-mcp", "serve", "--root", "/absolute/path/to/repo"]
    }
  }
}

From a local clone (no registry needed):

{
  "mcpServers": {
    "sqlite-graph": {
      "command": "node",
      "args": ["/absolute/path/to/sqlite-graph-mcp/dist/bin/cli.js", "serve", "--root", "/absolute/path/to/repo"]
    }
  }
}

The first tool call indexes the workspace automatically if .sqlite-graph/index.db is missing. Re-run graph_index after large refactors; it rebuilds the graph in one transaction.

The five operators

OperatorToolQuestion it answers
findgraph_find"Where is walkGraph defined?"
walkgraph_walk"What does this file import, transitively?"
filtergraph_filter"Of these nodes, which are docs under docs/?"
minusgraph_orphans (set difference)"Which files are never imported or linked?"
answergraph_plan"Chain the above and give me citations."

graph_find

FTS5 prefix ranking plus a substring/glob fallback, so index still finds GraphIndexer and *.test.ts works as a glob.

// graph_find { "query": "emoji", "kind": "symbol" }
{
  "count": 1,
  "nodes": [
    {
      "id": 12,
      "key": "symbol:src/greet.ts#greetEmoji",
      "kind": "symbol",
      "name": "greetEmoji",
      "citation": "src/greet.ts:5",
      "snippet": "export const greetEmoji = '👋';",
      "tags": ["symbol", "exported", "variable"]
    }
  ]
}

graph_walk

Traversal is a recursive CTE over edges. Cycle protection is path-based: a branch stops when the next id already appears in the path it travelled, so a → b → a terminates at depth 1 even with maxDepth=20.

WITH RECURSIVE walk(id, depth, path) AS (
  SELECT id, 0, ',' || id || ',' FROM nodes WHERE id IN (?, ?)
  UNION ALL
  SELECT e.dst, w.depth + 1, w.path || e.dst || ','
  FROM walk w
  JOIN edges e ON e.src = w.id
  WHERE w.depth < :maxDepth
    AND instr(w.path, ',' || e.dst || ',') = 0
    AND e.type IN ('imports', 'links_to')
)
SELECT id, MIN(depth) AS depth FROM walk GROUP BY id ORDER BY depth, id;
// graph_walk { "start": ["file:src/index.ts"], "edgeType": "imports", "direction": "out" }
{
  "count": 5,
  "nodes": [
    { "key": "file:src/index.ts",              "depth": 0, "citation": "src/index.ts:1" },
    { "key": "file:src/greet.ts",              "depth": 1, "citation": "src/greet.ts:1" },
    { "key": "file:src/graph/walker.ts",       "depth": 1, "citation": "src/graph/walker.ts:1" },
    { "key": "file:src/graph/cycle-a.ts",      "depth": 2, "citation": "src/graph/cycle-a.ts:1" },
    { "key": "file:src/graph/cycle-b.ts",      "depth": 3, "citation": "src/graph/cycle-b.ts:1" }
  ]
}

Direction in finds dependents ("who breaks if I rename this?"), both finds the neighbourhood. references edges make the rename question concrete — walk them inbound from a symbol to list every file that actually uses it (citations point at usage lines):

// graph_walk { "start": ["symbol:src/graph/walker.ts#walkGraph"], "edgeType": "references", "direction": "in" }
{
  "count": 3,
  "nodes": [
    { "key": "symbol:src/graph/walker.ts#walkGraph", "depth": 0, "citation": "src/graph/walker.ts:7" },
    { "key": "file:src/index.ts",                    "depth": 1, "citation": "src/index.ts:9" },
    { "key": "file:src/graph/walker.test.ts",        "depth": 1, "citation": "src/graph/walker.test.ts:6" }
  ]
}

graph_filter

// graph_filter { "ids": [12, 20, 21], "kind": "symbol", "prefix": "src/graph/", "tag": "exported" }
{ "count": 2, "nodes": [ /* WalkOptions, walkGraph */ ] }

Predicates: kind, notKind, path (glob), prefix, suffix, name, regex, tag, limit.

graph_orphans

Set difference in one query: files with no inbound imports/links_to edge, and symbols that are never exported. Test and entry files are excluded unless you ask for them.

{
  "files":   [{ "path": "src/legacy.ts", "citation": "src/legacy.ts:1" }],
  "symbols": [{ "name": "unusedHelper", "citation": "src/index.ts:13" }],
  "counts":  { "files": 1, "symbols": 2 }
}

graph_plan — chain them

A plan is a pipeline. Each step consumes the previous step's node set; find starts a new set.

find "walker" kind=symbol | walk type=defines dir=in depth=1 | filter kind=file

The same plan as JSON (what an LLM or a script would send):

{
  "steps": [
    { "op": "find", "query": "walker", "kind": "symbol" },
    { "op": "walk", "edgeType": "defines", "direction": "in", "maxDepth": 1 },
    { "op": "filter", "predicate": { "kind": "file" } }
  ],
  "limit": 50
}

Response (trimmed):

{
  "count": 1,
  "nodes": [{ "key": "file:src/graph/walker.ts", "citation": "src/graph/walker.ts:1", "depth": 1 }],
  "edges": [{ "src": 20, "dst": 22, "type": "defines", "citation": "src/graph/walker.ts:7" }],
  "citations": ["src/graph/walker.ts:1"],
  "steps": [
    { "index": 0, "op": "find",   "inputCount": 0, "outputCount": 1 },
    { "index": 1, "op": "walk",   "inputCount": 1, "outputCount": 2 },
    { "index": 2, "op": "filter", "inputCount": 2, "outputCount": 1 }
  ],
  "explain": [
    "find(\"walker\", kind=symbol) → 1 nodes",
    "walk(from 1, in, defines, depth=1) → 2 nodes",
    "filter({\"kind\":\"file\"}) 2 → 1 nodes"
  ],
  "truncated": false
}

Pipeline syntax:

StepOptions
find <query>kind=file,symbol, limit=20; * lists all, *.ts is a glob
walktype=imports,links_to,references, `dir=out
filterkind=, notKind=, path=src/**, prefix=, suffix=, name=, regex=, tag=, limit=
minus find <query>subtract another find from the current set

CLI

The same engine is usable without an MCP client:

sqlite-graph-mcp index [dir]                 # build/rebuild the graph
sqlite-graph-mcp find "walkGraph" --kind symbol
sqlite-graph-mcp walk <id|key> --type imports --dir out --depth 3
sqlite-graph-mcp plan 'find "graph" | walk type=imports depth=2'
sqlite-graph-mcp orphans --include-tests
sqlite-graph-mcp serve --root . --db .sqlite-graph/index.db

Every command accepts --json; find exits 1 when nothing matches, which makes it usable in shell conditions.

What it does not do (yet)

Being honest about the limits matters more than a longer feature list:

  • No full scope analysis. The default tree-sitter engine tracks imported bindings and their identifier usages, but it does not model scopes: a local that shadows an imported name can still count as a usage, and JSX identifiers are not matched. The heuristic fallback engine only sees import clauses ("who imports this symbol?", never "who calls it?").
  • Type resolution is partial. tsconfig/jsconfig paths + baseUrl (local extends chains) and workspace-local packages (main/module/index) resolve to real files; the package.json exports field, bundler-config aliases (vite/webpack), #-prefixed package-internal imports and tsconfigs in nested workspaces do not.
  • Unchanged files are re-parsed. Re-indexing is a full atomic rebuild (fast, but not incremental).
  • Local scope only. node_modules, dist, build, .git and friends are skipped, as are files over 512 KiB and workspaces over 5,000 files (both configurable in graph_index).

Development

npm install
npm run typecheck   # tsc --noEmit, tests included
npm test            # builds, then runs unit + stdio MCP integration tests
npm run build       # tsc → dist/

Layout:

bin/cli.ts        CLI entry (shebang, subcommands, JSON output)
src/ast.ts        tree-sitter (WASM) engine: parse-tree imports/symbols, binding usage
src/db.ts         schema, FTS5 index, GraphStore (prepared statements)
src/indexer.ts    workspace scan, comment masking, symbol/import/heading extraction, tsconfig paths, workspace packages
src/query.ts      find / walk / filter / minus / orphans over SQLite
src/plan.ts       pipeline DSL parser + answer executor with citations
src/mcp.ts        MCP server and six tools
test/             fixtures, unit tests, stdio MCP protocol tests

The test suite covers indexer counts and idempotency, extension remapping (.js import → .ts source), usage-based references (alias/default/namespace bindings, unused imports produce no edge, synthetic default exports), both engines, tsconfig paths aliases and workspace-local packages (see test/fixtures/mono), schema-version migration, cycle-safe traversal, every operator, the plan DSL, orphan detection, the CLI, and the MCP handshake both through the official SDK client and as raw newline-delimited JSON-RPC. Refresh the vendored grammars after bumping tree-sitter-wasms with npm run vendor:wasm.

License

MIT © 2026 Inkwon Jung (@developjik)

NPM
@developjik/sqlite-graph-mcp
Install Command
npm install @developjik/sqlite-graph-mcp