Shreg compiler

A local-first compiler that takes an Obsidian (or other Markdown-based) knowledge graph and compiles it into a queryable MCP server.

What it does

1. Parses a vault's Markdown files, frontmatter, and [[wikilinks]] into a graph of nodes and edges.
2. Analyzes the graph's structure — hub concepts, bridge nodes, clusters — and the reasoning patterns that recur across it.
3. Compiles the result into a runnable MCP server, so any connected AI agent (Claude Code, Cursor, etc.) can query the graph directly instead of re-reading raw notes.

Status

Early development, but the full pipeline works end to end: parsing a vault into a graph, storing it in SQLite, computing structural metrics, generating a graph profile with concrete usage scenarios, running a with/without evaluation harness that scores whether the graph actually helps, and serving the compiled graph as a live MCP server any external agent can connect to.

Usage

Requires Node 20+ and an ANTHROPIC_API_KEY environment variable for the profile and evaluate commands (compile and serve need neither).

npm install

# 1. Parse a vault into a graph
npm run cli -- compile <path-to-vault> <output.sqlite>

# 2. Generate a tool-facing description + concrete usage scenarios
npm run cli -- profile <output.sqlite> [scenario-count=5]

# 3. Run each scenario through a baseline agent (no tools) and a
#    graph-augmented agent (search_concepts/get_node/get_related tools),
#    judge both, and write an HTML comparison report
npm run cli -- evaluate <output.sqlite> <report.html>

# 4. Serve the compiled graph as a live MCP server over stdio
npm run cli -- serve <output.sqlite>

compile parses every Markdown file, resolves [[wikilinks]] (including [[Target|alias]] and [[Target#heading|alias]]), and computes in/out degree plus connected-component clustering for every node.

profile summarizes the graph's hub nodes and asks an LLM for (a) a description of what the graph is useful for — this becomes the MCP server's instructions, read by any connecting agent — and (b) concrete, general-purpose example questions (not trivia about one specific node) where having the graph should change the answer.

evaluate reuses those example questions as the eval set: each one is answered once with no context (baseline) and once by an agent that can call search_concepts, get_node, and get_related against the compiled graph, then a third LLM call judges both answers on groundedness, framework-consistency, and specificity, plus picks an overall winner. The output is a self-contained HTML report with a two-column comparison per question.

serve exposes the compiled graph as a real MCP server over stdio — search_concepts, get_node, and get_related become tools any MCP client can call directly. It's generic over the tool set (adding a tool later is a change in one file, src/llm/graphTools.ts, not in the server), and every response path is defensive: an unknown tool name, a missing/invalid argument, or an unexpected error all come back as a normal isError result instead of throwing — so one bad call from a client can never crash the server or hang the connection.

Connecting an agent to serve

Point your MCP client at the compiled CLI with serve and the database path as arguments. For Claude Code, Claude Desktop, or Cursor, add this to their MCP config file:

{
  "mcpServers": {
    "shreg-graph": {
      "command": "node",
      "args": ["--import", "tsx/esm", "/absolute/path/to/compiler/src/cli.ts", "serve", "/absolute/path/to/your-graph.sqlite"]
    }
  }
}

(Once npm run build is set up in your deployment, swap that for ["dist/cli.js", "serve", "..."] and drop --import tsx/esm.) Restart the client after editing its config — most MCP clients only read this file on startup.

Development

npm test        # run the test suite
npm run typecheck
npm run build   # compile to dist/

License

Functional Source License, Version 1.1, ALv2 Future License. Free for internal use, education, and research; converts to Apache 2.0 two years after each release. See fsl.software for a plain-language explanation.