@kivimedia/kmhub 2.9.0 → 2.10.0

package/tools.mjs

@@ -1,407 +1,407 @@
-/**
- * kmhub-mcp tool index (P5, families since 2.0.0).
- *
- * Single source of truth for the KM Hub MCP tools. Both transports import this:
- *   - index.mjs  -> local stdio server (one process = one org key from env)
- *   - remote.mjs -> remote Streamable-HTTP server (one process = many orgs,
- *                   each request scoped by the caller's Bearer token)
- *
- * A tool is registered against an McpServer instance with a `call` function that
- * is already bound to a single org's KM Hub API token. That keeps every tenant's
- * data isolated: the token IS the scope, and one org can never reach another's rows.
- *
- * The tools themselves live one family per file in ./tools/, and this file only
- * discovers, orders and filters them. Two consequences worth knowing:
- *
- *   1. Adding a family means adding a file. Nothing in here has to change, so a
- *      dozen people can add a dozen families without ever editing the same line.
- *      The contract every family file follows is ./tools/README.md.
- *   2. Loading is defensive. A family that fails to import, declares itself badly,
- *      or claims a tool name another family already took is skipped with a warning
- *      on stderr - it never takes the live server down with it.
- *
- * PROFILES exist because tool schemas are a per-turn context tax: every tool this
- * server registers is spent out of the caller's context window on every single
- * turn, used or not. A profile is a smaller, honest tool set for a caller who only
- * wants one side of the workspace. `full` is the default and holds everything, so
- * an existing client sees no change.
- */
-import { readdirSync, readFileSync } from 'node:fs';
-import { z } from 'zod';
-
-export const SERVER_NAME = 'kmhub';
-export const SERVER_VERSION = '2.9.0';
-
-export const DEFAULT_BASE =
-  process.env.KMHUB_API_BASE ||
-  'https://jpwbosrmkibsdgckowsm.supabase.co/functions/v1/kmhub-api';
-
-/**
- * Build a `call(method, path, body)` bound to one org's KM Hub API token.
- * Every request to the kmhub-api edge function carries this token, so the edge
- * function does the authoritative org scoping and scope-check (read vs write).
- */
-export function makeCaller(base, token) {
-  return async function call(method, path, body) {
-    const r = await fetch(`${base}${path}`, {
-      method,
-      headers: { Authorization: `Bearer ${token}`, 'content-type': 'application/json' },
-      body: body ? JSON.stringify(body) : undefined,
-    });
-    const text = await r.text();
-    let data;
-    try {
-      data = JSON.parse(text);
-    } catch {
-      data = text;
-    }
-    return { ok: r.ok, status: r.status, data };
-  };
-}
-
-// ---- shared response helpers ----------------------------------------------
-// Every family formats its answers through these, so a change here reaches all
-// of them at once - present and future.
-
-const BILLING_FALLBACK =
-  'To pick things back up, sign in at https://hub.kivimedia.co and restart the subscription under Settings > Billing. Once that is done, ask me again and it will just work.';
-
-/**
- * Format a kmhub-api result as an MCP tool response.
- *
- * A 402 (subscription_inactive) is rewritten into plain English on purpose. The
- * person on the other end of this is a working performer, not an engineer, and
- * "your subscription lapsed" is something they can act on where a JSON blob is not.
- * Every other status keeps the raw JSON body, which is what the model needs to
- * reason about validation errors and the like.
- */
-export function out(r) {
-  const body = r && r.data && typeof r.data === 'object' ? r.data : {};
-  const inactive = r && (r.status === 402 || body.error === 'subscription_inactive');
-  if (inactive) {
-    const detail = typeof body.message === 'string' && body.message.trim() ? body.message.trim() : '';
-    const url = typeof body.billing_url === 'string' && body.billing_url.trim() ? body.billing_url.trim() : '';
-    const lines = [
-      'Your KM Hub subscription is not active at the moment, so I could not do that.',
-      'Nothing in your workspace has changed, and none of your data has gone anywhere.',
-    ];
-    if (detail) lines.push(detail);
-    lines.push(url ? `To pick things back up, open ${url} and restart the subscription.` : BILLING_FALLBACK);
-    return { content: [{ type: 'text', text: lines.join('\n\n') }], isError: true };
-  }
-  // The way back to the window (Freshdesk #271, Jackie): "I always have this problem
-  // of not getting back to the correct window using Claude and KM Hub once it is
-  // closed." A route that answers out of one page of the app says so in
-  // `open_in_km_hub`, and that line is appended in plain text rather than left buried
-  // in the JSON, so the model reliably shows her a link she can click twice.
-  const link = typeof body.open_in_km_hub === 'string' ? body.open_in_km_hub.trim() : '';
-  const json = JSON.stringify(r.data, null, 2);
-  const payload = link ? `${json}\n\nOpen in KM Hub: ${link}` : json;
-  return { content: [{ type: 'text', text: payload }], isError: !r.ok };
-}
-
-/** A plain prose answer. Defaults to a success result: not every "no" is an error. */
-export function text(message, isError = false) {
-  return { content: [{ type: 'text', text: String(message) }], isError };
-}
-
-/** Build a query string from an object, dropping empty values. Returns '' or '?a=b'. */
-export function qs(params) {
-  const q = new URLSearchParams();
-  for (const [k, v] of Object.entries(params || {})) {
-    if (v === undefined || v === null || v === '') continue;
-    q.set(k, String(v));
-  }
-  const s = q.toString();
-  return s ? `?${s}` : '';
-}
-
-// ---- profiles --------------------------------------------------------------
-//
-// A profile is a named, SMALLER tool set. This map is the authority for it, and
-// there are two rules. The second one is the one that used to be missing:
-//
-//   1. A profile lists the families it loads. `full` is '*' and loads everything.
-//   2. For a family this map PLACES (see PLACED below), the map is the whole
-//      answer. Leaving a family out of a profile is a decision rather than an
-//      oversight, and that family's own PROFILES export no longer overrides it.
-//
-// Rule 2 exists because without it the split was theatre. Six of the ten families
-// declared PROFILES ['*'] and pinned themselves into every profile, so `core` was
-// 31 of the 63 tools, `outreach` was 54, and a `content` profile returned 37 tools
-// and not one content tool, because no content family has ever existed. Eleven of
-// the fifteen family names this map used to list were phantoms that no file
-// declared. All of it advertised a saving that was not delivered, which is worse
-// than having no profiles at all: a caller who asked for less and silently got
-// nearly everything had no way to find that out.
-//
-// A family this map has never heard of keeps the self-service opt-in documented in
-// ./tools/README.md, so a new family still joins a profile without anyone editing
-// this file, and it always lands in `full` whatever it declares.
-//
-// What each profile is FOR, and what it actually costs (measured, not estimated):
-//
-//   core      13  Orientation and the CRM floor: whose workspace this is, what is
-//                 waiting, the briefing, and the original ten tools. No plays here.
-//                 A play's task calls tools from every family at once, so a run
-//                 started on a narrow profile fails halfway through, which is a
-//                 worse outcome than not offering the play.
-//   money         The money side, whole. The read-only money tools, plus hr because
-//                 payroll is money owed to the people who did the work, plus crm
-//                 so you can open the client you are about to chase, plus knowledge
-//                 because the published ladder is the only legal source of a number.
-//   outreach  51  The cold outreach machine: outreach and sourcing, plus crm to turn
-//                 a name into a record, knowledge to ground the words, and calendar
-//                 because you never offer a date you have not checked. This profile
-//                 saves the least of the three, and that is honest rather than
-//                 disappointing: the outreach job genuinely reaches most of the
-//                 workspace. `core` is the profile that buys real context back.
-//   content       The being-found side: SEO and the newsletter, plus crm and
-//                 knowledge, because content that does not know who buys or what
-//                 the business sounds like is generic content. This profile only
-//                 became real when the marketing family shipped (workstream B1);
-//                 before that the name existed in the installer and silently fell
-//                 back to `full`, which was a small lie told to anyone who used it.
-//   full          Everything, including the plays. The default.
-//   coach         Fully Booked Coach operations, client delivery, acquisition,
-//                 content requests, and approval previews. It exposes no send
-//                 or publish tool.
-//
-// An unknown profile name still gets `full` rather than an error, exactly as before.
-
-export const DEFAULT_PROFILE = 'full';
-
-export const PROFILES = {
-  core: ['core', 'meta', 'briefing'],
-  money: ['core', 'meta', 'briefing', 'crm', 'knowledge', 'money', 'hr'],
-  outreach: ['core', 'meta', 'briefing', 'crm', 'calendar', 'knowledge', 'outreach', 'sourcing', 'marketing'],
-  content: ['core', 'meta', 'briefing', 'crm', 'knowledge', 'marketing'],
-  full: '*',
-  coach: ['coach'],
-};
-
-/**
- * The families this map speaks for. Everything named in a narrow profile above was
- * placed by hand, so its own PROFILES export stops deciding where it lands. `plays`
- * has to be named here on its own, because it is placed too and placed nowhere but
- * `full`: without this line its own ['*'] would put it back into all three.
- */
-// Coach is a public pilot surface with an explicit safety review. New families
-// must not silently join it through a wildcard declaration.
-const CLOSED_PROFILES = new Set(['coach']);
-
-const PLACED = new Set([...Object.values(PROFILES).filter(Array.isArray).flat(), 'plays']);
-
-export const PROFILE_NAMES = Object.keys(PROFILES);
-
-/** Normalise a caller-supplied profile. Unknown or empty falls back to `full`, never throws. */
-export function resolveProfile(raw) {
-  const p = typeof raw === 'string' ? raw.trim().toLowerCase() : '';
-  return Object.prototype.hasOwnProperty.call(PROFILES, p) ? p : DEFAULT_PROFILE;
-}
-
-// ---- family discovery ------------------------------------------------------
-
-const TOOLS_DIR = new URL('./tools/', import.meta.url);
-
-function warn(msg) {
-  console.error(`kmhub-mcp: ${msg}`);
-}
-
-async function discoverFamilies() {
-  let files;
-  try {
-    files = readdirSync(TOOLS_DIR)
-      .filter((f) => f.endsWith('.mjs'))
-      .sort();
-  } catch (e) {
-    warn(`could not read the tools/ directory: ${String(e?.message || e)}. No tools are available.`);
-    return [];
-  }
-
-  const loaded = [];
-  const seen = new Set();
-  for (const file of files) {
-    let mod;
-    try {
-      mod = await import(new URL(file, TOOLS_DIR).href);
-    } catch (e) {
-      warn(`skipping tools/${file}, it failed to load: ${String(e?.message || e)}`);
-      continue;
-    }
-    const family = typeof mod?.FAMILY === 'string' ? mod.FAMILY.trim() : '';
-    if (!family) {
-      warn(`skipping tools/${file}, it does not export a FAMILY name.`);
-      continue;
-    }
-    if (typeof mod.register !== 'function') {
-      warn(`skipping tools/${file}, family '${family}' does not export a register() function.`);
-      continue;
-    }
-    if (seen.has(family)) {
-      warn(`skipping tools/${file}, family '${family}' is already declared by another file.`);
-      continue;
-    }
-    seen.add(family);
-    loaded.push({
-      FAMILY: family,
-      TOOLS: Array.isArray(mod.TOOLS) ? mod.TOOLS.filter((t) => typeof t === 'string' && t) : [],
-      PROFILES: Array.isArray(mod.PROFILES) ? mod.PROFILES.filter((p) => typeof p === 'string' && p) : [],
-      register: mod.register,
-      file,
-    });
-  }
-
-  // Deterministic order so tools/list is stable across processes and restarts:
-  // core first (it is the original ten, and clients expect to see them first),
-  // then alphabetical.
-  loaded.sort((a, b) => {
-    if (a.FAMILY === 'core') return -1;
-    if (b.FAMILY === 'core') return 1;
-    return a.FAMILY.localeCompare(b.FAMILY);
-  });
-  return loaded;
-}
-
-const FAMILIES = await discoverFamilies();
-
-export const FAMILY_NAMES = FAMILIES.map((f) => f.FAMILY);
-
-/**
- * Is this family part of this profile?
- *
- * `full` takes everything. Otherwise the map decides for every family it places,
- * and only a family the map has never heard of gets to opt itself in.
- */
-function inProfile(family, profile) {
-  if (profile === DEFAULT_PROFILE) return true;
-  const listed = PROFILES[profile];
-  if (listed === '*') return true;
-  if (Array.isArray(listed) && listed.includes(family.FAMILY)) return true;
-  if (CLOSED_PROFILES.has(profile)) return false;
-  if (PLACED.has(family.FAMILY)) return false;
-  return family.PROFILES.includes('*') || family.PROFILES.includes(profile);
-}
-
-/** The family records a profile loads, in registration order. */
-export function familiesFor(profile) {
-  const p = resolveProfile(profile);
-  return FAMILIES.filter((f) => inProfile(f, p));
-}
-
-/** Declared tool names for a profile (deduped, in registration order). */
-export function toolNamesFor(profile) {
-  const names = [];
-  for (const f of familiesFor(profile)) {
-    for (const t of f.TOOLS) if (!names.includes(t)) names.push(t);
-  }
-  return names;
-}
-
-/** Every declared tool name across every family. Kept for the health payload and startup logs. */
-export const TOOL_NAMES = toolNamesFor(DEFAULT_PROFILE);
-
-// ---- registration ----------------------------------------------------------
-
-/**
- * Hand a family a registrar rather than the raw McpServer, so one family can never
- * claim a tool name another family already took. A duplicate name would otherwise
- * make the SDK throw mid-request and cost the caller every tool, not just the
- * clashing one. `raw` is there for the rare family that needs the real server.
- */
-/**
- * The tools announced as read-only, from read-only-tools.json (generated from the tool
- * source by scripts/generate-read-only-tools.mjs - see there for the rule).
- *
- * 🚨 CODEX STOPS EVERY UNANNOTATED TOOL FOR AN APPROVAL. With no hint on any KM Hub tool,
- * a Codex session asked permission before `km_me`, and `codex exec` failed every call with
- * "MCP tool call requires approval". readOnlyHint: true is what lets a read run. Writes stay
- * unannotated on purpose, so the person still approves each one.
- *
- * A missing or broken file costs the hints, never the tools.
- */
-const READ_ONLY_TOOLS = (() => {
-  try {
-    const doc = JSON.parse(readFileSync(new URL('./read-only-tools.json', import.meta.url), 'utf8'));
-    return new Set(Array.isArray(doc.tools) ? doc.tools : []);
-  } catch (e) {
-    warn(`read-only-tools.json could not be read (${String(e?.message || e)}). Every tool will be announced without a read-only hint.`);
-    return new Set();
-  }
-})();
-
-export function isReadOnlyTool(name) {
-  return READ_ONLY_TOOLS.has(name);
-}
-
-function markReadOnly(name, registeredTool) {
-  if (!registeredTool || !READ_ONLY_TOOLS.has(name) || typeof registeredTool.update !== 'function') return registeredTool;
-  try {
-    registeredTool.update({ annotations: { ...(registeredTool.annotations || {}), readOnlyHint: true } });
-  } catch (e) {
-    warn(`could not mark '${name}' read-only (${String(e?.message || e)}). It still works; hosts will ask before running it.`);
-  }
-  return registeredTool;
-}
-
-function guardedRegistrar(server, taken, family, registered) {
-  const claim = (name) => {
-    if (typeof name !== 'string' || !name.trim()) {
-      warn(`family '${family}' tried to register a tool with no name. Ignored.`);
-      return false;
-    }
-    const owner = taken.get(name);
-    if (owner) {
-      warn(`tool name collision on '${name}': family '${owner}' already registered it, so family '${family}' does not get it.`);
-      return false;
-    }
-    taken.set(name, family);
-    registered.push(name);
-    return true;
-  };
-  return {
-    tool: (name, ...rest) => (claim(name) ? markReadOnly(name, server.tool(name, ...rest)) : undefined),
-    registerTool: (name, ...rest) => (claim(name) ? markReadOnly(name, server.registerTool(name, ...rest)) : undefined),
-    prompt: (...args) => server.prompt(...args),
-    resource: (...args) => server.resource(...args),
-    raw: server,
-  };
-}
-
-/**
- * Register the KM Hub tools for one profile on an McpServer.
- *
- * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
- * @param {(method: string, path: string, body?: any) => Promise<{ok:boolean,status:number,data:any}>} call
- *        already bound to a single org's API token
- * @param {{ profile?: string }} [opts] profile name; unknown or absent means `full`
- * @returns {{ profile: string, families: string[], tools: string[] }} what actually registered
- */
-export function registerTools(server, call, opts = {}) {
-  const profile = resolveProfile(opts.profile);
-  const families = familiesFor(profile);
-  const taken = new Map();
-  const registered = [];
-
-  for (const family of families) {
-    const helpers = {
-      out,
-      text,
-      qs,
-      z,
-      profile,
-      family: family.FAMILY,
-      SERVER_NAME,
-      SERVER_VERSION,
-      DEFAULT_BASE,
-    };
-    try {
-      family.register(guardedRegistrar(server, taken, family.FAMILY, registered), call, helpers);
-    } catch (e) {
-      // One bad family must not cost the caller the other nine.
-      warn(`family '${family.FAMILY}' failed to register: ${String(e?.message || e)}. Its tools are unavailable; the rest still work.`);
-    }
-  }
-
-  return { profile, families: families.map((f) => f.FAMILY), tools: registered };
-}
+/**
+ * kmhub-mcp tool index (P5, families since 2.0.0).
+ *
+ * Single source of truth for the KM Hub MCP tools. Both transports import this:
+ *   - index.mjs  -> local stdio server (one process = one org key from env)
+ *   - remote.mjs -> remote Streamable-HTTP server (one process = many orgs,
+ *                   each request scoped by the caller's Bearer token)
+ *
+ * A tool is registered against an McpServer instance with a `call` function that
+ * is already bound to a single org's KM Hub API token. That keeps every tenant's
+ * data isolated: the token IS the scope, and one org can never reach another's rows.
+ *
+ * The tools themselves live one family per file in ./tools/, and this file only
+ * discovers, orders and filters them. Two consequences worth knowing:
+ *
+ *   1. Adding a family means adding a file. Nothing in here has to change, so a
+ *      dozen people can add a dozen families without ever editing the same line.
+ *      The contract every family file follows is ./tools/README.md.
+ *   2. Loading is defensive. A family that fails to import, declares itself badly,
+ *      or claims a tool name another family already took is skipped with a warning
+ *      on stderr - it never takes the live server down with it.
+ *
+ * PROFILES exist because tool schemas are a per-turn context tax: every tool this
+ * server registers is spent out of the caller's context window on every single
+ * turn, used or not. A profile is a smaller, honest tool set for a caller who only
+ * wants one side of the workspace. `full` is the default and holds everything, so
+ * an existing client sees no change.
+ */
+import { readdirSync, readFileSync } from 'node:fs';
+import { z } from 'zod';
+
+export const SERVER_NAME = 'kmhub';
+export const SERVER_VERSION = '2.10.0';
+
+export const DEFAULT_BASE =
+  process.env.KMHUB_API_BASE ||
+  'https://jpwbosrmkibsdgckowsm.supabase.co/functions/v1/kmhub-api';
+
+/**
+ * Build a `call(method, path, body)` bound to one org's KM Hub API token.
+ * Every request to the kmhub-api edge function carries this token, so the edge
+ * function does the authoritative org scoping and scope-check (read vs write).
+ */
+export function makeCaller(base, token) {
+  return async function call(method, path, body) {
+    const r = await fetch(`${base}${path}`, {
+      method,
+      headers: { Authorization: `Bearer ${token}`, 'content-type': 'application/json' },
+      body: body ? JSON.stringify(body) : undefined,
+    });
+    const text = await r.text();
+    let data;
+    try {
+      data = JSON.parse(text);
+    } catch {
+      data = text;
+    }
+    return { ok: r.ok, status: r.status, data };
+  };
+}
+
+// ---- shared response helpers ----------------------------------------------
+// Every family formats its answers through these, so a change here reaches all
+// of them at once - present and future.
+
+const BILLING_FALLBACK =
+  'To pick things back up, sign in at https://hub.kivimedia.co and restart the subscription under Settings > Billing. Once that is done, ask me again and it will just work.';
+
+/**
+ * Format a kmhub-api result as an MCP tool response.
+ *
+ * A 402 (subscription_inactive) is rewritten into plain English on purpose. The
+ * person on the other end of this is a working performer, not an engineer, and
+ * "your subscription lapsed" is something they can act on where a JSON blob is not.
+ * Every other status keeps the raw JSON body, which is what the model needs to
+ * reason about validation errors and the like.
+ */
+export function out(r) {
+  const body = r && r.data && typeof r.data === 'object' ? r.data : {};
+  const inactive = r && (r.status === 402 || body.error === 'subscription_inactive');
+  if (inactive) {
+    const detail = typeof body.message === 'string' && body.message.trim() ? body.message.trim() : '';
+    const url = typeof body.billing_url === 'string' && body.billing_url.trim() ? body.billing_url.trim() : '';
+    const lines = [
+      'Your KM Hub subscription is not active at the moment, so I could not do that.',
+      'Nothing in your workspace has changed, and none of your data has gone anywhere.',
+    ];
+    if (detail) lines.push(detail);
+    lines.push(url ? `To pick things back up, open ${url} and restart the subscription.` : BILLING_FALLBACK);
+    return { content: [{ type: 'text', text: lines.join('\n\n') }], isError: true };
+  }
+  // The way back to the window (Freshdesk #271, Jackie): "I always have this problem
+  // of not getting back to the correct window using Claude and KM Hub once it is
+  // closed." A route that answers out of one page of the app says so in
+  // `open_in_km_hub`, and that line is appended in plain text rather than left buried
+  // in the JSON, so the model reliably shows her a link she can click twice.
+  const link = typeof body.open_in_km_hub === 'string' ? body.open_in_km_hub.trim() : '';
+  const json = JSON.stringify(r.data, null, 2);
+  const payload = link ? `${json}\n\nOpen in KM Hub: ${link}` : json;
+  return { content: [{ type: 'text', text: payload }], isError: !r.ok };
+}
+
+/** A plain prose answer. Defaults to a success result: not every "no" is an error. */
+export function text(message, isError = false) {
+  return { content: [{ type: 'text', text: String(message) }], isError };
+}
+
+/** Build a query string from an object, dropping empty values. Returns '' or '?a=b'. */
+export function qs(params) {
+  const q = new URLSearchParams();
+  for (const [k, v] of Object.entries(params || {})) {
+    if (v === undefined || v === null || v === '') continue;
+    q.set(k, String(v));
+  }
+  const s = q.toString();
+  return s ? `?${s}` : '';
+}
+
+// ---- profiles --------------------------------------------------------------
+//
+// A profile is a named, SMALLER tool set. This map is the authority for it, and
+// there are two rules. The second one is the one that used to be missing:
+//
+//   1. A profile lists the families it loads. `full` is '*' and loads everything.
+//   2. For a family this map PLACES (see PLACED below), the map is the whole
+//      answer. Leaving a family out of a profile is a decision rather than an
+//      oversight, and that family's own PROFILES export no longer overrides it.
+//
+// Rule 2 exists because without it the split was theatre. Six of the ten families
+// declared PROFILES ['*'] and pinned themselves into every profile, so `core` was
+// 31 of the 63 tools, `outreach` was 54, and a `content` profile returned 37 tools
+// and not one content tool, because no content family has ever existed. Eleven of
+// the fifteen family names this map used to list were phantoms that no file
+// declared. All of it advertised a saving that was not delivered, which is worse
+// than having no profiles at all: a caller who asked for less and silently got
+// nearly everything had no way to find that out.
+//
+// A family this map has never heard of keeps the self-service opt-in documented in
+// ./tools/README.md, so a new family still joins a profile without anyone editing
+// this file, and it always lands in `full` whatever it declares.
+//
+// What each profile is FOR, and what it actually costs (measured, not estimated):
+//
+//   core      13  Orientation and the CRM floor: whose workspace this is, what is
+//                 waiting, the briefing, and the original ten tools. No plays here.
+//                 A play's task calls tools from every family at once, so a run
+//                 started on a narrow profile fails halfway through, which is a
+//                 worse outcome than not offering the play.
+//   money         The money side, whole. The read-only money tools, plus hr because
+//                 payroll is money owed to the people who did the work, plus crm
+//                 so you can open the client you are about to chase, plus knowledge
+//                 because the published ladder is the only legal source of a number.
+//   outreach  51  The cold outreach machine: outreach and sourcing, plus crm to turn
+//                 a name into a record, knowledge to ground the words, and calendar
+//                 because you never offer a date you have not checked. This profile
+//                 saves the least of the three, and that is honest rather than
+//                 disappointing: the outreach job genuinely reaches most of the
+//                 workspace. `core` is the profile that buys real context back.
+//   content       The being-found side: SEO and the newsletter, plus crm and
+//                 knowledge, because content that does not know who buys or what
+//                 the business sounds like is generic content. This profile only
+//                 became real when the marketing family shipped (workstream B1);
+//                 before that the name existed in the installer and silently fell
+//                 back to `full`, which was a small lie told to anyone who used it.
+//   full          Everything, including the plays. The default.
+//   coach         Fully Booked Coach operations, client delivery, acquisition,
+//                 content requests, and approval previews. It exposes no send
+//                 or publish tool.
+//
+// An unknown profile name still gets `full` rather than an error, exactly as before.
+
+export const DEFAULT_PROFILE = 'full';
+
+export const PROFILES = {
+  core: ['core', 'meta', 'briefing'],
+  money: ['core', 'meta', 'briefing', 'crm', 'knowledge', 'money', 'hr'],
+  outreach: ['core', 'meta', 'briefing', 'crm', 'calendar', 'knowledge', 'outreach', 'sourcing', 'marketing'],
+  content: ['core', 'meta', 'briefing', 'crm', 'knowledge', 'marketing'],
+  full: '*',
+  coach: ['coach'],
+};
+
+/**
+ * The families this map speaks for. Everything named in a narrow profile above was
+ * placed by hand, so its own PROFILES export stops deciding where it lands. `plays`
+ * has to be named here on its own, because it is placed too and placed nowhere but
+ * `full`: without this line its own ['*'] would put it back into all three.
+ */
+// Coach is a public pilot surface with an explicit safety review. New families
+// must not silently join it through a wildcard declaration.
+const CLOSED_PROFILES = new Set(['coach']);
+
+const PLACED = new Set([...Object.values(PROFILES).filter(Array.isArray).flat(), 'plays']);
+
+export const PROFILE_NAMES = Object.keys(PROFILES);
+
+/** Normalise a caller-supplied profile. Unknown or empty falls back to `full`, never throws. */
+export function resolveProfile(raw) {
+  const p = typeof raw === 'string' ? raw.trim().toLowerCase() : '';
+  return Object.prototype.hasOwnProperty.call(PROFILES, p) ? p : DEFAULT_PROFILE;
+}
+
+// ---- family discovery ------------------------------------------------------
+
+const TOOLS_DIR = new URL('./tools/', import.meta.url);
+
+function warn(msg) {
+  console.error(`kmhub-mcp: ${msg}`);
+}
+
+async function discoverFamilies() {
+  let files;
+  try {
+    files = readdirSync(TOOLS_DIR)
+      .filter((f) => f.endsWith('.mjs'))
+      .sort();
+  } catch (e) {
+    warn(`could not read the tools/ directory: ${String(e?.message || e)}. No tools are available.`);
+    return [];
+  }
+
+  const loaded = [];
+  const seen = new Set();
+  for (const file of files) {
+    let mod;
+    try {
+      mod = await import(new URL(file, TOOLS_DIR).href);
+    } catch (e) {
+      warn(`skipping tools/${file}, it failed to load: ${String(e?.message || e)}`);
+      continue;
+    }
+    const family = typeof mod?.FAMILY === 'string' ? mod.FAMILY.trim() : '';
+    if (!family) {
+      warn(`skipping tools/${file}, it does not export a FAMILY name.`);
+      continue;
+    }
+    if (typeof mod.register !== 'function') {
+      warn(`skipping tools/${file}, family '${family}' does not export a register() function.`);
+      continue;
+    }
+    if (seen.has(family)) {
+      warn(`skipping tools/${file}, family '${family}' is already declared by another file.`);
+      continue;
+    }
+    seen.add(family);
+    loaded.push({
+      FAMILY: family,
+      TOOLS: Array.isArray(mod.TOOLS) ? mod.TOOLS.filter((t) => typeof t === 'string' && t) : [],
+      PROFILES: Array.isArray(mod.PROFILES) ? mod.PROFILES.filter((p) => typeof p === 'string' && p) : [],
+      register: mod.register,
+      file,
+    });
+  }
+
+  // Deterministic order so tools/list is stable across processes and restarts:
+  // core first (it is the original ten, and clients expect to see them first),
+  // then alphabetical.
+  loaded.sort((a, b) => {
+    if (a.FAMILY === 'core') return -1;
+    if (b.FAMILY === 'core') return 1;
+    return a.FAMILY.localeCompare(b.FAMILY);
+  });
+  return loaded;
+}
+
+const FAMILIES = await discoverFamilies();
+
+export const FAMILY_NAMES = FAMILIES.map((f) => f.FAMILY);
+
+/**
+ * Is this family part of this profile?
+ *
+ * `full` takes everything. Otherwise the map decides for every family it places,
+ * and only a family the map has never heard of gets to opt itself in.
+ */
+function inProfile(family, profile) {
+  if (profile === DEFAULT_PROFILE) return true;
+  const listed = PROFILES[profile];
+  if (listed === '*') return true;
+  if (Array.isArray(listed) && listed.includes(family.FAMILY)) return true;
+  if (CLOSED_PROFILES.has(profile)) return false;
+  if (PLACED.has(family.FAMILY)) return false;
+  return family.PROFILES.includes('*') || family.PROFILES.includes(profile);
+}
+
+/** The family records a profile loads, in registration order. */
+export function familiesFor(profile) {
+  const p = resolveProfile(profile);
+  return FAMILIES.filter((f) => inProfile(f, p));
+}
+
+/** Declared tool names for a profile (deduped, in registration order). */
+export function toolNamesFor(profile) {
+  const names = [];
+  for (const f of familiesFor(profile)) {
+    for (const t of f.TOOLS) if (!names.includes(t)) names.push(t);
+  }
+  return names;
+}
+
+/** Every declared tool name across every family. Kept for the health payload and startup logs. */
+export const TOOL_NAMES = toolNamesFor(DEFAULT_PROFILE);
+
+// ---- registration ----------------------------------------------------------
+
+/**
+ * Hand a family a registrar rather than the raw McpServer, so one family can never
+ * claim a tool name another family already took. A duplicate name would otherwise
+ * make the SDK throw mid-request and cost the caller every tool, not just the
+ * clashing one. `raw` is there for the rare family that needs the real server.
+ */
+/**
+ * The tools announced as read-only, from read-only-tools.json (generated from the tool
+ * source by scripts/generate-read-only-tools.mjs - see there for the rule).
+ *
+ * 🚨 CODEX STOPS EVERY UNANNOTATED TOOL FOR AN APPROVAL. With no hint on any KM Hub tool,
+ * a Codex session asked permission before `km_me`, and `codex exec` failed every call with
+ * "MCP tool call requires approval". readOnlyHint: true is what lets a read run. Writes stay
+ * unannotated on purpose, so the person still approves each one.
+ *
+ * A missing or broken file costs the hints, never the tools.
+ */
+const READ_ONLY_TOOLS = (() => {
+  try {
+    const doc = JSON.parse(readFileSync(new URL('./read-only-tools.json', import.meta.url), 'utf8'));
+    return new Set(Array.isArray(doc.tools) ? doc.tools : []);
+  } catch (e) {
+    warn(`read-only-tools.json could not be read (${String(e?.message || e)}). Every tool will be announced without a read-only hint.`);
+    return new Set();
+  }
+})();
+
+export function isReadOnlyTool(name) {
+  return READ_ONLY_TOOLS.has(name);
+}
+
+function markReadOnly(name, registeredTool) {
+  if (!registeredTool || !READ_ONLY_TOOLS.has(name) || typeof registeredTool.update !== 'function') return registeredTool;
+  try {
+    registeredTool.update({ annotations: { ...(registeredTool.annotations || {}), readOnlyHint: true } });
+  } catch (e) {
+    warn(`could not mark '${name}' read-only (${String(e?.message || e)}). It still works; hosts will ask before running it.`);
+  }
+  return registeredTool;
+}
+
+function guardedRegistrar(server, taken, family, registered) {
+  const claim = (name) => {
+    if (typeof name !== 'string' || !name.trim()) {
+      warn(`family '${family}' tried to register a tool with no name. Ignored.`);
+      return false;
+    }
+    const owner = taken.get(name);
+    if (owner) {
+      warn(`tool name collision on '${name}': family '${owner}' already registered it, so family '${family}' does not get it.`);
+      return false;
+    }
+    taken.set(name, family);
+    registered.push(name);
+    return true;
+  };
+  return {
+    tool: (name, ...rest) => (claim(name) ? markReadOnly(name, server.tool(name, ...rest)) : undefined),
+    registerTool: (name, ...rest) => (claim(name) ? markReadOnly(name, server.registerTool(name, ...rest)) : undefined),
+    prompt: (...args) => server.prompt(...args),
+    resource: (...args) => server.resource(...args),
+    raw: server,
+  };
+}
+
+/**
+ * Register the KM Hub tools for one profile on an McpServer.
+ *
+ * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
+ * @param {(method: string, path: string, body?: any) => Promise<{ok:boolean,status:number,data:any}>} call
+ *        already bound to a single org's API token
+ * @param {{ profile?: string }} [opts] profile name; unknown or absent means `full`
+ * @returns {{ profile: string, families: string[], tools: string[] }} what actually registered
+ */
+export function registerTools(server, call, opts = {}) {
+  const profile = resolveProfile(opts.profile);
+  const families = familiesFor(profile);
+  const taken = new Map();
+  const registered = [];
+
+  for (const family of families) {
+    const helpers = {
+      out,
+      text,
+      qs,
+      z,
+      profile,
+      family: family.FAMILY,
+      SERVER_NAME,
+      SERVER_VERSION,
+      DEFAULT_BASE,
+    };
+    try {
+      family.register(guardedRegistrar(server, taken, family.FAMILY, registered), call, helpers);
+    } catch (e) {
+      // One bad family must not cost the caller the other nine.
+      warn(`family '${family.FAMILY}' failed to register: ${String(e?.message || e)}. Its tools are unavailable; the rest still work.`);
+    }
+  }
+
+  return { profile, families: families.map((f) => f.FAMILY), tools: registered };
+}