sqlite-graph-mcp
# sqlite-graph-mcp
[](https://github.com/developjik/sqlite-graph-mcp/actions/workflows/ci.yml)
**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 sqlite-graph-mcp index
npx -y 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 kind | Source | Example key |
| --- | --- | --- |
| `file` | `.ts .tsx .js .jsx .mts .cts .mjs .cjs .md .mdx .markdown package.json` | `file:src/index.ts` |
| `symbol` | top-level `function` / `class` / `const|let|var` / `interface` / `type` / `enum` | `symbol:src/graph/walker.ts#walkGraph` |
| `heading` | Markdown `#` headings, GitHub-style slugs | `heading:docs/spec.md#usage` |
| `package` | `package.json` name + dependencies, plus bare imports | `package:left-pad` |
| Edge type | Meaning |
| --- | --- |
| `imports` | file → file (static `import`, `export … from`, `require`, dynamic `import()`) |
| `exports` | file → symbol (declaration is exported) |
| `defines` | file → symbol, file → heading, `package.json` → its package |
| `links_to` | Markdown link/reference → file or heading, including `#anchors` |
| `depends_on` | file → package, package → dependency from the manifest |
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.
## Install
Requires Node.js **20+** (tested on 20 and 22). `better-sqlite3` ships prebuilt binaries.
```bash
# run without installing
npx -y sqlite-graph-mcp --help
# or install globally
npm install -g sqlite-graph-mcp
# or as a dependency
npm install 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
```bash
claude mcp add sqlite-graph -- npx -y sqlite-graph-mcp serve --root /absolute/path/to/repo
```
### Cursor (`~/.cursor/mcp.json`)
```json
{
"mcpServers": {
"sqlite-graph": {
"command": "npx",
"args": ["-y", "sqlite-graph-mcp", "serve", "--root", "/absolute/path/to/repo"]
}
}
}
```
### Codex (`~/.codex/config.toml`)
```toml
[mcp_servers.sqlite-graph]
command = "npx"
args = ["-y", "sqlite-graph-mcp", "serve", "--root", "/absolute/path/to/repo"]
```
### Claude Desktop (`claude_desktop_config.json`)
```json
{
"mcpServers": {
"sqlite-graph": {
"command": "npx",
"args": ["-y", "sqlite-graph-mcp", "serve", "--root", "/absolute/path/to/repo"]
}
}
}
```
From a local clone (no registry needed):
```json
{
"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
| Operator | Tool | Question it answers |
| --- | --- | --- |
| `find` | `graph_find` | "Where is `walkGraph` defined?" |
| `walk` | `graph_walk` | "What does this file import, transitively?" |
| `filter` | `graph_filter` | "Of these nodes, which are docs under `docs/`?" |
| `minus` | `graph_orphans` (set difference) | "Which files are never imported or linked?" |
| `answer` | `graph_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.
```jsonc
// 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`.
```sql
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;
```
```jsonc
// 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.
### `graph_filter`
```jsonc
// 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.
```jsonc
{
"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):
```json
{
"steps": [
{ "op": "find", "query": "walker", "kind": "symbol" },
{ "op": "walk", "edgeType": "defines", "direction": "in", "maxDepth": 1 },
{ "op": "filter", "predicate": { "kind": "file" } }
],
"limit": 50
}
```
Response (trimmed):
```jsonc
{
"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:
| Step | Options |
| --- | --- |
| `find <query>` | `kind=file,symbol`, `limit=20`; `*` lists all, `*.ts` is a glob |
| `walk` | `type=imports,links_to`, `dir=out|in|both`, `depth=6`, `start=<id>,<key>`, `limit=` |
| `filter` | `kind=`, `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:
```bash
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 a heuristic indexer matters more than a longer feature list:
- **No AST.** Imports, exports and declarations are extracted with comment-masked regular
expressions, not a TypeScript parser. Multi-line declarations are handled; exotic syntax and
computed export names are not.
- **No cross-file symbol references.** There is no `references` edge yet, so `walk` from a symbol
reaches its file and package, not every call site.
- **No type resolution.** Path aliases (`@/…`, `tsconfig` `paths`) are not resolved; only relative
specifiers and workspace files.
- **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
```bash
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/db.ts schema, FTS5 index, GraphStore (prepared statements)
src/indexer.ts workspace scan, comment masking, symbol/import/heading extraction
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), 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.
## License
MIT © 2026 Inkwon Jung ([@developjik](https://github.com/developjik))
TDQS
Scored across 6 tools
Each tool maps to a distinct operator: index (build), find (text search), filter (narrow node set), walk (traverse edges), orphans (dead-code minus), plan (composed pipeline). The only real overlap is graph_plan versus manually chaining find/walk/filter, and find versus filter could be briefly confused by an agent, but the descriptions clearly delineate text search from explicit-set narrowing.
All six tools use a uniform graph_<verb-or-operator> pattern (graph_index, graph_find, graph_filter, graph_walk, graph_orphans, graph_plan) in consistent snake_case. The naming even encodes the relational-operator metaphor, making the set predictable.
Six tools is a tight, well-scoped surface for a code-graph indexer, with no filler. Each tool corresponds to a genuinely distinct operation (build, search, filter, traverse, dead-code, compose) and the composition tool justifies the small count without bloating it.
The set covers the full query lifecycle: build the graph, search, narrow, traverse dependencies/dependents, detect orphans, and compose multi-step evidence pipelines with citations. Minor gaps exist—no tool to fetch full node details/file contents, no index stats or schema/health inspection, and no incremental update or teardown—but these are workable around a full rebuild.