toolfunnel 0.3.0 → 0.5.0

package/bin/toolfunnel.js

@@ -39,13 +39,40 @@ if (args.includes('--help') || args.includes('-h')) {
       '  toolfunnel --ui               Start the config web UI (127.0.0.1:9777)',
       '  toolfunnel --ui --port <n>    Bind a specific UI port (0 = OS-assigned)',
       '  toolfunnel install-oauth      Install the optional OAuth 2.1 dependency (jose)',
+      '  toolfunnel --config-dir <dir> Use <dir> as the CONFIG HOME (see below)',
       '  toolfunnel --help             Show this help',
       '',
+      'CONFIG HOME: the mutable config (tools/ mcp/ hooks/ auth/ logs/ toolfunnel.json) lives in',
+      'the config home — by default the package root (a git clone works as before), or the value',
+      'of --config-dir / the TOOLFUNNEL_HOME env var. An empty home is seeded from the shipped',
+      'defaults on first use and is NEVER overwritten after — so an npm update cannot eat your',
+      'tools. This is also how a wrapped MCP ships its own bundled setup.',
+      '',
+      'Identity + port defaults can be set in an OPTIONAL toolfunnel.json in the config home:',
+      '  { "serverName": "my-mcp", "serverVersion": "1.0.0", "httpPort": 9998, "uiPort": 9777 }',
+      'A --port flag always wins over the config value.',
+      '',
     ].join('\n')
   );
   process.exit(0);
 }
 
+// Resolve + seed the config home FIRST — before any src/ module is required — so every
+// module-load-time anchor (register/expose/hooks paths, auth + log config, identity) reads the
+// same resolved home. Precedence: --config-dir > TOOLFUNNEL_HOME env > the package root.
+const { initConfigHome } = require('../src/core/config-home');
+const configHome = initConfigHome({ dir: flagValue('--config-dir', '') }).home;
+
+// Advisory runtime preflight: the home's toolfunnel.json may declare `requires` (python, git, …)
+// for the tools it ships. A missing/old runtime breaks only the tools that need it, so each
+// problem is one loud stderr line and the gateway starts anyway. Never fatal, never throws.
+try {
+  const { checkRequires } = require('../src/core/requires');
+  for (const p of checkRequires(configHome)) {
+    process.stderr.write('[toolfunnel] REQUIRES: ' + p.problem + '\n');
+  }
+} catch (_e) { /* preflight must never stop the gateway */ }
+
 if (args[0] === 'install-oauth') {
   // Opt-in OAuth: pull the single audited dependency (jose) on demand. Keeps the default install
   // at zero runtime dependencies — you only ever fetch jose if you decide you need OAuth.
@@ -68,9 +95,13 @@ if (args[0] === 'install-oauth') {
     });
 } else if (args.includes('--ui')) {
   const { createUiServer } = require('../src/ui/server');
+  const { loadServerConfig } = require('../src/core/server-config');
+  const { resolveConfigHome } = require('../src/core/config-home');
+  const cfg = loadServerConfig(resolveConfigHome());
   const host = flagValue('--host', '127.0.0.1');
-  const parsedPort = parseInt(flagValue('--port', '9777'), 10);
-  const port = Number.isInteger(parsedPort) ? parsedPort : 9777;
+  // Precedence: --port flag > toolfunnel.json uiPort > 9777 (loadServerConfig folds in the default).
+  const parsedPort = parseInt(flagValue('--port', String(cfg.uiPort)), 10);
+  const port = Number.isInteger(parsedPort) ? parsedPort : cfg.uiPort;
   const server = createUiServer({ host, port });
   server
     .start()
@@ -88,9 +119,13 @@ if (args[0] === 'install-oauth') {
   process.on('SIGTERM', shutdown);
 } else if (args.includes('--http')) {
   const { createHttpMcpServer } = require('../src/mcp/http-transport');
+  const { loadServerConfig } = require('../src/core/server-config');
+  const { resolveConfigHome } = require('../src/core/config-home');
+  const cfg = loadServerConfig(resolveConfigHome());
   const host = flagValue('--host', '127.0.0.1');
-  const parsedPort = parseInt(flagValue('--port', '9998'), 10);
-  const port = Number.isInteger(parsedPort) ? parsedPort : 9998;
+  // Precedence: --port flag > toolfunnel.json httpPort > 9998 (loadServerConfig folds in the default).
+  const parsedPort = parseInt(flagValue('--port', String(cfg.httpPort)), 10);
+  const port = Number.isInteger(parsedPort) ? parsedPort : cfg.httpPort;
   const server = createHttpMcpServer({ host, port });
   server
     .start()

package/docs/KNOWN_BUGS.md

@@ -0,0 +1,33 @@
+# Known issues & roadmap
+
+ToolFunnel has no known correctness bugs at this release. This file tracks the upcoming
+compatibility work and any limitations worth knowing about.
+
+## Coming in 0.6.0 — the 2026-07-28 MCP specification
+
+The 2026-07-28 MCP revision is a **breaking** change to the protocol: it removes the `initialize`
+handshake, protocol-level sessions, and the standalone GET/SSE endpoint, and adds new required
+behaviours — per-request protocol metadata, `Mcp-Method` / `Mcp-Name` request headers, a
+`server/discover` endpoint, a `subscriptions/listen` change-notification stream, and
+`resultType` / `ttlMs` / `cacheScope` result fields.
+
+ToolFunnel 0.5.0 speaks the current `2024-11-05` protocol and works with every MCP client shipping
+today. **0.6.0** will add **dual-era** support — answering both the current handshake-based clients
+*and* the 2026-07-28 modern clients — built against the finalised spec after 28 July.
+
+Planned for 0.6.0:
+
+- **Dual-era transport** (current + 2026-07-28) so old and new clients both keep working.
+- `server/discover`, the new request-header validation, and the `subscriptions/listen` stream.
+- An **opt-in, per-upstream legacy-protocol shim**: keep an ageing MCP server working past the
+  cutover by pinning the protocol version ToolFunnel speaks *to that upstream* — off by default,
+  it names the exact version it drops to and warns at startup and on every call.
+
+## Current limitations
+
+- The OAuth 2.1 resource-server and Streamable-HTTP support are recent and less battle-tested than
+  the core — test your setup before relying on them in a networked deployment.
+- No Prometheus / OpenTelemetry metrics — a toggleable JSONL audit log and in-memory `/health`
+  call counters only.
+
+Found a bug, or want to help with the 0.6.0 work? Issues and PRs are welcome.

package/docs/packaging.md

@@ -0,0 +1,115 @@
+# Packaging: ship what you built
+
+ToolFunnel's config is a folder. That single fact is the whole packaging story: everything you
+build in a gateway — your tools and their scripts, which of them are promoted hot or hidden, the
+upstream MCPs you attached and the tools you chose to expose from them, the policy hooks that gate
+every call, and the identity the server introduces itself with — lives in one directory tree, the
+**config home**. Ship the tree and you have shipped the product.
+
+## The config home
+
+By default the home is the package/clone root — a git clone works exactly as it always did. Point
+the gateway elsewhere and the config lives there instead:
+
+```
+toolfunnel --config-dir D:\my-setup     # flag (wins)
+TOOLFUNNEL_HOME=D:\my-setup toolfunnel  # env var
+```
+
+An empty home is **seeded** on first use from the shipped defaults (the register + management
+scripts, an empty `mcp/expose.json`, the default hooks manifest) and is **never overwritten**
+afterwards — which is the point: with the home outside the package, `npm update toolfunnel`
+can never eat your tools.
+
+```
+<home>/
+  toolfunnel.json         # identity (serverName/serverVersion), port defaults, `requires`
+  tools/
+    tools.register.json   # your tool entries (incl. their inputSchema)
+    tools.state.json      # the hot/hidden/enabled curation — part of the product
+    scripts/              # the tool scripts
+  mcp/expose.json         # upstream references + curated exposure
+  hooks/                  # the policy gate: manifest + hook scripts
+```
+
+## `tf_pack` — one call to a deployment artifact
+
+The `tf_pack` management tool snapshots the LIVE setup into `<home>/dist/<name>/` — always a
+separate location, never the live tree. `auth/` (environment-specific) and `logs/` never ship.
+
+**`{ format: "home" }`** → a portable config home. Zip it, commit it to a repo, or run it as-is:
+
+```
+toolfunnel --config-dir path/to/the-pack
+```
+
+**`{ format: "npm", name: "my-mcp", version: "1.0.0" }`** → a publishable npm package:
+
+```
+dist/my-mcp/
+  package.json      # name, bin, files, dependencies: { "toolfunnel": "^0.4.0" }
+  bin/my-mcp.js     # 2 lines: pin --config-dir at ../home, delegate to toolfunnel
+  home/             # the bundled config home (identity rewritten to my-mcp@1.0.0)
+  README.md         # a stub to make your own
+```
+
+Review it, then `cd dist/my-mcp && npm publish`. Your users run `npx my-mcp` and get **your**
+server: your name in the MCP `initialize` handshake, your tools with your schemas, your curation,
+and — the part nobody else can say — **your gate**. The hooks travel inside the pack and enforce
+your policy on the recipient's machine regardless of which MCP client calls it.
+
+### Depend, never copy
+
+The generated package **depends on** `toolfunnel` (caret range) rather than vendoring it. Your own
+runtime dependencies go in **your** `package.json` exactly as with any npm package — npm installs
+the whole tree on `npx my-mcp`; toolfunnel itself adds zero. Why depending matters:
+
+- security and bug fixes reach every wrapped MCP through a normal `npm update` — no stale forks
+  carrying old bugs;
+- your package stays a few KB of config instead of a copied engine;
+- (and honestly) every install of your MCP counts as a toolfunnel download, which keeps the thing
+  you depend on alive.
+
+Your users can move the bundled home out of `node_modules` (so *their* edits survive *your*
+updates) via the `<NAME>_HOME` env var the generated launcher supports.
+
+## Declaring runtimes: `requires`
+
+Your tools may need runtimes the gateway doesn't (python, git, ffmpeg…). Declare them in the
+home's `toolfunnel.json` and they travel with every pack:
+
+```json
+{
+  "serverName": "my-mcp",
+  "requires": [
+    { "command": "python", "min": "3.10", "why": "the pdf-extract tools" },
+    { "command": "git" }
+  ]
+}
+```
+
+The gateway probes them once at startup and prints one clear stderr line per problem — found
+version vs needed, plus your `why`. Advisory by design: a missing runtime breaks only the tools
+that need it, so the server still starts and everything else keeps working.
+
+## Composite packs
+
+A pack is not just your own scripts. Because `mcp/expose.json` lives in the home, a pack carries
+**upstream references too**: "attach `@example/weather-mcp` (pin the version) and expose exactly
+these four tools under these names." The upstream itself travels as a *reference* — `npx` fetches
+it on the recipient's machine — while your **curation** and your **gate** travel as config. One
+pack = your tools + other people's servers, curated, renamed, and policed, as a single artifact.
+
+## Audit honesty
+
+Packs spawn commands — that is what they are for. Before you run anyone's pack (including one of
+ours), read **three files** — every command it can run is declared in plain JSON:
+
+- `tools/tools.register.json` — the tool invokes (scripts and shell commands);
+- `mcp/expose.json` — the upstream server commands it will spawn;
+- `toolfunnel.json` — the `requires` probes. Note these run **at gateway startup** (each declared
+  program is executed once with its version flag), which is why a `requires` command must be a
+  bare program name — the gateway rejects paths, spaces, and shell characters outright.
+
+Ship your own packs expecting the same scrutiny, and say so in your README (the `tf_pack` stub
+already does).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolfunnel",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "A zero-dependency MCP gateway: host your own tools, forward and curate tools from other MCP servers, expose them leanly to cut agent token cost, and gate every call through your own policy hooks before it runs.",
   "keywords": [
     "mcp",
@@ -28,9 +28,11 @@
   },
   "scripts": {
     "start": "node bin/toolfunnel.js",
+    "build": "echo toolfunnel has no build step - zero-dependency, runs from source",
     "http": "node bin/toolfunnel.js --http",
     "install-oauth": "node bin/toolfunnel.js install-oauth",
     "test": "node test/run-all.js",
+    "release": "node scripts/release.js",
     "test:integration": "node test/integration-real-mcp.test.js && node test/integration-http-client.test.js"
   },
   "dependencies": {},

package/src/auth/config.js

@@ -36,8 +36,10 @@
 const fs = require('node:fs');
 const path = require('node:path');
 
-/** Repo root: <root>/src/auth/config.js -> two dirs up. */
-const ROOT = path.resolve(__dirname, '..', '..');
+/** The CONFIG HOME (TOOLFUNNEL_HOME / --config-dir; defaults to the package root — see
+ *  src/core/config-home.js). Auth config is user-state, so it lives with the home. */
+const { resolveConfigHome } = require('../core/config-home');
+const ROOT = resolveConfigHome();
 
 /** The toggle/config file. NOT created until setConfig() writes it. */
 const CONFIG_PATH = path.join(ROOT, 'auth', 'auth.config.json');

package/src/auth/resource-server.js

@@ -112,7 +112,27 @@ async function resolveJwksUri(cfg, timeoutMs) {
   for (const url of candidates) {
     try {
       const doc = await fetchJson(url, timeoutMs);
-      if (doc && typeof doc.jwks_uri === 'string' && doc.jwks_uri.length > 0) return doc.jwks_uri;
+      if (doc && typeof doc.jwks_uri === 'string' && doc.jwks_uri.length > 0) {
+        // ORIGIN-PIN the discovered value. The ISSUER is operator-trusted config, but the discovery
+        // DOCUMENT arrives over the network — it must not be able to point key fetching at a
+        // foreign origin (key-substitution + SSRF-adjacent surface). Cross-origin JWKS hosting is
+        // real (e.g. Google's issuer and JWKS live on different hosts), so the escape hatch is an
+        // EXPLICIT trust statement: set "jwksUri" in the auth config and discovery is skipped.
+        let sameOrigin = false;
+        try {
+          sameOrigin = new URL(doc.jwks_uri).origin === new URL(cfg.issuer).origin;
+        } catch (_e) {
+          /* malformed URL on either side → treat as cross-origin → refuse */
+        }
+        if (!sameOrigin) {
+          throw new Error(
+            `discovered jwks_uri "${doc.jwks_uri}" is not on the issuer origin — refusing the ` +
+              'cross-origin discovery result. If your IdP intentionally hosts JWKS on a separate ' +
+              'origin, state that trust explicitly by setting "jwksUri" in auth/auth.config.json.'
+          );
+        }
+        return doc.jwks_uri;
+      }
       lastErr = new Error(`discovery doc at ${url} has no jwks_uri`);
     } catch (e) {
       lastErr = e;
@@ -121,13 +141,18 @@ async function resolveJwksUri(cfg, timeoutMs) {
   throw lastErr || new Error('OIDC discovery failed');
 }
 
-/** GET + parse JSON with a hard timeout. Throws on non-2xx, network error, or bad JSON. */
+/**
+ * GET + parse JSON with a hard timeout. Throws on non-2xx, network error, bad JSON — or a REDIRECT:
+ * discovery metadata must come from the exact well-known URL derived from the trusted issuer
+ * (following a redirect would let a bounced endpoint serve the document from anywhere, hollowing
+ * out the origin pin above). Only discovery uses this helper; the JWKS fetch itself is jose's.
+ */
 async function fetchJson(url, timeoutMs) {
   const ac = new AbortController();
   const ms = Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : 10000;
   const t = setTimeout(() => ac.abort(), ms);
   try {
-    const res = await fetch(url, { signal: ac.signal, redirect: 'follow' });
+    const res = await fetch(url, { signal: ac.signal, redirect: 'error' });
     if (!res || !res.ok) throw new Error(`GET ${url} -> HTTP ${res ? res.status : 'no-response'}`);
     return await res.json();
   } finally {

package/src/core/config-home.js

@@ -0,0 +1,134 @@
+'use strict';
+
+/**
+ * config-home.js — WHERE the gateway's mutable config lives (board item 9, the packaging enabler).
+ *
+ * The problem this solves: an npm/npx-installed gateway keeps its config INSIDE the package
+ * directory, so `npm update toolfunnel` replaces the package tree and EATS the user's tools,
+ * hooks, curation, and identity. Config must be able to live in a home of its own:
+ *
+ *   resolution precedence:  --config-dir flag  >  TOOLFUNNEL_HOME env  >  the package root
+ *
+ * The default is UNCHANGED: a git clone keeps everything in the repo root exactly as before
+ * (home === package root, no seeding, byte-identical behaviour). Pointing TOOLFUNNEL_HOME at an
+ * empty directory makes the gateway SEED it on first use — the shipped register + its scripts, an
+ * empty expose.json, the default hooks manifest — and every mutable path (tools/ mcp/ hooks/
+ * auth/ logs/ toolfunnel.json packages/) anchors there from then on. Seeding never overwrites an
+ * existing file, so a home survives package updates by construction.
+ *
+ * Two env vars are the process-tree contract (children inherit them via defaultRunScript's
+ * spawn env):
+ *   TOOLFUNNEL_HOME — the resolved ABSOLUTE config home (normalised at init so a relative value
+ *                     can't skew between processes with different cwds).
+ *   TOOLFUNNEL_PKG  — the package root of the gateway that spawned the tool, so a management
+ *                     script SEEDED INTO an external home can still require the engine code
+ *                     (src/…) it was copied away from. A script always prefers its own
+ *                     __dirname-derived root when that root contains the engine (the git-clone
+ *                     layout), so a stale inherited value can never shadow a real local install.
+ *
+ * Zero new dependencies. Node built-ins only.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+/** The package root: this file lives at <pkg>/src/core/config-home.js. */
+const PKG_ROOT = path.resolve(__dirname, '..', '..');
+
+/**
+ * Resolve the config home. Pure — no filesystem writes, no env mutation.
+ * @param {{dir?: string}} [opts]  dir = an explicit --config-dir value (wins over the env)
+ * @returns {string} absolute config-home path
+ */
+function resolveConfigHome(opts) {
+  const o = opts || {};
+  const fromFlag = typeof o.dir === 'string' && o.dir.trim().length > 0 ? o.dir.trim() : null;
+  const fromEnv = typeof process.env.TOOLFUNNEL_HOME === 'string' && process.env.TOOLFUNNEL_HOME.trim().length > 0
+    ? process.env.TOOLFUNNEL_HOME.trim()
+    : null;
+  const chosen = fromFlag || fromEnv;
+  return chosen ? path.resolve(chosen) : PKG_ROOT;
+}
+
+/** Recursively copy a directory, skipping any destination file that already exists. */
+function copyTreeIfAbsent(srcDir, destDir, seeded) {
+  let entries;
+  try {
+    entries = fs.readdirSync(srcDir, { withFileTypes: true });
+  } catch (_e) {
+    return; // a missing source dir seeds nothing (defensive)
+  }
+  fs.mkdirSync(destDir, { recursive: true });
+  for (const e of entries) {
+    const from = path.join(srcDir, e.name);
+    const to = path.join(destDir, e.name);
+    if (e.isDirectory()) {
+      copyTreeIfAbsent(from, to, seeded);
+    } else if (e.isFile() && !fs.existsSync(to)) {
+      fs.copyFileSync(from, to);
+      seeded.push(to);
+    }
+  }
+}
+
+/**
+ * Make `home` a working config home, seeding whatever is ABSENT from the shipped defaults.
+ * Idempotent and never destructive: an existing file is NEVER overwritten (a home must survive
+ * package updates — that is the whole point). home === package root → a no-op (the git-clone
+ * layout is already complete). Throws only if the home cannot be created at all.
+ *
+ * Deliberately NOT seeded: tools.state.json (absent = default visibility), auth/ (absent = auth
+ * off), logs/ (absent = logging off), toolfunnel.json (absent = the default identity — an
+ * npm-wrap ships its OWN copy inside its bundled home).
+ *
+ * @param {string} home  absolute config-home path (from resolveConfigHome)
+ * @returns {{home: string, seeded: string[]}} the files seeded on THIS call (empty = was complete)
+ */
+function ensureConfigHome(home) {
+  const seeded = [];
+  if (path.resolve(home) === PKG_ROOT) return { home: PKG_ROOT, seeded };
+  fs.mkdirSync(home, { recursive: true });
+
+  // The register + every shipped script (management tf_* + demo tools). The management scripts
+  // are config-tree citizens (the register's invoke paths point at them), so they travel.
+  copyTreeIfAbsent(path.join(PKG_ROOT, 'tools'), path.join(home, 'tools'), seeded);
+  // The state overlay is user-state, not a shipped default — drop a copied one if the package
+  // tree happened to carry local toggles (dev clone); a FRESH home starts with default visibility.
+  const strayState = path.join(home, 'tools', 'tools.state.json');
+  if (seeded.includes(strayState)) {
+    try { fs.unlinkSync(strayState); } catch (_e) { /* best-effort */ }
+    seeded.splice(seeded.indexOf(strayState), 1);
+  }
+
+  // The upstream/curation store and the hooks tree. NOTE the npm tarball ships
+  // mcp/expose.example.json but NOT mcp/expose.json (the live store is user-state), so after the
+  // tree copy the live store is synthesised EMPTY when absent. Never seed it from the example —
+  // the example is a POPULATED demo (it attaches the mock upstream), and a fresh home must start
+  // connected to nothing, exactly like a fresh clone.
+  copyTreeIfAbsent(path.join(PKG_ROOT, 'mcp'), path.join(home, 'mcp'), seeded);
+  const exposePath = path.join(home, 'mcp', 'expose.json');
+  if (!fs.existsSync(exposePath)) {
+    fs.mkdirSync(path.dirname(exposePath), { recursive: true });
+    fs.writeFileSync(exposePath, JSON.stringify({ version: 1, upstreams: [], expose: [] }, null, 2) + '\n');
+    seeded.push(exposePath);
+  }
+  copyTreeIfAbsent(path.join(PKG_ROOT, 'hooks'), path.join(home, 'hooks'), seeded);
+  return { home, seeded };
+}
+
+/**
+ * The one-call init used by bin/toolfunnel.js for every mode: resolve, seed, and write the
+ * process-tree contract back into the env (see the header) so every module loaded AFTER this —
+ * and every child tool spawned later — reads the same resolved home.
+ * @param {{dir?: string}} [opts]
+ * @returns {{home: string, seeded: string[]}}
+ */
+function initConfigHome(opts) {
+  const home = resolveConfigHome(opts);
+  const res = ensureConfigHome(home);
+  process.env.TOOLFUNNEL_HOME = res.home;
+  process.env.TOOLFUNNEL_PKG = PKG_ROOT;
+  return res;
+}
+
+module.exports = { PKG_ROOT, resolveConfigHome, ensureConfigHome, initConfigHome };

package/src/core/logger.js

@@ -27,8 +27,10 @@
 const fs = require('node:fs');
 const path = require('node:path');
 
-/** Repo root: <root>/src/core/logger.js -> two dirs up. */
-const ROOT = path.resolve(__dirname, '..', '..');
+/** The CONFIG HOME (TOOLFUNNEL_HOME / --config-dir; defaults to the package root — see
+ *  config-home.js). Logs + their toggle are user-state, so they live with the home. */
+const { resolveConfigHome } = require('./config-home');
+const ROOT = resolveConfigHome();
 
 /** The toggle/config file. NOT created until setConfig() writes it. */
 const CONFIG_PATH = path.join(ROOT, 'logs', 'log.config.json');

package/src/core/requires.js

@@ -0,0 +1,138 @@
+'use strict';
+
+/**
+ * requires.js — runtime-requirement preflight (the packaging story's honesty layer).
+ *
+ * A shipped pack's tools may need runtimes the gateway itself does not (python for a PDF tool,
+ * git for a repo tool). The pack DECLARES them in its toolfunnel.json — the identity file that
+ * already travels with every config home — and the gateway probes them ONCE at startup:
+ *
+ *   "requires": [
+ *     { "command": "python", "min": "3.10", "why": "the pdf-extract tools" },
+ *     { "command": "git" }
+ *   ]
+ *
+ * Probes are ADVISORY, never fatal: a missing runtime breaks only the tools that need it, so the
+ * gateway starts and the operator gets a clear stderr line naming what is missing, the version
+ * found vs needed, and the declared "why". Fields per entry (only `command` is required):
+ *   command     the executable to probe (e.g. "python", "node", "git")
+ *   versionArg  the flag that prints a version (default "--version")
+ *   min         minimum version, dotted numerics (e.g. "3.10" / "18" / "3.10.2")
+ *   why         shown in the warning so the operator knows which tools care
+ *
+ * Zero new dependencies: child_process probes + a hand-rolled dotted-numeric compare. NO semver
+ * library — by the packaging hard constraint, and dotted numerics cover real runtime versions.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+/** Parse the FIRST dotted-numeric version out of a probe's output ("Python 3.12.1" → [3,12,1]).
+ *  Returns null when no version-shaped token is present. */
+function parseVersion(text) {
+  const m = /(\d+)\.(\d+)(?:\.(\d+))?/.exec(String(text || ''));
+  if (!m) {
+    const single = /\b(\d+)\b/.exec(String(text || ''));
+    return single ? [Number(single[1]), 0, 0] : null;
+  }
+  return [Number(m[1]), Number(m[2]), Number(m[3] || 0)];
+}
+
+/** Hand-rolled dotted-numeric compare: -1 | 0 | 1 for a<b | a==b | a>b. */
+function compareVersions(a, b) {
+  for (let i = 0; i < 3; i += 1) {
+    const x = a[i] || 0;
+    const y = b[i] || 0;
+    if (x < y) return -1;
+    if (x > y) return 1;
+  }
+  return 0;
+}
+
+/**
+ * Probe one command for its version string. On Windows a PATHEXT shim (a .cmd like npx) cannot be
+ * spawned shell:false (ENOENT/EINVAL — the CVE-2024-27980 mitigation), so a failed direct probe is
+ * retried through cmd.exe, mirroring mcp-client's winLaunch.
+ * @param {string} command
+ * @param {string} versionArg
+ * @returns {{found: boolean, version: (number[]|null), raw: string}}
+ */
+function probe(command, versionArg) {
+  const runOnce = (cmd, args) => spawnSync(cmd, args, { encoding: 'utf8', windowsHide: true, timeout: 5000 });
+  let res = runOnce(command, [versionArg]);
+  if (res.error && process.platform === 'win32') {
+    const comspec = process.env.ComSpec || 'cmd.exe';
+    res = runOnce(comspec, ['/c', command, versionArg]);
+  }
+  if (res.error || res.status == null) return { found: false, version: null, raw: '' };
+  const raw = `${res.stdout || ''} ${res.stderr || ''}`.trim();
+  const version = parseVersion(raw);
+  // "Spawned" is not "exists": the cmd.exe fallback launches fine for a NONEXISTENT command and
+  // exits non-zero ("is not recognized…"). Existence = a clean exit OR a version-shaped answer.
+  const found = res.status === 0 || version !== null;
+  return { found, version: found ? version : null, raw };
+}
+
+/**
+ * Check the `requires` declared in `<home>/toolfunnel.json`. Returns the problem list — the
+ * caller decides how to surface it (the gateway logs each to stderr and starts anyway). NEVER
+ * throws; a malformed requires entry is itself reported as a problem rather than crashing.
+ * @param {string} home  the resolved config home
+ * @returns {Array<{command:string, problem:string}>}
+ */
+function checkRequires(home) {
+  let cfg;
+  try {
+    cfg = JSON.parse(fs.readFileSync(path.join(home, 'toolfunnel.json'), 'utf8'));
+  } catch (_e) {
+    return []; // absent/bad identity file → nothing declared
+  }
+  const list = cfg && Array.isArray(cfg.requires) ? cfg.requires : [];
+  const problems = [];
+  for (const entry of list) {
+    if (!entry || typeof entry !== 'object' || typeof entry.command !== 'string' || entry.command.trim() === '') {
+      problems.push({ command: String(entry && entry.command), problem: 'malformed requires entry (needs a "command" string)' });
+      continue;
+    }
+    const command = entry.command.trim();
+    // A requires command is a bare PROGRAM NAME, never a shell string. This is load-bearing on
+    // Windows: the cmd.exe shim fallback below hands the token to cmd, where an unquoted
+    // metacharacter ("x&evil") would CHAIN commands — a probe must never be able to run anything
+    // beyond `<program> <versionArg>`. Reject anything shell-shaped up front (also catches paths:
+    // declare tools by PATH name, which is the only portable claim a pack can make anyway).
+    if (!/^[A-Za-z0-9][A-Za-z0-9._+-]*$/.test(command)) {
+      problems.push({ command, problem: `requires.command "${command}" is not a bare program name (no paths, spaces, or shell characters)` });
+      continue;
+    }
+    const why = typeof entry.why === 'string' && entry.why ? ` (needed for: ${entry.why})` : '';
+    const versionArg = typeof entry.versionArg === 'string' && /^--?[A-Za-z][A-Za-z-]*$/.test(entry.versionArg)
+      ? entry.versionArg
+      : '--version'; // same rule: a version FLAG, never a shell fragment
+    const p = probe(command, versionArg);
+    if (!p.found) {
+      problems.push({ command, problem: `"${command}" was not found on PATH${why}` });
+      continue;
+    }
+    if (typeof entry.min === 'string' && entry.min.trim() !== '') {
+      const min = parseVersion(entry.min);
+      if (!min) {
+        problems.push({ command, problem: `requires.min "${entry.min}" is not a dotted numeric version` });
+        continue;
+      }
+      if (!p.version) {
+        problems.push({ command, problem: `"${command}" answered but printed no recognisable version (wanted >= ${entry.min})${why}` });
+        continue;
+      }
+      if (compareVersions(p.version, min) < 0) {
+        problems.push({
+          command,
+          problem: `"${command}" is ${p.version.join('.')} but this setup declares >= ${entry.min}${why}`,
+        });
+      }
+    }
+  }
+  return problems;
+}
+
+module.exports = { checkRequires, parseVersion, compareVersions, probe };