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 context-graph serve: unified web UI + MCP-over-HTTP + watcher in one process
anirudhkumar-nanonetsbc190e4f8cb5
diff --git a/DEMO.md b/DEMO.mdindex 7c61818b..442ae887 100644--- a/DEMO.md+++ b/DEMO.md@@ -101,6 +101,16 @@ Add this to your Claude Code MCP config (`.mcp.json` in your project, or `claude```Restart Claude Code so it picks up the server and its 7 tools.+Alternatively, run one process for the web UI + MCP together with `context-graph serve` and point Claude Code at the HTTP endpoint (no per-session process to spawn):++```json+{+ "mcpServers": {+ "context-graph": { "type": "http", "url": "http://localhost:4680/mcp" }+ }+}+```+### 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."diff --git a/Dockerfile b/Dockerfileindex 6ef9a87b..6808f5f0 100644--- a/Dockerfile+++ b/Dockerfile@@ -1,10 +1,13 @@-# Context Graph — team-brain web UI in one container.+# Context Graph — the whole engine in one container.#-# docker compose up → http://localhost:4680+# docker compose up → web UI at http://localhost:4680+# MCP (HTTP) at http://localhost:4680/mcp#-# The graph persists to the /data volume as a single SQLite file. The server-# binds 0.0.0.0 inside the container and requires the access token printed in-# the container logs on first start (or set CONTEXT_GRAPH_WEB_TOKEN).+# Runs `context-graph serve`: the web UI, the MCP server (over HTTP), and the+# folder watcher share one engine and one port. The graph persists to the /data+# volume as a single SQLite file. The server binds 0.0.0.0 inside the container+# and requires the access token printed in the container logs on first start+# (or set CONTEXT_GRAPH_WEB_TOKEN); the token also gates /mcp.FROM node:22-slim AS buildWORKDIR /app@@ -32,4 +35,6 @@ RUN mkdir -p /data && chown node:node /dataUSER nodeEXPOSE 4680VOLUME /data-CMD ["node", "dist/web.js"]+# Resumes any registered watch folders; mount them and register via the UI or+# `context-graph watch <dir>` so they persist in the /data volume.+CMD ["node", "dist/serve.js"]diff --git a/README.md b/README.mdindex 2232b6d1..9814bec4 100644--- a/README.md+++ b/README.md@@ -41,6 +41,16 @@ Everything runs on your machine (the server binds to localhost only). Set `OPENRRunning it for your whole team? One `docker compose up` gives everyone the same graph at one URL — see [Team sharing](#team-sharing).+### Or run everything at once — `context-graph serve`++```bash+context-graph serve+# → web UI http://localhost:4680+# MCP (HTTP) http://localhost:4680/mcp+```++One process runs the web UI, the MCP server (over HTTP), and the folder watcher on a single port over **one shared engine** — the supported way to run the whole thing at once, with no separate `watch` daemon to babysit. Open the UI, click **Connect a folder**, tick **Keep watching**, and that folder is ingested and watched live; it's remembered, so the next `serve` resumes it. Prefer the command line? Pass folders directly: `context-graph serve ./sample-docs`.+### Runs locally by default — keys are optionalOut of the box the engine needs **no accounts and no cloud calls**:@@ -160,6 +170,18 @@ Add to your Claude Code / MCP client config:}```+Or, if you're running `context-graph serve`, point any MCP client at its HTTP endpoint instead of spawning a process:++```json+{+ "mcpServers": {+ "context-graph": { "type": "http", "url": "http://localhost:4680/mcp" }+ }+}+```++When the server is exposed beyond localhost, add `"headers": { "Authorization": "Bearer <access-token>" }` — the same token the web UI prints.+The API-key env vars are optional — add `OPENROUTER_API_KEY` (and optionally `OPENAI_API_KEY` for embeddings) only if you want cloud models instead of the local defaults.Tools exposed:diff --git a/docker-compose.yml b/docker-compose.ymlindex 604786a3..746ec3ec 100644--- a/docker-compose.yml+++ b/docker-compose.yml@@ -1,10 +1,11 @@-# Context Graph — one shared team-brain server.+# Context Graph — one shared team-brain server (web UI + MCP-over-HTTP + watcher).## docker compose up -d# cat ./data/share-link.txt # grab the access/share link## The graph lives in ./data as a single SQLite file. Put documents you want to# ingest into ./docs and type /docs in the UI's "Ingest a folder" box.+# Agents connect over MCP at http://<host>:4680/mcp (Bearer = the access token).services:context-graph:build: .diff --git a/package.json b/package.jsonindex 25d381bb..530a5d0d 100644--- a/package.json+++ b/package.json@@ -25,7 +25,8 @@"bin": {"context-graph": "./dist/cli.js","context-graph-mcp": "./dist/mcp.js",- "context-graph-web": "./dist/web.js"+ "context-graph-web": "./dist/web.js",+ "context-graph-serve": "./dist/serve.js"},"files": ["dist",@@ -38,6 +39,7 @@"cli": "tsx src/cli.ts","mcp": "tsx src/mcp.ts","web": "tsx src/web.ts",+ "serve": "tsx src/serve.ts","example": "tsx examples/quickstart.ts","test": "node --import tsx --test test/*.test.ts","prepare": "npm run build",diff --git a/src/cli.ts b/src/cli.tsindex a9dfff93..3d280547 100644--- a/src/cli.ts+++ b/src/cli.ts@@ -20,6 +20,7 @@ import { ContextGraphEngine } from "./engine.js";import { GraphWatcher, type WatchEvent } from "./watch.js";import { resolveConfig } from "./ai/providers.js";import { toHtml, toMermaid } from "./graph/export.js";+import { startServe } from "./serve.js";const program = new Command();@@ -596,6 +597,53 @@ program}});+program+ .command("serve")+ .description(+ "Run everything in one process: the web UI, the MCP server (over HTTP at /mcp), and the " ++ "watcher — one engine, one watcher, one port. Resumes registered folders unless --no-watch.",+ )+ .argument("[dirs...]", "extra folders to register and watch")+ .option("-p, --port <port>", "port to listen on (default 4680)", (v) => parseInt(v, 10))+ .option("-H, --host <host>", "host to bind (default 127.0.0.1; use 0.0.0.0 to expose)")+ .option("-e, --ext <exts...>", 'extensions to watch (default: ".pdf" ".md" ".markdown" ".txt")')+ .option("--no-watch", "start the web/MCP servers without resuming or watching any folders")+ .action(+ async (+ dirs: string[],+ opts: { port?: number; host?: string; ext?: string[]; watch: boolean },+ ) => {+ const { db } = program.opts<{ db?: string }>();+ const running = await startServe({+ host: opts.host,+ port: opts.port,+ watch: opts.watch,+ dirs,+ extensions: opts.ext,+ engineConfig: { dbPath: db },+ });+ const cfg = resolveConfig({ dbPath: db });+ const watched = running.engine.listWatchedDirs().length;+ console.log(`Context Graph → ${running.url}`);+ console.log(` web UI: ${running.url}`);+ console.log(` MCP (HTTP): ${running.url}/mcp`);+ console.log(` graph db: ${resolve(cfg.dbPath)}`);+ if (opts.watch && watched > 0) console.log(` watching: ${watched} registered folder(s)`);+ console.log(" Ctrl-C to stop.");++ let stopping = false;+ const stop = async () => {+ if (stopping) return;+ stopping = true;+ console.log("\nstopping…");+ await running.close();+ process.exit(0);+ };+ process.on("SIGINT", () => void stop());+ process.on("SIGTERM", () => void stop());+ },+ );+program.parseAsync().catch((err) => {console.error(err instanceof Error ? err.message : err);process.exit(1);diff --git a/src/mcp.ts b/src/mcp.tsindex ed21974e..c9fe558a 100644--- a/src/mcp.ts+++ b/src/mcp.ts@@ -4,437 +4,474 @@* etc.). Agents `context_read` before doing work and `context_contribute` what* they learn — mirroring the "shared skill / durable memory" integration model.*+ * The tool registrations are packaged as {@link createContextGraphMcpServer} so+ * the same server can be driven over stdio (`context-graph-mcp`, below) or over+ * Streamable HTTP by the unified `context-graph serve` command — both sharing a+ * single engine and watcher.+ ** Run: context-graph-mcp (configure the db via CONTEXT_GRAPH_DB)*/import "dotenv/config";import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";import { z } from "zod";+import { fileURLToPath } from "node:url";+import { resolve } from "node:path";import { writeFileSync, readFileSync, existsSync } from "node:fs";import { ContextGraphEngine } from "./engine.js";import { GraphWatcher, type WatchEvent } from "./watch.js";import { toHtml } from "./graph/export.js";-const engine = new ContextGraphEngine();--// One lazily-created watcher for the life of this MCP process. Folders added-// via context_watch_dir keep updating the graph in the background for as long-// as the client session (and thus this process) lives. context_watch_dir-// temporarily points `progressSink` at its own progress notifications while-// the catch-up scan runs.-let watcher: GraphWatcher | undefined;-let progressSink: ((event: WatchEvent) => void) | undefined;--function getWatcher(): GraphWatcher {- return (watcher ??= new GraphWatcher(engine, {- onEvent: (event) => {- // stderr only — stdout is the JSON-RPC channel.- if (event.type === "error") console.error(`watch: ✗ ${event.file}: ${event.error}`);- else if (event.type === "ingested" && !event.result.skipped) {- console.error(`watch: ✓ ${event.result.title} (+${event.result.nodesCreated} entities)`);- }- progressSink?.(event);- },- }));+/** Dependencies a context-graph MCP server binds to. Shared across transports. */+export interface McpDeps {+ /** The (shared) engine every tool operates on. */+ engine: ContextGraphEngine;+ /** Ensure/return the watcher used by `context_watch_dir`. */+ getWatcher: () => GraphWatcher;+ /** Peek at the watcher without creating one (status/unwatch). Defaults to a non-creating view. */+ peekWatcher?: () => GraphWatcher | undefined;+ /** Point the watcher's catch-up progress at a sink for the duration of a watch call. */+ setProgressSink: (sink: ((event: WatchEvent) => void) | undefined) => void;}-const server = new McpServer({- name: "context-graph-engine",- version: "0.1.0",-});+/**+ * Build an {@link McpServer} with the context-graph tools registered against the+ * given dependencies. Every transport (stdio, Streamable HTTP) gets its own+ * server instance, but they can all share one engine + watcher via `deps`.+ */+export function createContextGraphMcpServer(deps: McpDeps): McpServer {+ const { engine } = deps;+ const peekWatcher = deps.peekWatcher ?? (() => undefined);++ const server = new McpServer({+ name: "context-graph-engine",+ version: "0.1.0",+ });-server.registerTool(- "context_read",- {- title: "Read shared context",- description:- "Read the shared context graph for a query BEFORE doing work. Returns relevant entities, relationships, and supporting sources as a ready-to-use context block.",- inputSchema: {- query: z.string().describe("What you need context about."),- maxNodes: z.number().int().min(1).max(50).optional().describe("Max entities (default 8)."),- maxChunks: z.number().int().min(0).max(50).optional().describe("Max source passages (default 6)."),+ server.registerTool(+ "context_read",+ {+ title: "Read shared context",+ description:+ "Read the shared context graph for a query BEFORE doing work. Returns relevant entities, relationships, and supporting sources as a ready-to-use context block.",+ inputSchema: {+ query: z.string().describe("What you need context about."),+ maxNodes: z.number().int().min(1).max(50).optional().describe("Max entities (default 8)."),+ maxChunks: z.number().int().min(0).max(50).optional().describe("Max source passages (default 6)."),+ },},- },- async ({ query, maxNodes, maxChunks }) => {- const bundle = await engine.read(query, { maxNodes, maxChunks });- return { content: [{ type: "text", text: bundle.prompt }] };- },-);+ async ({ query, maxNodes, maxChunks }) => {+ const bundle = await engine.read(query, { maxNodes, maxChunks });+ return { content: [{ type: "text", text: bundle.prompt }] };+ },+ );-server.registerTool(- "context_contribute",- {- title: "Contribute a learning",- description:- "Contribute something you learned back into the shared context graph so future agents benefit. It is deduplicated and merged with existing knowledge.",- inputSchema: {- learning: z.string().describe("The fact or insight to record, in plain language."),- agentId: z.string().optional().describe("Your agent identifier (default 'agent')."),+ server.registerTool(+ "context_contribute",+ {+ title: "Contribute a learning",+ description:+ "Contribute something you learned back into the shared context graph so future agents benefit. It is deduplicated and merged with existing knowledge.",+ inputSchema: {+ learning: z.string().describe("The fact or insight to record, in plain language."),+ agentId: z.string().optional().describe("Your agent identifier (default 'agent')."),+ },},- },- async ({ learning, agentId }) => {- const r = await engine.contribute(learning, { agentId });- return {- content: [- {- type: "text",- text: `Recorded. +${r.nodesCreated} new entities, ${r.nodesUpdated} reinforced; +${r.edgesCreated} new relationships, ${r.edgesUpdated} reinforced.`,- },- ],- };- },-);+ async ({ learning, agentId }) => {+ const r = await engine.contribute(learning, { agentId });+ return {+ content: [+ {+ type: "text",+ text: `Recorded. +${r.nodesCreated} new entities, ${r.nodesUpdated} reinforced; +${r.edgesCreated} new relationships, ${r.edgesUpdated} reinforced.`,+ },+ ],+ };+ },+ );-server.registerTool(- "context_ingest",- {- title: "Ingest a document",- description: "Ingest a document (raw text) into the shared context graph.",- inputSchema: {- text: z.string().describe("The document text to ingest."),- title: z.string().optional().describe("A title for the document."),+ server.registerTool(+ "context_ingest",+ {+ title: "Ingest a document",+ description: "Ingest a document (raw text) into the shared context graph.",+ inputSchema: {+ text: z.string().describe("The document text to ingest."),+ title: z.string().optional().describe("A title for the document."),+ },+ },+ async ({ text, title }) => {+ const r = await engine.ingest(text, { title });+ return {+ content: [+ {+ type: "text",+ text: r.skipped+ ? "Document already ingested; skipped."+ : `Ingested "${r.title}": ${r.chunks} chunks, +${r.nodesCreated} entities, +${r.edgesCreated} relationships.`,+ },+ ],+ };},- },- async ({ text, title }) => {- const r = await engine.ingest(text, { title });- return {- content: [- {- type: "text",- text: r.skipped- ? "Document already ingested; skipped."- : `Ingested "${r.title}": ${r.chunks} chunks, +${r.nodesCreated} entities, +${r.edgesCreated} relationships.`,- },- ],- };- },-);+ );-server.registerTool(- "context_ingest_file",- {- title: "Ingest a file (incl. PDFs)",- description:- "Ingest one or more files from disk into the shared context graph. PDF files are parsed to text automatically. Accepts absolute paths.",- inputSchema: {- paths: z- .array(z.string())- .min(1)- .describe("Absolute file paths to ingest (e.g. PDFs)."),+ server.registerTool(+ "context_ingest_file",+ {+ title: "Ingest a file (incl. PDFs)",+ description:+ "Ingest one or more files from disk into the shared context graph. PDF files are parsed to text automatically. Accepts absolute paths.",+ inputSchema: {+ paths: z+ .array(z.string())+ .min(1)+ .describe("Absolute file paths to ingest (e.g. PDFs)."),+ },},- },- async ({ paths }) => {- const lines: string[] = [];- for (const path of paths) {- try {- const r = await engine.ingestFile(path);- lines.push(- r.skipped- ? `• ${r.title}: already ingested, skipped`- : `✓ ${r.title}: ${r.chunks} chunks, +${r.nodesCreated} entities (${r.nodesUpdated} reinforced), +${r.edgesCreated} relationships`,- );- } catch (err) {- lines.push(`✗ ${path}: ${err instanceof Error ? err.message : String(err)}`);+ async ({ paths }) => {+ const lines: string[] = [];+ for (const path of paths) {+ try {+ const r = await engine.ingestFile(path);+ lines.push(+ r.skipped+ ? `• ${r.title}: already ingested, skipped`+ : `✓ ${r.title}: ${r.chunks} chunks, +${r.nodesCreated} entities (${r.nodesUpdated} reinforced), +${r.edgesCreated} relationships`,+ );+ } catch (err) {+ lines.push(`✗ ${path}: ${err instanceof Error ? err.message : String(err)}`);+ }}- }- return { content: [{ type: "text", text: lines.join("\n") }] };- },-);+ return { content: [{ type: "text", text: lines.join("\n") }] };+ },+ );-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."),- extensions: z- .array(z.string())- .optional()- .describe('File extensions to include (e.g. [".md", ".rst"]). Default: .pdf .md .markdown .txt'),+ 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."),+ extensions: z+ .array(z.string())+ .optional()+ .describe('File extensions to include (e.g. [".md", ".rst"]). Default: .pdf .md .markdown .txt'),+ },},- },- async ({ dir, extensions }, 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, { extensions, 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") }] };- },-);+ async ({ dir, extensions }, 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, { extensions, 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_ingest_repo",- {- title: "Ingest a code repository (as summaries)",- description:- "Ingest a code repository into the shared context graph. Each source file is summarized " +- "into prose (purpose, key exports, dependencies, design decisions) and the summaries are " +- "ingested — raw code is never fed to the extractor. Incremental: re-running only " +- "re-summarizes files whose content changed.",- inputSchema: {- dir: z.string().describe("Absolute path to the repository root."),- extensions: z- .array(z.string())- .optional()- .describe('File extensions to treat as code (default: common languages, e.g. ".ts", ".py", ".go").'),+ server.registerTool(+ "context_ingest_repo",+ {+ title: "Ingest a code repository (as summaries)",+ description:+ "Ingest a code repository into the shared context graph. Each source file is summarized " ++ "into prose (purpose, key exports, dependencies, design decisions) and the summaries are " ++ "ingested — raw code is never fed to the extractor. Incremental: re-running only " ++ "re-summarizes files whose content changed.",+ inputSchema: {+ dir: z.string().describe("Absolute path to the repository root."),+ extensions: z+ .array(z.string())+ .optional()+ .describe('File extensions to treat as code (default: common languages, e.g. ".ts", ".py", ".go").'),+ },},- },- async ({ dir, extensions }, extra) => {- const progressToken = extra?._meta?.progressToken;- const onProgress = progressToken- ? ({ phase, index, total, file }: { phase: string; index: number; total: number; file: string }) => {- void extra.sendNotification({- method: "notifications/progress",- params: {- progressToken,- progress: index,- total,- message: `${phase === "summarize" ? "Summarizing" : "Ingesting"} ${file} (${index + 1}/${total})`,- },- });- }- : undefined;- const r = await engine.ingestRepo(dir, { extensions, onProgress });- const lines = [- `Repo ingested: ${r.files} code files → ${r.summarized} summarized, ${r.cached} unchanged (cache hits).`,- ...r.modules.map((m) =>- m.skipped- ? `• ${m.title}: unchanged, skipped`- : `✓ ${m.title}: ${m.chunks} chunks, +${m.nodesCreated} entities, +${m.edgesCreated} relationships`,- ),- ...r.errors.map((e) => `✗ ${e}`),- ];- return { content: [{ type: "text", text: lines.join("\n") }] };- },-);+ async ({ dir, extensions }, extra) => {+ const progressToken = extra?._meta?.progressToken;+ const onProgress = progressToken+ ? ({ phase, index, total, file }: { phase: string; index: number; total: number; file: string }) => {+ void extra.sendNotification({+ method: "notifications/progress",+ params: {+ progressToken,+ progress: index,+ total,+ message: `${phase === "summarize" ? "Summarizing" : "Ingesting"} ${file} (${index + 1}/${total})`,+ },+ });+ }+ : undefined;+ const r = await engine.ingestRepo(dir, { extensions, onProgress });+ const lines = [+ `Repo ingested: ${r.files} code files → ${r.summarized} summarized, ${r.cached} unchanged (cache hits).`,+ ...r.modules.map((m) =>+ m.skipped+ ? `• ${m.title}: unchanged, skipped`+ : `✓ ${m.title}: ${m.chunks} chunks, +${m.nodesCreated} entities, +${m.edgesCreated} relationships`,+ ),+ ...r.errors.map((e) => `✗ ${e}`),+ ];+ return { content: [{ type: "text", text: lines.join("\n") }] };+ },+ );-server.registerTool(- "context_watch_dir",- {- title: "Watch a folder (evolving graph)",- description:- "Connect a folder to the graph and keep it evolving: existing documents are ingested now, " +- "and any file added or edited later is re-ingested automatically for as long as this session " +- "lives. The folder is registered, so `context-graph watch` (or CONTEXT_GRAPH_AUTOWATCH=1) " +- "resumes it in future sessions. Deleting a file forgets what it taught: its facts are pruned " +- "unless still supported by another source.",- inputSchema: {- dir: z.string().describe("Absolute path to the folder to watch."),- extensions: z- .array(z.string())- .optional()- .describe('File extensions to include (e.g. [".md", ".rst"]). Default: .pdf .md .markdown .txt'),+ server.registerTool(+ "context_watch_dir",+ {+ title: "Watch a folder (evolving graph)",+ description:+ "Connect a folder to the graph and keep it evolving: existing documents are ingested now, " ++ "and any file added or edited later is re-ingested automatically for as long as this session " ++ "lives. The folder is registered, so `context-graph watch` (or `context-graph serve`) " ++ "resumes it in future sessions.",+ inputSchema: {+ dir: z.string().describe("Absolute path to the folder to watch."),+ extensions: z+ .array(z.string())+ .optional()+ .describe('File extensions to include (e.g. [".md", ".rst"]). Default: .pdf .md .markdown .txt'),+ },},- },- async ({ dir, extensions }, extra) => {- const w = getWatcher();- // Extensions are fixed per watcher process; a custom set is recorded in- // the registry and takes effect when a daemon starts from it.- engine.addWatchedDir(dir, extensions);+ async ({ dir, extensions }, extra) => {+ const w = deps.getWatcher();+ // Extensions are fixed per watcher process; a custom set is recorded in+ // the registry and takes effect when a daemon starts from it.+ engine.addWatchedDir(dir, extensions);- const progressToken = extra?._meta?.progressToken;- const lines: string[] = [];- let ingested = 0;- let queued = 0;- progressSink = (event) => {- if (event.type === "queued") queued++;- if (event.type === "ingested") {- ingested++;- lines.push(- event.result.skipped- ? `• ${event.result.title}: unchanged, skipped`- : `✓ ${event.result.title}: +${event.result.nodesCreated} entities, +${event.result.edgesCreated} relationships`,- );- if (progressToken) {- void extra.sendNotification({- method: "notifications/progress",- params: {- progressToken,- progress: ingested,- total: queued,- message: `Ingesting ${event.file.split("/").pop()} (${ingested}/${queued})`,- },- });+ const progressToken = extra?._meta?.progressToken;+ const lines: string[] = [];+ let ingested = 0;+ let queued = 0;+ deps.setProgressSink((event) => {+ if (event.type === "queued") queued++;+ if (event.type === "ingested") {+ ingested++;+ lines.push(+ event.result.skipped+ ? `• ${event.result.title}: unchanged, skipped`+ : `✓ ${event.result.title}: +${event.result.nodesCreated} entities, +${event.result.edgesCreated} relationships`,+ );+ if (progressToken) {+ void extra.sendNotification({+ method: "notifications/progress",+ params: {+ progressToken,+ progress: ingested,+ total: queued,+ message: `Ingesting ${event.file.split("/").pop()} (${ingested}/${queued})`,+ },+ });+ }}+ if (event.type === "error") lines.push(`✗ ${event.file}: ${event.error}`);+ });+ try {+ await w.add(dir);+ await w.idle();+ } finally {+ deps.setProgressSink(undefined);}- if (event.type === "error") lines.push(`✗ ${event.file}: ${event.error}`);- };- try {- await w.add(dir);- await w.idle();- } finally {- progressSink = undefined;- }- lines.push(- `\nWatching ${dir} — new and edited files will be ingested automatically while this session lives.`,- );- return { content: [{ type: "text", text: lines.join("\n") }] };- },-);--server.registerTool(- "context_unwatch_dir",- {- title: "Stop watching a folder",- description:- "Stop auto-ingesting a folder and remove it from the watch registry. Knowledge already " +- "learned from it stays in the graph.",- inputSchema: {- dir: z.string().describe("Absolute path of the watched folder to disconnect."),+ lines.push(+ `\nWatching ${dir} — new and edited files will be ingested automatically while this session lives.`,+ );+ return { content: [{ type: "text", text: lines.join("\n") }] };},- },- async ({ dir }) => {- await watcher?.remove(dir);- const removed = engine.removeWatchedDir(dir);- return {- content: [- {- type: "text",- text: removed- ? `Stopped watching ${dir}. Its knowledge remains in the graph.`- : `${dir} was not being watched.`,- },- ],- };- },-);+ );-server.registerTool(- "context_watch_status",- {- title: "Watched folders",- description:- "List folders connected for auto-watching: registered folders, which are live in this session, and the ingest queue size.",- inputSchema: {},- },- async () => {- const registered = engine.listWatchedDirs();- const live = new Set(watcher?.dirs() ?? []);- if (registered.length === 0 && live.size === 0) {+ server.registerTool(+ "context_unwatch_dir",+ {+ title: "Stop watching a folder",+ description:+ "Stop auto-ingesting a folder and remove it from the watch registry. Knowledge already " ++ "learned from it stays in the graph.",+ inputSchema: {+ dir: z.string().describe("Absolute path of the watched folder to disconnect."),+ },+ },+ async ({ dir }) => {+ await peekWatcher()?.remove(dir);+ const removed = engine.removeWatchedDir(dir);return {content: [- { type: "text", text: "No watched folders. Connect one with context_watch_dir." },+ {+ type: "text",+ text: removed+ ? `Stopped watching ${dir}. Its knowledge remains in the graph.`+ : `${dir} was not being watched.`,+ },],};- }- const lines = registered.map(- (wd) => `${live.has(wd.dir) ? "● live" : "○ registered"} ${wd.dir}`,- );- for (const dir of live) {- if (!registered.some((wd) => wd.dir === dir)) lines.push(`● live (unregistered) ${dir}`);- }- const pending = watcher?.pendingCount() ?? 0;- if (pending > 0) lines.push(`\n${pending} file(s) queued for ingestion.`);- 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)."),+ server.registerTool(+ "context_watch_status",+ {+ title: "Watched folders",+ description:+ "List folders connected for auto-watching: registered folders, which are live in this session, and the ingest queue size.",+ inputSchema: {},},- },- async ({ path }) => {- const g = await 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.`,- },- ],- };- },-);+ async () => {+ const registered = engine.listWatchedDirs();+ const w = peekWatcher();+ const live = new Set(w?.dirs() ?? []);+ if (registered.length === 0 && live.size === 0) {+ return {+ content: [+ { type: "text", text: "No watched folders. Connect one with context_watch_dir." },+ ],+ };+ }+ const lines = registered.map(+ (wd) => `${live.has(wd.dir) ? "● live" : "○ registered"} ${wd.dir}`,+ );+ for (const dir of live) {+ if (!registered.some((wd) => wd.dir === dir)) lines.push(`● live (unregistered) ${dir}`);+ }+ const pending = w?.pendingCount() ?? 0;+ if (pending > 0) lines.push(`\n${pending} file(s) queued for ingestion.`);+ return { content: [{ type: "text", text: lines.join("\n") }] };+ },+ );-server.registerTool(- "context_stats",- {- title: "Graph statistics",- description: "Report how much knowledge the shared context graph currently holds.",- inputSchema: {},- },- async () => {- const s = await engine.stats();- return {- content: [- {- type: "text",- text: `documents: ${s.documents}, entities: ${s.nodes}, relationships: ${s.edges}, source passages: ${s.chunks}`,- },- ],- };- },-);+ 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 = await 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_sync",- {- title: "Sync the graph (git mode)",- description:- "Team sync (Mode A): import + re-merge the committed graph file, then write the merged graph back so it can be committed. Idempotent — safe to run repeatedly. Uses graph.jsonl next to the db unless a path is given.",- inputSchema: {- file: z- .string()- .optional()- .describe("Path to the graph JSONL file (default: graph.jsonl next to the db)."),+ server.registerTool(+ "context_stats",+ {+ title: "Graph statistics",+ description: "Report how much knowledge the shared context graph currently holds.",+ inputSchema: {},},- },- async ({ file }) => {- const path = file ?? engine.graphFilePath;- if (!path) {+ async () => {+ const s = await engine.stats();return {- content: [{ type: "text", text: "This graph is in-memory and can't be synced to a file." }],+ content: [+ {+ type: "text",+ text: `documents: ${s.documents}, entities: ${s.nodes}, relationships: ${s.edges}, source passages: ${s.chunks}`,+ },+ ],};- }- const lines: string[] = [];- if (existsSync(path)) {- const r = await engine.importJsonl(readFileSync(path, "utf8"));- for (const w of r.warnings) lines.push(`⚠ ${w}`);- lines.push(- `Merged in: +${r.nodesCreated} entities (${r.nodesUpdated} reinforced), ` +- `+${r.edgesCreated} relationships (${r.edgesUpdated} reinforced).`,- );- }- writeFileSync(path, await engine.exportJsonl());- const s = await engine.stats();- lines.push(`Wrote merged graph (${s.nodes} entities, ${s.edges} relationships) to ${path}.`);- return { content: [{ type: "text", text: lines.join("\n") }] };- },-);+ },+ );++ server.registerTool(+ "context_sync",+ {+ title: "Sync the graph (git mode)",+ description:+ "Team sync (Mode A): import + re-merge the committed graph file, then write the merged graph back so it can be committed. Idempotent — safe to run repeatedly. Uses graph.jsonl next to the db unless a path is given.",+ inputSchema: {+ file: z+ .string()+ .optional()+ .describe("Path to the graph JSONL file (default: graph.jsonl next to the db)."),+ },+ },+ async ({ file }) => {+ const path = file ?? engine.graphFilePath;+ if (!path) {+ return {+ content: [{ type: "text", text: "This graph is in-memory and can't be synced to a file." }],+ };+ }+ const lines: string[] = [];+ if (existsSync(path)) {+ const r = await engine.importJsonl(readFileSync(path, "utf8"));+ for (const w of r.warnings) lines.push(`⚠ ${w}`);+ lines.push(+ `Merged in: +${r.nodesCreated} entities (${r.nodesUpdated} reinforced), ` ++ `+${r.edgesCreated} relationships (${r.edgesUpdated} reinforced).`,+ );+ }+ writeFileSync(path, await engine.exportJsonl());+ const s = await engine.stats();+ lines.push(`Wrote merged graph (${s.nodes} entities, ${s.edges} relationships) to ${path}.`);+ return { content: [{ type: "text", text: lines.join("\n") }] };+ },+ );++ return server;+}+/** Standalone `context-graph-mcp` (stdio) entry point. */async function main(): Promise<void> {+ const engine = new ContextGraphEngine();++ // One lazily-created watcher for the life of this MCP process. Folders added+ // via context_watch_dir keep updating the graph in the background for as long+ // as the client session (and thus this process) lives.+ let watcher: GraphWatcher | undefined;+ let progressSink: ((event: WatchEvent) => void) | undefined;+ const getWatcher = (): GraphWatcher =>+ (watcher ??= new GraphWatcher(engine, {+ onEvent: (event) => {+ // stderr only — stdout is the JSON-RPC channel.+ if (event.type === "error") console.error(`watch: ✗ ${event.file}: ${event.error}`);+ else if (event.type === "ingested" && !event.result.skipped) {+ console.error(`watch: ✓ ${event.result.title} (+${event.result.nodesCreated} entities)`);+ }+ progressSink?.(event);+ },+ }));++ const server = createContextGraphMcpServer({+ engine,+ getWatcher,+ peekWatcher: () => watcher,+ setProgressSink: (sink) => {+ progressSink = sink;+ },+ });+const transport = new StdioServerTransport();await server.connect(transport);// Log to stderr so we don't corrupt the stdio JSON-RPC channel.@@ -457,7 +494,11 @@ async function main(): Promise<void> {}}-main().catch((err) => {- console.error(err);- process.exit(1);-});+// Run the stdio server only when invoked directly (as the `context-graph-mcp`+// bin), not when imported by `serve`.+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {+ main().catch((err) => {+ console.error(err);+ process.exit(1);+ });+}diff --git a/src/serve.ts b/src/serve.tsnew file mode 100644index 00000000..8b1b60a1--- /dev/null+++ b/src/serve.ts@@ -0,0 +1,283 @@+#!/usr/bin/env node+/**+ * `context-graph serve` — the whole engine in one process on one port.+ *+ * Runs a single {@link ContextGraphEngine}, a single {@link GraphWatcher}, the+ * web UI, and the MCP server (over Streamable HTTP) together. This is the+ * supported way to run everything at once: because there is exactly one engine+ * and one watcher, it sidesteps the "one watcher per db" footgun you hit when+ * running `context-graph-web` and a `context-graph watch` daemon side by side+ * (concurrent writers whose merges aren't transactional).+ *+ * Routing on the single HTTP server:+ * - `/mcp` → MCP over Streamable HTTP (POST to call, GET to stream)+ * - everything else → the web UI + `/api/*` (see {@link createWebApp})+ *+ * Env mirrors `context-graph-web`: CONTEXT_GRAPH_DB, PORT (4680), HOST+ * (127.0.0.1), CONTEXT_GRAPH_WEB_TOKEN (also gates `/mcp` when exposed).+ */+import "dotenv/config";+import { createServer, type IncomingMessage, type ServerResponse, type Server } from "node:http";+import { randomUUID } from "node:crypto";+import { fileURLToPath } from "node:url";+import { resolve } from "node:path";+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";+import { ContextGraphEngine } from "./engine.js";+import { GraphWatcher, type WatchEvent } from "./watch.js";+import { resolveConfig, type EngineConfig } from "./ai/providers.js";+import { createWebApp } from "./web.js";+import { createContextGraphMcpServer } from "./mcp.js";++export interface ServeOptions {+ /** Host to bind (default 127.0.0.1; a token guards /api and /mcp when non-loopback). */+ host?: string;+ /** Port to bind (default 4680; 0 picks a free port — handy for tests). */+ port?: number;+ /** Resume registered watch folders (and watch `dirs`) at startup. Default true. */+ watch?: boolean;+ /** Extra folders to register and watch, on top of the persisted registry. */+ dirs?: string[];+ /** Extensions the watcher ingests (default {@link DOC_EXTENSIONS}). */+ extensions?: string[];+ /** Engine config override (tests pass `:memory:` + fake providers here). */+ engineConfig?: EngineConfig;+ /** Provide an engine directly (tests); takes precedence over `engineConfig`. */+ engine?: ContextGraphEngine;+}++export interface RunningServer {+ /** Local URL the server is listening on. */+ url: string;+ /** The bound port (resolved even when `port: 0` was requested). */+ port: number;+ /** The shared engine, for tests/embedding. */+ engine: ContextGraphEngine;+ /** Stop everything: MCP transports, watcher, HTTP server, then the engine. */+ close: () => Promise<void>;+}++/** Read and JSON-parse a request body (for MCP POST bodies). */+function readJson(req: IncomingMessage, maxBytes = 50_000_000): Promise<unknown> {+ return new Promise((res, rej) => {+ let data = "";+ req.on("data", (c) => {+ data += c;+ if (data.length > maxBytes) rej(new Error("body too large"));+ });+ req.on("end", () => {+ try {+ res(data ? JSON.parse(data) : undefined);+ } catch (e) {+ rej(e);+ }+ });+ req.on("error", rej);+ });+}++/**+ * Log a watcher event. A `default` branch deliberately swallows event types this+ * command doesn't know about, so a new {@link WatchEvent} variant (e.g. a+ * significance-skip added elsewhere) can never break `serve`.+ */+function logWatchEvent(event: WatchEvent): void {+ switch (event.type) {+ case "ingested":+ if (!event.result.skipped) {+ console.log(`watch: ✓ ${event.result.title} (+${event.result.nodesCreated} entities)`);+ }+ break;+ case "deleted": {+ const p = event.pruned;+ console.log(+ p+ ? `watch: • ${event.file} deleted (−${p.nodesRemoved} entities, −${p.edgesRemoved} relationships)`+ : `watch: • ${event.file} deleted`,+ );+ break;+ }+ case "error":+ console.error(`watch: ✗ ${event.file}: ${event.error}`);+ break;+ default:+ break;+ }+}++/**+ * Start the unified server. Resolves once it is listening; call the returned+ * {@link RunningServer.close} to shut it down.+ */+export async function startServe(opts: ServeOptions = {}): Promise<RunningServer> {+ const host = opts.host ?? process.env.HOST ?? "127.0.0.1";+ const wantPort = opts.port ?? Number(process.env.PORT ?? 4680);+ const engineConfig = opts.engineConfig ?? {};+ const cfg = resolveConfig(engineConfig);+ const engine = opts.engine ?? new ContextGraphEngine(engineConfig);++ // One shared watcher. Its events are logged and also forwarded to whatever+ // MCP tool call is currently reporting catch-up progress.+ let currentProgressSink: ((event: WatchEvent) => void) | undefined;+ const watcher = new GraphWatcher(engine, {+ extensions: opts.extensions,+ onEvent: (event) => {+ logWatchEvent(event);+ currentProgressSink?.(event);+ },+ });++ const app = createWebApp({+ engine,+ cfg,+ host,+ port: wantPort,+ ensureWatcher: () => watcher,+ getWatcher: () => watcher,+ });++ // --- MCP over Streamable HTTP: one transport (and server) per client session ---+ const transports: Record<string, StreamableHTTPServerTransport> = {};++ async function handleMcp(req: IncomingMessage, res: ServerResponse): Promise<void> {+ // Gate /mcp with the same bearer token the web /api uses when exposed.+ if (app.exposed && !app.isAuthorized(req)) {+ res.writeHead(401, { "content-type": "application/json" });+ res.end(JSON.stringify({ error: "access token required" }));+ return;+ }++ const sid = req.headers["mcp-session-id"] as string | undefined;++ if (req.method === "POST") {+ const body = await readJson(req);+ let transport = sid ? transports[sid] : undefined;+ if (!transport) {+ // A new session must open with an `initialize` request and no session id.+ if (sid || !isInitializeRequest(body)) {+ res.writeHead(400, { "content-type": "application/json" });+ res.end(+ JSON.stringify({+ jsonrpc: "2.0",+ error: { code: -32000, message: "Bad Request: no valid session" },+ id: null,+ }),+ );+ return;+ }+ transport = new StreamableHTTPServerTransport({+ sessionIdGenerator: () => randomUUID(),+ onsessioninitialized: (id) => {+ transports[id] = transport!;+ },+ });+ transport.onclose = () => {+ const id = transport!.sessionId;+ if (id) delete transports[id];+ };+ const mcp = createContextGraphMcpServer({+ engine,+ getWatcher: () => watcher,+ peekWatcher: () => watcher,+ setProgressSink: (sink) => {+ currentProgressSink = sink;+ },+ });+ await mcp.connect(transport);+ }+ await transport.handleRequest(req, res, body);+ return;+ }++ // GET (SSE stream) and DELETE (end session) require an established session.+ if (!sid || !transports[sid]) {+ res.writeHead(400, { "content-type": "application/json" });+ res.end(JSON.stringify({ error: "invalid or missing mcp-session-id" }));+ return;+ }+ await transports[sid].handleRequest(req, res);+ }++ const server: Server = createServer((req, res) => {+ const url = new URL(req.url ?? "/", `http://localhost:${wantPort}`);+ if (url.pathname === "/mcp") {+ void handleMcp(req, res).catch((e) => {+ if (!res.headersSent) {+ res.writeHead(500, { "content-type": "application/json" });+ res.end(JSON.stringify({ error: e instanceof Error ? e.message : String(e) }));+ }+ });+ return;+ }+ void app.handler(req, res);+ });++ // Resume registered watch folders (and any passed on the CLI) in the+ // background — the catch-up scan is a cheap hash-dedup pass for already-known+ // content, so we don't hold up listening on it.+ if (opts.watch !== false) {+ for (const d of opts.dirs ?? []) engine.addWatchedDir(d, opts.extensions);+ const registered = engine.listWatchedDirs();+ for (const wd of registered) {+ watcher.add(wd.dir).catch((err) =>+ console.error(`watch: ✗ ${wd.dir}: ${err instanceof Error ? err.message : String(err)}`),+ );+ }+ }++ await new Promise<void>((res) => server.listen(wantPort, host, res));+ const addr = server.address();+ const port = typeof addr === "object" && addr ? addr.port : wantPort;+ const url = `http://${host}:${port}`;++ const close = async (): Promise<void> => {+ for (const t of Object.values(transports)) {+ try {+ await t.close();+ } catch {+ /* ignore */+ }+ }+ await watcher.close();+ await new Promise<void>((res) => server.close(() => res()));+ await engine.close();+ };++ return { url, port, engine, close };+}++/** Standalone `context-graph-serve` entry point. */+async function main(): Promise<void> {+ const running = await startServe();+ const cfg = resolveConfig();+ const watchedCount = running.engine.listWatchedDirs().length;++ console.log(`Context Graph → ${running.url}`);+ console.log(` web UI: ${running.url}`);+ console.log(` MCP (HTTP): ${running.url}/mcp`);+ console.log(` graph db: ${resolve(cfg.dbPath)}`);+ console.log(+ ` extraction: ${cfg.openrouterApiKey && !cfg.forceLocal ? `openrouter (${cfg.openrouterModel})` : `ollama (${cfg.ollamaModel})`}`,+ );+ console.log(` embeddings: ${cfg.openaiApiKey && !cfg.forceLocal ? "openai" : "local"}`);+ if (watchedCount > 0) console.log(` watching: ${watchedCount} registered folder(s)`);++ let stopping = false;+ const stop = async () => {+ if (stopping) return;+ stopping = true;+ console.log("\nstopping…");+ await running.close();+ process.exit(0);+ };+ process.on("SIGINT", () => void stop());+ process.on("SIGTERM", () => void stop());+}++// Run only when invoked directly (the `context-graph-serve` bin / `serve` cmd).+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {+ main().catch((err) => {+ console.error(err);+ process.exit(1);+ });+}diff --git a/src/web.ts b/src/web.tsindex deca28a5..5c509585 100644--- a/src/web.ts+++ b/src/web.ts@@ -7,6 +7,11 @@* as documents are ingested; contribute learnings back. Serves a single* self-contained page from ./web/ui.html.*+ * The request handling is packaged as {@link createWebApp} so the unified+ * `context-graph serve` command can mount it alongside the MCP-over-HTTP+ * endpoint on one port, sharing a single engine and watcher. Run directly+ * (`context-graph-web`) it keeps its original standalone behavior.+ ** Env: CONTEXT_GRAPH_DB (graph file), PORT (default 4680),* HOST (default 127.0.0.1 — set 0.0.0.0 to expose on a network, e.g. Docker),* CONTEXT_GRAPH_WEB_TOKEN (access token for /api; auto-generated and@@ -19,64 +24,17 @@ import { createServer, type IncomingMessage, type ServerResponse } from "node:htimport { createHash, randomBytes, timingSafeEqual } from "node:crypto";import { readFileSync, writeFileSync, existsSync, statSync, mkdirSync } from "node:fs";import { networkInterfaces } from "node:os";+import { fileURLToPath } from "node:url";import { resolve, dirname, join } from "node:path";import OpenAI from "openai";import { ContextGraphEngine } from "./engine.js";import { GraphWatcher } from "./watch.js";-import { resolveConfig } from "./ai/providers.js";+import { resolveConfig, type ResolvedConfig } from "./ai/providers.js";import { extractPdfTextFromData, isPdfPath } from "./ingest/pdf.js";-const PORT = Number(process.env.PORT ?? 4680);-const HOST = process.env.HOST ?? "127.0.0.1";-const engine = new ContextGraphEngine();-const cfg = resolveConfig();+const LOCAL_HOSTNAMES = new Set(["localhost", "127.0.0.1", "[::1]", "::1"]);-const uiPath = new URL("./web/ui.html", import.meta.url);--/** Which extraction/answer provider is live, so the UI can say so honestly. */-function providerStatus() {- return {- extraction: cfg.openrouterApiKey && !cfg.forceLocal ? "openrouter" : "ollama",- embeddings: cfg.openaiApiKey && !cfg.forceLocal ? "openai" : "local",- canSynthesize: Boolean(cfg.openrouterApiKey && !cfg.forceLocal),- model: cfg.openrouterApiKey ? cfg.openrouterModel : cfg.ollamaModel,- db: resolve(cfg.dbPath),- };-}--/** Synthesize a grounded natural-language answer from a retrieval bundle. */-async function synthesizeAnswer(- question: string,- prompt: string,- sourceTitles: string[],-): Promise<string> {- const client = new OpenAI({- apiKey: cfg.openrouterApiKey,- baseURL: cfg.openrouterBaseUrl,- defaultHeaders: { "X-Title": "Context Graph Web" },- });- const response = await client.chat.completions.create({- model: cfg.openrouterModel,- temperature: 0,- messages: [- {- role: "system",- content:- "You answer questions using ONLY the provided context from a team knowledge graph. " +- "Be direct and specific. Cite sources inline with bracketed numbers like [1], [2] " +- "matching the numbered source list. If the context does not contain the answer, say " +- "exactly what is missing — never invent facts.",- },- {- role: "user",- content: `${prompt}\n\n## Numbered sources\n${sourceTitles- .map((t, i) => `[${i + 1}] ${t}`)- .join("\n")}\n\n## Question\n${question}`,- },- ],- });- return response.choices[0]?.message?.content ?? "";-}+// --- pure helpers (no module state) ---function readBody(req: IncomingMessage, maxBytes = 10_000_000): Promise<string> {return new Promise((res, rej) => {@@ -96,91 +54,6 @@ function json(res: ServerResponse, status: number, body: unknown): void {res.end(payload);}-const LOCAL_HOSTNAMES = new Set(["localhost", "127.0.0.1", "[::1]", "::1"]);--/**- * Directory that holds durable server state (the graph db, and the persisted- * access token). Defaults next to the SQLite file so it rides the same mounted- * volume in Docker. Undefined for an in-memory db — nothing to persist.- */-function dataDir(): string | undefined {- if (cfg.dbPath === ":memory:") return undefined;- return dirname(resolve(cfg.dbPath));-}--/**- * Resolve the access token, persisting a generated one so it survives restarts.- *- * Precedence: an explicit CONTEXT_GRAPH_WEB_TOKEN always wins (and is never- * written to disk). Otherwise, when exposed, reuse a previously persisted token- * or mint one and save it (owner-only) beside the db — so a `docker compose- * restart` no longer invalidates every teammate's saved link. Also drops a- * human-readable share-link.txt so the deployer never has to grep the logs.- */-function resolveWebToken(): { token?: string; sharePath?: string } {- const explicit = process.env.CONTEXT_GRAPH_WEB_TOKEN?.trim();- if (explicit) return { token: explicit };- if (!EXPOSED) return {};-- const dir = dataDir();- if (!dir) return { token: randomBytes(18).toString("base64url") };-- const tokenPath = join(dir, ".web-token");- let token: string;- try {- token = existsSync(tokenPath) ? readFileSync(tokenPath, "utf8").trim() : "";- if (!token) {- token = randomBytes(18).toString("base64url");- mkdirSync(dir, { recursive: true });- writeFileSync(tokenPath, token + "\n", { mode: 0o600 });- }- } catch {- // Read-only volume or similar — fall back to an in-memory token so the- // server still starts (it'll just change on restart, as before).- return { token: randomBytes(18).toString("base64url") };- }-- // Best-effort human-readable share file; failure here must not block startup.- let sharePath: string | undefined;- try {- const lan = lanAddress();- const base = lan ? `http://${lan}:${PORT}` : `http://<this-machine>:${PORT}`;- const share = join(dir, "share-link.txt");- writeFileSync(- share,- `Context Graph — team access\n\n` +- `Access token:\n ${token}\n\n` +- `Share this link with your team (opens the UI already signed in):\n ${base}/#token=${token}\n\n` +- `On this machine, use:\n http://localhost:${PORT}/#token=${token}\n`,- { mode: 0o600 },- );- sharePath = share;- } catch {- /* ignore */- }- return { token, sharePath };-}--/**- * Access token for the API. On the loopback default no token is needed — the- * OS already gates who can reach the port. The moment the server is exposed- * beyond loopback (HOST=0.0.0.0, Docker, a VPS) a token is required: taken- * from CONTEXT_GRAPH_WEB_TOKEN, or persisted next to the db and printed at- * startup (see resolveWebToken).- */-const EXPOSED = !LOCAL_HOSTNAMES.has(HOST);-const { token: WEB_TOKEN, sharePath: SHARE_PATH } = resolveWebToken();--function isAuthorized(req: IncomingMessage): boolean {- if (!WEB_TOKEN) return true;- const header = req.headers.authorization ?? "";- const presented = header.startsWith("Bearer ") ? header.slice(7) : "";- // Hash both sides so timingSafeEqual gets equal-length buffers.- const a = createHash("sha256").update(presented).digest();- const b = createHash("sha256").update(WEB_TOKEN).digest();- return timingSafeEqual(a, b);-}-/** Best-guess LAN address, to print a ready-to-share URL at startup. */function lanAddress(): string | undefined {for (const addrs of Object.values(networkInterfaces())) {@@ -202,249 +75,457 @@ function hostnameOf(headerValue: string | undefined): string | undefined {}}+/** Which extraction/answer/embedding providers are live, for the UI to display honestly. */+export interface ProviderStatus {+ extraction: string;+ embeddings: string;+ canSynthesize: boolean;+ model: string;+ db: string;+}++export interface WebAppOptions {+ /** The (shared) engine backing the UI. */+ engine: ContextGraphEngine;+ /** Resolved config; defaults to {@link resolveConfig}. */+ cfg?: ResolvedConfig;+ /** Host the server binds to — decides whether an access token is required. */+ host: string;+ /** Port the server listens on — used only to render share links. */+ port: number;+ /** Lazily create (or return) the watcher used for in-process auto-watch. */+ ensureWatcher: () => GraphWatcher;+ /** Peek at the live watcher without creating one (for status endpoints). */+ getWatcher?: () => GraphWatcher | undefined;+}++export interface WebApp {+ /** node:http request handler for the UI + /api/* endpoints. */+ handler: (req: IncomingMessage, res: ServerResponse) => void;+ /** True if a presented bearer token authorizes /api access (always true when unguarded). */+ isAuthorized: (req: IncomingMessage) => boolean;+ /** Whether the server is exposed beyond loopback (a token is then required). */+ exposed: boolean;+ /** The active access token, if any. */+ webToken?: string;+ /** Path of the human-readable share-link file, if written. */+ sharePath?: string;+ /** Which extraction/answer/embedding providers are live. */+ providerStatus: () => ProviderStatus;+}+/**- * Browser-facing hardening for a loopback server: a malicious webpage must not- * be able to drive state-changing endpoints (CSRF) or read responses via DNS- * rebinding. When HOST is loopback (the default), only localhost Host headers- * are accepted; POSTs must be application/json and, if a browser sent an- * Origin, it must be a localhost origin too.+ * Build the web request handler over a given engine. The handler is transport+ * agnostic: `context-graph-web`'s `main()` wraps it in its own HTTP server, and+ * `context-graph serve` mounts it behind a router that also serves `/mcp`.*/-function rejectForeignRequest(req: IncomingMessage, res: ServerResponse): boolean {- const boundToLoopback = LOCAL_HOSTNAMES.has(HOST);- if (boundToLoopback) {- const host = hostnameOf(req.headers.host);- if (!host || !LOCAL_HOSTNAMES.has(host)) {- json(res, 403, { error: "forbidden: unexpected Host header" });- return true;- }+export function createWebApp(opts: WebAppOptions): WebApp {+ const { engine, host, port, ensureWatcher } = opts;+ const cfg = opts.cfg ?? resolveConfig();+ const getWatcher = opts.getWatcher ?? (() => undefined);+ const uiPath = new URL("./web/ui.html", import.meta.url);+ const EXPOSED = !LOCAL_HOSTNAMES.has(host);++ /** Which extraction/answer provider is live, so the UI can say so honestly. */+ function providerStatus(): ProviderStatus {+ return {+ extraction: cfg.openrouterApiKey && !cfg.forceLocal ? "openrouter" : "ollama",+ embeddings: cfg.openaiApiKey && !cfg.forceLocal ? "openai" : "local",+ canSynthesize: Boolean(cfg.openrouterApiKey && !cfg.forceLocal),+ model: cfg.openrouterApiKey ? cfg.openrouterModel : cfg.ollamaModel,+ db: resolve(cfg.dbPath),+ };}- if (req.method === "POST") {- if (!(req.headers["content-type"] ?? "").startsWith("application/json")) {- json(res, 415, { error: "content-type must be application/json" });- return true;- }- const origin = hostnameOf(req.headers.origin);- if (boundToLoopback && req.headers.origin && (!origin || !LOCAL_HOSTNAMES.has(origin))) {- json(res, 403, { error: "forbidden: cross-origin request" });- return true;- }++ /** Synthesize a grounded natural-language answer from a retrieval bundle. */+ async function synthesizeAnswer(+ question: string,+ prompt: string,+ sourceTitles: string[],+ ): Promise<string> {+ const client = new OpenAI({+ apiKey: cfg.openrouterApiKey,+ baseURL: cfg.openrouterBaseUrl,+ defaultHeaders: { "X-Title": "Context Graph Web" },+ });+ const response = await client.chat.completions.create({+ model: cfg.openrouterModel,+ temperature: 0,+ messages: [+ {+ role: "system",+ content:+ "You answer questions using ONLY the provided context from a team knowledge graph. " ++ "Be direct and specific. Cite sources inline with bracketed numbers like [1], [2] " ++ "matching the numbered source list. If the context does not contain the answer, say " ++ "exactly what is missing — never invent facts.",+ },+ {+ role: "user",+ content: `${prompt}\n\n## Numbered sources\n${sourceTitles+ .map((t, i) => `[${i + 1}] ${t}`)+ .join("\n")}\n\n## Question\n${question}`,+ },+ ],+ });+ return response.choices[0]?.message?.content ?? "";}- return false;-}-const server = createServer(async (req, res) => {- const url = new URL(req.url ?? "/", `http://localhost:${PORT}`);- try {- if (rejectForeignRequest(req, res)) return;- if (req.method === "GET" && (url.pathname === "/" || url.pathname === "/index.html")) {- // The page itself is public — it holds no data. All data flows through- // /api/*, which is what the token gates.- res.writeHead(200, { "content-type": "text/html; charset=utf-8" });- res.end(readFileSync(uiPath, "utf8"));- return;- }+ /**+ * Directory that holds durable server state (the graph db, and the persisted+ * access token). Defaults next to the SQLite file so it rides the same mounted+ * volume in Docker. Undefined for an in-memory db — nothing to persist.+ */+ function dataDir(): string | undefined {+ if (cfg.dbPath === ":memory:") return undefined;+ return dirname(resolve(cfg.dbPath));+ }- if (url.pathname.startsWith("/api/") && !isAuthorized(req)) {- return json(res, 401, { error: "access token required" });+ /**+ * Resolve the access token, persisting a generated one so it survives restarts.+ *+ * Precedence: an explicit CONTEXT_GRAPH_WEB_TOKEN always wins (and is never+ * written to disk). Otherwise, when exposed, reuse a previously persisted token+ * or mint one and save it (owner-only) beside the db — so a `docker compose+ * restart` no longer invalidates every teammate's saved link. Also drops a+ * human-readable share-link.txt so the deployer never has to grep the logs.+ */+ function resolveWebToken(): { token?: string; sharePath?: string } {+ const explicit = process.env.CONTEXT_GRAPH_WEB_TOKEN?.trim();+ if (explicit) return { token: explicit };+ if (!EXPOSED) return {};++ const dir = dataDir();+ if (!dir) return { token: randomBytes(18).toString("base64url") };++ const tokenPath = join(dir, ".web-token");+ let token: string;+ try {+ token = existsSync(tokenPath) ? readFileSync(tokenPath, "utf8").trim() : "";+ if (!token) {+ token = randomBytes(18).toString("base64url");+ mkdirSync(dir, { recursive: true });+ writeFileSync(tokenPath, token + "\n", { mode: 0o600 });+ }+ } catch {+ // Read-only volume or similar — fall back to an in-memory token so the+ // server still starts (it'll just change on restart, as before).+ return { token: randomBytes(18).toString("base64url") };}- if (req.method === "GET" && url.pathname === "/api/stats") {- json(res, 200, { ...(await engine.stats()), provider: providerStatus() });- return;+ // Best-effort human-readable share file; failure here must not block startup.+ let sharePath: string | undefined;+ try {+ const lan = lanAddress();+ const base = lan ? `http://${lan}:${port}` : `http://<this-machine>:${port}`;+ const share = join(dir, "share-link.txt");+ writeFileSync(+ share,+ `Context Graph — team access\n\n` ++ `Access token:\n ${token}\n\n` ++ `Share this link with your team (opens the UI already signed in):\n ${base}/#token=${token}\n\n` ++ `On this machine, use:\n http://localhost:${port}/#token=${token}\n`,+ { mode: 0o600 },+ );+ sharePath = share;+ } catch {+ /* ignore */}+ return { token, sharePath };+ }- if (req.method === "GET" && url.pathname === "/api/graph") {- json(res, 200, await engine.exportGraph());- return;- }+ const { token: WEB_TOKEN, sharePath: SHARE_PATH } = resolveWebToken();- if (req.method === "GET" && url.pathname === "/api/documents") {- json(res, 200, await engine.store.allDocuments());- return;- }+ function isAuthorized(req: IncomingMessage): boolean {+ if (!WEB_TOKEN) return true;+ const header = req.headers.authorization ?? "";+ const presented = header.startsWith("Bearer ") ? header.slice(7) : "";+ // Hash both sides so timingSafeEqual gets equal-length buffers.+ const a = createHash("sha256").update(presented).digest();+ const b = createHash("sha256").update(WEB_TOKEN).digest();+ return timingSafeEqual(a, b);+ }- if (req.method === "GET" && url.pathname === "/api/watched") {- json(res, 200, {- registered: engine.listWatchedDirs(),- live: webWatcher?.dirs() ?? [],- pending: webWatcher?.pendingCount() ?? 0,- });- return;+ /**+ * Browser-facing hardening for a loopback server: a malicious webpage must not+ * be able to drive state-changing endpoints (CSRF) or read responses via DNS+ * rebinding. When host is loopback (the default), only localhost Host headers+ * are accepted; POSTs must be application/json and, if a browser sent an+ * Origin, it must be a localhost origin too.+ */+ function rejectForeignRequest(req: IncomingMessage, res: ServerResponse): boolean {+ const boundToLoopback = LOCAL_HOSTNAMES.has(host);+ if (boundToLoopback) {+ const h = hostnameOf(req.headers.host);+ if (!h || !LOCAL_HOSTNAMES.has(h)) {+ json(res, 403, { error: "forbidden: unexpected Host header" });+ return true;+ }}+ if (req.method === "POST") {+ if (!(req.headers["content-type"] ?? "").startsWith("application/json")) {+ json(res, 415, { error: "content-type must be application/json" });+ return true;+ }+ const origin = hostnameOf(req.headers.origin);+ if (boundToLoopback && req.headers.origin && (!origin || !LOCAL_HOSTNAMES.has(origin))) {+ json(res, 403, { error: "forbidden: cross-origin request" });+ return true;+ }+ }+ return false;+ }++ const handler = async (req: IncomingMessage, res: ServerResponse): Promise<void> => {+ const url = new URL(req.url ?? "/", `http://localhost:${port}`);+ try {+ if (rejectForeignRequest(req, res)) return;+ if (req.method === "GET" && (url.pathname === "/" || url.pathname === "/index.html")) {+ // The page itself is public — it holds no data. All data flows through+ // /api/*, which is what the token gates.+ res.writeHead(200, { "content-type": "text/html; charset=utf-8" });+ res.end(readFileSync(uiPath, "utf8"));+ return;+ }++ if (url.pathname.startsWith("/api/") && !isAuthorized(req)) {+ return json(res, 401, { error: "access token required" });+ }++ if (req.method === "GET" && url.pathname === "/api/stats") {+ json(res, 200, { ...(await engine.stats()), provider: providerStatus() });+ return;+ }++ if (req.method === "GET" && url.pathname === "/api/graph") {+ json(res, 200, await engine.exportGraph());+ return;+ }++ if (req.method === "GET" && url.pathname === "/api/documents") {+ json(res, 200, await engine.store.allDocuments());+ return;+ }++ if (req.method === "GET" && url.pathname === "/api/watched") {+ const live = getWatcher();+ json(res, 200, {+ registered: engine.listWatchedDirs(),+ live: live?.dirs() ?? [],+ pending: live?.pendingCount() ?? 0,+ });+ return;+ }++ if (req.method === "POST" && url.pathname === "/api/ask") {+ const { question } = JSON.parse(await readBody(req)) as { question?: string };+ if (!question?.trim()) return json(res, 400, { error: "question is required" });++ const bundle = await engine.read(question, { maxNodes: 8, maxChunks: 6 });+ let answer: string | null = null;+ if (providerStatus().canSynthesize && (bundle.nodes.length || bundle.chunks.length)) {+ try {+ answer = await synthesizeAnswer(+ question,+ bundle.prompt,+ bundle.chunks.map((c) => c.documentTitle),+ );+ } catch (e) {+ // Answer synthesis is an upgrade, not a requirement — degrade to the+ // structured bundle rather than failing the whole request.+ answer = null;+ }+ }+ json(res, 200, { answer, bundle });+ return;+ }- if (req.method === "POST" && url.pathname === "/api/ask") {- const { question } = JSON.parse(await readBody(req)) as { question?: string };- if (!question?.trim()) return json(res, 400, { error: "question is required" });+ if (req.method === "POST" && url.pathname === "/api/ingest-dir") {+ // Accepts a directory or a single file on the server's disk. With+ // watch:true the directory is also registered and watched in-process,+ // so future edits keep flowing into the graph while the server runs.+ const { dir, extensions, watch } = JSON.parse(await readBody(req)) as {+ dir?: string;+ extensions?: string[];+ watch?: boolean;+ };+ if (!dir?.trim()) return json(res, 400, { error: "dir is required" });+ const abs = resolve(dir);+ if (!existsSync(abs)) {+ return json(res, 400, { error: `no such file or directory: ${abs}` });+ }+ const isDir = statSync(abs).isDirectory();- const bundle = await engine.read(question, { maxNodes: 8, maxChunks: 6 });- let answer: string | null = null;- if (providerStatus().canSynthesize && (bundle.nodes.length || bundle.chunks.length)) {+ // Stream progress as NDJSON so the UI can narrate a long ingest live.+ res.writeHead(200, { "content-type": "application/x-ndjson", "cache-control": "no-store" });+ const emit = (event: unknown) => res.write(JSON.stringify(event) + "\n");try {- answer = await synthesizeAnswer(- question,- bundle.prompt,- bundle.chunks.map((c) => c.documentTitle),- );+ const results = isDir+ ? await engine.ingestDir(abs, {+ extensions,+ onProgress: (info) => emit({ type: "progress", ...info }),+ })+ : [await engine.ingestFile(abs)];+ let watching = false;+ if (watch && isDir) {+ engine.addWatchedDir(abs, extensions);+ // The just-finished ingest makes the watcher's catch-up scan a+ // pure hash-dedup pass — no LLM calls. Don't hold the response.+ void ensureWatcher()+ .add(abs)+ .catch((e) => console.error(`watch: ✗ ${abs}: ${e instanceof Error ? e.message : String(e)}`));+ watching = true;+ }+ emit({ type: "done", results, watching, stats: await engine.stats() });} catch (e) {- // Answer synthesis is an upgrade, not a requirement — degrade to the- // structured bundle rather than failing the whole request.- answer = null;+ emit({ type: "error", error: e instanceof Error ? e.message : String(e) });}+ res.end();+ return;}- json(res, 200, { answer, bundle });- return;- }- if (req.method === "POST" && url.pathname === "/api/ingest-dir") {- // Accepts a directory or a single file on the server's disk. With- // watch:true the directory is also registered and watched in-process,- // so future edits keep flowing into the graph while the server runs.- const { dir, extensions, watch } = JSON.parse(await readBody(req)) as {- dir?: string;- extensions?: string[];- watch?: boolean;- };- if (!dir?.trim()) return json(res, 400, { error: "dir is required" });- const abs = resolve(dir);- if (!existsSync(abs)) {- return json(res, 400, { error: `no such file or directory: ${abs}` });- }- const isDir = statSync(abs).isDirectory();-- // Stream progress as NDJSON so the UI can narrate a long ingest live.- res.writeHead(200, { "content-type": "application/x-ndjson", "cache-control": "no-store" });- const emit = (event: unknown) => res.write(JSON.stringify(event) + "\n");- try {- const results = isDir- ? await engine.ingestDir(abs, {- extensions,- onProgress: (info) => emit({ type: "progress", ...info }),- })- : [await engine.ingestFile(abs)];- let watching = false;- if (watch && isDir) {- engine.addWatchedDir(abs, extensions);- // The just-finished ingest makes the watcher's catch-up scan a- // pure hash-dedup pass — no LLM calls. Don't hold the response.- void ensureWebWatcher()- .add(abs)- .catch((e) => console.error(`watch: ✗ ${abs}: ${e instanceof Error ? e.message : String(e)}`));- watching = true;+ if (req.method === "POST" && url.pathname === "/api/ingest-upload") {+ // One uploaded file at a time (the browser folder picker can't hand us a+ // server path, so it ships file contents instead). Text files arrive as+ // `text`; PDFs and other binaries arrive base64-encoded in `dataBase64`.+ // `relPath` (folder/sub/file.md) keys the document when present, so two+ // same-named files in different folders don't replace each other and a+ // synced folder's re-uploads update the right document.+ // 60 MB cap leaves room for a large PDF plus base64's ~33% overhead.+ const { name, relPath, text, dataBase64 } = JSON.parse(await readBody(req, 60_000_000)) as {+ name?: string;+ relPath?: string;+ text?: string;+ dataBase64?: string;+ };+ if (!name?.trim()) return json(res, 400, { error: "name is required" });++ let content: string;+ if (isPdfPath(name)) {+ if (!dataBase64) return json(res, 400, { error: "PDF upload needs dataBase64" });+ content = await extractPdfTextFromData(new Uint8Array(Buffer.from(dataBase64, "base64")));+ } else {+ content = text ?? "";}- emit({ type: "done", results, watching, stats: await engine.stats() });- } catch (e) {- emit({ type: "error", error: e instanceof Error ? e.message : String(e) });+ if (!content.trim()) return json(res, 200, { skipped: true, name, empty: true });++ const result = await engine.ingest(content, {+ title: name,+ source: relPath?.trim() || name,+ });+ json(res, 200, { result, stats: await engine.stats() });+ return;}- res.end();- return;- }- if (req.method === "POST" && url.pathname === "/api/ingest-upload") {- // One uploaded file at a time (the browser folder picker can't hand us a- // server path, so it ships file contents instead). Text files arrive as- // `text`; PDFs and other binaries arrive base64-encoded in `dataBase64`.- // `relPath` (folder/sub/file.md) keys the document when present, so two- // same-named files in different folders don't replace each other and a- // synced folder's re-uploads update the right document.- // 60 MB cap leaves room for a large PDF plus base64's ~33% overhead.- const { name, relPath, text, dataBase64 } = JSON.parse(await readBody(req, 60_000_000)) as {- name?: string;- relPath?: string;- text?: string;- dataBase64?: string;- };- if (!name?.trim()) return json(res, 400, { error: "name is required" });-- let content: string;- if (isPdfPath(name)) {- if (!dataBase64) return json(res, 400, { error: "PDF upload needs dataBase64" });- content = await extractPdfTextFromData(new Uint8Array(Buffer.from(dataBase64, "base64")));- } else {- content = text ?? "";+ if (req.method === "POST" && url.pathname === "/api/contribute") {+ const { learning, agentId } = JSON.parse(await readBody(req)) as {+ learning?: string;+ agentId?: string;+ };+ if (!learning?.trim()) return json(res, 400, { error: "learning is required" });+ const result = await engine.contribute(learning, { agentId: agentId || "web-user" });+ json(res, 200, { ...result, stats: await engine.stats() });+ return;}- if (!content.trim()) return json(res, 200, { skipped: true, name, empty: true });-- const result = await engine.ingest(content, {- title: name,- source: relPath?.trim() || name,- });- json(res, 200, { result, stats: await engine.stats() });- return;- }- if (req.method === "POST" && url.pathname === "/api/contribute") {- const { learning, agentId } = JSON.parse(await readBody(req)) as {- learning?: string;- agentId?: string;- };- if (!learning?.trim()) return json(res, 400, { error: "learning is required" });- const result = await engine.contribute(learning, { agentId: agentId || "web-user" });- json(res, 200, { ...result, stats: await engine.stats() });- return;+ json(res, 404, { error: "not found" });+ } catch (e) {+ json(res, 500, { error: e instanceof Error ? e.message : String(e) });}+ };- json(res, 404, { error: "not found" });- } catch (e) {- json(res, 500, { error: e instanceof Error ? e.message : String(e) });- }-});--// In-process auto-watch. Created lazily: by CONTEXT_GRAPH_WATCH=1 at startup-// (resumes registered folders), or the first time the UI ingests a server-// path with "keep watching" enabled.-let webWatcher: GraphWatcher | undefined;--function ensureWebWatcher(): GraphWatcher {- return (webWatcher ??= new GraphWatcher(engine, {- onEvent: (event) => {- if (event.type === "ingested" && !event.result.skipped) {- console.log(`watch: ✓ ${event.result.title} (+${event.result.nodesCreated} entities)`);- } else if (event.type === "deleted") {- const p = event.pruned;- const detail = p ? ` (pruned ${p.nodesRemoved} entities, ${p.edgesRemoved} relationships)` : "";- console.log(`watch: • ${event.file} deleted${detail}`);- } else if (event.type === "error") {- console.error(`watch: ✗ ${event.file}: ${event.error}`);- }- },- }));+ return {+ handler,+ isAuthorized,+ exposed: EXPOSED,+ webToken: WEB_TOKEN,+ sharePath: SHARE_PATH,+ providerStatus,+ };}-if (process.env.CONTEXT_GRAPH_WATCH === "1") {- const dirs = engine.listWatchedDirs();- if (dirs.length > 0) {- for (const wd of dirs) {- ensureWebWatcher()- .add(wd.dir)- .catch((err) =>- console.error(`watch: ✗ ${wd.dir}: ${err instanceof Error ? err.message : String(err)}`),- );+/** Standalone `context-graph-web` entry point. */+async function main(): Promise<void> {+ const PORT = Number(process.env.PORT ?? 4680);+ const HOST = process.env.HOST ?? "127.0.0.1";+ const engine = new ContextGraphEngine();++ // In-process auto-watch. Created lazily: by CONTEXT_GRAPH_WATCH=1 at startup+ // (resumes registered folders), or the first time the UI ingests a server+ // path with "keep watching" enabled.+ let webWatcher: GraphWatcher | undefined;+ const ensureWatcher = (): GraphWatcher =>+ (webWatcher ??= new GraphWatcher(engine, {+ onEvent: (event) => {+ if (event.type === "ingested" && !event.result.skipped) {+ console.log(`watch: ✓ ${event.result.title} (+${event.result.nodesCreated} entities)`);+ } else if (event.type === "deleted") {+ const p = event.pruned;+ console.log(+ p+ ? `watch: • ${event.file} deleted (−${p.nodesRemoved} entities, −${p.edgesRemoved} relationships)`+ : `watch: • ${event.file} deleted`,+ );+ } else if (event.type === "error") {+ console.error(`watch: ✗ ${event.file}: ${event.error}`);+ }+ },+ }));++ const app = createWebApp({+ engine,+ host: HOST,+ port: PORT,+ ensureWatcher,+ getWatcher: () => webWatcher,+ });++ if (process.env.CONTEXT_GRAPH_WATCH === "1") {+ const dirs = engine.listWatchedDirs();+ if (dirs.length > 0) {+ for (const wd of dirs) {+ ensureWatcher()+ .add(wd.dir)+ .catch((err) =>+ console.error(`watch: ✗ ${wd.dir}: ${err instanceof Error ? err.message : String(err)}`),+ );+ }+ } else {+ console.log("CONTEXT_GRAPH_WATCH=1 but no folders are registered — run: context-graph watch <dir>");}- } else {- console.log("CONTEXT_GRAPH_WATCH=1 but no folders are registered — run: context-graph watch <dir>");}++ const server = createServer(app.handler);+ server.listen(PORT, HOST, () => {+ const p = app.providerStatus();+ console.log(`Context Graph web UI → http://localhost:${PORT}`);+ if (app.exposed && app.webToken) {+ const lan = lanAddress();+ console.log(` access token: ${app.webToken}`);+ // Token travels in the URL *fragment*: browsers never send fragments over+ // the network, so it can't leak into proxy or access logs.+ if (lan) console.log(` share with your team: http://${lan}:${PORT}/#token=${app.webToken}`);+ else console.log(` share: http://<this-machine>:${PORT}/#token=${app.webToken}`);+ // The same link is written to a file on the mounted volume, so the deployer+ // (who ran `docker compose up -d` and sees no logs) can just open it.+ if (app.sharePath) console.log(` share link also saved to: ${app.sharePath}`);+ }+ console.log(` graph db: ${p.db}`);+ console.log(` extraction: ${p.extraction} (${p.model})`);+ console.log(` embeddings: ${p.embeddings}`);+ if (!p.canSynthesize) {+ console.log(+ " note: no OPENROUTER_API_KEY — answers show structured context without LLM synthesis",+ );+ }+ });}-server.listen(PORT, HOST, () => {- const p = providerStatus();- console.log(`Context Graph web UI → http://localhost:${PORT}`);- if (EXPOSED && WEB_TOKEN) {- const lan = lanAddress();- console.log(` access token: ${WEB_TOKEN}`);- // Token travels in the URL *fragment*: browsers never send fragments over- // the network, so it can't leak into proxy or access logs.- if (lan) console.log(` share with your team: http://${lan}:${PORT}/#token=${WEB_TOKEN}`);- else console.log(` share: http://<this-machine>:${PORT}/#token=${WEB_TOKEN}`);- // The same link is written to a file on the mounted volume, so the deployer- // (who ran `docker compose up -d` and sees no logs) can just open it.- if (SHARE_PATH) console.log(` share link also saved to: ${SHARE_PATH}`);- }- console.log(` graph db: ${p.db}`);- console.log(` extraction: ${p.extraction} (${p.model})`);- console.log(` embeddings: ${p.embeddings}`);- if (!p.canSynthesize) {- console.log(- " note: no OPENROUTER_API_KEY — answers show structured context without LLM synthesis",- );- }-});+// Run the standalone server only when invoked directly (as the+// `context-graph-web` bin), not when imported by `serve`.+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {+ main().catch((err) => {+ console.error(err);+ process.exit(1);+ });+}diff --git a/test/serve.test.ts b/test/serve.test.tsnew file mode 100644index 00000000..a5024f04--- /dev/null+++ b/test/serve.test.ts@@ -0,0 +1,74 @@+/**+ * The unified `context-graph serve` server: one process exposing the web UI,+ * the `/api/*` endpoints, and the MCP server over Streamable HTTP — all on one+ * port over a single shared engine. Runs fully offline on the fake providers.+ */+import { test } from "node:test";+import assert from "node:assert/strict";+import { ContextGraphEngine } from "../src/index.js";+import { startServe } from "../src/serve.js";+import { Client } from "@modelcontextprotocol/sdk/client/index.js";+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";+import { fakeProviders } from "./helpers.ts";++test("serve exposes the web UI, /api, and MCP-over-HTTP on one port", async () => {+ const engine = new ContextGraphEngine({ dbPath: ":memory:", ...fakeProviders() });+ await engine.ingest("[[Auth Service]] ==uses==> [[OAuth]]", { title: "auth", source: "auth.md" });++ // port 0 → a free port; watch:false so no folder resume in the test.+ const server = await startServe({ engine, host: "127.0.0.1", port: 0, watch: false });+ try {+ // 1) The web UI is served at the root.+ const home = await fetch(`${server.url}/`);+ assert.equal(home.status, 200);+ assert.match(await home.text(), /<!doctype html|<html/i);++ // 2) The JSON API works on the same port.+ const statsRes = await fetch(`${server.url}/api/stats`);+ assert.equal(statsRes.status, 200);+ const stats = (await statsRes.json()) as { documents: number; nodes: number };+ assert.ok(stats.documents >= 1, "ingested document is visible via /api/stats");++ // 3) MCP over Streamable HTTP: full handshake with the real SDK client.+ const client = new Client({ name: "serve-test", version: "0.0.0" });+ const transport = new StreamableHTTPClientTransport(new URL(`${server.url}/mcp`));+ await client.connect(transport);++ const tools = await client.listTools();+ const names = tools.tools.map((t) => t.name);+ assert.ok(names.includes("context_read"), "context_read tool is exposed over HTTP");+ assert.ok(names.includes("context_contribute"), "context_contribute tool is exposed over HTTP");++ // The MCP server reads the SAME engine the web API saw.+ const read = (await client.callTool({+ name: "context_read",+ arguments: { query: "auth" },+ })) as { content: Array<{ type: string; text: string }> };+ const text = read.content.map((c) => c.text).join("\n");+ assert.match(text, /Auth Service|OAuth/i, "context_read returns the ingested entities");++ await client.close();+ } finally {+ await server.close();+ }+});++test("serve requires no token on loopback and 404s unknown paths", async () => {+ const engine = new ContextGraphEngine({ dbPath: ":memory:", ...fakeProviders() });+ const server = await startServe({ engine, host: "127.0.0.1", port: 0, watch: false });+ try {+ const missing = await fetch(`${server.url}/api/nope`);+ assert.equal(missing.status, 404);++ // A POST to /mcp that isn't an initialize (and carries no session) is a 400,+ // not a crash — proves the session guard is wired.+ const bad = await fetch(`${server.url}/mcp`, {+ method: "POST",+ headers: { "content-type": "application/json", accept: "application/json, text/event-stream" },+ body: JSON.stringify({ jsonrpc: "2.0", method: "tools/list", id: 1 }),+ });+ assert.equal(bad.status, 400);+ } finally {+ await server.close();+ }+});