Skip to content

Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.

Add directory ingest, graph visualization, and MCP timeout fix

anirudhkumar-nanonets0c4c6ddbe46d
diff --git a/DEMO.md b/DEMO.md
index caf5c157..7c61818b 100644
--- a/DEMO.md
+++ b/DEMO.md
@@ -23,9 +23,10 @@ Think "durable, structured memory for a team of agents" — the same integration
| **Storage** (`src/graph/sqlite-store.ts`) | Embedded SQLite (`better-sqlite3`), zero infra; swappable behind a `GraphStore` interface | ✅ Done |
| **Local-first providers** (`src/ai/local.ts`) | In-process embeddings (transformers.js) + local extraction (Ollama) — **runs with no API keys** | ✅ Done |
| **Cloud auto-upgrade** (`src/engine.ts`) | If `OPENROUTER_API_KEY` is set, uses OpenRouter for extraction automatically (any tool-calling model) for higher quality | ✅ Done |
-| **PDF ingestion** (`src/ingest/pdf.ts`) | `.pdf` files parsed to text automatically (pure-JS `unpdf`, no native deps) — via CLI, library, or the `context_ingest_file` MCP tool | ✅ Done |
-| **Three access modes** | Library, `context-graph` CLI, and `context-graph-mcp` MCP server (5 tools) for any agent | ✅ Done |
-| **Demo PDFs** (`examples/demo-docs/`) | 3 detail-rich fictional docs + a generator script | ✅ Done |
+| **PDF + directory ingestion** (`src/ingest/pdf.ts`) | `.pdf` parsed automatically (pure-JS `unpdf`, no native deps); `ingest-dir` walks a folder of mixed docs (PDF/MD/TXT) | ✅ Done |
+| **Graph visualization** (`src/graph/export.ts`) | Export the whole graph to a self-contained interactive HTML page (also JSON / Mermaid) | ✅ Done |
+| **Three access modes** | Library, `context-graph` CLI, and `context-graph-mcp` MCP server (7 tools) for any agent | ✅ Done |
+| **Demo docs** (`examples/demo-docs/`) | 3 detail-rich PDFs + 1 Markdown glossary + a PDF generator script | ✅ Done |
| **One-line installer** (`install.sh`) | `curl … | sh` clones, builds, and puts both commands on PATH | ✅ Done |
| Update modes (silent vs. flagged) | Deferred per your call — needs discussion | ⏸ Deferred |
| Delete / decay of stale nodes | In the spec, not yet built | ⬜ Not started |
@@ -60,22 +61,30 @@ No accounts, nothing leaves the machine. Slightly coarser graph and a one-time m
## 4. The MCP demo (the main event)
-This is the flow to show: **install → point an MCP client at it → ingest PDFs → ask questions → the facts from the PDFs come back.** Verified end-to-end (OpenRouter extraction + local embeddings).
+This is the flow to show: **install → point Claude Code at a folder → "build a context graph" → Claude Code does it via MCP → open the visual graph → ask questions.** Verified end-to-end (OpenRouter extraction + local embeddings).
-There are 3 demo PDFs already generated in `examples/demo-docs/` (fictional "Northwind" company — architecture, billing runbook, onboarding). Regenerate them any time with `node scripts/make-demo-pdfs.mjs`.
+There are 4 demo docs already in `examples/demo-docs/` — a fictional "Northwind" company: 3 PDFs (architecture, billing runbook, onboarding) + 1 Markdown glossary. Regenerate the PDFs any time with `node scripts/make-demo-pdfs.mjs`.
+
+### The 7 MCP tools Claude Code gets
+| Tool | What Claude Code uses it for |
+|------|------------------------------|
+| `context_ingest_dir` | **Point at a folder → build the whole graph in one call** |
+| `context_ingest_file` | Ingest specific files (incl. PDFs) by path |
+| `context_ingest` | Ingest raw text |
+| `context_read` | Answer a question from the graph |
+| `context_contribute` | Write a new learning back into the graph |
+| `context_export` | Write the graph to an interactive HTML file to show |
+| `context_stats` | Report entity/relationship counts |
### Step 1 — Install
```bash
-# the one-liner your manager asked for (once the repo URL is filled in):
-curl -fsSL https://raw.githubusercontent.com/NanoNets/context-graph-engine/main/install.sh | sh
-
-# …or, from this checkout, for today:
-npm install && npm run build && npm link
+git clone [email protected]:NanoNets/context-graph-engine.git
+cd context-graph-engine && ./install.sh
```
-`npm link` puts `context-graph` and `context-graph-mcp` on your PATH.
+That builds and puts `context-graph` + `context-graph-mcp` on your PATH. (One command — no manual npm steps.)
-### Step 2 — Point your MCP client at it
-Add this to your Claude Code / Cursor MCP config (`.mcp.json` or the client's settings). Set a DB path for the demo graph and your OpenRouter key:
+### Step 2 — Point Claude Code at it
+Add this to your Claude Code MCP config (`.mcp.json` in your project, or `claude mcp add`). Set a DB path for the demo graph and your OpenRouter key:
```json
{
@@ -90,18 +99,25 @@ Add this to your Claude Code / Cursor MCP config (`.mcp.json` or the client's se
}
}
```
-Restart the client so it picks up the server. The agent now has 5 tools: `context_read`, `context_contribute`, `context_ingest`, `context_ingest_file`, `context_stats`.
+Restart Claude Code so it picks up the server and its 7 tools.
+
+### Step 3 — Ask Claude Code to build the graph (just say this)
+> "Use the context-graph tools to build a context graph from the folder
+> `/abs/path/context-graph-engine/examples/demo-docs`, then show me the stats."
-### Step 3 — Ingest the PDFs (say this to the agent)
-> "Ingest these files into the context graph:
-> /abs/path/examples/demo-docs/northwind-architecture.pdf,
-> /abs/path/examples/demo-docs/northwind-billing-runbook.pdf,
-> /abs/path/examples/demo-docs/northwind-onboarding.pdf"
+Claude Code calls **`context_ingest_dir`** on the folder. All 4 docs are parsed (PDFs included), chunked, embedded, and extracted into the graph — you'll watch the progress tick file-by-file. Result: **~62 entities and ~71 relationships** across 4 documents. (Progress notifications keep the call alive past the default 60s MCP timeout — a multi-file cloud ingest takes ~1–2 min.)
-The agent calls `context_ingest_file`. The PDFs are parsed, chunked, embedded, and extracted into the graph. You'll see something like "✓ 3 chunks, +23 entities, +35 relationships" per file. Then ask it to run `context_stats` — ~58 entities, ~70 relationships across 3 documents.
+### Step 4 — Show the graph (the visual)
+> "Export the context graph to `/tmp/northwind-graph.html` and tell me the path."
+
+Claude Code calls **`context_export`**. Open the file:
+```bash
+open /tmp/northwind-graph.html
+```
+You get an **interactive, force-directed graph** — nodes colored by type (service, person, policy, metric…), sized by how often they were observed, draggable/zoomable, with hover tooltips showing each entity's summary and confidence. This is the "show the created context graph" moment.
-### Step 4 — Ask questions (the payoff)
-Ask the agent things that only live inside the PDFs. It calls `context_read` and gets the answer back — as structured entities/relationships **and** the exact source passages:
+### Step 5 — Ask questions (the payoff)
+Ask Claude Code things that only live inside those docs. It calls `context_read` and answers — structured entities/relationships **and** the exact source passages:
- *"How are failed charges retried, and when does an account get suspended?"*
→ 3 retries with exponential backoff (1h / 6h / 24h) → `past_due` → suspended after 7 days.
@@ -109,19 +125,17 @@ Ask the agent things that only live inside the PDFs. It calls `context_read` and
→ access tokens expire after 15 minutes; Auth Service is backed by Redis for token revocation.
- *"Who do I escalate a Stripe outage to?"*
→ Dana Whitfield (Payments team lead), post in `#billing-incidents`, page PagerDuty service `northwind-billing`.
-- *"What do I do in my first week as a new hire?"*
- → security training, ship one small prod change, on-call shadow; buddy assigned day one.
-**The point to land:** these facts came from three separate PDFs, and the agent gets a *structured, cross-referenced* answer with the source text as evidence — not a blind vector-snippet dump.
+**The point to land:** these facts came from separate PDFs + a Markdown file, and the agent gets a *structured, cross-referenced* answer with the source text as evidence — not a blind vector-snippet dump.
-### Step 5 (optional) — Show it getting smarter
-Tell the agent: *"Contribute this learning: the Dunning Worker also posts to #billing-alerts after the final retry."* It calls `context_contribute`. Ask the billing question again — the new fact is now merged into the graph, and re-stated facts reinforce (bump confidence) rather than duplicate.
+### Step 6 (optional) — Show it getting smarter
+Tell Claude Code: *"Contribute this learning to the graph: the Dunning Worker also posts to #billing-alerts after the final retry."* It calls `context_contribute`. Ask the billing question again — the new fact is merged in, and re-stated facts reinforce (bump confidence) rather than duplicate.
### Fallback (no MCP client handy) — same thing via CLI
```bash
-context-graph --db ./northwind-demo.db ingest examples/demo-docs/*.pdf
+context-graph --db ./northwind-demo.db ingest-dir examples/demo-docs
+context-graph --db ./northwind-demo.db export --out northwind-graph.html && open northwind-graph.html
context-graph --db ./northwind-demo.db query "how are failed charges retried?"
-context-graph --db ./northwind-demo.db stats
```
(Delete `northwind-demo.db*` to reset.)
@@ -167,12 +181,13 @@ src/
types.ts ← the data model (nodes, edges, chunks) — read this to grok the domain
merge.ts ← dedup + reinforcement (the "gets smarter" logic)
sqlite-store.ts ← the embedded storage backend
+ export.ts ← graph → interactive HTML / JSON / Mermaid
ingest/
chunker.ts ← paragraph-aware chunking with overlap
pdf.ts ← PDF → text extraction (unpdf)
retrieval/retriever.ts ← semantic match + one-hop expansion + prompt rendering
- cli.ts ← the CLI
- mcp.ts ← the MCP server (context_read / _contribute / _ingest / _ingest_file / _stats)
+ cli.ts ← the CLI (ingest / ingest-dir / query / contribute / export / stats)
+ mcp.ts ← the MCP server (7 tools incl. _ingest_dir and _export)
examples/
quickstart.ts ← library quickstart
demo-docs/*.pdf ← the 3 demo PDFs used in §4
diff --git a/README.md b/README.md
index 7e5e1caa..03d62a2a 100644
--- a/README.md
+++ b/README.md
@@ -86,8 +86,12 @@ npm run example
```bash
# Ingest documents (Markdown, text, and PDFs — PDFs are parsed automatically)
context-graph ingest ./docs/*.md ./handbook.pdf
+context-graph ingest-dir ./docs # a whole folder, recursively
echo "some notes" | context-graph ingest-text --title "Notes"
+# Visualize the graph (interactive HTML; also --format json|mermaid)
+context-graph export --out graph.html && open graph.html
+
# Read the graph
context-graph query "how does billing retry failed charges?"
context-graph query "billing" --json # full structured bundle
@@ -133,6 +137,8 @@ Tools exposed:
| `context_contribute` | Write a learning back into the shared graph |
| `context_ingest` | Ingest a document (raw text) into the graph |
| `context_ingest_file` | Ingest files from disk, including **PDFs** (parsed automatically) |
+| `context_ingest_dir` | Ingest a whole **directory** of docs (PDF/MD/TXT), recursively |
+| `context_export` | Write the graph to an interactive **HTML** visualization |
| `context_stats` | Report how much the graph currently holds |
A natural agent workflow: **read context → do the task → contribute what you learned.**
@@ -220,9 +226,11 @@ This is exactly how the test suite runs the whole pipeline offline with fake pro
```ts
class ContextGraphEngine {
ingest(text: string, opts?: { title?; source? }): Promise<IngestResult>;
- ingestFile(path: string, opts?): Promise<IngestResult>;
+ ingestFile(path: string, opts?): Promise<IngestResult>; // .pdf parsed automatically
+ ingestDir(dir: string, opts?): Promise<IngestResult[]>; // recursive; PDF/MD/TXT
read(query: string, opts?: { maxNodes?; maxChunks?; expand? }): Promise<ContextBundle>;
contribute(learning: string, opts?: { agentId?; source? }): Promise<ContributeResult>;
+ exportGraph(): GraphExport; // -> toHtml / toMermaid
stats(): GraphStats;
close(): void;
}
diff --git a/examples/demo-docs/northwind-glossary.md b/examples/demo-docs/northwind-glossary.md
new file mode 100644
index 00000000..41750f08
--- /dev/null
+++ b/examples/demo-docs/northwind-glossary.md
@@ -0,0 +1,16 @@
+# Northwind Glossary
+
+**Dunning**: The automated process of retrying failed payments and notifying
+customers before suspending an account. Owned by the Payments team.
+
+**past_due**: The subscription state entered after three failed charge retries.
+An account in past_due for 7 days is automatically suspended.
+
+**SLO**: Northwind's charge success rate service-level objective is 97%. The
+error budget is exhausted if the rate drops below 95% for 30 minutes.
+
+**Blue-green deploy**: The Platform team's deployment strategy. New versions are
+rolled out to a green environment on Kubernetes before traffic is switched over.
+
+**On-call**: Each team runs a weekly PagerDuty rotation. The billing rotation is
+`northwind-billing`; the platform rotation is `northwind-platform`.
diff --git a/src/cli.ts b/src/cli.ts
index 9829eea3..a42238b8 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -12,8 +12,9 @@
*/
import "dotenv/config";
import { Command } from "commander";
-import { readFileSync } from "node:fs";
+import { readFileSync, writeFileSync } from "node:fs";
import { ContextGraphEngine } from "./engine.js";
+import { toHtml, toMermaid } from "./graph/export.js";
const program = new Command();
@@ -107,6 +108,60 @@ program
}
});
+program
+ .command("ingest-dir")
+ .description("Ingest every supported doc (.pdf .md .txt) in a directory, recursively")
+ .argument("<dir>", "directory to ingest")
+ .action(async (dir: string) => {
+ const engine = engineFrom();
+ try {
+ const results = await engine.ingestDir(dir);
+ if (results.length === 0) {
+ console.log(`No supported files found under ${dir}`);
+ return;
+ }
+ for (const r of results) {
+ console.log(
+ r.skipped
+ ? `• ${r.title} — already ingested, skipped`
+ : `✓ ${r.title} — ${r.chunks} chunks, +${r.nodesCreated} nodes, +${r.edgesCreated} edges`,
+ );
+ }
+ } finally {
+ engine.close();
+ }
+ });
+
+program
+ .command("export")
+ .description("Export the whole graph for viewing (interactive HTML, JSON, or Mermaid)")
+ .option("-f, --format <fmt>", "html | json | mermaid", "html")
+ .option("-o, --out <path>", "output file (default: context-graph.<ext>)")
+ .action((opts: { format: string; out?: string }) => {
+ const engine = engineFrom();
+ try {
+ const g = engine.exportGraph();
+ let content: string;
+ let ext: string;
+ if (opts.format === "json") {
+ content = JSON.stringify(g, null, 2);
+ ext = "json";
+ } else if (opts.format === "mermaid") {
+ content = toMermaid(g);
+ ext = "mmd";
+ } else {
+ content = toHtml(g);
+ ext = "html";
+ }
+ const out = opts.out ?? `context-graph.${ext}`;
+ writeFileSync(out, content);
+ console.log(`✓ wrote ${g.nodes.length} entities / ${g.edges.length} relationships to ${out}`);
+ if (ext === "html") console.log(` open it: open ${out}`);
+ } finally {
+ engine.close();
+ }
+ });
+
program
.command("stats")
.description("Show graph statistics")
diff --git a/src/engine.ts b/src/engine.ts
index 3518c52d..6b2e4860 100644
--- a/src/engine.ts
+++ b/src/engine.ts
@@ -1,6 +1,7 @@
-import { readFileSync } from "node:fs";
-import { basename } from "node:path";
+import { readFileSync, readdirSync } from "node:fs";
+import { basename, join } from "node:path";
import { extractPdfText, isPdfPath } from "./ingest/pdf.js";
+import { buildGraphExport, type GraphExport } from "./graph/export.js";
import type { GraphStore } from "./graph/store.js";
import { SqliteStore } from "./graph/sqlite-store.js";
import type { Embedder, EngineConfig, Extractor, ResolvedConfig } from "./ai/providers.js";
@@ -181,11 +182,41 @@ export class ContextGraphEngine {
return { documentId, title, skipped: false, chunks: pieces.length, ...totals };
}
+ /**
+ * Ingest every supported document in a directory (recursively). Supported
+ * extensions: .pdf, .md, .markdown, .txt. Returns one result per file.
+ *
+ * `onProgress` is invoked before each file starts (so callers can report
+ * progress on long, multi-file ingests — e.g. to keep an MCP client's request
+ * timeout from firing).
+ */
+ async ingestDir(
+ dir: string,
+ opts: {
+ extensions?: string[];
+ onProgress?: (info: { index: number; total: number; file: string }) => void;
+ } = {},
+ ): Promise<IngestResult[]> {
+ const exts = opts.extensions ?? [".pdf", ".md", ".markdown", ".txt"];
+ const files = walkDir(dir).filter((f) => exts.some((e) => f.toLowerCase().endsWith(e)));
+ const results: IngestResult[] = [];
+ for (let i = 0; i < files.length; i++) {
+ opts.onProgress?.({ index: i, total: files.length, file: files[i] });
+ results.push(await this.ingestFile(files[i]));
+ }
+ return results;
+ }
+
/** Read the graph for a query, returning a structured context bundle. */
async read(query: string, opts: RetrieveOptions = {}): Promise<ContextBundle> {
return retrieve(this.store, this.embedder, query, opts);
}
+ /** A serializable snapshot of the whole graph, for export/visualization. */
+ exportGraph(): GraphExport {
+ return buildGraphExport(this.store);
+ }
+
/**
* Contribute a learning discovered by an agent. The text is stored as
* retrievable evidence and its entities/relations are merged into the graph,
@@ -254,6 +285,18 @@ export class ContextGraphEngine {
}
}
+/** Recursively list all files under a directory (skips dot-directories). */
+function walkDir(dir: string): string[] {
+ const out: string[] = [];
+ for (const entry of readdirSync(dir, { withFileTypes: true })) {
+ if (entry.name.startsWith(".")) continue;
+ const full = join(dir, entry.name);
+ if (entry.isDirectory()) out.push(...walkDir(full));
+ else if (entry.isFile()) out.push(full);
+ }
+ return out;
+}
+
/** Run `fn` over `items` with at most `limit` in flight at once, preserving order. */
async function mapWithConcurrency<T, R>(
items: T[],
diff --git a/src/graph/export.ts b/src/graph/export.ts
new file mode 100644
index 00000000..6f1ac992
--- /dev/null
+++ b/src/graph/export.ts
@@ -0,0 +1,118 @@
+import type { GraphStore } from "./store.js";
+import type { GraphEdge, GraphNode } from "./types.js";
+
+/** A plain, serializable snapshot of the whole graph. */
+export interface GraphExport {
+ nodes: Array<Pick<GraphNode, "id" | "name" | "type" | "summary" | "confidence" | "observations">>;
+ edges: Array<Pick<GraphEdge, "sourceId" | "targetId" | "relation" | "description" | "confidence">>;
+}
+
+/** Read the entire graph out of a store into a serializable snapshot. */
+export function buildGraphExport(store: GraphStore): GraphExport {
+ const nodes = store.allNodes().map((n) => ({
+ id: n.id,
+ name: n.name,
+ type: n.type,
+ summary: n.summary,
+ confidence: n.confidence,
+ observations: n.observations,
+ }));
+ const edges = store.allEdges().map((e) => ({
+ sourceId: e.sourceId,
+ targetId: e.targetId,
+ relation: e.relation,
+ description: e.description,
+ confidence: e.confidence,
+ }));
+ return { nodes, edges };
+}
+
+/** Render the graph as a Mermaid `graph LR` definition (handy for docs/markdown). */
+export function toMermaid(g: GraphExport): string {
+ const safe = (id: string) => id.replace(/[^a-zA-Z0-9_]/g, "_");
+ const lines = ["graph LR"];
+ for (const n of g.nodes) {
+ lines.push(` ${safe(n.id)}["${n.name.replace(/"/g, "'")} (${n.type})"]`);
+ }
+ for (const e of g.edges) {
+ lines.push(` ${safe(e.sourceId)} -->|${e.relation}| ${safe(e.targetId)}`);
+ }
+ return lines.join("\n");
+}
+
+/**
+ * Render the graph as a self-contained, interactive HTML page.
+ *
+ * Uses vis-network (loaded from a CDN) for a draggable/zoomable force layout —
+ * the graph data itself is embedded inline, so the only network dependency is
+ * the viz library. Nodes are colored by type and sized by observation count.
+ */
+export function toHtml(g: GraphExport, title = "Context Graph"): string {
+ const palette = [
+ "#4f46e5", "#0891b2", "#059669", "#d97706", "#dc2626",
+ "#7c3aed", "#db2777", "#65a30d", "#0284c7", "#ca8a04",
+ ];
+ const types = [...new Set(g.nodes.map((n) => n.type))];
+ const colorFor = (t: string) => palette[types.indexOf(t) % palette.length];
+
+ const nodes = g.nodes.map((n) => ({
+ id: n.id,
+ label: n.name,
+ title: `${n.name} (${n.type})\nconfidence ${Math.round(n.confidence * 100)}% · ${n.observations} observation(s)\n${n.summary}`,
+ group: n.type,
+ value: n.observations,
+ color: colorFor(n.type),
+ }));
+ const edges = g.edges.map((e) => ({
+ from: e.sourceId,
+ to: e.targetId,
+ label: e.relation,
+ title: e.description || e.relation,
+ width: 1 + e.confidence * 2,
+ }));
+
+ const legend = types
+ .map((t) => `<span class="chip"><i style="background:${colorFor(t)}"></i>${t}</span>`)
+ .join("");
+
+ return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>${title}</title>
+<script src="https://unpkg.com/[email protected]/standalone/umd/vis-network.min.js"
+ integrity="sha384-yxKDWWf0wwdUj/gPeuL11czrnKFQROnLgY8ll7En9NYoXibgg3C6NK/UDHNtUgWJ"
+ crossorigin="anonymous"></script>
+<style>
+ :root { color-scheme: light dark; }
+ body { margin: 0; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; }
+ header { padding: 12px 16px; border-bottom: 1px solid #8883; }
+ h1 { font-size: 16px; margin: 0 0 6px; }
+ .meta { font-size: 12px; opacity: 0.7; }
+ .legend { margin-top: 8px; display: flex; flex-wrap: wrap; gap: 8px; }
+ .chip { font-size: 11px; display: inline-flex; align-items: center; gap: 4px; }
+ .chip i { width: 10px; height: 10px; border-radius: 50%; display: inline-block; }
+ #graph { width: 100vw; height: calc(100vh - 92px); }
+</style>
+</head>
+<body>
+<header>
+ <h1>${title}</h1>
+ <div class="meta">${g.nodes.length} entities · ${g.edges.length} relationships</div>
+ <div class="legend">${legend}</div>
+</header>
+<div id="graph"></div>
+<script>
+ const nodes = new vis.DataSet(${JSON.stringify(nodes)});
+ const edges = new vis.DataSet(${JSON.stringify(edges)});
+ new vis.Network(document.getElementById("graph"), { nodes, edges }, {
+ nodes: { shape: "dot", scaling: { min: 8, max: 32 }, font: { size: 14 } },
+ edges: { arrows: "to", font: { size: 10, align: "middle" }, color: { opacity: 0.5 }, smooth: { type: "dynamic" } },
+ physics: { stabilization: true, barnesHut: { gravitationalConstant: -8000, springLength: 140 } },
+ interaction: { hover: true, tooltipDelay: 120 },
+ });
+</script>
+</body>
+</html>`;
+}
diff --git a/src/graph/sqlite-store.ts b/src/graph/sqlite-store.ts
index 5b985099..0b751774 100644
--- a/src/graph/sqlite-store.ts
+++ b/src/graph/sqlite-store.ts
@@ -228,6 +228,11 @@ export class SqliteStore implements GraphStore {
return rows.map((r) => this.rowToNode(r));
}
+ allNodes(): GraphNode[] {
+ const rows = this.db.prepare(`SELECT * FROM nodes`).all() as NodeRow[];
+ return rows.map((r) => this.rowToNode(r));
+ }
+
upsertNode(node: GraphNode): void {
this.db
.prepare(
@@ -334,6 +339,11 @@ export class SqliteStore implements GraphStore {
return rows.map((r) => this.rowToEdge(r));
}
+ allEdges(): GraphEdge[] {
+ const rows = this.db.prepare(`SELECT * FROM edges`).all() as EdgeRow[];
+ return rows.map((r) => this.rowToEdge(r));
+ }
+
private rowToEdge(row: EdgeRow): GraphEdge {
return {
id: row.id,
diff --git a/src/graph/store.ts b/src/graph/store.ts
index 6d4acc42..cf404e61 100644
--- a/src/graph/store.ts
+++ b/src/graph/store.ts
@@ -31,6 +31,8 @@ export interface GraphStore {
findNodesByName(normalizedName: string): GraphNode[];
/** All nodes that have an embedding, for in-memory vector search & dedup. */
allEmbeddedNodes(): GraphNode[];
+ /** Every node in the graph (for export/visualization). */
+ allNodes(): GraphNode[];
upsertNode(node: GraphNode): void;
// --- edges ---
@@ -39,6 +41,8 @@ export interface GraphStore {
upsertEdge(edge: GraphEdge): void;
/** All edges incident to any of the given node ids. */
edgesForNodes(nodeIds: string[]): GraphEdge[];
+ /** Every edge in the graph (for export/visualization). */
+ allEdges(): GraphEdge[];
// --- misc ---
documentTitle(documentId: string): string;
diff --git a/src/index.ts b/src/index.ts
index af846fb1..e101cfda 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -38,6 +38,8 @@ export { retrieve, renderPrompt } from "./retrieval/retriever.js";
export type { GraphStore } from "./graph/store.js";
export { SqliteStore } from "./graph/sqlite-store.js";
export { mergeExtraction } from "./graph/merge.js";
+export type { GraphExport } from "./graph/export.js";
+export { buildGraphExport, toHtml, toMermaid } from "./graph/export.js";
export type {
GraphNode,
diff --git a/src/mcp.ts b/src/mcp.ts
index 4cf7a390..dcd4a97c 100644
--- a/src/mcp.ts
+++ b/src/mcp.ts
@@ -10,7 +10,9 @@ import "dotenv/config";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
+import { writeFileSync } from "node:fs";
import { ContextGraphEngine } from "./engine.js";
+import { toHtml } from "./graph/export.js";
const engine = new ContextGraphEngine();
@@ -117,6 +119,72 @@ server.registerTool(
},
);
+server.registerTool(
+ "context_ingest_dir",
+ {
+ title: "Ingest a directory",
+ description:
+ "Ingest every supported document (.pdf, .md, .markdown, .txt) in a directory, recursively, into the shared context graph. Point this at a folder of docs and it builds the graph in one call.",
+ inputSchema: {
+ dir: z.string().describe("Absolute path to the directory of documents to ingest."),
+ },
+ },
+ async ({ dir }, extra) => {
+ // Report progress per file. If the client supplied a progressToken (and
+ // resets its request timeout on progress, as Claude Code does), this keeps
+ // long multi-file ingests from tripping the default 60s tool timeout.
+ const progressToken = extra?._meta?.progressToken;
+ const onProgress = progressToken
+ ? ({ index, total, file }: { index: number; total: number; file: string }) => {
+ void extra.sendNotification({
+ method: "notifications/progress",
+ params: {
+ progressToken,
+ progress: index,
+ total,
+ message: `Ingesting ${file.split("/").pop()} (${index + 1}/${total})`,
+ },
+ });
+ }
+ : undefined;
+ const results = await engine.ingestDir(dir, { onProgress });
+ if (results.length === 0) {
+ return { content: [{ type: "text", text: `No supported files found under ${dir}.` }] };
+ }
+ const created = results.reduce((a, r) => a + r.nodesCreated, 0);
+ const edges = results.reduce((a, r) => a + r.edgesCreated, 0);
+ const lines = results.map((r) =>
+ r.skipped ? `• ${r.title}: skipped (already ingested)` : `✓ ${r.title}: +${r.nodesCreated} entities, +${r.edgesCreated} relationships`,
+ );
+ lines.push(`\nTotal: ${results.length} files → +${created} entities, +${edges} relationships.`);
+ return { content: [{ type: "text", text: lines.join("\n") }] };
+ },
+);
+
+server.registerTool(
+ "context_export",
+ {
+ title: "Export the graph as HTML",
+ description:
+ "Write the entire context graph to a self-contained, interactive HTML file that can be opened in a browser to visualize entities and relationships.",
+ inputSchema: {
+ path: z.string().describe("Absolute path to write the HTML file to (e.g. /tmp/context-graph.html)."),
+ },
+ },
+ async ({ path }) => {
+ const g = engine.exportGraph();
+ writeFileSync(path, toHtml(g));
+ return {
+ content: [
+ {
+ type: "text",
+ text: `Wrote graph (${g.nodes.length} entities, ${g.edges.length} relationships) to ${path}. Open it in a browser to explore.`,
+ },
+ ],
+ };
+ },
+);
+
server.registerTool(
"context_stats",
{