Skip to content
Back to search

sqlite-graph-mcp

Zero-embedding local code & spec graph MCP server powered by SQLite recursive CTEs and 5-operator query planning.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/developjik--sqlite-graph-mcp/badge.svg)](/listings/developjik--sqlite-graph-mcp)

HTML

<a href="/listings/developjik--sqlite-graph-mcp"><img src="/api/listings/developjik--sqlite-graph-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 404 lines
  1. # sqlite-graph-mcp
  2. **한국어 문서: [README.ko.md](README.ko.md)** · English documentation
  3. **A code & spec graph your AI agent can actually cite** — no embeddings, no Docker, no Neo4j, no API key.
  4. One SQLite file, five operators, `file:line` evidence for every answer.
  5. ```
  6. npx -y @developjik/sqlite-graph-mcp index
  7. npx -y @developjik/sqlite-graph-mcp plan 'find "walker" kind=symbol | walk type=defines dir=in depth=1 | filter kind=file'
  8. # → src/graph/walker.ts:1
  9. ```
  10. Most "code graph" tools ask you to run an embedding pipeline, push your source to a vector
  11. database, and then return semantically similar chunks you still have to verify. This one builds a
  12. small, deterministic graph in a local SQLite file during `index`, and answers structural questions
  13. with recursive CTEs. When the agent says "this file defines `walkGraph`, and `index.ts` imports
  14. it", the claim comes with a path and a line number.
  15. ---
  16. ## Why a graph in SQLite
  17. - **Deterministic.** The same workspace produces the same graph. Nothing depends on a model,
  18. a chunking strategy, or a similarity threshold.
  19. - **Zero infrastructure.** `node:sqlite`-class storage via `better-sqlite3`, one file at
  20. `.sqlite-graph/index.db`, `.gitignore`-friendly. No daemon, no container, no account.
  21. - **Fast enough to re-index on every commit.** A few thousand files index in well under a second.
  22. - **Auditable.** Every node is a row, every edge is a row. You can open the database with
  23. `sqlite3` and check the agent's reasoning yourself.
  24. - **Citations by construction.** Nodes carry `path` and `line`; edges carry the line of the
  25. import/definition/link that created them.
  26. ## What it indexes
  27. | Node kind | Source | Example key |
  28. | --- | --- | --- |
  29. | `file` | `.ts .tsx .js .jsx .mts .cts .mjs .cjs .md .mdx .markdown package.json` | `file:src/index.ts` |
  30. | `symbol` | top-level `function` / `class` / `const|let|var` / `interface` / `type` / `enum` | `symbol:src/graph/walker.ts#walkGraph` |
  31. | `heading` | Markdown `#` headings, GitHub-style slugs | `heading:docs/spec.md#usage` |
  32. | `package` | `package.json` name + dependencies, plus bare imports | `package:left-pad` |
  33. | Edge type | Meaning |
  34. | --- | --- |
  35. | `imports` | file → file (static `import`, `export … from`, `require`, dynamic `import()`), including tsconfig `paths` aliases and workspace-local package entries |
  36. | `exports` | file → symbol (declaration is exported) |
  37. | `defines` | file → symbol, file → heading, `package.json` → its package |
  38. | `links_to` | Markdown link/reference → file or heading, including `#anchors` |
  39. | `depends_on` | file → package, package → dependency from the manifest |
  40. | `references` | file → symbol: the file actually uses that symbol (named/default/namespace/`require` bindings; an imported-but-unused binding cites the import line) |
  41. Files are tagged (`code`, `ts`, `doc`, `test`, `entry`, `manifest`, `exported`, …), and tags are
  42. filterable — that is how `graph_orphans` can skip test and entry files without extra arguments.
  43. ### Extraction engines
  44. The default **`ast` engine** parses TypeScript/TSX (and plain JS) with
  45. tree-sitter WASM grammars vendored in the package — no native build, no
  46. network. Imports, symbols and exports come from the parse tree, and
  47. `references` edges cite the first line where an imported binding is actually
  48. used; an imported-but-unused binding cites the import line, because the clause
  49. itself is a rename-sensitive mention. If the WASM files cannot load, indexing falls back to the
  50. **`heuristic` engine** (comment-masked regexes, import-clause-based
  51. references). Force it explicitly with `graph_index { engine: "heuristic" }` or
  52. `--engine heuristic`; the index report says which engine ran (`engine: "ast"`).
  53. ## Install
  54. The package is published as **`@developjik/sqlite-graph-mcp`** (the unscoped name on npm is an
  55. unrelated project, so always use the scope). Requires Node.js **20+** (tested on 20 and 22);
  56. `better-sqlite3` ships prebuilt binaries. After installing, the binary is `sqlite-graph-mcp`
  57. (or the alias `sqlite-graph`).
  58. ```bash
  59. # run without installing
  60. npx -y @developjik/sqlite-graph-mcp --help
  61. # or install globally
  62. npm install -g @developjik/sqlite-graph-mcp
  63. # or as a dependency
  64. npm install @developjik/sqlite-graph-mcp
  65. ```
  66. ## MCP setup
  67. The server speaks MCP over stdio. `--root` is the workspace to index; it defaults to the
  68. process's current directory, which is usually what an MCP client gives you.
  69. ### Claude Code
  70. ```bash
  71. claude mcp add sqlite-graph -- npx -y @developjik/sqlite-graph-mcp serve --root /absolute/path/to/repo
  72. ```
  73. ### Cursor (`~/.cursor/mcp.json`)
  74. ```json
  75. {
  76. "mcpServers": {
  77. "sqlite-graph": {
  78. "command": "npx",
  79. "args": ["-y", "@developjik/sqlite-graph-mcp", "serve", "--root", "/absolute/path/to/repo"]
  80. }
  81. }
  82. }
  83. ```
  84. ### Codex (`~/.codex/config.toml`)
  85. ```toml
  86. [mcp_servers.sqlite-graph]
  87. command = "npx"
  88. args = ["-y", "@developjik/sqlite-graph-mcp", "serve", "--root", "/absolute/path/to/repo"]
  89. ```
  90. ### Claude Desktop (`claude_desktop_config.json`)
  91. ```json
  92. {
  93. "mcpServers": {
  94. "sqlite-graph": {
  95. "command": "npx",
  96. "args": ["-y", "@developjik/sqlite-graph-mcp", "serve", "--root", "/absolute/path/to/repo"]
  97. }
  98. }
  99. }
  100. ```
  101. From a local clone (no registry needed):
  102. ```json
  103. {
  104. "mcpServers": {
  105. "sqlite-graph": {
  106. "command": "node",
  107. "args": ["/absolute/path/to/sqlite-graph-mcp/dist/bin/cli.js", "serve", "--root", "/absolute/path/to/repo"]
  108. }
  109. }
  110. }
  111. ```
  112. The first tool call indexes the workspace automatically if `.sqlite-graph/index.db` is missing.
  113. Re-run `graph_index` after large refactors; it rebuilds the graph in one transaction.
  114. ## The five operators
  115. | Operator | Tool | Question it answers |
  116. | --- | --- | --- |
  117. | `find` | `graph_find` | "Where is `walkGraph` defined?" |
  118. | `walk` | `graph_walk` | "What does this file import, transitively?" |
  119. | `filter` | `graph_filter` | "Of these nodes, which are docs under `docs/`?" |
  120. | `minus` | `graph_orphans` (set difference) | "Which files are never imported or linked?" |
  121. | `answer` | `graph_plan` | "Chain the above and give me citations." |
  122. ### `graph_find`
  123. FTS5 prefix ranking plus a substring/glob fallback, so `index` still finds `GraphIndexer` and
  124. `*.test.ts` works as a glob.
  125. ```jsonc
  126. // graph_find { "query": "emoji", "kind": "symbol" }
  127. {
  128. "count": 1,
  129. "nodes": [
  130. {
  131. "id": 12,
  132. "key": "symbol:src/greet.ts#greetEmoji",
  133. "kind": "symbol",
  134. "name": "greetEmoji",
  135. "citation": "src/greet.ts:5",
  136. "snippet": "export const greetEmoji = '👋';",
  137. "tags": ["symbol", "exported", "variable"]
  138. }
  139. ]
  140. }
  141. ```
  142. ### `graph_walk`
  143. Traversal is a recursive CTE over `edges`. Cycle protection is path-based: a branch stops when
  144. the next id already appears in the path it travelled, so `a → b → a` terminates at depth 1 even
  145. with `maxDepth=20`.
  146. ```sql
  147. WITH RECURSIVE walk(id, depth, path) AS (
  148. SELECT id, 0, ',' || id || ',' FROM nodes WHERE id IN (?, ?)
  149. UNION ALL
  150. SELECT e.dst, w.depth + 1, w.path || e.dst || ','
  151. FROM walk w
  152. JOIN edges e ON e.src = w.id
  153. WHERE w.depth < :maxDepth
  154. AND instr(w.path, ',' || e.dst || ',') = 0
  155. AND e.type IN ('imports', 'links_to')
  156. )
  157. SELECT id, MIN(depth) AS depth FROM walk GROUP BY id ORDER BY depth, id;
  158. ```
  159. ```jsonc
  160. // graph_walk { "start": ["file:src/index.ts"], "edgeType": "imports", "direction": "out" }
  161. {
  162. "count": 5,
  163. "nodes": [
  164. { "key": "file:src/index.ts", "depth": 0, "citation": "src/index.ts:1" },
  165. { "key": "file:src/greet.ts", "depth": 1, "citation": "src/greet.ts:1" },
  166. { "key": "file:src/graph/walker.ts", "depth": 1, "citation": "src/graph/walker.ts:1" },
  167. { "key": "file:src/graph/cycle-a.ts", "depth": 2, "citation": "src/graph/cycle-a.ts:1" },
  168. { "key": "file:src/graph/cycle-b.ts", "depth": 3, "citation": "src/graph/cycle-b.ts:1" }
  169. ]
  170. }
  171. ```
  172. Direction `in` finds dependents ("who breaks if I rename this?"), `both` finds the neighbourhood.
  173. `references` edges make the rename question concrete — walk them inbound from a symbol to list
  174. every file that actually uses it (citations point at usage lines):
  175. ```jsonc
  176. // graph_walk { "start": ["symbol:src/graph/walker.ts#walkGraph"], "edgeType": "references", "direction": "in" }
  177. {
  178. "count": 3,
  179. "nodes": [
  180. { "key": "symbol:src/graph/walker.ts#walkGraph", "depth": 0, "citation": "src/graph/walker.ts:7" },
  181. { "key": "file:src/index.ts", "depth": 1, "citation": "src/index.ts:9" },
  182. { "key": "file:src/graph/walker.test.ts", "depth": 1, "citation": "src/graph/walker.test.ts:6" }
  183. ]
  184. }
  185. ```
  186. ### `graph_filter`
  187. ```jsonc
  188. // graph_filter { "ids": [12, 20, 21], "kind": "symbol", "prefix": "src/graph/", "tag": "exported" }
  189. { "count": 2, "nodes": [ /* WalkOptions, walkGraph */ ] }
  190. ```
  191. Predicates: `kind`, `notKind`, `path` (glob), `prefix`, `suffix`, `name`, `regex`, `tag`, `limit`.
  192. ### `graph_orphans`
  193. Set difference in one query: files with no inbound `imports`/`links_to` edge, and symbols that
  194. are never exported. Test and entry files are excluded unless you ask for them.
  195. ```jsonc
  196. {
  197. "files": [{ "path": "src/legacy.ts", "citation": "src/legacy.ts:1" }],
  198. "symbols": [{ "name": "unusedHelper", "citation": "src/index.ts:13" }],
  199. "counts": { "files": 1, "symbols": 2 }
  200. }
  201. ```
  202. ### `graph_diff` — what breaks if we ship this?
  203. Indexes two workspace states and compares the graphs. Each side is a git revision
  204. (branch, tag, SHA — verified with `git rev-parse`, no shell) or a plain directory:
  205. ```jsonc
  206. // graph_diff { "base": "main", "head": "HEAD" }
  207. {
  208. "counts": { "addedNodes": 14, "removedNodes": 3, "addedEdges": 41, "removedEdges": 9,
  209. "breaking": 1, "newOrphans": 1 },
  210. "breaking": [
  211. {
  212. "symbol": { "key": "symbol:src/graph/walker.ts#walkGraph", "citation": "src/graph/walker.ts:7" },
  213. "unexportedOnly": true,
  214. "importers": [
  215. { "key": "file:src/index.ts", "citation": "src/index.ts:9" },
  216. { "key": "file:src/graph/walker.test.ts", "citation": "src/graph/walker.test.ts:6" }
  217. ]
  218. }
  219. ],
  220. "newOrphans": [{ "key": "file:src/legacy.ts", "citation": "src/legacy.ts:1" }],
  221. "truncated": false
  222. }
  223. ```
  224. **breaking** lists every symbol the head no longer exports (removed or un-exported)
  225. while base-side files were still using it, with the importer citations — the
  226. mechanical answer to "is this PR safe to merge?". **newOrphans** lists files
  227. that kept existing but lost their last inbound `imports`/`links_to` edge.
  228. The CLI form doubles as a review gate:
  229. ```bash
  230. sqlite-graph-mcp diff main HEAD --check # exit 3 when a breaking change is found
  231. ```
  232. ### `graph_plan` — chain them
  233. A plan is a pipeline. Each step consumes the previous step's node set; `find` starts a new set.
  234. ```
  235. find "walker" kind=symbol | walk type=defines dir=in depth=1 | filter kind=file
  236. ```
  237. The same plan as JSON (what an LLM or a script would send):
  238. ```json
  239. {
  240. "steps": [
  241. { "op": "find", "query": "walker", "kind": "symbol" },
  242. { "op": "walk", "edgeType": "defines", "direction": "in", "maxDepth": 1 },
  243. { "op": "filter", "predicate": { "kind": "file" } }
  244. ],
  245. "limit": 50
  246. }
  247. ```
  248. Response (trimmed):
  249. ```jsonc
  250. {
  251. "count": 1,
  252. "nodes": [{ "key": "file:src/graph/walker.ts", "citation": "src/graph/walker.ts:1", "depth": 1 }],
  253. "edges": [{ "src": 20, "dst": 22, "type": "defines", "citation": "src/graph/walker.ts:7" }],
  254. "citations": ["src/graph/walker.ts:1"],
  255. "steps": [
  256. { "index": 0, "op": "find", "inputCount": 0, "outputCount": 1 },
  257. { "index": 1, "op": "walk", "inputCount": 1, "outputCount": 2 },
  258. { "index": 2, "op": "filter", "inputCount": 2, "outputCount": 1 }
  259. ],
  260. "explain": [
  261. "find(\"walker\", kind=symbol) → 1 nodes",
  262. "walk(from 1, in, defines, depth=1) → 2 nodes",
  263. "filter({\"kind\":\"file\"}) 2 → 1 nodes"
  264. ],
  265. "truncated": false
  266. }
  267. ```
  268. Pipeline syntax:
  269. | Step | Options |
  270. | --- | --- |
  271. | `find <query>` | `kind=file,symbol`, `limit=20`; `*` lists all, `*.ts` is a glob |
  272. | `walk` | `type=imports,links_to,references`, `dir=out|in|both`, `depth=6`, `start=<id>,<key>`, `limit=` |
  273. | `filter` | `kind=`, `notKind=`, `path=src/**`, `prefix=`, `suffix=`, `name=`, `regex=`, `tag=`, `limit=` |
  274. | `minus find <query>` | subtract another find from the current set |
  275. ## CLI
  276. The same engine is usable without an MCP client:
  277. ```bash
  278. sqlite-graph-mcp index [dir] # build/rebuild the graph
  279. sqlite-graph-mcp find "walkGraph" --kind symbol
  280. sqlite-graph-mcp walk <id|key> --type imports --dir out --depth 3
  281. sqlite-graph-mcp plan 'find "graph" | walk type=imports depth=2'
  282. sqlite-graph-mcp orphans --include-tests
  283. sqlite-graph-mcp serve --root . --db .sqlite-graph/index.db
  284. ```
  285. Every command accepts `--json`; `find` exits `1` when nothing matches, which makes it usable in
  286. shell conditions.
  287. ## What it does not do (yet)
  288. Being honest about the limits matters more than a longer feature list:
  289. - **No full scope analysis.** The default tree-sitter engine tracks imported
  290. bindings and their identifier usages, but it does not model scopes: a local
  291. that shadows an imported name can still count as a usage, and JSX
  292. identifiers are not matched. The heuristic fallback engine only sees import
  293. clauses ("who imports this symbol?", never "who calls it?").
  294. - **Type resolution is partial.** tsconfig/jsconfig `paths` + `baseUrl` (local `extends` chains)
  295. and workspace-local packages (`main`/`module`/`index`) resolve to real files; the package.json
  296. `exports` field, bundler-config aliases (vite/webpack), `#`-prefixed package-internal imports
  297. and tsconfigs in nested workspaces do not.
  298. - **Unchanged files are re-parsed.** Re-indexing is a full atomic rebuild (fast, but not
  299. incremental).
  300. - **Local scope only.** `node_modules`, `dist`, `build`, `.git` and friends are skipped, as are
  301. files over 512 KiB and workspaces over 5,000 files (both configurable in `graph_index`).
  302. ## Development
  303. ```bash
  304. npm install
  305. npm run typecheck # tsc --noEmit, tests included
  306. npm test # builds, then runs unit + stdio MCP integration tests
  307. npm run build # tsc → dist/
  308. ```
  309. Layout:
  310. ```
  311. bin/cli.ts CLI entry (shebang, subcommands, JSON output)
  312. src/ast.ts tree-sitter (WASM) engine: parse-tree imports/symbols, binding usage
  313. src/db.ts schema, FTS5 index, GraphStore (prepared statements)
  314. src/indexer.ts workspace scan, comment masking, symbol/import/heading extraction, tsconfig paths, workspace packages
  315. src/query.ts find / walk / filter / minus / orphans over SQLite
  316. src/plan.ts pipeline DSL parser + answer executor with citations
  317. src/mcp.ts MCP server and six tools
  318. test/ fixtures, unit tests, stdio MCP protocol tests
  319. ```
  320. The test suite covers indexer counts and idempotency, extension remapping (`.js` import →
  321. `.ts` source), usage-based `references` (alias/default/namespace bindings, unused imports
  322. cited at the import line, synthetic default exports), both engines, tsconfig `paths` aliases and
  323. workspace-local packages (see `test/fixtures/mono`), schema-version migration, cycle-safe
  324. traversal, every operator, the plan DSL, orphan detection, the CLI, and the MCP handshake
  325. both through the official SDK client and as raw newline-delimited JSON-RPC. Refresh the
  326. vendored grammars after bumping `tree-sitter-wasms` with `npm run vendor:wasm`.
  327. ## License
  328. MIT © 2026 Inkwon Jung ([@developjik](https://github.com/developjik))

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.