toolfunnel 0.3.0 → 0.4.0

package/src/mcp/server.js

@@ -53,7 +53,18 @@ const logger = require('../core/logger');
 const metrics = require('../core/metrics');
 
 // ── Path anchors (everything stays under the host root) ───────────────────────────────────────
-const ROOT = path.resolve(__dirname, '..', '..'); // <…>/<root>
+// The CODE lives in the package; the mutable CONFIG lives in the resolved config home — the same
+// directory in a git clone, distinct when TOOLFUNNEL_HOME / --config-dir points elsewhere (npm
+// installs, npm-wrapped MCPs — an `npm update` must never eat the user's tools). Every anchor
+// below derives from the HOME.
+const { PKG_ROOT, resolveConfigHome, ensureConfigHome } = require('../core/config-home');
+const ROOT = resolveConfigHome(); // <…>/<config home>
+// The process-tree contract for child tools (defaultRunScript spawns with process.env): a
+// management script SEEDED into an external home finds the engine code via TOOLFUNNEL_PKG, and
+// the resolved ABSOLUTE home is written back so no child re-resolves a relative value against a
+// different cwd.
+process.env.TOOLFUNNEL_PKG = PKG_ROOT;
+if (ROOT !== PKG_ROOT) process.env.TOOLFUNNEL_HOME = ROOT;
 const REGISTER_PATH = path.join(ROOT, 'tools', 'tools.register.json');
 // The ACTIVE/DISABLED overlay (tool-state.js). toolfunnel_list_tools filters DISABLED tools out so
 // they are not surfaced to the client. Read FRESH per list() call so UI toggles take effect with no
@@ -68,7 +79,14 @@ const SCRIPTS_ROOT = path.join(ROOT, 'tools', 'scripts');
 const EXPOSE_PATH = path.join(ROOT, 'mcp', 'expose.json');
 
 const PROTOCOL_VERSION = '2024-11-05';
-const SERVER_INFO = { name: 'toolfunnel', version: '0.3.0' };
+// Identity comes from the OPTIONAL toolfunnel.json at the root (absent → name "toolfunnel",
+// version from package.json — serverInfo can never drift from the released version). The config
+// seam is what lets a wrapped MCP introduce itself as ITSELF in the initialize handshake and
+// /health. Loaded once at module init: clients cache serverInfo from initialize, so identity is
+// deliberately NOT hot-reloaded (a mid-session identity swap would lie to connected clients).
+const { loadServerConfig } = require('../core/server-config');
+const SERVER_CONFIG = loadServerConfig(ROOT);
+const SERVER_INFO = { name: SERVER_CONFIG.serverName, version: SERVER_CONFIG.serverVersion };
 
 // ── Diagnostics → stderr only (stdout is the JSON-RPC channel; never pollute it). ─────────────
 function logErr(...parts) {
@@ -248,6 +266,11 @@ function makeRegistryAdapter(registry, opts) {
 //   - engine, ctx: threaded into gatedRun for the curated-direct path (a curated tool runs
 //                  THROUGH the same PreToolUse gate as toolfunnel_run_tool — the safety invariant).
 function buildProtocol() {
+  // Make the config home real before anything reads from it: seeds an external home's register/
+  // scripts/expose/hooks from the shipped defaults on first use. A no-op when home === package
+  // root; idempotent and never-overwriting afterwards. A failure falls through to loadRegistry's
+  // own clear error.
+  try { ensureConfigHome(ROOT); } catch (err) { logErr('config-home init failed:', (err && err.message) || String(err)); }
   const registry = loadRegistry(REGISTER_PATH, { scriptsRoot: SCRIPTS_ROOT });
   const loader = loadManifest(MANIFEST_PATH);
 
@@ -947,6 +970,31 @@ async function reloadExpose(build, send) {
   logErr('reloadExpose: expose.json reloaded — upstreams reconnected');
 }
 
+/**
+ * Re-read tools.register.json and swap the ONE live Registry's index IN PLACE (Registry.reload —
+ * last-good on any failure). In-place mutation is the point: the Registry instance is CAPTURED by
+ * the protocol adapter at build time, so swapping internals means every reader — the lean
+ * meta-tools, run_tool resolution, and the top-level hot surface — sees the new entries on its
+ * next call with no rewiring. Emits list_changed: a hot-promoted local tool's definition may have
+ * appeared, changed, or gone. NEVER throws.
+ *
+ * @param {{registry?:object}} build
+ * @param {(obj:object)=>void} send  the stdio writer, for the list_changed notification
+ * @returns {void}
+ */
+function reloadRegister(build, send) {
+  try {
+    if (build && build.registry && typeof build.registry.reload === 'function' && build.registry.reload()) {
+      emitToolsListChanged(send);
+      logErr('reloadRegister: tools.register.json reloaded');
+    } else {
+      logErr('reloadRegister: reload failed (bad JSON / invalid entry / mid-write?) — keeping the last-good register');
+    }
+  } catch (err) {
+    logErr('reloadRegister: unexpected failure (keeping current register):', (err && err.message) || String(err));
+  }
+}
+
 /**
  * Re-read the hooks manifest + state overlay and swap a fresh HookEngine into `build`. The next
  * gated call (toolfunnel_run_tool / curated-direct) uses the new engine, so an added/changed/toggled
@@ -1001,6 +1049,23 @@ function startConfigWatchers(build, send) {
     if (hooksTimer && typeof hooksTimer.unref === 'function') hooksTimer.unref();
   }
 
+  let registerTimer = null;
+  function scheduleRegister() {
+    if (registerTimer) clearTimeout(registerTimer);
+    registerTimer = setTimeout(() => { registerTimer = null; reloadRegister(build, send); }, DEBOUNCE_MS);
+    if (registerTimer && typeof registerTimer.unref === 'function') registerTimer.unref();
+  }
+
+  // tools.state.json needs NO reload (it is read fresh per tools/list & tools/call) — but a
+  // hot/hidden/enabled toggle CHANGES the top-level surface, so a connected client must be told
+  // to re-fetch. Notification only.
+  let stateTimer = null;
+  function scheduleStateNotify() {
+    if (stateTimer) clearTimeout(stateTimer);
+    stateTimer = setTimeout(() => { stateTimer = null; emitToolsListChanged(send); }, DEBOUNCE_MS);
+    if (stateTimer && typeof stateTimer.unref === 'function') stateTimer.unref();
+  }
+
   try {
     const w = fs.watch(mcpDir, (_event, filename) => {
       // null filename (some platforms don't report it) → reload to be safe; else only expose.json.
@@ -1024,6 +1089,23 @@ function startConfigWatchers(build, send) {
   } catch (err) {
     logErr('startConfigWatchers: cannot watch', hooksDir + ':', (err && err.message) || String(err));
   }
+
+  // The register + state overlay live in tools/. Register edits (tf_tool_add from its child
+  // process, the UI, a hand edit) were the ONE config surface with no watcher — a running gateway
+  // served its startup snapshot until restart, which broke the "add a tool live" story the moment
+  // the server outlived the edit. State toggles only need the list_changed nudge (read-fresh).
+  const toolsDir = path.dirname(REGISTER_PATH);
+  try {
+    const w = fs.watch(toolsDir, (_event, filename) => {
+      const base = filename ? path.basename(String(filename)) : '';
+      if (!filename || base === 'tools.register.json') scheduleRegister();
+      if (!filename || base === 'tools.state.json') scheduleStateNotify();
+    });
+    if (w && typeof w.unref === 'function') w.unref();
+    logErr('startConfigWatchers: watching', toolsDir, 'for register/state changes');
+  } catch (err) {
+    logErr('startConfigWatchers: cannot watch', toolsDir + ':', (err && err.message) || String(err));
+  }
 }
 
 // ─────────────────────────────────────────────────────────────────────────────────────────────

package/src/packages/packager.js

@@ -33,9 +33,11 @@
 const fs = require('node:fs');
 const path = require('node:path');
 
-// ROOT resolution mirrors src/mcp/server.js: this file lives at
-// <root>/src/packages/packager.js, so two levels up is the project root.
-const ROOT = path.resolve(__dirname, '..', '..'); // <…> project root
+// ROOT = the CONFIG HOME (TOOLFUNNEL_HOME / --config-dir; defaults to the package root — see
+// src/core/config-home.js). Packages are config-tree citizens: they export FROM and import INTO
+// the home's register/manifest/expose stores, and the packages/ tree itself lives in the home.
+const { resolveConfigHome } = require('../core/config-home');
+const ROOT = resolveConfigHome(); // <…> config home
 
 const PACKAGE_MANIFEST = 'package.json';
 

package/src/tools/registry.js

@@ -130,6 +130,15 @@ function validateEntry(entry, { requireId = true } = {}) {
   if (inv.type === 'shell' && (typeof inv.command !== 'string' || inv.command.length === 0)) {
     throw new Error(`Registry: shell invoke needs a non-empty "command" (id=${entry.id})`);
   }
+  // Optional MCP input schema. When present it must be a plain object — a hot-promoted tool
+  // advertises it VERBATIM to MCP clients (tools/list), so a typo'd shape must fail loudly at
+  // authoring time rather than silently degrade to the free-form fallback at surface time.
+  if (
+    entry.inputSchema !== undefined &&
+    (typeof entry.inputSchema !== 'object' || entry.inputSchema === null || Array.isArray(entry.inputSchema))
+  ) {
+    throw new Error(`Registry: entry.inputSchema must be an object when present (id=${entry.id})`);
+  }
   return entry;
 }
 
@@ -284,6 +293,40 @@ class Registry {
     return true;
   }
 
+  /**
+   * Re-read the register FILE and swap the in-memory index — the hot-reload seam. A running
+   * gateway holds ONE Registry instance (captured by the protocol adapter at build time), while
+   * tf_tool_add / the UI / a hand edit mutate the FILE from another process — without this, those
+   * edits are invisible until restart. LAST-GOOD semantics: the replacement index is built and
+   * fully validated FIRST; any read/parse/validation failure (including a mid-write partial file)
+   * leaves the current index untouched and returns false. NEVER throws.
+   * @returns {boolean} true when the on-disk register replaced the in-memory index
+   */
+  reload() {
+    let data;
+    try {
+      data = JSON.parse(fs.readFileSync(this._filePath, 'utf8'));
+    } catch (_e) {
+      return false; // unreadable / mid-write / bad JSON → keep last-good
+    }
+    if (!data || typeof data !== 'object' || Array.isArray(data)) return false;
+    const tools = Array.isArray(data.tools) ? data.tools : [];
+    const next = new Map();
+    try {
+      for (const t of tools) {
+        validateEntry(t);
+        if (next.has(t.id)) throw new Error(`duplicate tool id "${t.id}"`);
+        next.set(t.id, cloneEntry(t));
+      }
+    } catch (_e) {
+      return false; // an invalid entry → keep last-good
+    }
+    if (typeof data.version === 'number') this._version = data.version;
+    if (typeof data.description === 'string') this._description = data.description;
+    this._byId = next;
+    return true;
+  }
+
   /**
    * Write a host-local script's text under this scriptsRoot, atomically.
    *

package/src/ui/server.js

@@ -19,6 +19,9 @@
  * DIRECTLY (no MCP round-trip). Every write is atomic (temp + rename) inside the store.
  *
  * SAFETY CONTRACT (mirrors src/mcp/http-transport.js):
+ *   - start() HARD-REFUSES a non-loopback bind host. The UI has no auth path at all, and it can
+ *     spawn processes (mcp add/discover) and write scripts (tools/hooks) — off-loopback it would be
+ *     an unauthenticated remote console. Loopback-only by design; no flag overrides it.
  *   - Binds 127.0.0.1 by default; a non-loopback Host header is rejected (DNS-rebind guard).
  *   - The request listener NEVER throws — a bad request becomes a clean JSON error.
  *   - start() rejects cleanly on EADDRINUSE (caller decides); stop() is idempotent.
@@ -91,6 +94,17 @@ function isLoopbackHost(hostHeader) {
   return host === '127.0.0.1' || host === 'localhost' || host === '::1' || host === '0:0:0:0:0:0:0:1';
 }
 
+/**
+ * Is the BIND address loopback? STRICTER than the Host-header check above: a missing Host header
+ * is legitimately loopback (the bind address is the boundary), but a missing/empty BIND address is
+ * not a loopback claim — it must name a loopback host explicitly to pass.
+ * @param {string|undefined} bindHost
+ * @returns {boolean}
+ */
+function isLoopbackBindHost(bindHost) {
+  return typeof bindHost === 'string' && bindHost.trim() !== '' && isLoopbackHost(bindHost);
+}
+
 /** Regex-escape a literal so a matcher built from it FULL-matches the string verbatim. */
 function escapeRegex(str) {
   return String(str).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
@@ -183,7 +197,8 @@ function logConfigChange(fields) {
  * @param {object}  [opts]
  * @param {string}  [opts.host]  bind address (default 127.0.0.1 — loopback only).
  * @param {number}  [opts.port]  bind port (default 9777; pass 0 for an OS-assigned port).
- * @param {string}  [opts.root]  repo root holding tools/ mcp/ hooks/ (default path.resolve(__dirname,'..','..')).
+ * @param {string}  [opts.root]  config root holding tools/ mcp/ hooks/ (default: the resolved
+ *                               config home — TOOLFUNNEL_HOME / --config-dir / the package root).
  * @returns {{ start: () => Promise<{url:string, port:number}>, stop: () => Promise<void>, get url():(string|null) }}
  */
 function createUiServer(opts = {}) {
@@ -191,8 +206,11 @@ function createUiServer(opts = {}) {
   const host = typeof o.host === 'string' && o.host.length > 0 ? o.host : DEFAULT_HOST;
   // A port of 0 is VALID (OS-assigned) so distinguish "not provided" from 0.
   const requestedPort = Number.isInteger(o.port) && o.port >= 0 ? o.port : DEFAULT_PORT;
-  // The repo root: tools.register.json etc. live under <root>/tools, <root>/mcp, <root>/hooks.
-  const root = typeof o.root === 'string' && o.root.length > 0 ? o.root : path.resolve(__dirname, '..', '..');
+  // The config root: tools.register.json etc. live under <root>/tools, <root>/mcp, <root>/hooks.
+  // Default = the resolved config home (see src/core/config-home.js), so a --config-dir /
+  // TOOLFUNNEL_HOME gateway and its UI edit the SAME stores.
+  const { resolveConfigHome } = require('../core/config-home');
+  const root = typeof o.root === 'string' && o.root.length > 0 ? o.root : resolveConfigHome();
 
   // ── Path anchors (everything resolved from the repo root) ────────────────────────────────────
   const REGISTER_PATH = path.join(root, 'tools', 'tools.register.json');
@@ -990,6 +1008,23 @@ function createUiServer(opts = {}) {
       const pathName = qIndex === -1 ? rawUrl : rawUrl.slice(0, qIndex);
       const method = (req.method || 'GET').toUpperCase();
 
+      // CSRF guard. The bind address stops the NETWORK, not the browser: any web page the
+      // operator visits can fire a no-cors POST at 127.0.0.1:<port>, and the mutating routes
+      // below write tool scripts and register process-spawning upstreams. Browsers ALWAYS send
+      // an Origin header on cross-origin POSTs, so: a PRESENT Origin must itself be loopback
+      // (the UI's own pages), while an ABSENT Origin (curl, CLI clients, non-browser tools) is
+      // allowed — for those, the bind address remains the boundary. GETs stay open (read-only).
+      if (method !== 'GET') {
+        const origin = req.headers && req.headers.origin;
+        if (origin) {
+          let originHost = null;
+          try { originHost = new URL(origin).host; } catch (_e) { /* malformed → reject below */ }
+          if (!originHost || !isLoopbackHost(originHost)) {
+            return sendJson(res, 403, { ok: false, error: 'forbidden: cross-origin request (CSRF guard)' });
+          }
+        }
+      }
+
       // ── Static assets ─────────────────────────────────────────────────────────────────────────
       if (method === 'GET' && (pathName === '/' || pathName === '/index.html')) {
         return sendStatic(res, 'index.html');
@@ -1079,6 +1114,16 @@ function createUiServer(opts = {}) {
    */
   function start() {
     if (started) return Promise.resolve({ url: currentUrl(), port: boundPort });
+    // The HTTP transport refuses a non-loopback bind unless OAuth is enabled; the UI has NO auth
+    // path, so its refusal is unconditional. This endpoint spawns processes and writes scripts —
+    // "--ui --host 0.0.0.0" would hand an unauthenticated remote console to the LAN.
+    if (!isLoopbackBindHost(host)) {
+      return Promise.reject(new Error(
+        `refusing to bind the config UI to non-loopback host "${host}" — the UI is unauthenticated ` +
+          'and can spawn processes / write tool scripts. It is loopback-only by design; to configure ' +
+          'the gateway from another machine, use an SSH tunnel to 127.0.0.1 instead.'
+      ));
+    }
     httpServer = http.createServer(onRequest);
     return new Promise((resolve, reject) => {
       const onListenError = (err) => {
@@ -1140,5 +1185,6 @@ module.exports = {
   createUiServer,
   // Exported for unit tests / reuse — the small pure seams.
   isLoopbackHost,
+  isLoopbackBindHost,
   escapeRegex,
 };

package/tools/scripts/tf-env.js

@@ -0,0 +1,43 @@
+'use strict';
+
+/**
+ * tf-env.js — shared HOME/ENGINE resolution for the tf-* management scripts.
+ *
+ * A management script runs in one of two layouts:
+ *   1. The git-clone original: it lives at <pkg>/tools/scripts/, and TWO dirs up is a root that
+ *      holds BOTH the config (tools/ mcp/ hooks/) and the engine code (src/).
+ *   2. A copy SEEDED into an external CONFIG HOME (TOOLFUNNEL_HOME / --config-dir — see
+ *      src/core/config-home.js): the config sits beside it, but the engine code does NOT.
+ *      The gateway that spawned it wrote the process-tree contract into the env:
+ *      TOOLFUNNEL_HOME (the resolved absolute home) + TOOLFUNNEL_PKG (the package root).
+ *
+ * Resolution rules:
+ *   - ENGINE: prefer the LOCAL __dirname-derived root whenever it actually contains the engine
+ *     (layout 1) so a stale inherited TOOLFUNNEL_PKG can never shadow a real install; else the
+ *     env; else the local root anyway (the require failure is then the clearest error).
+ *   - HOME:   TOOLFUNNEL_HOME when set (the gateway always sets it), else the local root.
+ *
+ * Same-dir require ('./tf-env') keeps this working in BOTH layouts — the seeder copies the whole
+ * scripts directory, so this file always travels with its callers. Node built-ins only.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const LOCAL_ROOT = path.resolve(__dirname, '..', '..');
+const HAS_LOCAL_ENGINE = fs.existsSync(path.join(LOCAL_ROOT, 'src', 'tools', 'registry.js'));
+
+/** The package root holding the engine code (src/…). */
+const PKG = HAS_LOCAL_ENGINE ? LOCAL_ROOT : (process.env.TOOLFUNNEL_PKG || LOCAL_ROOT);
+
+/** The config home holding tools/ mcp/ hooks/ (the mutable state this script edits). */
+const HOME = typeof process.env.TOOLFUNNEL_HOME === 'string' && process.env.TOOLFUNNEL_HOME.trim().length > 0
+  ? path.resolve(process.env.TOOLFUNNEL_HOME.trim())
+  : LOCAL_ROOT;
+
+/** Require an engine module by its src-relative path, e.g. srcRequire('tools/registry'). */
+function srcRequire(rel) {
+  return require(path.join(PKG, 'src', rel));
+}
+
+module.exports = { PKG, HOME, srcRequire };

package/tools/scripts/tf-hook-add.js

@@ -37,12 +37,11 @@
  */
 
 const path = require('node:path');
-const { loadManifest } = require('../../src/core/hook-loader');
+// Shared HOME/engine resolution (see tf-env.js): config beside us, engine from the package.
+const { HOME, srcRequire } = require('./tf-env');
+const { loadManifest } = srcRequire('core/hook-loader');
 
-/**
- * ToolFunnel root, two dirs up from this script (tools/scripts -> tools -> root).
- */
-const ROOT = path.resolve(__dirname, '..', '..');
+const ROOT = HOME;
 
 /** The hook manifest, relative to ROOT. */
 const MANIFEST = path.join(ROOT, 'hooks', 'hooks.manifest.json');

package/tools/scripts/tf-hook-set.js

@@ -33,12 +33,11 @@
  */
 
 const path = require('node:path');
-const { loadManifest } = require('../../src/core/hook-loader');
+// Shared HOME/engine resolution (see tf-env.js): config beside us, engine from the package.
+const { HOME, srcRequire } = require('./tf-env');
+const { loadManifest } = srcRequire('core/hook-loader');
 
-/**
- * ToolFunnel root, two dirs up from this script (tools/scripts -> tools -> root).
- */
-const ROOT = path.resolve(__dirname, '..', '..');
+const ROOT = HOME;
 
 /** The hook manifest, relative to ROOT. */
 const MANIFEST = path.join(ROOT, 'hooks', 'hooks.manifest.json');

package/tools/scripts/tf-list.js

@@ -48,19 +48,16 @@
 
 const path = require('node:path');
 
-const { loadRegistry } = require('../../src/tools/registry');
-const { loadToolState, isToolEnabled, isToolHidden } = require('../../src/tools/tool-state');
-const { loadExposeStore } = require('../../src/mcp/expose-store');
-const { loadManifest } = require('../../src/core/hook-loader');
+// HOME/engine resolution shared by every tf-* script (see tf-env.js): the config lives beside
+// this script (the git-clone root OR a seeded external config home); the engine code is required
+// from the package that spawned us when it is not local.
+const { HOME, srcRequire } = require('./tf-env');
+const { loadRegistry } = srcRequire('tools/registry');
+const { loadToolState, isToolEnabled, isToolHidden } = srcRequire('tools/tool-state');
+const { loadExposeStore } = srcRequire('mcp/expose-store');
+const { loadManifest } = srcRequire('core/hook-loader');
 
-/**
- * The toolfunnel root, resolved from THIS file's location so the tool stays inside
- * the sandbox and is portable wherever the tree is copied.
- *
- * This script lives at:  <root>/tools/scripts/tf-list.js
- * so the root is two directories up from __dirname:  scripts -> tools -> <root>
- */
-const ROOT = path.resolve(__dirname, '..', '..');
+const ROOT = HOME;
 
 // Canonical store paths (see the script contract).
 const REGISTER_PATH = path.join(ROOT, 'tools', 'tools.register.json');

package/tools/scripts/tf-log.js

@@ -21,7 +21,10 @@
  *   failure:        { ok:false, error }
  */
 
-const logger = require('../../src/core/logger');
+// Shared HOME/engine resolution (see tf-env.js): the logger module itself resolves the config
+// home from the env the gateway set, so requiring it from the right PACKAGE is all we need.
+const { srcRequire } = require('./tf-env');
+const logger = srcRequire('core/logger');
 
 /**
  * Parse TOOLFUNNEL_TOOL_ARGS (a JSON string; {} if absent). Throws on malformed JSON

package/tools/scripts/tf-mcp-add.js

@@ -41,13 +41,11 @@
  */
 
 const path = require('node:path');
-const { loadExposeStore } = require('../../src/mcp/expose-store');
+// Shared HOME/engine resolution (see tf-env.js): config beside us, engine from the package.
+const { HOME, srcRequire } = require('./tf-env');
+const { loadExposeStore } = srcRequire('mcp/expose-store');
 
-/**
- * ToolFunnel root, resolved from THIS file's location:
- *   <root>/tools/scripts/tf-mcp-add.js -> root is two dirs up.
- */
-const ROOT = path.resolve(__dirname, '..', '..');
+const ROOT = HOME;
 
 /** The MCP config (upstreams + expose), per the host path contract. */
 const EXPOSE_PATH = path.join(ROOT, 'mcp', 'expose.json');

package/tools/scripts/tf-mcp-set.js

@@ -29,13 +29,11 @@
  */
 
 const path = require('node:path');
-const { loadExposeStore } = require('../../src/mcp/expose-store');
+// Shared HOME/engine resolution (see tf-env.js): config beside us, engine from the package.
+const { HOME, srcRequire } = require('./tf-env');
+const { loadExposeStore } = srcRequire('mcp/expose-store');
 
-/**
- * ToolFunnel root, resolved from THIS file's location:
- *   <root>/tools/scripts/tf-mcp-set.js -> root is two dirs up.
- */
-const ROOT = path.resolve(__dirname, '..', '..');
+const ROOT = HOME;
 
 /** The MCP config (upstreams + expose), per the host path contract. */
 const EXPOSE_PATH = path.join(ROOT, 'mcp', 'expose.json');