@omega.js/mcp-router 0.1.0

package/src/lib/kill-tree.js

@@ -0,0 +1,74 @@
+/**
+ * Killing a child and everything it started.
+ *
+ * The pid the router holds is often only the ROOT of a tree: `npx` starts npm,
+ * which starts the real server, which starts a browser. Signalling that one
+ * pid ends the wrapper and REPARENTS the rest to init, out of reach of anything
+ * the router knows — which is how a stopped upstream leaves a browser burning
+ * cores for the rest of the day. So the tree is walked and signalled deepest
+ * first, while the links between the processes still exist to be read.
+ */
+
+const { execFileSync } = require('node:child_process');
+
+/**
+ * The direct children of one process.
+ *
+ * @param {number} pid - Parent pid
+ * @returns {number[]} Child pids, empty when there are none to find
+ */
+const childPids = (pid) => {
+  try {
+    return execFileSync('pgrep', ['-P', String(pid)], { encoding: 'utf8' })
+      .split('\n')
+      .map((line) => Number(line.trim()))
+      .filter((child) => Number.isInteger(child) && child > 0);
+  } catch {
+    // pgrep exits 1 when nothing matches, which execFileSync raises; a platform
+    // with no pgrep at all answers the same way. Either is "no children we can
+    // see", and the pid itself is still signalled by the caller.
+    return [];
+  }
+};
+
+/**
+ * Every descendant of one process, deepest first.
+ *
+ * One level is never enough for a capture: the MIDDLE of a tree exits with the
+ * root above it, and the browser it started is reparented and invisible to any
+ * walk by the time a grace period runs. The tree has to be read whole while it
+ * is still a tree.
+ *
+ * @param {number} pid - Root pid, itself not included
+ * @returns {number[]} Descendant pids, deepest first, empty when there are none
+ */
+const descendantPids = (pid) => {
+  const found = [];
+  for (const child of childPids(pid)) found.push(...descendantPids(child), child);
+  return found;
+};
+
+/**
+ * Signal a process and every descendant, deepest first.
+ *
+ * Deepest first is what makes it a tree kill rather than a race: a parent
+ * signalled first would take its links with it and leave the rest unreachable.
+ *
+ * @param {number} pid - Root pid of the tree
+ * @param {string|number} signal - Signal to send (e.g. 'SIGKILL')
+ * @returns {void}
+ * @throws {Error} Whatever process.kill rejected with, except ESRCH
+ */
+const killTree = (pid, signal) => {
+  for (const child of childPids(pid)) killTree(child, signal);
+
+  try {
+    process.kill(pid, signal);
+  } catch (err) {
+    // ESRCH is the process having exited on its own between the walk and the
+    // signal — the outcome we wanted. Anything else (EPERM) is a real problem.
+    if (err.code !== 'ESRCH') throw err;
+  }
+};
+
+module.exports = { descendantPids, killTree };

package/src/lib/log.js

@@ -0,0 +1,17 @@
+/**
+ * The router's log sink. Everything a router process says goes to STDERR —
+ * stdout is the MCP wire, and one stray byte on it corrupts the protocol.
+ */
+
+/**
+ * Write one line to stderr.
+ *
+ * @param {string} level - `info` | `warn` | `error` | `fatal`
+ * @param {...*} args - Message parts, joined with a space
+ * @returns {void}
+ */
+function log(level, ...args) {
+  process.stderr.write(`[mcp-router ${level}] ${args.join(' ')}\n`);
+}
+
+module.exports = { log };

package/src/lib/oneshot.js

@@ -0,0 +1,116 @@
+/**
+ * Connecting to an upstream child, under the router's spawn budget.
+ *
+ * Two surfaces refresh a schema (the router's `router__refresh_upstream` and
+ * `omega-mcp refresh`), and both do the same thing: spawn the upstream once,
+ * read its tool list, close it. They ran as two copies of that sequence and the
+ * copies drifted (the cleanup, then the read budget, landed on the router side
+ * only), so the sequence lives here ONCE and both callers import it.
+ *
+ * The connect deadline is shared wider still: the router's lazy cold spawn
+ * connects through the same helper, on the same budget.
+ */
+
+// How long a connect gets to finish the MCP handshake. A child that corrupts
+// the stdio wire never answers initialize, and an unbounded connect would leave
+// the router's `spawning` promise pending: every later call would await that
+// dead promise and die at the caller's own tool timeout, for the rest of the
+// session. The deadline bounds it so the NEXT call spawns fresh. It bounds the
+// one-shot refresh connect AND its tools/list read too, on the same budget.
+// MCP_ROUTER_SPAWN_TIMEOUT_MS is the test seam, alongside the two in paths.js.
+const SPAWN_TIMEOUT_MS = Number(process.env.MCP_ROUTER_SPAWN_TIMEOUT_MS) || 30000;
+
+/**
+ * Connect a client over its transport, bounded by SPAWN_TIMEOUT_MS.
+ *
+ * The deadline abandons a connect the SDK has not settled (the SDK's own
+ * request timeout answers much later); Promise.race already attaches the
+ * rejection handler, so the explicit catch on `connected` only documents the
+ * abandonment. On ANY rejection the transport is closed — a stuck handshake,
+ * or one that lands after the deadline, would otherwise leave its child
+ * running for the rest of the session — then the rejection is rethrown.
+ *
+ * @param {object} client - Proxy client to connect
+ * @param {object} transport - Transport whose child is terminated on failure
+ * @returns {Promise<void>} Resolves once the handshake lands
+ * @throws {Error} When the handshake does not finish within SPAWN_TIMEOUT_MS
+ */
+const connectWithDeadline = async (client, transport) => {
+  const connected = client.connect(transport);
+  connected.catch(() => {});
+
+  let deadline;
+  try {
+    await Promise.race([
+      connected,
+      new Promise((_, reject) => {
+        deadline = setTimeout(
+          () => reject(new Error(`handshake did not finish within ${SPAWN_TIMEOUT_MS}ms`)),
+          SPAWN_TIMEOUT_MS,
+        );
+      }),
+    ]);
+  } catch (err) {
+    await transport.close().catch(() => {});
+    throw err;
+  } finally {
+    clearTimeout(deadline);
+  }
+};
+
+/**
+ * Connect an already-built pair, read the tool list once, and close.
+ *
+ * A child that finishes the handshake can still fail the tools/list read (an
+ * error answer, or a stall). The read carries the router's own budget because
+ * the SDK would otherwise hold the caller for its 60s default.
+ * connectWithDeadline is done with the transport by then, so nothing else would
+ * close it and the one-shot child would run for the rest of the session. The
+ * success path closes through the client instead, so the transport is never
+ * closed twice.
+ *
+ * @param {object} client - Client to connect and read through
+ * @param {object} transport - Transport whose child is terminated on any failure
+ * @returns {Promise<object[]>} The upstream's tool descriptors
+ * @throws {Error} Whatever the connect or the read rejected with
+ */
+const readToolsOnce = async (client, transport) => {
+  await connectWithDeadline(client, transport);
+
+  let result;
+  try {
+    result = await client.listTools(undefined, { timeout: SPAWN_TIMEOUT_MS });
+  } catch (err) {
+    await transport.close().catch(() => {});
+    throw err;
+  }
+  await client.close();
+  return result.tools;
+};
+
+/**
+ * Spawn an upstream once, read its tool list, and close it.
+ *
+ * The SDK is required HERE rather than at module load so the CLI commands that
+ * never reach this path (list, help) still work when node_modules is missing.
+ *
+ * @param {{command: string, args: string[], env: object}} spawn - Resolved spawn shape for the child
+ * @returns {Promise<object[]>} The upstream's tool descriptors
+ * @throws {Error} Whatever the connect or the read rejected with
+ */
+const listToolsOnce = async (spawn) => {
+  const { Client } = require('@modelcontextprotocol/sdk/client/index.js');
+  const { StdioClientTransport } = require('@modelcontextprotocol/sdk/client/stdio.js');
+
+  const transport = new StdioClientTransport({
+    command: spawn.command,
+    args: spawn.args,
+    env: spawn.env,
+    stderr: 'inherit',
+  });
+  const client = new Client({ name: 'mcp-router-refresh', version: '1.0.0' }, { capabilities: {} });
+
+  return readToolsOnce(client, transport);
+};
+
+module.exports = { SPAWN_TIMEOUT_MS, connectWithDeadline, readToolsOnce, listToolsOnce };

package/src/lib/paths.js

@@ -0,0 +1,41 @@
+/**
+ * Where the router reads and writes.
+ *
+ * Two layers, one direction: the BUNDLED defaults ship inside the package
+ * (read-only — for a consumer they live in node_modules), and the OVERLAY
+ * under `~/.omega/mcp-router/` is the only thing anything ever writes.
+ *
+ * Both env seams exist for tests and power users:
+ *   MCP_ROUTER_SERVERS_DIR — overrides the overlay servers dir
+ *   MCP_ROUTER_ENV_FILE    — overrides the overlay .env path
+ */
+
+const os = require('node:os');
+const path = require('node:path');
+
+// src/lib/paths.js → the package root is two levels up.
+const PACKAGE_ROOT = path.join(__dirname, '..', '..');
+
+const BUNDLED_SERVERS_DIR = path.join(PACKAGE_ROOT, 'servers');
+
+const OVERLAY_ROOT = path.join(os.homedir(), '.omega', 'mcp-router');
+
+/**
+ * The overlay servers dir for this process.
+ *
+ * @returns {string} Absolute path
+ */
+function overlayServersDir() {
+  return process.env.MCP_ROUTER_SERVERS_DIR || path.join(OVERLAY_ROOT, 'servers');
+}
+
+/**
+ * The .env file secrets interpolate from.
+ *
+ * @returns {string} Absolute path (the file need not exist)
+ */
+function envFile() {
+  return process.env.MCP_ROUTER_ENV_FILE || path.join(OVERLAY_ROOT, '.env');
+}
+
+module.exports = { PACKAGE_ROOT, BUNDLED_SERVERS_DIR, OVERLAY_ROOT, overlayServersDir, envFile };

package/src/lib/registry.js

@@ -0,0 +1,232 @@
+/**
+ * The layered upstream registry — the one view of "what upstreams exist",
+ * shared by the router and the CLI.
+ *
+ * Two layers: the BUNDLED defaults that ship in `servers/` inside this
+ * package, then the user's OVERLAY at `~/.omega/mcp-router/servers/`. The
+ * merge is SHALLOW and field-level — an overlay entry's top-level keys win
+ * over the bundled entry's, so:
+ *
+ *   {"enabled": false}                     turns a bundled default off
+ *   {"args": [...]}                        re-points one field of a default
+ *   a full entry under a new name          adds a private upstream
+ *
+ * Every WRITE lands in the overlay, never in the bundled dir — for a consumer
+ * the bundled dir lives inside node_modules, which nothing may edit.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { log } = require('./log.js');
+const { BUNDLED_SERVERS_DIR, overlayServersDir } = require('./paths.js');
+
+/**
+ * Resolve the two layer directories for a call.
+ *
+ * @param {object} [options] - `{ bundledDir, overlayDir }` overrides (tests pass fixtures)
+ * @returns {{bundledDir: string, overlayDir: string}} The layers, weakest first
+ */
+function layers(options = {}) {
+  return {
+    bundledDir: options.bundledDir || BUNDLED_SERVERS_DIR,
+    overlayDir: options.overlayDir || overlayServersDir(),
+  };
+}
+
+/**
+ * Read one layer's `<name>/config.json`.
+ *
+ * @param {string} dir - A layer directory
+ * @param {string} name - Upstream name
+ * @returns {object|null} The parsed config, or null when absent/unreadable (unreadable logs loudly)
+ */
+function readLayer(dir, name) {
+  const file = path.join(dir, name, 'config.json');
+  if (!fs.existsSync(file)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (err) {
+    // One malformed config must never take down the whole registry.
+    log('error', `Skipping ${file}: unreadable config.json (${err.message})`);
+    return null;
+  }
+}
+
+/**
+ * Every upstream name either layer knows about.
+ *
+ * @param {object} [options] - `{ bundledDir, overlayDir }`
+ * @returns {string[]} Sorted names
+ */
+function names(options) {
+  const { bundledDir, overlayDir } = layers(options);
+  const found = new Set();
+  for (const dir of [bundledDir, overlayDir]) {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue; // a missing layer is normal: no overlay yet, or a bare checkout
+    }
+    for (const entry of entries) {
+      if (entry.isDirectory() && fs.existsSync(path.join(dir, entry.name, 'config.json'))) found.add(entry.name);
+    }
+  }
+  return [...found].sort();
+}
+
+/**
+ * The merged RAW config for one upstream — bundled fields with the overlay's
+ * top-level keys layered over them.
+ *
+ * @param {string} name - Upstream name
+ * @param {object} [options] - `{ bundledDir, overlayDir }`
+ * @returns {object|null} The merged config, or null when neither layer has it
+ */
+function mergedConfig(name, options) {
+  const { bundledDir, overlayDir } = layers(options);
+  const bundled = readLayer(bundledDir, name);
+  const overlay = readLayer(overlayDir, name);
+  if (!bundled && !overlay) return null;
+  return { ...(bundled || {}), ...(overlay || {}) };
+}
+
+/**
+ * Normalize a raw config into the shape the router and CLI consume.
+ *
+ * @param {string} name - Upstream name
+ * @param {object} config - A merged raw config
+ * @param {object} sources - `{ bundled: boolean, overlay: boolean }`
+ * @returns {object} The registry entry
+ */
+function normalize(name, config, sources) {
+  return {
+    name,
+    enabled_on_disk: config.enabled === true,
+    default: config.default === 'on-demand' ? 'on-demand' : 'auto',
+    locked: config.locked === true,
+    command: config.command,
+    args: config.args || [],
+    env: config.env || {},
+    tools: Array.isArray(config.tools) ? config.tools : [],
+    bundled: sources.bundled,
+    overlaid: sources.overlay,
+  };
+}
+
+/**
+ * One upstream's layered entry.
+ *
+ * @param {string} name - Upstream name
+ * @param {object} [options] - `{ bundledDir, overlayDir }`
+ * @returns {object|null} The registry entry, or null when unknown
+ */
+function loadUpstream(name, options) {
+  const { bundledDir, overlayDir } = layers(options);
+  const config = mergedConfig(name, { bundledDir, overlayDir });
+  if (!config) return null;
+  return normalize(name, config, {
+    bundled: readLayer(bundledDir, name) !== null,
+    overlay: readLayer(overlayDir, name) !== null,
+  });
+}
+
+/**
+ * The whole layered registry.
+ *
+ * @param {object} [options] - `{ bundledDir, overlayDir }`
+ * @returns {object} name → registry entry
+ */
+function loadUpstreams(options) {
+  const { bundledDir, overlayDir } = layers(options);
+  const upstreams = {};
+  for (const name of names({ bundledDir, overlayDir })) {
+    const entry = loadUpstream(name, { bundledDir, overlayDir });
+    // Both layers unreadable — readLayer already said so.
+    if (entry) upstreams[name] = entry;
+  }
+  return upstreams;
+}
+
+/**
+ * Is this name a bundled default?
+ *
+ * @param {string} name - Upstream name
+ * @param {object} [options] - `{ bundledDir }`
+ * @returns {boolean} True when the package ships it
+ */
+function isBundled(name, options) {
+  const { bundledDir } = layers(options);
+  return fs.existsSync(path.join(bundledDir, name, 'config.json'));
+}
+
+/**
+ * The user's overlay entry as written on disk, unmerged.
+ *
+ * @param {string} name - Upstream name
+ * @param {object} [options] - `{ overlayDir }`
+ * @returns {object|null} The overlay config, or null when there is none
+ */
+function readOverlayEntry(name, options) {
+  const { overlayDir } = layers(options);
+  return readLayer(overlayDir, name);
+}
+
+/**
+ * Merge fields into the overlay entry and write it. This is the ONLY write
+ * path: a bundled default is never touched, it is only shadowed.
+ *
+ * @param {string} name - Upstream name
+ * @param {object} patch - Top-level keys to set
+ * @param {object} [options] - `{ overlayDir }`
+ * @returns {object} The overlay entry as written
+ */
+function patchOverlayEntry(name, patch, options) {
+  const { overlayDir } = layers(options);
+  const next = { ...(readLayer(overlayDir, name) || {}), ...patch };
+  const dir = path.join(overlayDir, name);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, 'config.json'), `${JSON.stringify(next, null, 2)}\n`);
+  return next;
+}
+
+/**
+ * The one refusal message for a locked upstream, shared by every caller that
+ * flips `enabled` on: the CLI and the router's meta-tool say the same thing.
+ *
+ * @param {string} name - Upstream name
+ * @returns {string} The refusal, naming the field and the shell escape hatch
+ */
+function lockedRefusal(name) {
+  return `Upstream "${name}" is locked (locked: true in its overlay config.json) and will not be enabled. `
+    + `Remove that field to unlock it, or run \`omega-mcp enable ${name} --force\` from the shell.`;
+}
+
+/**
+ * Delete an overlay entry — a bundled default under the same name comes back.
+ *
+ * @param {string} name - Upstream name
+ * @param {object} [options] - `{ overlayDir }`
+ * @returns {boolean} True when something was removed
+ */
+function removeOverlayEntry(name, options) {
+  const { overlayDir } = layers(options);
+  const dir = path.join(overlayDir, name);
+  if (!fs.existsSync(path.join(dir, 'config.json'))) return false;
+  fs.rmSync(dir, { recursive: true });
+  return true;
+}
+
+module.exports = {
+  layers,
+  names,
+  mergedConfig,
+  loadUpstream,
+  loadUpstreams,
+  isBundled,
+  readOverlayEntry,
+  lockedRefusal,
+  patchOverlayEntry,
+  removeOverlayEntry,
+};