# Shreg compiler

A local-first compiler that takes an Obsidian (or other Markdown-based) knowledge graph and compiles it into a queryable [MCP](https://modelcontextprotocol.io) 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).

```sh
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:

```json
{
  "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

```sh
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](./LICENSE.md). Free for internal use, education, and research; converts to Apache 2.0 two years after each release. See [fsl.software](https://fsl.software) for a plain-language explanation.