Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.
TypeScript ai-agentsanthropicclaude-codeclicode-graphcodexcontext-engineeringcursordeveloper-toolsgeminiknowledge-graphllmmcpmcp-serveropen-sourceopenaitree-sitter
Add directory ingest, graph visualization, and MCP timeout fix
anirudhkumar-nanonets0c4c6ddbe46d
diff --git a/DEMO.md b/DEMO.mdindex 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.htmlcontext-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 domainmerge.ts ← dedup + reinforcement (the "gets smarter" logic)sqlite-store.ts ← the embedded storage backend+ export.ts ← graph → interactive HTML / JSON / Mermaidingest/chunker.ts ← paragraph-aware chunking with overlappdf.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 quickstartdemo-docs/*.pdf ← the 3 demo PDFs used in §4diff --git a/README.md b/README.mdindex 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, recursivelyecho "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 graphcontext-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```tsclass 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/TXTread(query: string, opts?: { maxNodes?; maxChunks?; expand? }): Promise<ContextBundle>;contribute(learning: string, opts?: { agentId?; source? }): Promise<ContributeResult>;+ exportGraph(): GraphExport; // -> toHtml / toMermaidstats(): GraphStats;close(): void;}diff --git a/examples/demo-docs/northwind-glossary.md b/examples/demo-docs/northwind-glossary.mdnew file mode 100644index 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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",{