toolfunnel 0.3.0

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

@@ -0,0 +1,104 @@
+#!/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');
+const { loadExposeStore } = require('../../src/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, '..', '..');
+
+/** 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 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);
+      return { ok: true, action, id, upstream };
+    }
+    case 'remove': {
+      store.removeUpstream(id);
+      return { ok: true, action, id, removed: 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();

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

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * tf-tool-add.js — a first-party MANAGEMENT tool that ADDS a register entry.
+ *
+ * Purpose
+ * -------
+ * The write-side counterpart to the read-only status / inventory tools: it lets
+ * the manager surface a NEW tool in the register at runtime (no reconnect — the
+ * meta-tools re-read the register every call). Optionally it also writes the
+ * host-local script the new entry invokes, so a single call can create both the
+ * register entry AND its backing script atomically.
+ *
+ * This is a "gateway-run" tool: it mutates ToolFunnel's OWN config (the register
+ * and, optionally, a script under the scripts root). It runs through the same
+ * register -> resolveExecution -> gated run path as any other script tool, so
+ * the PreToolUse gate still applies to invoking it.
+ *
+ * Contract with the register (registry.js `defaultRunScript`)
+ * ----------------------------------------------------------
+ *   - Structured args arrive as JSON in env TOOLFUNNEL_TOOL_ARGS ({} / absent => null).
+ *   - Args: { id, name, summary?, category?, instructions?,
+ *             invoke: { type:'script'|'shell', path?|command? },
+ *             scriptText? }
+ *       When scriptText is a string AND invoke.type === 'script', the script is
+ *       written first (registry.writeScript), THEN the entry is added.
+ *   - Prints a SINGLE JSON object to stdout and exits 0 — ALWAYS exit 0, even on
+ *     a logical error (reported as { ok:false, error }), never a thrown exception.
+ *
+ * Output (stdout), exactly one JSON object:
+ *   success: { ok:true, ...<the added register entry>, scriptPath?: "<abs path>" }
+ *   failure: { ok:false, error }
+ *
+ * Safety invariants:
+ *   - Touches ONLY files inside the toolfunnel root, resolved from THIS script's
+ *     own location (__dirname) — never a caller-supplied absolute path. The
+ *     register's writeScript guards path-escape (basename + inside-root check).
+ *   - NO network. Writes are atomic (temp + fsync + rename) via the register module.
+ *   - NEVER throws for ordinary bad input — only well-shaped JSON on stdout.
+ */
+
+const path = require('node:path');
+const { loadRegistry } = require('../../src/tools/registry');
+
+/**
+ * The toolfunnel root, resolved from THIS file's location so the tool is portable
+ * and stays inside the sandbox.
+ *
+ * This script lives at:  <root>/tools/scripts/tf-tool-add.js
+ * so the root is two directories up from __dirname:
+ *   scripts -> tools -> <root>
+ */
+const ROOT = path.resolve(__dirname, '..', '..');
+const REGISTER_PATH = path.join(ROOT, 'tools', 'tools.register.json');
+const SCRIPTS_ROOT = path.join(ROOT, 'tools', 'scripts');
+
+/**
+ * Parse the structured args handed in via env TOOLFUNNEL_TOOL_ARGS.
+ * @returns {{ value: any } | { parseError: string }}
+ */
+function parseStructuredArgs() {
+  const raw = process.env.TOOLFUNNEL_TOOL_ARGS;
+  if (raw === undefined || raw === null || raw === '') {
+    return { value: null };
+  }
+  try {
+    return { value: JSON.parse(raw) };
+  } catch (_err) {
+    return { parseError: `TOOLFUNNEL_TOOL_ARGS was not valid JSON: ${String(raw)}` };
+  }
+}
+
+/**
+ * Pure core: given the parsed args, add the register entry (and optionally write
+ * its backing script first). Throws are caught by main() and surfaced as
+ * { ok:false, error }; loadRegistry / writeScript / add all throw on bad shape.
+ *
+ * @param {any} args
+ * @returns {object} the JSON-serialisable result
+ */
+function run(args) {
+  if (!args || typeof args !== 'object' || Array.isArray(args)) {
+    return {
+      ok: false,
+      error: 'args must be an object { id, name, summary?, category?, instructions?, invoke, scriptText? }',
+    };
+  }
+  const { id, name, summary, category, instructions, invoke, scriptText } = args;
+
+  // Build a clean register entry (only carry through the optional fields when
+  // present so the persisted entry stays tidy). registry.add validates shape.
+  const entry = { id, name, invoke };
+  if (summary !== undefined) entry.summary = summary;
+  if (category !== undefined) entry.category = category;
+  if (instructions !== undefined) entry.instructions = instructions;
+
+  const registry = loadRegistry(REGISTER_PATH, { scriptsRoot: SCRIPTS_ROOT });
+
+  // When a script body is supplied for a script invoke, write it FIRST so the
+  // entry never references a missing file once add() succeeds.
+  let scriptPath;
+  if (typeof scriptText === 'string' && invoke && invoke.type === 'script') {
+    scriptPath = registry.writeScript(invoke.path, scriptText);
+  }
+
+  const added = registry.add(entry);
+  const result = { ok: true, ...added };
+  if (scriptPath) result.scriptPath = scriptPath;
+  return result;
+}
+
+function main() {
+  const parsed = parseStructuredArgs();
+  let payload;
+  if (parsed.parseError) {
+    payload = { ok: false, error: parsed.parseError };
+  } else {
+    try {
+      payload = run(parsed.value);
+    } 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-tool-set.js

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * tf-tool-set.js — a first-party MANAGEMENT tool that toggles or removes a tool.
+ *
+ * Purpose
+ * -------
+ * The state-side counterpart to tf-tool-add: it flips a tool's ACTIVE/DISABLED
+ * overlay flag (enable / disable) or fully removes a tool (drops the register
+ * entry AND clears its state overlay). Register/state edits are visible to the
+ * meta-tools on the next call — no reconnect.
+ *
+ * This is a "gateway-run" tool: it mutates ToolFunnel's OWN config (the per-tool
+ * state overlay, and for `remove`, the register too). It runs through the same
+ * gated run path as any other script tool.
+ *
+ * Contract with the register (registry.js `defaultRunScript`)
+ * ----------------------------------------------------------
+ *   - Structured args arrive as JSON in env TOOLFUNNEL_TOOL_ARGS ({} / absent => null).
+ *   - Args: { id, action: 'enable' | 'disable' | 'hot' | 'unhot' | 'hide' | 'unhide' | 'remove' }.
+ *       enable/disable -> setToolEnabled(state, id, bool)  (overlay merge; preserves hidden/hot)
+ *       hot/unhot      -> setToolHot(state, id, bool)      (overlay merge; preserves enabled/hidden)
+ *                         — promote/demote the tool on the TOP-LEVEL every-turn surface (the matrix).
+ *       hide/unhide    -> setToolHidden(state, id, bool)   (overlay merge; preserves enabled/hot)
+ *                         — declutter the MANAGER views only (tf_list + the UI); does NOT change
+ *                           what the connected AI sees (the lean list / top-level surface).
+ *       remove         -> registry.remove(id) AND clearToolState(state, id)
+ *   - Prints a SINGLE JSON object to stdout and exits 0 — ALWAYS exit 0, even on
+ *     a logical error (reported as { ok:false, error }), never a thrown exception.
+ *
+ * Output (stdout), exactly one JSON object:
+ *   enable/disable: { ok:true, id, action, enabled, state }
+ *   hot/unhot:      { ok:true, id, action, hot, state }
+ *   hide/unhide:    { ok:true, id, action, hidden, state }
+ *   remove:         { ok:true, id, action, removed:true, state }
+ *   failure:        { ok:false, error }
+ *   (`state` is the resulting overlay map after the operation.)
+ *
+ * Safety invariants:
+ *   - Touches ONLY config files inside the toolfunnel root, resolved from THIS
+ *     script's own location (__dirname) — never a caller-supplied path.
+ *   - NO network. Writes are atomic (temp + fsync + rename) via the store modules.
+ *   - NEVER throws for ordinary bad input — only well-shaped JSON on stdout.
+ */
+
+const path = require('node:path');
+const { loadRegistry } = require('../../src/tools/registry');
+const { setToolEnabled, setToolHot, setToolHidden, clearToolState } = require('../../src/tools/tool-state');
+
+/**
+ * The toolfunnel root, resolved from THIS file's location so the tool is portable
+ * and stays inside the sandbox.
+ *
+ * This script lives at:  <root>/tools/scripts/tf-tool-set.js
+ * so the root is two directories up from __dirname:
+ *   scripts -> tools -> <root>
+ */
+const ROOT = path.resolve(__dirname, '..', '..');
+const REGISTER_PATH = path.join(ROOT, 'tools', 'tools.register.json');
+const STATE_PATH = path.join(ROOT, 'tools', 'tools.state.json');
+const SCRIPTS_ROOT = path.join(ROOT, 'tools', 'scripts');
+
+/**
+ * Parse the structured args handed in via env TOOLFUNNEL_TOOL_ARGS.
+ * @returns {{ value: any } | { parseError: string }}
+ */
+function parseStructuredArgs() {
+  const raw = process.env.TOOLFUNNEL_TOOL_ARGS;
+  if (raw === undefined || raw === null || raw === '') {
+    return { value: null };
+  }
+  try {
+    return { value: JSON.parse(raw) };
+  } catch (_err) {
+    return { parseError: `TOOLFUNNEL_TOOL_ARGS was not valid JSON: ${String(raw)}` };
+  }
+}
+
+/**
+ * Pure core: given the parsed args, perform the requested state/register change.
+ * Throws are caught by main() and surfaced as { ok:false, error }; registry.remove
+ * throws on an unknown id, setToolEnabled/clearToolState throw on a bad id.
+ *
+ * @param {any} args
+ * @returns {object} the JSON-serialisable result
+ */
+function run(args) {
+  if (!args || typeof args !== 'object' || Array.isArray(args)) {
+    return { ok: false, error: "args must be an object { id, action: 'enable'|'disable'|'hot'|'unhot'|'hide'|'unhide'|'remove' }" };
+  }
+  const { id, action } = args;
+  if (typeof id !== 'string' || id.length === 0) {
+    return { ok: false, error: 'id must be a non-empty string' };
+  }
+
+  if (action === 'enable' || action === 'disable') {
+    const enabled = action === 'enable';
+    const state = setToolEnabled(STATE_PATH, id, enabled);
+    return { ok: true, id, action, enabled, state };
+  }
+
+  if (action === 'hot' || action === 'unhot') {
+    // Promote (hot) / demote (unhot) the tool on the TOP-LEVEL every-turn surface. Keyed by the
+    // surfaced name (a local id, an upstream surfaced name, or a meta-tool name) — the same key the
+    // server's matrix assembler reads. The id is NOT verified against the register here: an upstream
+    // surfaced name or a meta-tool name is a legitimate key with no register entry.
+    const hot = action === 'hot';
+    const state = setToolHot(STATE_PATH, id, hot);
+    return { ok: true, id, action, hot, state };
+  }
+
+  if (action === 'hide' || action === 'unhide') {
+    // Declutter the MANAGER views (tf_list + the UI) only — hide/unhide does NOT change the lean list
+    // or the top-level surface the connected AI sees. Same id-not-verified policy as hot/unhot.
+    const hidden = action === 'hide';
+    const state = setToolHidden(STATE_PATH, id, hidden);
+    return { ok: true, id, action, hidden, state };
+  }
+
+  if (action === 'remove') {
+    // Drop the register entry first (throws on unknown id), then clear any overlay.
+    const registry = loadRegistry(REGISTER_PATH, { scriptsRoot: SCRIPTS_ROOT });
+    registry.remove(id);
+    const state = clearToolState(STATE_PATH, id);
+    return { ok: true, id, action, removed: true, state };
+  }
+
+  return { ok: false, error: "action must be one of 'enable'|'disable'|'hot'|'unhot'|'hide'|'unhide'|'remove'" };
+}
+
+function main() {
+  const parsed = parseStructuredArgs();
+  let payload;
+  if (parsed.parseError) {
+    payload = { ok: false, error: parsed.parseError };
+  } else {
+    try {
+      payload = run(parsed.value);
+    } 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/uuid.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * uuid-tool.js — a safe, dependency-free local UUID generator.
+ *
+ * Purpose
+ * -------
+ * Generate one or more RFC 4122 v4 UUIDs via the Node built-in
+ * `node:crypto.randomUUID()`. Useful from the Tool Manager whenever a fresh
+ * identifier is needed. No network, no filesystem, no new deps.
+ *
+ * Contract with the register (the register's `defaultRunScript`)
+ * ----------------------------------------------------------
+ *   - Structured args arrive as JSON in env TOOLFUNNEL_TOOL_ARGS.
+ *   - Args: { count?: <integer> } — how many UUIDs to mint. Defaults to 1.
+ *     count is clamped to the range [1, 100] so a runaway request cannot ask
+ *     for an unbounded number.
+ *   - Prints a SINGLE JSON object to stdout and exits 0 — ALWAYS exit 0, even
+ *     on bad input (reported as { ok:false, error }), never a thrown exception.
+ *
+ * Output (stdout), exactly one JSON object:
+ *   success: { ok:true,  uuids: [ "...", ... ] }
+ *   failure: { ok:false, error }
+ *
+ * Safety invariants (mirror the isolation rule):
+ *   - NO filesystem, NO network, NO process mutation. Pure CPU on the args.
+ *   - count is hard-capped at 100; a non-integer / out-of-range count is an
+ *     error rather than a silent surprise.
+ *   - NEVER throws for ordinary bad input — only well-shaped JSON on stdout.
+ */
+
+const crypto = require('node:crypto');
+
+const MAX_COUNT = 100;
+
+/**
+ * Parse the structured args handed in via env TOOLFUNNEL_TOOL_ARGS.
+ * @returns {{ value: any } | { parseError: string }}
+ */
+function parseStructuredArgs() {
+  const raw = process.env.TOOLFUNNEL_TOOL_ARGS;
+  if (raw === undefined || raw === null || raw === '') {
+    return { value: null };
+  }
+  try {
+    return { value: JSON.parse(raw) };
+  } catch (_err) {
+    return { parseError: `TOOLFUNNEL_TOOL_ARGS was not valid JSON: ${String(raw)}` };
+  }
+}
+
+/**
+ * Pure core: given the parsed args, produce the result object. Never throws.
+ *
+ * @param {any} args  may be null (treated as { count: 1 })
+ * @returns {object} the JSON-serialisable result
+ */
+function run(args) {
+  // No args (or null) is valid — default to a single UUID.
+  let count = 1;
+  if (args !== null && args !== undefined) {
+    if (typeof args !== 'object' || Array.isArray(args)) {
+      return { ok: false, error: 'args must be an object { count? }' };
+    }
+    if (args.count !== undefined && args.count !== null) {
+      if (typeof args.count !== 'number' || !Number.isInteger(args.count)) {
+        return { ok: false, error: 'count must be an integer' };
+      }
+      if (args.count < 1) {
+        return { ok: false, error: 'count must be >= 1' };
+      }
+      if (args.count > MAX_COUNT) {
+        return { ok: false, error: `count must be <= ${MAX_COUNT}` };
+      }
+      count = args.count;
+    }
+  }
+  const uuids = [];
+  for (let i = 0; i < count; i += 1) {
+    uuids.push(crypto.randomUUID());
+  }
+  return { ok: true, uuids };
+}
+
+function main() {
+  const parsed = parseStructuredArgs();
+  let payload;
+  if (parsed.parseError) {
+    payload = { ok: false, error: parsed.parseError };
+  } else {
+    try {
+      payload = run(parsed.value);
+    } catch (err) {
+      payload = { ok: false, error: `unexpected error: ${(err && err.message) || String(err)}` };
+    }
+  }
+  process.stdout.write(JSON.stringify(payload) + '\n');
+  process.exit(0);
+}
+
+main();

package/tools/tools.register.json

@@ -0,0 +1,171 @@
+{
+  "version": 1,
+  "description": "Tool register for the gateway — built-in demo scripts.",
+  "tools": [
+    {
+      "id": "echo",
+      "name": "Echo",
+      "summary": "Return the provided arguments back unchanged.",
+      "category": "demo",
+      "instructions": "Echoes its structured args back in the result. Pass any JSON value as args and the same value is returned. Useful as a connectivity / round-trip smoke test.",
+      "invoke": {
+        "type": "script",
+        "path": "scripts/echo.js"
+      }
+    },
+    {
+      "id": "base64",
+      "name": "Base64 Encode/Decode",
+      "summary": "Encode text to Base64 or decode Base64 back to text.",
+      "category": "encoding",
+      "instructions": "Args: { op: \"encode\"|\"decode\", text: string }. Both args required. encode -> Base64 of the UTF-8 text; decode -> UTF-8 from valid Base64 (malformed input is reported, not mangled).",
+      "invoke": {
+        "type": "script",
+        "path": "scripts/base64.js"
+      }
+    },
+    {
+      "id": "hash",
+      "name": "Hash",
+      "summary": "Compute a cryptographic digest (e.g. sha256) of input text.",
+      "category": "crypto",
+      "instructions": "Args: { algo?: \"sha256\"|\"sha1\"|\"md5\" (default \"sha256\"), text: string }. Returns the lowercase hex digest of the UTF-8 text.",
+      "invoke": {
+        "type": "script",
+        "path": "scripts/hash.js"
+      }
+    },
+    {
+      "id": "uuid",
+      "name": "UUID Generator",
+      "summary": "Generate a random RFC 4122 v4 UUID.",
+      "category": "generators",
+      "instructions": "Args: { count?: number (default 1) }. Returns one or more freshly generated v4 UUID strings.",
+      "invoke": {
+        "type": "script",
+        "path": "scripts/uuid.js"
+      }
+    },
+    {
+      "id": "json",
+      "name": "JSON Format",
+      "summary": "Validate and pretty-print a JSON string.",
+      "category": "data",
+      "instructions": "Args: { text: string, indent?: number (default 2) }. Parses the input; returns the re-serialised, indented JSON, or a clear parse error.",
+      "invoke": {
+        "type": "script",
+        "path": "scripts/json.js"
+      }
+    },
+    {
+      "id": "text-stats",
+      "name": "Text Stats",
+      "summary": "Count characters, words, and lines in a block of text.",
+      "category": "text",
+      "instructions": "Args: { text: string }. Returns { chars, words, lines } computed from the input text.",
+      "invoke": {
+        "type": "script",
+        "path": "scripts/text-stats.js"
+      }
+    },
+    {
+      "id": "danger",
+      "name": "Danger Demo",
+      "summary": "Demonstrate a gated, potentially destructive operation.",
+      "category": "demo",
+      "instructions": "A sample tool that represents a destructive action. It is intended to be exercised behind the gate so the gating path can be tested end to end. Pass { confirm: true } to proceed.",
+      "invoke": {
+        "type": "script",
+        "path": "scripts/danger.js"
+      }
+    },
+    {
+      "id": "tf_tool_add",
+      "name": "tf_tool_add",
+      "summary": "Register a new tool entry in the gateway tool register.",
+      "category": "management",
+      "instructions": "Add a register entry. Args: { id, name, summary?, category?, instructions?, invoke:{type:'script',path:'scripts/<file>'}|{type:'shell',command}, scriptText? }. If scriptText is given for a script invoke, the body is written to tools/scripts/<basename> first. Change is LIVE (no reconnect). Fails if id already exists.",
+      "invoke": {
+        "type": "script",
+        "path": "scripts/tf-tool-add.js"
+      }
+    },
+    {
+      "id": "tf_tool_set",
+      "name": "tf_tool_set",
+      "summary": "Activate, deactivate, promote (hot), hide, or remove a register tool.",
+      "category": "management",
+      "instructions": "Args: { id, action:'enable'|'disable'|'hot'|'unhot'|'hide'|'unhide'|'remove' }. enable/disable flips the active overlay (default ON) — disabled tools drop from toolfunnel_list_tools. hot/unhot promote/demote on the TOP-LEVEL every-turn surface (tools/list), making it directly callable (default OFF). hide/unhide declutter the MANAGER views only (tf_list + UI) and do NOT change what the AI sees. The id may be a local tool id, an upstream surfaced name, or a meta-tool name. remove deletes the register entry and purges its state key. All LIVE (no restart).",
+      "invoke": {
+        "type": "script",
+        "path": "scripts/tf-tool-set.js"
+      }
+    },
+    {
+      "id": "tf_mcp_add",
+      "name": "tf_mcp_add",
+      "summary": "Register an upstream MCP (and optionally expose some of its tools).",
+      "category": "management",
+      "instructions": "Args: { id, command, args?, env?, transport?='stdio', enabled?=true, description?, expose?:[{tool, as?, category?, enabled?}] }. Adds an upstreams[] entry; each expose[] item adds a curated-direct selection. Curated-direct changes need an aggregator reconnect to surface.",
+      "invoke": {
+        "type": "script",
+        "path": "scripts/tf-mcp-add.js"
+      }
+    },
+    {
+      "id": "tf_mcp_set",
+      "name": "tf_mcp_set",
+      "summary": "Enable, disable, or remove an upstream MCP.",
+      "category": "management",
+      "instructions": "Args: { id, action:'enable'|'disable'|'remove' }. enable/disable toggles the upstream; remove deletes it and cascades its expose entries. Reconnect needed for the curated-direct surface to change.",
+      "invoke": {
+        "type": "script",
+        "path": "scripts/tf-mcp-set.js"
+      }
+    },
+    {
+      "id": "tf_hook_add",
+      "name": "tf_hook_add",
+      "summary": "Add a hook manifest entry (e.g. a PreToolUse gate).",
+      "category": "management",
+      "instructions": "Args: { id, event, matcher?, command, script?, timeout?, enabled?=true, description?, scriptText? }. id format '<kebab-event>/<name>'. command should use the portable ${HOOKS_DIR} token. If scriptText is given, the script is authored under hooks/scripts/ (path-guarded). enabled is the manifest seed; live toggles live in hooks.state.json.",
+      "invoke": {
+        "type": "script",
+        "path": "scripts/tf-hook-add.js"
+      }
+    },
+    {
+      "id": "tf_hook_set",
+      "name": "tf_hook_set",
+      "summary": "Enable, disable, or remove a hook.",
+      "category": "management",
+      "instructions": "Args: { id, action:'enable'|'disable'|'remove' }. enable/disable writes the hooks.state.json overlay (wins over the manifest seed) and mirrors the manifest; remove deletes the manifest entry and purges the overlay key (the script file is left in place).",
+      "invoke": {
+        "type": "script",
+        "path": "scripts/tf-hook-set.js"
+      }
+    },
+    {
+      "id": "tf_list",
+      "name": "tf_list",
+      "summary": "List register tools, upstream MCPs, or hooks with their active state.",
+      "category": "management",
+      "instructions": "Args: { kind:'tools'|'mcps'|'hooks' }. tools → register briefs + enabled/hidden overlay; mcps → upstreams + expose selections; hooks → configured + auto-detected inventory with live enabled state. Read-only.",
+      "invoke": {
+        "type": "script",
+        "path": "scripts/tf-list.js"
+      }
+    },
+    {
+      "id": "tf_log",
+      "name": "tf_log",
+      "summary": "Enable, disable, or check the gateway activity/audit log.",
+      "category": "management",
+      "instructions": "Args: { action:'enable'|'disable'|'status', path? }. Toggles ToolFunnel's JSONL audit log (tool runs + gate allow/deny decisions). Default OFF. 'status' returns {enabled,path} + recent count. Like any tool, tf_log can itself be disabled to revoke logging control.",
+      "invoke": {
+        "type": "script",
+        "path": "scripts/tf-log.js"
+      }
+    }
+  ]
+}