@kivimedia/kmhub 2.0.0

package/tools.mjs

@@ -0,0 +1,349 @@
+/**
+ * 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 } from 'node:fs';
+import { z } from 'zod';
+
+export const SERVER_NAME = 'kmhub';
+export const SERVER_VERSION = '2.0.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 };
+  }
+  return { content: [{ type: 'text', text: JSON.stringify(r.data, null, 2) }], 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     38  The money side, whole. The nine read-only money tools, 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.
+//   full      63  Everything, including the plays. The default.
+//
+// There is deliberately no `content` profile. There are no content tools. An older
+// client that still asks for one gets `full` rather than an error, exactly as any
+// other unknown name does.
+
+export const DEFAULT_PROFILE = 'full';
+
+export const PROFILES = {
+  core: ['core', 'meta', 'briefing'],
+  money: ['core', 'meta', 'briefing', 'crm', 'knowledge', 'money'],
+  outreach: ['core', 'meta', 'briefing', 'crm', 'calendar', 'knowledge', 'outreach', 'sourcing'],
+  full: '*',
+};
+
+/**
+ * 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.
+ */
+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 (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.
+ */
+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) ? server.tool(name, ...rest) : undefined),
+    registerTool: (name, ...rest) => (claim(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 };
+}