toolfunnel 0.7.0 → 0.8.0

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

@@ -1,117 +1,130 @@
-#!/usr/bin/env node
-'use strict';
-
-/**
- * tf-mcp-add.js - gateway-run MANAGEMENT tool: register an upstream MCP in the
- * ExposeStore and (optionally) curate which of its tools are exposed downstream.
- *
- * This is a first-party "management" script-tool: it is discovered via list_tools
- * and executed via run_tool through the PreToolUse gate. It does not add new
- * MCP-protocol commands - it edits ToolFunnel's own MCP config (mcp/expose.json)
- * by way of the ExposeStore, the on-disk source of truth the aggregator consumes.
- *
- * Contract with the register (`defaultRunScript`)
- * ----------------------------------------------------------
- *   - Structured args arrive as a JSON string in env TOOLFUNNEL_TOOL_ARGS ({} if
- *     absent). Shape:
- *       {
- *         id, command,
- *         args?:[], env?:{}, transport?='stdio', enabled?=true, description?,
- *         expose?:[ { tool, as?, category?, enabled? } ]
- *       }
- *   - Prints EXACTLY ONE JSON line to stdout and exits 0 - ALWAYS. A logical
- *     failure (bad args, validation error from the store) is reported as
- *     { ok:false, error }, never a non-zero exit or a crash.
- *
- * Output (stdout), exactly one JSON object:
- *   success: { ok:true, upstream:{...}, exposed:[{...}, ...] }
- *   failure: { ok:false, error }
- *
- * Behaviour
- *   - addUpstream({ id, command, args, env, transport, enabled, description }) -
- *     the store validates (unique non-empty id, transport==='stdio', non-empty
- *     command) and persists atomically.
- *   - For each expose[] item: addExpose({ upstream:id, tool, as, category, enabled }).
- *     The store requires the upstream to exist (it does - we just added it), a
- *     non-empty tool, and a unique (upstream,tool) pair.
- *
- * Note: there is no cross-step transaction. If the upstream is added but a later
- * expose[] item fails validation, the upstream (and any earlier exposes) remain
- * persisted; the failure is reported as { ok:false, error }.
- */
-
-const path = require('node:path');
-// 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');
-
-const ROOT = HOME;
-
-/** The MCP config (upstreams + expose), per the host path contract. */
-const EXPOSE_PATH = path.join(ROOT, 'mcp', 'expose.json');
-
-/**
- * Parse TOOLFUNNEL_TOOL_ARGS (a JSON string; {} if absent). Throws on malformed
- * JSON or a non-object payload so the caller reports { ok:false, error }.
- * @returns {object}
- */
-function parseArgs() {
-  const raw = process.env.TOOLFUNNEL_TOOL_ARGS;
-  if (raw === undefined || raw === null || raw === '') return {};
-  const parsed = JSON.parse(raw);
-  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
-    throw new Error('TOOLFUNNEL_TOOL_ARGS must be a JSON object');
-  }
-  return parsed;
-}
-
-/**
- * Perform the add. May throw - main() turns any throw into { ok:false, error }.
- * @returns {object} the success payload
- */
-function run() {
-  const args = parseArgs();
-  const store = loadExposeStore(EXPOSE_PATH);
-
-  // The store's normaliseUpstream already defaults transport/enabled/args/env, but
-  // apply the documented defaults explicitly so the intent is visible here too.
-  const upstream = store.addUpstream({
-    id: args.id,
-    command: args.command,
-    args: args.args,
-    env: args.env,
-    transport: typeof args.transport === 'string' ? args.transport : 'stdio',
-    enabled: typeof args.enabled === 'boolean' ? args.enabled : true,
-    description: args.description,
-  });
-
-  const exposed = [];
-  const exposeList = Array.isArray(args.expose) ? args.expose : [];
-  for (const item of exposeList) {
-    const e = item && typeof item === 'object' && !Array.isArray(item) ? item : {};
-    exposed.push(
-      store.addExpose({
-        upstream: upstream.id,
-        tool: e.tool,
-        as: e.as,
-        category: e.category,
-        enabled: typeof e.enabled === 'boolean' ? e.enabled : true,
-      })
-    );
-  }
-
-  return { ok: true, upstream, exposed };
-}
-
-function main() {
-  let payload;
-  try {
-    payload = run();
-  } catch (err) {
-    payload = { ok: false, error: (err && err.message) || String(err) };
-  }
-  process.stdout.write(JSON.stringify(payload) + '\n');
-  process.exit(0);
-}
-
-main();
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * tf-mcp-add.js - gateway-run MANAGEMENT tool: register an upstream MCP in the
+ * ExposeStore and (optionally) curate which of its tools are exposed downstream.
+ *
+ * This is a first-party "management" script-tool: it is discovered via list_tools
+ * and executed via run_tool through the PreToolUse gate. It does not add new
+ * MCP-protocol commands - it edits ToolFunnel's own MCP config (mcp/expose.json)
+ * by way of the ExposeStore, the on-disk source of truth the aggregator consumes.
+ *
+ * Contract with the register (`defaultRunScript`)
+ * ----------------------------------------------------------
+ *   - Structured args arrive as a JSON string in env TOOLFUNNEL_TOOL_ARGS ({} if
+ *     absent). Shape:
+ *       {
+ *         id, command,
+ *         args?:[], env?:{}, transport?='stdio', enabled?=true, description?,
+ *         expose?:[ { tool, as?, category?, enabled? } ]
+ *       }
+ *   - Prints EXACTLY ONE JSON line to stdout and exits 0 - ALWAYS. A logical
+ *     failure (bad args, validation error from the store) is reported as
+ *     { ok:false, error }, never a non-zero exit or a crash.
+ *
+ * Output (stdout), exactly one JSON object:
+ *   success: { ok:true, upstream:{...}, exposed:[{...}, ...] }
+ *   failure: { ok:false, error }
+ *
+ * Behaviour
+ *   - addUpstream({ id, command, args, env, transport, enabled, description }) -
+ *     the store validates (unique non-empty id, transport==='stdio', non-empty
+ *     command) and persists atomically.
+ *   - For each expose[] item: addExpose({ upstream:id, tool, as, category, enabled }).
+ *     The store requires the upstream to exist (it does - we just added it), a
+ *     non-empty tool, and a unique (upstream,tool) pair.
+ *
+ * Note: there is no cross-step transaction. If the upstream is added but a later
+ * expose[] item fails validation, the upstream (and any earlier exposes) remain
+ * persisted; the failure is reported as { ok:false, error }.
+ */
+
+const path = require('node:path');
+// 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');
+const { snapshotForStoreFile, restoreSnapshot } = srcRequire('core/rename-migration');
+
+const ROOT = HOME;
+
+/** The MCP config (upstreams + expose), per the host path contract. */
+const EXPOSE_PATH = path.join(ROOT, 'mcp', 'expose.json');
+
+/**
+ * Parse TOOLFUNNEL_TOOL_ARGS (a JSON string; {} if absent). Throws on malformed
+ * JSON or a non-object payload so the caller reports { ok:false, error }.
+ * @returns {object}
+ */
+function parseArgs() {
+  const raw = process.env.TOOLFUNNEL_TOOL_ARGS;
+  if (raw === undefined || raw === null || raw === '') return {};
+  const parsed = JSON.parse(raw);
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error('TOOLFUNNEL_TOOL_ARGS must be a JSON object');
+  }
+  return parsed;
+}
+
+/**
+ * Perform the add. May throw - main() turns any throw into { ok:false, error }.
+ * @returns {object} the success payload
+ */
+function run() {
+  const args = parseArgs();
+  const store = loadExposeStore(EXPOSE_PATH);
+
+  // Values go to the store RAW: it defaults what is absent and REFUSES what is wrong-typed,
+  // naming the field. Coercing here - `enabled: "false"` to true - would hide exactly the
+  // mistake the store reports.
+  const upstream = store.addUpstream({
+    id: args.id,
+    command: args.command,
+    args: args.args,
+    env: args.env,
+    transport: args.transport,
+    enabled: args.enabled,
+    description: args.description,
+  });
+
+  // addUpstream has persisted; a later expose item can still be refused. A reply of ok:false must
+  // not keep half the add - the natural retry would die as a duplicate id. Unwind the whole add, as
+  // the UI's /api/mcp/add does: removeUpstream cascades this id's expose entries, and the snapshot
+  // puts back the gate matchers / state keys an ENABLED aliased item migrated as it landed.
+  const snap = snapshotForStoreFile(EXPOSE_PATH);
+  const exposed = [];
+  const exposeList = Array.isArray(args.expose) ? args.expose : [];
+  try {
+    for (const item of exposeList) {
+      const e = item && typeof item === 'object' && !Array.isArray(item) ? item : {};
+      exposed.push(
+        store.addExpose({
+          upstream: upstream.id,
+          tool: e.tool,
+          as: e.as,
+          category: e.category,
+          enabled: e.enabled,
+        })
+      );
+    }
+  } catch (err) {
+    try { store.removeUpstream(upstream.id); } catch (_e) { /* best-effort; the real error is reported below */ }
+    restoreSnapshot(snap);
+    throw err;
+  }
+
+  return { ok: true, upstream, exposed };
+}
+
+function main() {
+  let payload;
+  try {
+    payload = run();
+  } catch (err) {
+    payload = { ok: false, error: (err && err.message) || String(err) };
+  }
+  process.stdout.write(JSON.stringify(payload) + '\n');
+  process.exit(0);
+}
+
+main();

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

@@ -1,121 +1,121 @@
-#!/usr/bin/env node
-'use strict';
-
-/**
- * tf-mcp-set.js - gateway-run MANAGEMENT tool: enable, disable, or remove an
- * upstream MCP in the ExposeStore.
- *
- * A first-party "management" script-tool (discovered via list_tools, executed via
- * run_tool through the PreToolUse gate). It edits ToolFunnel's own MCP config
- * (mcp/expose.json) via the ExposeStore - it does not add MCP-protocol commands.
- *
- * Contract with the register (`defaultRunScript`)
- * ----------------------------------------------------------
- *   - Structured args arrive as a JSON string in env TOOLFUNNEL_TOOL_ARGS ({} if
- *     absent). Shape: { id, action: 'enable'|'disable'|'remove' }.
- *   - Prints EXACTLY ONE JSON line to stdout and exits 0 - ALWAYS. A logical
- *     failure (bad args, unknown id) is reported as { ok:false, error }.
- *
- * Output (stdout), exactly one JSON object:
- *   enable/disable: { ok:true, action, id, upstream:{...} }   // the updated entry
- *   remove:         { ok:true, action, id, removed:true }     // cascades expose[]
- *   failure:        { ok:false, error }
- *
- * Behaviour
- *   - enable  -> setUpstreamEnabled(id, true)
- *   - disable -> setUpstreamEnabled(id, false)
- *   - remove  -> removeUpstream(id)  (the store cascade-removes its expose entries)
- * All three throw on an unknown id; the throw is reported as { ok:false, error }.
- */
-
-const path = require('node:path');
-// 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');
-const { loadToolState, getPassthrough, setPassthrough } = srcRequire('tools/tool-state');
-
-const ROOT = HOME;
-
-/** The MCP config (upstreams + expose), per the host path contract. */
-const EXPOSE_PATH = path.join(ROOT, 'mcp', 'expose.json');
-const STATE_PATH = path.join(ROOT, 'tools', 'tools.state.json');
-
-/**
- * If `id` is the currently-wrapped upstream, clear the wrap - a disable/remove of the wrapped
- * upstream would otherwise BRICK the whole surface (empty tool list, tf_wrap itself gone) with
- * only out-of-band recovery. Returns true if a wrap was cleared.
- */
-function clearWrapIfTarget(id) {
-  try {
-    if (getPassthrough(loadToolState(STATE_PATH)) === id) {
-      setPassthrough(STATE_PATH, null);
-      return true;
-    }
-  } catch (_e) { /* never let wrap-cleanup sink the primary action */ }
-  return false;
-}
-
-/**
- * Parse TOOLFUNNEL_TOOL_ARGS (a JSON string; {} if absent). Throws on malformed
- * JSON or a non-object payload so the caller reports { ok:false, error }.
- * @returns {object}
- */
-function parseArgs() {
-  const raw = process.env.TOOLFUNNEL_TOOL_ARGS;
-  if (raw === undefined || raw === null || raw === '') return {};
-  const parsed = JSON.parse(raw);
-  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
-    throw new Error('TOOLFUNNEL_TOOL_ARGS must be a JSON object');
-  }
-  return parsed;
-}
-
-/**
- * Perform the action. May throw - main() turns any throw into { ok:false, error }.
- * @returns {object} the success payload
- */
-function run() {
-  const args = parseArgs();
-  const id = args.id;
-  const action = args.action;
-
-  if (typeof id !== 'string' || id.length === 0) {
-    throw new Error('args.id must be a non-empty string');
-  }
-
-  const store = loadExposeStore(EXPOSE_PATH);
-
-  switch (action) {
-    case 'enable': {
-      const upstream = store.setUpstreamEnabled(id, true);
-      return { ok: true, action, id, upstream };
-    }
-    case 'disable': {
-      const upstream = store.setUpstreamEnabled(id, false);
-      const unwrapped = clearWrapIfTarget(id);
-      return { ok: true, action, id, upstream, ...(unwrapped ? { wrapCleared: true } : {}) };
-    }
-    case 'remove': {
-      store.removeUpstream(id);
-      const unwrapped = clearWrapIfTarget(id);
-      return { ok: true, action, id, removed: true, ...(unwrapped ? { wrapCleared: true } : {}) };
-    }
-    default:
-      throw new Error(
-        `args.action must be one of enable|disable|remove (got ${JSON.stringify(action)})`
-      );
-  }
-}
-
-function main() {
-  let payload;
-  try {
-    payload = run();
-  } catch (err) {
-    payload = { ok: false, error: (err && err.message) || String(err) };
-  }
-  process.stdout.write(JSON.stringify(payload) + '\n');
-  process.exit(0);
-}
-
-main();
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * tf-mcp-set.js - gateway-run MANAGEMENT tool: enable, disable, or remove an
+ * upstream MCP in the ExposeStore.
+ *
+ * A first-party "management" script-tool (discovered via list_tools, executed via
+ * run_tool through the PreToolUse gate). It edits ToolFunnel's own MCP config
+ * (mcp/expose.json) via the ExposeStore - it does not add MCP-protocol commands.
+ *
+ * Contract with the register (`defaultRunScript`)
+ * ----------------------------------------------------------
+ *   - Structured args arrive as a JSON string in env TOOLFUNNEL_TOOL_ARGS ({} if
+ *     absent). Shape: { id, action: 'enable'|'disable'|'remove' }.
+ *   - Prints EXACTLY ONE JSON line to stdout and exits 0 - ALWAYS. A logical
+ *     failure (bad args, unknown id) is reported as { ok:false, error }.
+ *
+ * Output (stdout), exactly one JSON object:
+ *   enable/disable: { ok:true, action, id, upstream:{...} }   // the updated entry
+ *   remove:         { ok:true, action, id, removed:true }     // cascades expose[]
+ *   failure:        { ok:false, error }
+ *
+ * Behaviour
+ *   - enable  -> setUpstreamEnabled(id, true)
+ *   - disable -> setUpstreamEnabled(id, false)
+ *   - remove  -> removeUpstream(id)  (the store cascade-removes its expose entries)
+ * All three throw on an unknown id; the throw is reported as { ok:false, error }.
+ */
+
+const path = require('node:path');
+// 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');
+const { loadToolState, getPassthrough, setPassthrough } = srcRequire('tools/tool-state');
+
+const ROOT = HOME;
+
+/** The MCP config (upstreams + expose), per the host path contract. */
+const EXPOSE_PATH = path.join(ROOT, 'mcp', 'expose.json');
+const STATE_PATH = path.join(ROOT, 'tools', 'tools.state.json');
+
+/**
+ * If `id` is the currently-wrapped upstream, clear the wrap - a disable/remove of the wrapped
+ * upstream would otherwise BRICK the whole surface (empty tool list, tf_wrap itself gone) with
+ * only out-of-band recovery. Returns true if a wrap was cleared.
+ */
+function clearWrapIfTarget(id) {
+  try {
+    if (getPassthrough(loadToolState(STATE_PATH)) === id) {
+      setPassthrough(STATE_PATH, null);
+      return true;
+    }
+  } catch (_e) { /* never let wrap-cleanup sink the primary action */ }
+  return false;
+}
+
+/**
+ * Parse TOOLFUNNEL_TOOL_ARGS (a JSON string; {} if absent). Throws on malformed
+ * JSON or a non-object payload so the caller reports { ok:false, error }.
+ * @returns {object}
+ */
+function parseArgs() {
+  const raw = process.env.TOOLFUNNEL_TOOL_ARGS;
+  if (raw === undefined || raw === null || raw === '') return {};
+  const parsed = JSON.parse(raw);
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error('TOOLFUNNEL_TOOL_ARGS must be a JSON object');
+  }
+  return parsed;
+}
+
+/**
+ * Perform the action. May throw - main() turns any throw into { ok:false, error }.
+ * @returns {object} the success payload
+ */
+function run() {
+  const args = parseArgs();
+  const id = args.id;
+  const action = args.action;
+
+  if (typeof id !== 'string' || id.length === 0) {
+    throw new Error('args.id must be a non-empty string');
+  }
+
+  const store = loadExposeStore(EXPOSE_PATH);
+
+  switch (action) {
+    case 'enable': {
+      const upstream = store.setUpstreamEnabled(id, true);
+      return { ok: true, action, id, upstream };
+    }
+    case 'disable': {
+      const upstream = store.setUpstreamEnabled(id, false);
+      const unwrapped = clearWrapIfTarget(id);
+      return { ok: true, action, id, upstream, ...(unwrapped ? { wrapCleared: true } : {}) };
+    }
+    case 'remove': {
+      store.removeUpstream(id);
+      const unwrapped = clearWrapIfTarget(id);
+      return { ok: true, action, id, removed: true, ...(unwrapped ? { wrapCleared: true } : {}) };
+    }
+    default:
+      throw new Error(
+        `args.action must be one of enable|disable|remove (got ${JSON.stringify(action)})`
+      );
+  }
+}
+
+function main() {
+  let payload;
+  try {
+    payload = run();
+  } catch (err) {
+    payload = { ok: false, error: (err && err.message) || String(err) };
+  }
+  process.stdout.write(JSON.stringify(payload) + '\n');
+  process.exit(0);
+}
+
+main();