membot 0.0.1 → 0.1.0

package/package.json

@@ -1,26 +1,83 @@
 {
-  "name": "membot",
-  "version": "0.0.1",
-  "description": "Versioned context store with hybrid search for AI agents. Stdio + HTTP MCP server and CLI.",
-  "keywords": [
-    "mcp",
-    "model-context-protocol",
-    "context",
-    "memory",
-    "agent",
-    "rag",
-    "embeddings",
-    "duckdb",
-    "bun"
-  ],
-  "license": "MIT",
-  "author": "Evan Tahler <evan@arcade.dev>",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/evantahler/membot.git"
-  },
-  "homepage": "https://github.com/evantahler/membot",
-  "bugs": {
-    "url": "https://github.com/evantahler/membot/issues"
-  }
+	"name": "membot",
+	"version": "0.1.0",
+	"description": "Versioned context store with hybrid search for AI agents. Stdio + HTTP MCP server and CLI.",
+	"type": "module",
+	"exports": {
+		".": "./src/sdk.ts",
+		"./cli": "./src/cli.ts"
+	},
+	"main": "./src/sdk.ts",
+	"types": "./src/sdk.ts",
+	"bin": {
+		"membot": "./src/cli.ts"
+	},
+	"files": [
+		"src",
+		"patches",
+		"scripts",
+		"README.md",
+		"LICENSE"
+	],
+	"scripts": {
+		"dev": "bun run src/cli.ts",
+		"test": "bun test",
+		"lint": "biome ci . && tsc --noEmit",
+		"format": "biome check --write .",
+		"prebuild": "bash scripts/apply-transformers-patch.sh",
+		"build": "bun build --compile --minify --sourcemap --external '@duckdb/*' ./src/cli.ts --outfile dist/membot"
+	},
+	"keywords": [
+		"mcp",
+		"model-context-protocol",
+		"context",
+		"memory",
+		"agent",
+		"rag",
+		"embeddings",
+		"duckdb",
+		"bun"
+	],
+	"license": "MIT",
+	"author": "Evan Tahler <evan@arcade.dev>",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/evantahler/membot.git"
+	},
+	"homepage": "https://github.com/evantahler/membot",
+	"bugs": {
+		"url": "https://github.com/evantahler/membot/issues"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"dependencies": {
+		"@anthropic-ai/sdk": "^0.32.0",
+		"@duckdb/node-api": "1.5.2-r.1",
+		"@evantahler/mcpx": "^0.21.4",
+		"@huggingface/transformers": "^4.2.0",
+		"@modelcontextprotocol/sdk": "^1.29.0",
+		"ansis": "^4.2.0",
+		"commander": "^14.0.3",
+		"gray-matter": "^4.0.3",
+		"mammoth": "^1.8.0",
+		"nanospinner": "^1.2.2",
+		"onnxruntime-web": "1.26.0-dev.20260416-b7804b056c",
+		"picomatch": "^4.0.4",
+		"@types/picomatch": "^4.0.3",
+		"tesseract.js": "^5.1.0",
+		"turndown": "^7.2.0",
+		"@types/turndown": "^5.0.5",
+		"unpdf": "^0.12.0",
+		"zod": "^4.0.0",
+		"zod-to-json-schema": "^3.23.0"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.4.14",
+		"@types/bun": "latest",
+		"typescript": "^6"
+	},
+	"peerDependencies": {
+		"typescript": "^6"
+	}
 }

package/patches/@huggingface%2Ftransformers@4.2.0.patch

@@ -0,0 +1,137 @@
+diff --git a/dist/transformers.node.mjs b/dist/transformers.node.mjs
+index bacb354fe1b898d4c535a39f5ef1ba5c6a463d75..0ab58f60460236259f9eba88447313f8661cc0ca 100644
+--- a/dist/transformers.node.mjs
++++ b/dist/transformers.node.mjs
+@@ -7542,7 +7542,10 @@ var uint16_to_float32 = /* @__PURE__ */ (function() {
+ })();
+ 
+ // src/backends/onnx.js
+-import * as ONNX_NODE from "onnxruntime-node";
++// PATCHED (mcpx): static `import 'onnxruntime-node'` makes Bun --compile bundle
++// the native binding which then fails to dlopen libonnxruntime at runtime.
++// We never want the native bindings — onnxruntime-web (WASM) runs fine.
++var ONNX_NODE = void 0;
+ 
+ // ../../node_modules/.pnpm/onnxruntime-web@1.26.0-dev.20260416-b7804b056c/node_modules/onnxruntime-web/dist/ort.webgpu.bundle.min.mjs
+ var ort_webgpu_bundle_min_exports = {};
+@@ -11551,23 +11554,12 @@ var ORT_SYMBOL = /* @__PURE__ */ Symbol.for("onnxruntime");
+ if (ORT_SYMBOL in globalThis) {
+   ONNX = globalThis[ORT_SYMBOL];
+ } else if (apis.IS_NODE_ENV) {
+-  ONNX = ONNX_NODE;
+-  switch (process.platform) {
+-    case "win32":
+-      supportedDevices.push("dml");
+-      break;
+-    case "linux":
+-      if (process.arch === "x64") {
+-        supportedDevices.push("cuda");
+-      }
+-      break;
+-    case "darwin":
+-      supportedDevices.push("coreml");
+-      break;
+-  }
+-  supportedDevices.push("webgpu");
+-  supportedDevices.push("cpu");
+-  defaultDevices = ["cpu"];
++  // PATCHED (mcpx): force the WASM backend in node-like envs so onnxruntime-node
++  // native bindings are never loaded (they can't be bundled into the Bun
++  // --compile single binary).
++  ONNX = ort_webgpu_bundle_min_exports;
++  supportedDevices.push("wasm");
++  defaultDevices = ["wasm"];
+ } else {
+   ONNX = ort_webgpu_bundle_min_exports;
+   if (apis.IS_WEBNN_AVAILABLE) {
+@@ -17738,7 +17730,14 @@ var CohereAsrProcessor = class extends Processor {
+ };
+ 
+ // src/utils/image.js
+-import sharp from "sharp";
++// PATCHED (mcpx): sharp has native bindings that can't be bundled into a
++// Bun --compile binary. We don't need image processing for text embeddings;
++// stub sharp with a function that throws lazily if image processing is ever
++// actually invoked. Truthy so the `else if (sharp)` branch below initializes
++// loadImageFunction normally.
++var sharp = function sharpStub() {
++  throw new Error("Image processing (sharp) is not available in this build.");
++};
+ var createCanvasFunction;
+ var ImageDataClass;
+ var loadImageFunction;
+@@ -22328,11 +22327,16 @@ function getExternalDataChunkNames(fullName, numChunks) {
+ async function getCoreModelFile(pretrained_model_name_or_path, fileName, options, suffix) {
+   const baseName = `${fileName}${suffix}.onnx`;
+   const fullPath = `${options.subfolder ?? ""}/${baseName}`;
+-  return await getModelFile(pretrained_model_name_or_path, fullPath, true, options, apis.IS_NODE_ENV);
++  // PATCHED (mcpx): always return the model bytes (buffer) instead of a path.
++  // Our patched onnxruntime backend is the bundled webgpu/web build, which
++  // can't read paths via node:fs and would try to `fetch()` a bare path,
++  // failing with `ERR_INVALID_URL`. Returning the buffer skips the fetch.
++  return await getModelFile(pretrained_model_name_or_path, fullPath, true, options, false);
+ }
+ async function getModelDataFiles(pretrained_model_name_or_path, fileName, suffix, options, use_external_data_format, session_options = {}) {
+   const baseName = `${fileName}${suffix}.onnx`;
+-  const return_path = apis.IS_NODE_ENV;
++  // PATCHED (mcpx): see getCoreModelFile patch above — return buffers, not paths.
++  const return_path = false;
+   let externalDataPromises = [];
+   const num_chunks = resolveExternalDataFormat(use_external_data_format, baseName, fileName);
+   if (num_chunks > 0) {
+diff --git a/src/backends/onnx.js b/src/backends/onnx.js
+index 13b1a748272d03aa062950ff585c1a2277ba96c9..9863c46653618091593b6428a8c16622186318d6 100644
+--- a/src/backends/onnx.js
++++ b/src/backends/onnx.js
+@@ -20,7 +20,10 @@ import { env, apis, LogLevel } from '../env.js';
+ 
+ // NOTE: Import order matters here. We need to import `onnxruntime-node` before `onnxruntime-web`.
+ // In either case, we select the default export if it exists, otherwise we use the named export.
+-import * as ONNX_NODE from 'onnxruntime-node';
++// PATCHED (mcpx): the static `import 'onnxruntime-node'` segfaults under Bun
++// (oven-sh/bun#26081). We never want the native bindings — `onnxruntime-web` (WASM) runs
++// fine on Bun + Node + browsers. The IS_NODE_ENV branch below is rerouted to ONNX_WEB.
++const ONNX_NODE = undefined;
+ import * as ONNX_WEB from 'onnxruntime-web/webgpu';
+ import { loadWasmBinary, loadWasmFactory } from './utils/cacheWasm.js';
+ import { isBlobURL, toAbsoluteURL } from '../utils/hub/utils.js';
+@@ -106,34 +109,11 @@ if (ORT_SYMBOL in globalThis) {
+     // If the JS runtime exposes their own ONNX runtime, use it
+     ONNX = globalThis[ORT_SYMBOL];
+ } else if (apis.IS_NODE_ENV) {
+-    ONNX = ONNX_NODE;
+-
+-    // Updated as of ONNX Runtime 1.23.0-dev.20250612-70f14d7670
+-    // The following table lists the supported versions of ONNX Runtime Node.js binding provided with pre-built binaries.
+-    // | EPs/Platforms         | Windows x64        | Windows arm64      | Linux x64          | Linux arm64        | MacOS x64          | MacOS arm64        |
+-    // | --------------------- | ------------------ | ------------------ | ------------------ | ------------------ | ------------------ | ------------------ |
+-    // | CPU                   | ✔️                  | ✔️                  | ✔️                  | ✔️                  | ✔️                  | ✔️                  |
+-    // | WebGPU (experimental) | ✔️                  | ✔️                  | ✔️                  | ❌                  | ✔️                  | ✔️                  |
+-    // | DirectML              | ✔️                  | ✔️                  | ❌                  | ❌                  | ❌                  | ❌                  |
+-    // | CUDA                  | ❌                  | ❌                  | ✔️ (CUDA v12)       | ❌                  | ❌                  | ❌                  |
+-    // | CoreML                | ❌                  | ❌                  | ❌                  | ❌                  | ✔️                  | ✔️                  |
+-    switch (process.platform) {
+-        case 'win32': // Windows x64 and Windows arm64
+-            supportedDevices.push('dml');
+-            break;
+-        case 'linux': // Linux x64 and Linux arm64
+-            if (process.arch === 'x64') {
+-                supportedDevices.push('cuda');
+-            }
+-            break;
+-        case 'darwin': // MacOS x64 and MacOS arm64
+-            supportedDevices.push('coreml');
+-            break;
+-    }
+-
+-    supportedDevices.push('webgpu');
+-    supportedDevices.push('cpu');
+-    defaultDevices = ['cpu'];
++    // PATCHED (mcpx): force the WASM backend in node-like envs to avoid
++    // loading onnxruntime-node native bindings (segfaults under Bun).
++    ONNX = ONNX_WEB;
++    supportedDevices.push('wasm');
++    defaultDevices = ['wasm'];
+ } else {
+     ONNX = ONNX_WEB;
+ 

package/scripts/apply-transformers-patch.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Apply the @huggingface/transformers patch to node_modules so that
+# `bun build --compile` produces a binary using the WASM backend
+# (onnxruntime-web) instead of onnxruntime-node, whose native bindings
+# can't be bundled into a single-binary distribution.
+#
+# We apply the patch imperatively (rather than via package.json
+# `patchedDependencies`) because that field, when present in a
+# published package, breaks `bun install` from a tarball.
+
+PATCH="patches/@huggingface%2Ftransformers@4.2.0.patch"
+TARGET="node_modules/@huggingface/transformers"
+MARKER="$TARGET/.membot-transformers-patch-applied"
+
+if [ ! -d "$TARGET" ]; then
+	echo "error: $TARGET not found — run \`bun install\` first" >&2
+	exit 1
+fi
+
+if [ ! -f "$PATCH" ]; then
+	echo "error: $PATCH not found" >&2
+	exit 1
+fi
+
+if [ -f "$MARKER" ]; then
+	echo "transformers patch already applied — skipping"
+	exit 0
+fi
+
+echo "Applying transformers patch ($PATCH) to $TARGET..."
+git apply --directory="$TARGET" "$PATCH"
+touch "$MARKER"
+echo "Patch applied."

package/src/cli.ts

@@ -0,0 +1,70 @@
+#!/usr/bin/env bun
+
+import { bold, cyan, dim, green, yellow } from "ansis";
+import { program } from "commander";
+import pkg from "../package.json" with { type: "json" };
+import { registerCheckUpdateCommand } from "./commands/check-update.ts";
+import { registerMcpxCommand } from "./commands/mcpx.ts";
+import { registerReindexCommand } from "./commands/reindex.ts";
+import { registerServeCommand } from "./commands/serve.ts";
+import { registerUpgradeCommand } from "./commands/upgrade.ts";
+import type { BuildContextOptions } from "./context.ts";
+import { mountAsCommanderCommand } from "./mount/commander.ts";
+import { OPERATIONS } from "./operations/index.ts";
+import { logger } from "./output/logger.ts";
+import { maybeCheckForUpdate } from "./update/background.ts";
+
+program
+	.name("membot")
+	.description("Versioned context store with hybrid search for AI agents. Stdio + HTTP MCP server and CLI.")
+	.version(pkg.version)
+	.option("-c, --config <path>", "membot data dir (default ~/.membot)")
+	.option("-j, --json", "force JSON output")
+	.option("-v, --verbose", "verbose / debug logging")
+	.option("--no-color", "disable ANSI colors")
+	.option("--no-interactive", "force non-interactive mode (no spinners)");
+
+program.configureHelp({
+	styleTitle: (str) => bold(str),
+	styleCommandText: (str) => cyan(str),
+	styleSubcommandText: (str) => cyan(str),
+	styleOptionText: (str) => yellow(str),
+	styleArgumentText: (str) => green(str),
+	styleDescriptionText: (str) => dim(str),
+});
+
+const getContextOptions = (): BuildContextOptions => {
+	const opts = program.opts<{
+		config?: string;
+		json?: boolean;
+		verbose?: boolean;
+		color?: boolean;
+		interactive?: boolean;
+	}>();
+	return {
+		configFlag: opts.config,
+		json: opts.json,
+		verbose: opts.verbose,
+		noColor: opts.color === false,
+		noInteractive: opts.interactive === false,
+	};
+};
+
+for (const op of OPERATIONS) {
+	mountAsCommanderCommand(program, op, getContextOptions);
+}
+
+registerServeCommand(program);
+registerReindexCommand(program);
+registerMcpxCommand(program);
+registerCheckUpdateCommand(program);
+registerUpgradeCommand(program);
+
+const updateNotice = maybeCheckForUpdate();
+
+program.parse();
+
+process.on("beforeExit", async () => {
+	const notice = await updateNotice;
+	if (notice) logger.writeRaw(notice);
+});

package/src/commands/check-update.ts

@@ -0,0 +1,69 @@
+import { cyan, dim, green, yellow } from "ansis";
+import type { Command } from "commander";
+import { createSpinner } from "nanospinner";
+import pkg from "../../package.json" with { type: "json" };
+import { saveUpdateCache } from "../update/cache.ts";
+import { checkForUpdate, type UpdateCache } from "../update/checker.ts";
+
+/**
+ * Register `membot check-update`. Performs a non-destructive npm-registry check,
+ * caches the result, and prints the current/latest version (plus changelog when an
+ * update is available). Emits raw `UpdateInfo` JSON when `--json` is set.
+ */
+export function registerCheckUpdateCommand(program: Command) {
+	program
+		.command("check-update")
+		.description("Check for a newer version of membot")
+		.action(async () => {
+			const opts = program.opts();
+			const json = !!(opts.json as boolean | undefined);
+			const isTTY = process.stderr.isTTY ?? false;
+
+			const spinner =
+				!json && isTTY ? createSpinner("Checking for updates...", { stream: process.stderr }).start() : null;
+
+			try {
+				const info = await checkForUpdate(pkg.version);
+
+				const cache: UpdateCache = {
+					lastCheckAt: new Date().toISOString(),
+					latestVersion: info.latestVersion,
+					hasUpdate: info.hasUpdate,
+					changelog: info.changelog,
+				};
+				await saveUpdateCache(cache);
+
+				spinner?.stop();
+
+				if (json) {
+					console.log(JSON.stringify(info, null, 2));
+					return;
+				}
+
+				if (!info.hasUpdate) {
+					if (info.aheadOfLatest) {
+						console.log(
+							yellow(`membot v${info.currentVersion} is ahead of latest published release (v${info.latestVersion})`),
+						);
+					} else {
+						console.log(green(`membot is up to date (v${info.currentVersion})`));
+					}
+					return;
+				}
+
+				console.log(yellow(`Update available: ${info.currentVersion} → ${info.latestVersion}`));
+
+				if (info.changelog) {
+					console.log("");
+					console.log(dim(info.changelog));
+				}
+
+				console.log("");
+				console.log(cyan("Run `membot upgrade` to update"));
+			} catch (err) {
+				spinner?.error({ text: "Failed to check for updates" });
+				console.error(String(err));
+				process.exit(1);
+			}
+		});
+}

package/src/commands/mcpx.ts

@@ -0,0 +1,112 @@
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import type { Command } from "commander";
+import { logger } from "../output/logger.ts";
+
+const require = createRequire(import.meta.url);
+
+/**
+ * Resolve the path to the bundled mcpx CLI entrypoint. We spawn it as a
+ * child process rather than calling its functions directly so that the
+ * upstream's argv parsing, output formatting, and config conventions stay
+ * authoritative — `membot mcpx <subcmd>` behaves identically to the user
+ * running `mcpx <subcmd>` themselves, just with our project's `--config`
+ * resolution layered on top when applicable.
+ */
+const MCPX_CLI = fileURLToPath(import.meta.resolve("@evantahler/mcpx/cli"));
+
+/**
+ * Forward an argv slice to the bundled mcpx CLI. Inherits stdio so prompts
+ * and pretty output flow through as if mcpx were called directly. Exits
+ * the parent process with the child's status code on failure.
+ */
+export async function runMcpx(args: string[]): Promise<void> {
+	const proc = Bun.spawn(["bun", MCPX_CLI, ...args], {
+		stdout: "inherit",
+		stderr: "inherit",
+		stdin: "inherit",
+	});
+	const code = await proc.exited;
+	if (code !== 0) process.exit(code);
+}
+
+/**
+ * Pull the verbatim argv tokens that follow `mcpx` in `process.argv`. We
+ * forward them unmodified so flags (`--help`, `-c`, etc.) reach the
+ * upstream CLI exactly as the user typed them.
+ */
+function getRawMcpxArgs(): string[] {
+	const idx = process.argv.indexOf("mcpx");
+	return idx === -1 ? [] : process.argv.slice(idx + 1);
+}
+
+const PASSTHROUGH_SUBCOMMANDS: ReadonlyArray<[name: string, desc: string]> = [
+	["servers", "List configured MCP server names"],
+	["info", "Show server overview or schema for a specific tool"],
+	["search", "Search tools by keyword and/or semantic similarity"],
+	["exec", "Execute a tool call"],
+	["add", "Add an MCP server"],
+	["remove", "Remove an MCP server"],
+	["ping", "Check connectivity to MCP servers"],
+	["auth", "Authenticate with an HTTP MCP server"],
+	["deauth", "Remove stored authentication for a server"],
+	["resource", "List resources for a server, or read a specific resource"],
+	["prompt", "List prompts for a server, or get a specific prompt"],
+	["task", "Manage async tool tasks (list, get, result, cancel)"],
+	["index", "Build the search index from all configured servers"],
+];
+
+/**
+ * Register `membot mcpx <subcommand>` for every passthrough subcommand on
+ * the upstream CLI. `--help` and unknown options are forwarded so users
+ * always get authoritative mcpx help text.
+ */
+export function registerMcpxCommand(program: Command): void {
+	const mcpx = program.command("mcpx").description("Forward to the bundled mcpx CLI for managing MCP servers");
+
+	const verifyVersion = (() => {
+		try {
+			const ourPkg = require("../../package.json") as { dependencies: Record<string, string> };
+			const mcpxPkg = require("@evantahler/mcpx/package.json") as { version: string };
+			const declared = ourPkg.dependencies["@evantahler/mcpx"];
+			if (!declared) return true;
+			return (
+				mcpxPkg.version === declared ||
+				declared.startsWith(mcpxPkg.version) ||
+				mcpxPkg.version.startsWith(declared.replace(/^[\^~]/, ""))
+			);
+		} catch {
+			return true;
+		}
+	})();
+	if (!verifyVersion) {
+		logger.warn("@evantahler/mcpx version mismatch — `membot mcpx` may behave unexpectedly.");
+	}
+
+	for (const [name, description] of PASSTHROUGH_SUBCOMMANDS) {
+		mcpx
+			.command(name)
+			.description(description)
+			.allowUnknownOption(true)
+			.helpOption(false)
+			.argument("[args...]", "arguments forwarded to mcpx")
+			.action(async () => {
+				await runMcpx(getRawMcpxArgs());
+			});
+	}
+
+	// Upstream mcpx's "list" is the default action when invoked with no
+	// subcommand — not a registered subcommand — so strip the "list" token
+	// before forwarding.
+	mcpx
+		.command("list")
+		.description("List all tools, resources, and prompts across all configured servers")
+		.allowUnknownOption(true)
+		.helpOption(false)
+		.argument("[args...]", "arguments forwarded to mcpx")
+		.action(async () => {
+			const raw = getRawMcpxArgs();
+			const args = raw[0] === "list" ? raw.slice(1) : raw;
+			await runMcpx(args);
+		});
+}

package/src/commands/reindex.ts

@@ -0,0 +1,53 @@
+import type { Command } from "commander";
+import { buildContext, closeContext } from "../context.ts";
+import { rebuildFts } from "../db/chunks.ts";
+import { logger } from "../output/logger.ts";
+
+/**
+ * `membot reindex`
+ *
+ * Rebuild the FTS index over `current_chunks`. Useful after manually
+ * editing the DB or upgrading after a schema change. Does NOT re-embed —
+ * embeddings are durable and are managed by the ingest/refresh pipelines.
+ */
+export function registerReindexCommand(program: Command): void {
+	program
+		.command("reindex")
+		.description("Rebuild the FTS keyword index over current chunks")
+		.action(async () => {
+			const ctx = await buildContext({});
+			try {
+				const result = await rebuildFts(ctx.db);
+				switch (result.kind) {
+					case "rebuilt":
+						logger.info(`reindex: FTS index rebuilt over ${result.chunk_count} chunks`);
+						console.log(JSON.stringify({ ok: true, chunk_count: result.chunk_count }));
+						break;
+					case "no_chunks":
+						logger.info("reindex: no chunks to index — run `membot add <path>` to ingest content first");
+						console.log(JSON.stringify({ ok: true, chunk_count: 0 }));
+						break;
+					case "extension_unavailable":
+						logger.warn(
+							`reindex: FTS extension unavailable — search will degrade to semantic-only${
+								result.cause ? ` (${result.cause})` : ""
+							}`,
+						);
+						console.log(
+							JSON.stringify({
+								ok: false,
+								reason: "fts_extension_unavailable",
+								cause: result.cause,
+							}),
+						);
+						break;
+					case "rebuild_failed":
+						logger.warn(`reindex: FTS rebuild failed${result.cause ? ` (${result.cause})` : ""}`);
+						console.log(JSON.stringify({ ok: false, reason: "rebuild_failed", cause: result.cause }));
+						break;
+				}
+			} finally {
+				await closeContext(ctx);
+			}
+		});
+}

package/src/commands/serve.ts

@@ -0,0 +1,58 @@
+import type { Command } from "commander";
+import { buildContext, closeContext } from "../context.ts";
+import { startStdioServer } from "../mcp/server.ts";
+import { logger } from "../output/logger.ts";
+import { startDaemon } from "../refresh/scheduler.ts";
+
+/**
+ * `membot serve [--http <port>] [--watch] [--tick <sec>]`
+ *
+ * Start the MCP server in stdio mode (default) or HTTP streamable mode
+ * (when `--http <port>` is given). Optionally also start the refresh
+ * daemon (`--watch`) which ticks every `--tick` seconds and refreshes
+ * any rows whose `refresh_frequency_sec` has elapsed.
+ */
+export function registerServeCommand(program: Command): void {
+	program
+		.command("serve")
+		.description("Run the MCP server (stdio default, --http for streamable HTTP) and optionally the refresh daemon")
+		.option("--http <port>", "expose MCP over HTTP on this port instead of stdio")
+		.option("--watch", "also run the refresh daemon (auto-refresh due rows)")
+		.option("--tick <sec>", "daemon tick interval in seconds (default 60)")
+		.action(async (options: { http?: string; watch?: boolean; tick?: string }) => {
+			const httpPort = options.http ? Number(options.http) : null;
+			let stopServer: (() => Promise<void>) | null = null;
+			let stopDaemon: (() => void) | null = null;
+
+			const onShutdown = async () => {
+				if (stopDaemon) stopDaemon();
+				if (stopServer) await stopServer();
+			};
+			process.on("SIGINT", () => {
+				logger.info("shutting down...");
+				onShutdown().finally(() => process.exit(0));
+			});
+			process.on("SIGTERM", () => {
+				onShutdown().finally(() => process.exit(0));
+			});
+
+			if (httpPort && !Number.isFinite(httpPort)) {
+				logger.error(`invalid --http port: ${options.http}`);
+				process.exit(2);
+			}
+
+			if (options.watch) {
+				const ctx = await buildContext({});
+				const tickSec = options.tick ? Number(options.tick) : ctx.config.daemon.tick_interval_sec;
+				stopDaemon = startDaemon(ctx, Number.isFinite(tickSec) && tickSec > 0 ? tickSec : 60);
+				process.on("beforeExit", () => closeContext(ctx));
+			}
+
+			if (httpPort) {
+				const { startHttpServer } = await import("../mcp/server.ts");
+				stopServer = await startHttpServer(httpPort);
+			} else {
+				stopServer = await startStdioServer();
+			}
+		});
+}