@kivimedia/kmhub 2.0.0

package/index.mjs

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+/**
+ * kmhub-mcp (C9) - a standalone LOCAL (stdio) MCP server that wraps the KM Hub public
+ * REST API (the kmhub-api edge function) as MCP tools. Any MCP client (Claude Desktop,
+ * Claude Code, IDEs) can then read your queue and create leads, authenticated with a
+ * single KM Hub API key from the environment.
+ *
+ * For the multi-tenant, zero-local-install variant (one VPS process serving many orgs
+ * over Streamable HTTP, each request scoped by its own Bearer token), see remote.mjs.
+ *
+ * Setup:
+ *   1. In KM Hub: Settings > Developer & API > create an API key (kmh_live_...).
+ *   2. npm install (in this folder).
+ *   3. Add to your MCP client config with env KMHUB_API_KEY=kmh_live_...
+ *
+ * Env:
+ *   KMHUB_API_KEY   required, the org's key
+ *   KMHUB_API_BASE  override the kmhub-api base URL
+ *   KMHUB_PROFILE   which tool families to load: core, outreach, money, content, full.
+ *                   Default full (everything). A narrower profile means fewer tool
+ *                   schemas in every turn, which is real context back for the model.
+ *
+ * One org-scoped auth substrate: the same key + routes the Telegram bot / Zapier use.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  DEFAULT_BASE,
+  SERVER_NAME,
+  SERVER_VERSION,
+  makeCaller,
+  registerTools,
+  resolveProfile,
+} from './tools.mjs';
+
+const BASE = DEFAULT_BASE;
+const KEY = process.env.KMHUB_API_KEY;
+if (!KEY) {
+  console.error('kmhub-mcp: set KMHUB_API_KEY (create one in KM Hub > Settings > Developer & API).');
+  process.exit(1);
+}
+
+// An unknown KMHUB_PROFILE falls back to full rather than failing to start: a typo in
+// a config file should never cost someone their whole toolset.
+const PROFILE = resolveProfile(process.env.KMHUB_PROFILE);
+
+const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION });
+const { families, tools } = registerTools(server, makeCaller(BASE, KEY), { profile: PROFILE });
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error(
+  `kmhub-mcp ${SERVER_VERSION}: connected (stdio), profile '${PROFILE}' ` +
+    `(families: ${families.join(', ')}). Tools: ${tools.join(', ')}.`,
+);

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@kivimedia/kmhub",
+  "version": "2.0.0",
+  "description": "KM Hub Terminal Mode. Installs the KM Hub MCP connector into your own Claude Code on your own machine, and ships the kmhub CLI that registers, updates and diagnoses it.",
+  "keywords": [
+    "kmhub",
+    "kivimedia",
+    "mcp",
+    "model-context-protocol",
+    "claude-code",
+    "terminal-mode",
+    "crm"
+  ],
+  "homepage": "https://hub.kivimedia.co",
+  "license": "UNLICENSED",
+  "author": "Kivi Media (https://hub.kivimedia.co)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kivimedia/kmhub.git",
+    "directory": "mcp-server"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=18.17"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "kmhub": "bin/kmhub.mjs",
+    "kmhub-mcp": "index.mjs",
+    "kmhub-mcp-remote": "remote.mjs"
+  },
+  "files": [
+    "bin/kmhub.mjs",
+    "index.mjs",
+    "remote.mjs",
+    "tools.mjs",
+    "tools/*.mjs"
+  ],
+  "scripts": {
+    "start": "node index.mjs",
+    "start:remote": "node remote.mjs",
+    "check:version": "node -e \"const fs=require('fs');const p=JSON.parse(fs.readFileSync('package.json','utf8'));const t=fs.readFileSync('tools.mjs','utf8');const m=t.match(/SERVER_VERSION\\s*=\\s*'([^']+)'/);if(!m){console.error('kmhub: could not find SERVER_VERSION in tools.mjs, so the two identities cannot be compared.');process.exit(1)}if(m[1]!==p.version){console.error('kmhub: version mismatch. package.json is '+p.version+' and tools.mjs SERVER_VERSION is '+m[1]+'. Make them the same string in one commit, then publish.');process.exit(1)}console.log('kmhub: version check ok, both say '+p.version)\"",
+    "prepublishOnly": "npm run check:version"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.23.8"
+  }
+}

package/remote.mjs

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+/**
+ * kmhub-mcp REMOTE (P5) - a Streamable-HTTP MCP server for KM Hub power users.
+ *
+ * ONE process serves MANY orgs. There is no server-wide API key. Instead every
+ * request authenticates itself with a KM Hub org API key sent as a Bearer token:
+ *
+ *     Authorization: Bearer kmh_live_xxxxxxxx
+ *
+ * That token is bound to a fresh, per-request McpServer whose tools call kmhub-api
+ * with exactly that token. The kmhub-api edge function then does the authoritative
+ * org scoping + scope check (read vs write), so one caller can never reach another
+ * tenant's rows. This is the multi-tenant twin of the local stdio server (index.mjs);
+ * both share the SAME tool definitions from tools.mjs.
+ *
+ * Transport: MCP Streamable HTTP, STATELESS mode (sessionIdGenerator: undefined) -
+ * each POST /mcp is a self-contained request/response, so there is no session state
+ * to leak across tenants. Deployed on the VPS as pm2 process `kmhub-mcp`; see
+ * DEPLOY-VPS.md.
+ *
+ * Endpoints:
+ *   GET  /health  -> { ok: true, ... }        (no auth; for pm2 / nginx / uptime checks)
+ *   POST /mcp     -> MCP Streamable HTTP       (Bearer token required)
+ *   GET  /mcp     -> 405 (no server-initiated SSE stream in stateless mode)
+ *
+ * Tool profiles: a caller can load a subset of the tools instead of all of them, which
+ * costs the model far fewer tool schemas per turn. Two ways to ask, both per-request so
+ * the server stays stateless and two tenants can hold different profiles at the same time:
+ *   POST /mcp?profile=money            (query string, wins if both are present)
+ *   X-KMHub-Profile: money             (header)
+ * Known profiles: core, outreach, money, content, full. Anything else falls back to full
+ * rather than erroring, because a typo should never cost someone their tools.
+ *
+ * Env:
+ *   PORT            listen port (default 8830)
+ *   HOST            bind address (default 0.0.0.0)
+ *   KMHUB_API_BASE  override the kmhub-api base URL (default = the shared one)
+ *   MCP_RATE_LIMIT  max POST /mcp requests per token per minute (default 120)
+ */
+import http from 'node:http';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import {
+  DEFAULT_BASE,
+  DEFAULT_PROFILE,
+  FAMILY_NAMES,
+  PROFILE_NAMES,
+  SERVER_NAME,
+  SERVER_VERSION,
+  TOOL_NAMES,
+  makeCaller,
+  registerTools,
+  resolveProfile,
+  toolNamesFor,
+} from './tools.mjs';
+
+const PORT = Number(process.env.PORT || 8830);
+const HOST = process.env.HOST || '0.0.0.0';
+const BASE = DEFAULT_BASE;
+const RATE_LIMIT = Number(process.env.MCP_RATE_LIMIT || 120); // requests / token / minute
+const WINDOW_MS = 60_000;
+
+// ---- light in-memory per-token rate limiter -------------------------------
+// First line of defense at the MCP layer. kmhub-api still enforces the
+// authoritative per-key limit (60 reads / 20 writes per minute) downstream.
+const buckets = new Map(); // token -> { count, resetAt }
+
+function rateLimited(token) {
+  const now = Date.now();
+  let b = buckets.get(token);
+  if (!b || now >= b.resetAt) {
+    b = { count: 0, resetAt: now + WINDOW_MS };
+    buckets.set(token, b);
+  }
+  b.count += 1;
+  if (b.count > RATE_LIMIT) {
+    return Math.max(1, Math.ceil((b.resetAt - now) / 1000)); // retry-after seconds
+  }
+  return 0;
+}
+
+// Periodically evict stale buckets so memory does not grow unbounded.
+setInterval(() => {
+  const now = Date.now();
+  for (const [token, b] of buckets) if (now >= b.resetAt) buckets.delete(token);
+}, WINDOW_MS).unref();
+
+// ---- helpers --------------------------------------------------------------
+function sendJson(res, status, obj) {
+  const body = JSON.stringify(obj);
+  res.writeHead(status, { 'content-type': 'application/json', 'content-length': Buffer.byteLength(body) });
+  res.end(body);
+}
+
+// A well-formed JSON-RPC error response (id null: the request never reached a handler).
+function sendRpcError(res, status, code, message, extraHeaders = {}) {
+  const body = JSON.stringify({ jsonrpc: '2.0', error: { code, message }, id: null });
+  res.writeHead(status, { 'content-type': 'application/json', 'content-length': Buffer.byteLength(body), ...extraHeaders });
+  res.end(body);
+}
+
+function bearerToken(req) {
+  const h = req.headers['authorization'] || req.headers['Authorization'];
+  if (!h || typeof h !== 'string') return null;
+  const m = h.match(/^Bearer\s+(.+)$/i);
+  return m ? m[1].trim() : null;
+}
+
+// Which tool profile this ONE request asked for. Query string beats header; an
+// unknown or missing value resolves to `full`, never an error. Derived per request
+// and passed down by argument - nothing about the profile is ever stored, so the
+// server stays stateless and two tenants can hold two different profiles at once.
+function requestProfile(req, url) {
+  const fromQuery = url.searchParams.get('profile');
+  const raw = req.headers['x-kmhub-profile'];
+  const fromHeader = Array.isArray(raw) ? raw[0] : raw;
+  return resolveProfile((fromQuery && fromQuery.trim()) || (typeof fromHeader === 'string' ? fromHeader.trim() : ''));
+}
+
+// ---- one MCP request, scoped to one org's token ---------------------------
+async function handleMcpPost(req, res, token, profile) {
+  const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION });
+  registerTools(server, makeCaller(BASE, token), { profile });
+
+  const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+
+  // Tear the per-request server + transport down when the response closes.
+  res.on('close', () => {
+    transport.close().catch(() => {});
+    server.close().catch(() => {});
+  });
+
+  try {
+    await server.connect(transport);
+    // Let the transport read + parse the request body and write the response.
+    await transport.handleRequest(req, res);
+  } catch (err) {
+    console.error('kmhub-mcp remote: request error', err);
+    if (!res.headersSent) {
+      sendRpcError(res, 500, -32603, 'Internal server error');
+    }
+  }
+}
+
+// ---- router ---------------------------------------------------------------
+const httpServer = http.createServer(async (req, res) => {
+  const url = new URL(req.url, `http://${req.headers.host || 'localhost'}`);
+  const path = url.pathname.replace(/\/+$/, '') || '/';
+
+  // Health: no auth, cheap, used by pm2 / nginx / uptime monitors.
+  if (req.method === 'GET' && (path === '/health' || path === '/healthz')) {
+    return sendJson(res, 200, {
+      ok: true,
+      server: SERVER_NAME,
+      version: SERVER_VERSION,
+      transport: 'streamable-http',
+      tools: TOOL_NAMES.length,
+      families: FAMILY_NAMES,
+      default_profile: DEFAULT_PROFILE,
+      profiles: Object.fromEntries(PROFILE_NAMES.map((p) => [p, toolNamesFor(p).length])),
+    });
+  }
+
+  if (path === '/mcp') {
+    // Streamable HTTP stateless: only POST carries JSON-RPC. GET (server SSE) is unused.
+    if (req.method === 'GET' || req.method === 'DELETE') {
+      return sendRpcError(res, 405, -32000, 'Method not allowed: this server is stateless (POST /mcp only).', {
+        allow: 'POST',
+      });
+    }
+    if (req.method !== 'POST') {
+      return sendRpcError(res, 405, -32000, 'Method not allowed.', { allow: 'POST' });
+    }
+
+    const token = bearerToken(req);
+    if (!token) {
+      return sendRpcError(
+        res,
+        401,
+        -32001,
+        'Missing KM Hub API key. Send it as: Authorization: Bearer kmh_live_...',
+        { 'www-authenticate': 'Bearer realm="kmhub-mcp"' },
+      );
+    }
+
+    const retryAfter = rateLimited(token);
+    if (retryAfter) {
+      return sendRpcError(res, 429, -32002, `Rate limit exceeded. Retry after ${retryAfter}s.`, {
+        'retry-after': String(retryAfter),
+      });
+    }
+
+    return handleMcpPost(req, res, token, requestProfile(req, url));
+  }
+
+  return sendRpcError(res, 404, -32601, `Not found: ${req.method} ${path}`);
+});
+
+httpServer.listen(PORT, HOST, () => {
+  console.error(
+    `kmhub-mcp remote ${SERVER_VERSION}: listening on http://${HOST}:${PORT}  (POST /mcp, GET /health). ` +
+      `Families: ${FAMILY_NAMES.join(', ')}. Profiles: ${PROFILE_NAMES.join(', ')} (default ${DEFAULT_PROFILE}). ` +
+      `Tools: ${TOOL_NAMES.join(', ')}.`,
+  );
+});
+
+// Graceful shutdown for pm2 restarts.
+for (const sig of ['SIGINT', 'SIGTERM']) {
+  process.on(sig, () => {
+    httpServer.close(() => process.exit(0));
+    setTimeout(() => process.exit(0), 3000).unref();
+  });
+}

package/tools/briefing.mjs

@@ -0,0 +1,91 @@
+/**
+ * Tool family: briefing - the morning handoff. One tool, one call, the whole day.
+ *
+ * WHY A WHOLE FAMILY FOR ONE TOOL
+ * Every other family is a door onto one part of the workspace. This one is the
+ * front door. A Terminal Mode session starts cold every single time: the model
+ * knows the workspace exists and knows nothing about what is happening in it. The
+ * old opening move was km_waiting, which hands back six counts, and then four or
+ * five list calls to turn those counts back into things a person can act on. That
+ * is five round trips before anyone has said a useful sentence, and a guess in the
+ * middle of it about which of the six numbers actually mattered.
+ *
+ * km_briefing is that whole opening move as one call, with the guess replaced by a
+ * ranking done on the server where the data already is. It comes back as ONE
+ * ordered list, most-worth-doing first, every entry carrying the reason it is
+ * there, plus the diary, plus the raw gate counts, plus one suggested play when
+ * the shape of the day genuinely calls for one.
+ *
+ * WHAT IT DOES NOT DO
+ * It reads. It cannot send, approve, complete, schedule or spend, and the play it
+ * suggests is never one that can spend the client's money. Everything it surfaces
+ * still ends where it ended before: a draft in the Approval Queue, a decision in
+ * front of a human.
+ *
+ * The route behind it is GET /briefing. That route owns the ranking rule and the
+ * suggestion rule, so this file passes two optional parameters through and
+ * reshapes nothing.
+ *
+ * The family contract this file follows is documented in ./README.md.
+ */
+import { z } from 'zod';
+
+export const FAMILY = 'briefing';
+
+export const TOOLS = ['km_briefing'];
+
+// Every profile. A session that can read invoices but cannot ask what needs doing
+// today is a session that starts every conversation from nothing. This is the one
+// tool whose absence is felt in every other family's work.
+export const PROFILES = ['*'];
+
+/** The API has not shipped this route yet (404 / 405 / 501 all mean the same here). */
+function routeMissing(r) {
+  return r.status === 404 || r.status === 405 || r.status === 501;
+}
+
+/**
+ * If the workspace is on an older kmhub-api, say so in one sentence and name the
+ * fallback. This is the first tool of the session, so an unexplained JSON 404 here
+ * would set the tone for everything after it.
+ */
+const NOT_SUPPORTED =
+  'This KM Hub is on an older version of the API that does not have the morning briefing yet. Nothing is broken and no data is missing. Fall back to km_waiting for the gate counts, then km_list_outreach_drafts, km_list_outreach_replies, km_list_tasks with overdue true, km_list_invoices with overdue true, and km_my_schedule for the diary. Say plainly that you are stitching it together by hand rather than pretending you have the ranked version.';
+
+/**
+ * @param {{ tool: Function }} server guarded registrar (see ./README.md)
+ * @param {(method: string, path: string, body?: any) => Promise<{ok:boolean,status:number,data:any}>} call
+ * @param {{ out: Function, text: Function, qs: Function }} helpers shared response helpers from ../tools.mjs
+ */
+export function register(server, call, { out, text, qs }) {
+  server.tool(
+    'km_briefing',
+    'THE FIRST TOOL TO REACH FOR on any open question about the day. If the user says any of "what needs me today", "what have I got on", "morning", "catch me up", "where are we", "what should I do first", "anything urgent", "what did I miss", or opens a session without a specific task, call this before anything else and answer from what it returns. ' +
+      'It REPLACES the old opening sequence entirely: km_waiting plus km_list_outreach_drafts plus km_list_outreach_replies plus km_list_tasks plus km_list_invoices plus km_my_schedule, all in one call. Do not run those first and do not run them afterwards to double check. Go to a list tool only when the user asks for more of one specific thing than the briefing carried, for example the full text of a draft (km_read_outreach_draft) or every invoice rather than only the late ones (km_list_invoices). ' +
+      'What comes back, in one response: a headline sentence you can read straight out loud; `items`, ONE list ranked in the order a person should actually deal with them, each with a plain reason it is there; `calendar`, today and the next few days including any date that is only pencilled in and has nothing signed behind it; `waiting`, the same raw gate counts km_waiting would have given you; and `suggested_play` when the shape of the day genuinely calls for one. ' +
+      'The ranking is not a list of lists. A new enquiry nobody has answered and a reply nobody has handled sit near the top because they are the things that stop being worth anything if you leave them, and money that is already late and worth real amounts outranks something merely unread. A gig today is near the top too, but as a fact to absorb rather than a decision to make. Trust the order: work down it, and do not silently re-sort it into your own idea of importance. Each item carries `score` so you can see why it sits where it does, and `next_tool` naming the read tool that opens it. ' +
+      'Read the `notes` array and the `complete` flag before you summarise. When a part of the workspace could not be read, the briefing says which part rather than quietly showing an empty list, and you must pass that on rather than telling somebody they have a clear day when you do not know that. ' +
+      'This tool only reads. It never sends, approves, completes, schedules or spends anything, and a play it suggests is never one that can spend money.',
+    {
+      days: z
+        .number()
+        .int()
+        .min(1)
+        .max(14)
+        .optional()
+        .describe('How far ahead the calendar part looks, in days including today. Default 3. Raise it when the user asks about the week or the fortnight ahead.'),
+      limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(60)
+        .optional()
+        .describe('How many ranked items to return, most important first. Default 25, which is already more than a person will do in a morning. `counts.truncated` tells you when there were more.'),
+    },
+    async ({ days, limit }) => {
+      const r = await call('GET', `/briefing${qs({ days, limit })}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+}

package/tools/calendar.mjs

@@ -0,0 +1,161 @@
+/**
+ * Tool family: calendar - the diary. What is on, what is free, and what one gig is.
+ *
+ * core.mjs already lists bookings and calendar events. This family is for the
+ * questions a performer asks in a car park at 5pm, where the answer has to
+ * arrive in one tool call and be readable out loud:
+ *
+ *   km_my_schedule        what have I got this week
+ *   km_check_availability am I free on that date, and at that hour
+ *   km_get_booking        tell me everything about this gig
+ *   km_update_booking     fix the details of a gig that is already agreed
+ *   km_blocked_dates      which days are already spoken for
+ *
+ * The availability answer is computed by the same database functions that drive
+ * the public booking widget and the lead gate, never re-derived on the way past,
+ * because a second opinion about a free Saturday is how a real person ends up
+ * double booked. When those functions decline to answer, the tool says it cannot
+ * tell rather than guessing "free".
+ *
+ * km_update_booking is deliberately the narrowest write in the whole server. It
+ * cannot move a date or a time, cannot touch money, and cannot cancel or
+ * complete anything, because those commit the business to something a person
+ * should be the one to commit to. It can confirm, and the description says in
+ * plain words what confirming does to the calendar.
+ *
+ * The family contract this file follows is documented in ./README.md.
+ */
+import { z } from 'zod';
+
+export const FAMILY = 'calendar';
+
+export const TOOLS = [
+  'km_my_schedule',
+  'km_check_availability',
+  'km_get_booking',
+  'km_update_booking',
+  'km_blocked_dates',
+];
+
+// The diary is the context every other family reasons against: a money question
+// and a follow-up question both start with what is already on the books. It
+// carries five tools, so the cost of joining every profile is small.
+export const PROFILES = ['*'];
+
+/**
+ * @param {{ tool: Function }} server guarded registrar (see ./README.md)
+ * @param {(method: string, path: string, body?: any) => Promise<{ok:boolean,status:number,data:any}>} call
+ * @param {{ out: Function, qs: Function }} helpers shared response helpers from ../tools.mjs
+ */
+export function register(server, call, { out, qs }) {
+  server.tool(
+    'km_my_schedule',
+    'What is on in KM Hub, day by day, in one call. Reach for this when the question is specifically '
+      + 'about the DIARY: a named week, a named day, or the next gig. "What have I got this week", '
+      + '"am I busy Saturday", "when is my next gig". Do NOT answer the broad question about the day from '
+      + 'here: if the person says "what needs me today", "catch me up", "what should I do first", or just '
+      + 'opens a session with nothing specific, km_briefing is the tool. It carries this diary AND the '
+      + 'enquiries, replies, tasks and money that are waiting, ranked against each other, none of which '
+      + 'this tool can see. Running both means paying for the same diary twice. It returns a plain-English '
+      + 'headline, one readable line per day, and the detail behind each line: the gigs with their times, '
+      + 'client, venue, guest count and fee, anything else in the diary, days blocked off, and dates that '
+      + 'are only pencilled in by a live lead. Days are counted in the workspace timezone, so "today" means '
+      + 'today where the performer is. Defaults to the next 7 days starting today. Read only: it never '
+      + 'changes anything. Use km_check_availability instead when the question is whether a specific date '
+      + 'is free rather than what is already booked.',
+    {
+      from: z.string().optional().describe('First day, YYYY-MM-DD. Defaults to today in the workspace timezone.'),
+      days: z.number().int().min(1).max(31).optional().describe('How many days to cover, 1 to 31. Default 7.'),
+    },
+    async ({ from, days }) => out(await call('GET', `/schedule${qs({ from, days })}`)),
+  );
+
+  server.tool(
+    'km_check_availability',
+    'Is a date free for a booking. Ask this before telling anyone a date might work. The verdict comes '
+      + 'from the same availability check that the public booking page and the lead forms use, so it '
+      + 'already counts confirmed bookings, days blocked off by hand, weekends the workspace does not work, '
+      + 'and dates a live lead has pencilled in. Give start_time (and optionally end_time or '
+      + 'duration_minutes, plus setup, packdown and travel padding) and it answers for that time window '
+      + 'instead of the whole day, so two non-overlapping gigs on one day both read as possible. Alongside '
+      + 'each verdict it lists what is actually in the diary that day, so a "taken" comes with the gig that '
+      + 'is taking it. If the workspace has switched its availability check off, the tool reports that it '
+      + 'cannot give a verdict and shows the diary instead: it will never call a day free when it does not '
+      + 'know. Read only, and it never reserves or holds anything.',
+    {
+      from: z.string().optional().describe('First date to check, YYYY-MM-DD. Defaults to today in the workspace timezone.'),
+      to: z.string().optional().describe('Last date to check, YYYY-MM-DD. Defaults to the same day as from. Up to 92 days for a whole-day check, 14 days when a start_time is given.'),
+      start_time: z.string().optional().describe('Start of the slot, HH:MM in 24 hour time. Supply it to check a time window rather than the whole day.'),
+      end_time: z.string().optional().describe('End of the slot, HH:MM in 24 hour time. Only meaningful with start_time; without it the workspace default duration is used.'),
+      duration_minutes: z.number().int().min(1).max(1440).optional().describe('How long the gig runs, when end_time is unknown.'),
+      buffer_before_minutes: z.number().int().min(0).max(1440).optional().describe('Setup time needed before the slot.'),
+      buffer_after_minutes: z.number().int().min(0).max(1440).optional().describe('Packdown time needed after the slot.'),
+      travel_minutes: z.number().int().min(0).max(1440).optional().describe('Travel time each way, added to both ends of the window.'),
+    },
+    async (args) => out(await call('GET', `/availability${qs(args)}`)),
+  );
+
+  server.tool(
+    'km_get_booking',
+    'Everything about one booking in KM Hub: the date, the start, end and setup times, the client with '
+      + 'their phone and email, the venue with its address and on-site contact, the event type and guest '
+      + 'count, the fee with deposit and outstanding balance, the client notes, internal notes and special '
+      + 'requirements, the pipeline deal it belongs to, and any diary entries attached to it. This is the '
+      + 'tool for "what is this gig", "where am I playing on Saturday", "who is the contact for the Kaplan '
+      + 'wedding" and "what do I need to bring". Needs the booking id, which km_my_schedule and '
+      + 'km_list_bookings both return. Read only.',
+    {
+      booking_id: z.string().describe('UUID of the booking (from km_my_schedule or km_list_bookings).'),
+    },
+    async ({ booking_id }) => out(await call('GET', `/bookings/${encodeURIComponent(String(booking_id || '').trim())}`)),
+  );
+
+  server.tool(
+    'km_update_booking',
+    'Correct the working details of a gig that is already agreed: its title, event type, guest count, '
+      + 'setup time, venue, client notes, internal notes, special requirements, and its status. '
+      + 'CONFIRMING IS CONSEQUENTIAL: setting status to confirmed marks that whole date as taken across '
+      + 'KM Hub, so the public booking page, the lead forms and every availability check start turning '
+      + 'other people away from it. Moving the status back to pending releases the date and offers it '
+      + 'again. Only make that call when the performer has actually said the gig is on or off. '
+      + 'WHAT THIS TOOL WILL NOT DO, by design, so do not try: it cannot move a booking to another date, '
+      + 'cannot change the start or end time, cannot change the fee, deposit or balance, cannot mark money '
+      + 'as paid, cannot mark a gig completed, and cannot cancel one. Those bind the business or free a '
+      + 'date for someone else, so a person does them in KM Hub. It also refuses to touch a gig that is '
+      + 'already completed or cancelled, and any booking owned by the meeting scheduler. Every change is '
+      + 'written to the AI activity log so the owner can see it; booking edits are not auto-undoable, so '
+      + 'get it right rather than counting on undo.',
+    {
+      booking_id: z.string().describe('UUID of the booking (from km_my_schedule or km_list_bookings).'),
+      title: z.string().optional().describe('What the gig is called on the calendar.'),
+      event_type: z.string().optional().describe('e.g. wedding, corporate, birthday. The value "meeting" is reserved by the scheduler and is refused.'),
+      guest_count: z.number().int().min(0).nullable().optional().describe('How many people are expected. Send null to clear it.'),
+      setup_start_time: z.string().nullable().optional().describe('Load-in time, HH:MM in 24 hour time. This is the performer\'s own logistics, not the event start. Send null to clear it.'),
+      venue_id: z.string().optional().describe('UUID of a venue already in this workspace.'),
+      client_notes: z.string().optional().describe('Notes the client would be shown.'),
+      internal_notes: z.string().optional().describe('Notes only the team sees.'),
+      special_requirements: z.string().optional().describe('Anything the gig needs: access, power, dress code, dietary.'),
+      status: z
+        .enum(['pending', 'confirmed', 'in_progress'])
+        .optional()
+        .describe('confirmed marks the date taken everywhere; pending releases it; in_progress means the gig is under way. Cancelled and completed are not available here.'),
+    },
+    async ({ booking_id, ...changes }) =>
+      out(await call('PATCH', `/bookings/${encodeURIComponent(String(booking_id || '').trim())}`, changes)),
+  );
+
+  server.tool(
+    'km_blocked_dates',
+    'The days that are already spoken for in KM Hub without being a gig: dates blocked off by hand with '
+      + 'their reason (holiday, family, studio time), and active holds, including dates a live lead has '
+      + 'pencilled in and that will expire on their own if the lead goes cold. Use it to answer "what am I '
+      + 'blocked out for", "why does that weekend show as unavailable", or before suggesting dates to '
+      + 'someone. Defaults to the next 90 days. Read only: blocking or unblocking a date decides whether '
+      + 'real work can be booked, so a person does that in KM Hub.',
+    {
+      from: z.string().optional().describe('First date, YYYY-MM-DD. Defaults to today in the workspace timezone.'),
+      to: z.string().optional().describe('Last date, YYYY-MM-DD. Defaults to 90 days out. At most a year at a time.'),
+    },
+    async ({ from, to }) => out(await call('GET', `/blocked-dates${qs({ from, to })}`)),
+  );
+}