Skip to content

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

Add context-graph serve: unified web UI + MCP-over-HTTP + watcher in one process

anirudhkumar-nanonetsbc190e4f8cb5
diff --git a/DEMO.md b/DEMO.md
index 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/Dockerfile
index 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 build
WORKDIR /app
@@ -32,4 +35,6 @@ RUN mkdir -p /data && chown node:node /data
USER node
EXPOSE 4680
VOLUME /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.md
index 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 `OPENR
Running 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 optional
Out 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.yml
index 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.json
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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:ht
import { 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.ts
new file mode 100644
index 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();
+ }
+});