@kivimedia/kmhub 2.9.1 → 2.11.0

package/README.md

@@ -1,170 +1,170 @@
-# kmhub-mcp
-
-A standalone [MCP](https://modelcontextprotocol.io) server for KM Hub. It exposes your
-workspace to any MCP client (Claude Desktop, Claude Code, IDEs, agents) using a KM Hub
-API key, by wrapping the public REST API (`kmhub-api`).
-
-It ships in two transports that share the exact same tool set (`tools.mjs` plus the
-family modules in `tools/`):
-
-- **Local stdio** (`index.mjs`) - the client spawns the process; the org key comes from
-  the `KMHUB_API_KEY` env var. One process = one workspace. Best for a single power user
-  on their own machine.
-- **Remote Streamable HTTP** (`remote.mjs`) - one long-running server (hosted on the VPS)
-  serves many orgs with zero local install. Each request authenticates with its own KM Hub
-  key sent as a `Authorization: Bearer kmh_live_...` header, and is scoped to that org only.
-  Deploy runbook: [DEPLOY-VPS.md](./DEPLOY-VPS.md).
-
-## Tools
-
-Tools are grouped into **families**, one file per family in [`tools/`](./tools/README.md).
-`tools.mjs` discovers them at load time, so a new family is a new file and nothing else.
-
-### `core` - orientation and the CRM essentials
-- `km_me` - the connected workspace (id, name, plan) + the key's scopes
-- `km_waiting` - what needs you (approvals, enquiries, tasks, invoices, contracts)
-- `km_list_clients` - recent clients / leads (optional `limit`)
-- `km_create_lead` - create a lead (`first_name`, `last_name`, `company`, `email`, `phone`, `notes`)
-- `km_list_deals` - pipeline deals (optional `limit`, `stage`, `status`)
-- `km_list_events` - calendar events (optional `limit`, `from`/`to` start-date range)
-- `km_list_bookings` - recent bookings (optional `limit`, `status`, `from`/`to` event-date range)
-- `km_create_inquiry` - log an enquiry + its client (`client_name` required; `event_type`, `event_date`, `budget_cents`, `notes`, ...). Opens a pipeline deal automatically. Audited + undoable in the AI activity log.
-- `km_create_booking` - create a real booking + its client (`client_name` and `event_date` required; optional `status`: `pending` default or `confirmed`). Opens a pipeline deal at booked/won. Audited + undoable.
-- `km_create_outreach_draft` - queue an outreach message as a DRAFT (`body` required; optional `subject`, `channel` email/linkedin/ig/sms_whatsapp, `deal_id`, `contact_id`). It only QUEUES: a human approves the draft in the Approval Queue before anything can send. Audited.
-
-### `meta` - keeping the connection current
-- `km_check_updates` - asks KM Hub what it publishes today (`GET /version` returns
-  `api_version`, `rules_version`, `tools_version`, `min_client`, `changelog_url`) and answers
-  in plain language. Two judgements: is this connector still above `min_client` (the build
-  KM Hub refuses to serve below), and is the rules file on disk still the published
-  `rules_version`? Pass the local one in as `rules_version`. The rules pack carries a content
-  hash after a `+`, and the two endpoints do not always both publish it, so the semver base
-  and the hash are judged separately rather than looping on a suffix that proves nothing.
-- `km_fetch_rules` - downloads the current KM Hub operating rules (`GET /rules`) and returns
-  `{ version, markdown, sha256, bytes, instructions }`. The model is instructed to write that
-  markdown verbatim over the user's global rules file (for Claude Code, their `CLAUDE.md`),
-  replacing any older KM Hub block, and then to tell the user it did so.
-
-Both meta tools degrade gracefully: if your KM Hub has not shipped `/version` or `/rules` yet
-they say "your KM Hub does not support update checks yet" and report success, rather than
-failing. The checksum is computed locally from the bytes that actually arrived; if KM Hub also
-sends one and the two differ, the response carries a warning instead of a silent bad write.
-
-## Profiles
-
-Every tool schema is loaded into every turn, so a big tool set is a real context tax. A
-profile loads only the families you want:
-
-| Profile | Loads |
-|---|---|
-| `core` | orientation + CRM essentials, plus `meta` |
-| `outreach` | `core` + the outreach families |
-| `money` | `core` + the billing families |
-| `content` | `core` + the content families |
-| `coach` | Fully Booked Coach operations, client delivery, acquisition, and content requests |
-| `full` | everything (**default**) |
-
-`full` is the default, so nothing changes for an existing connection. An unknown profile name
-falls back to `full` rather than erroring: a typo in a config file should never cost someone
-their tools.
-
-- **Remote**: per request, `POST /mcp?profile=money` or an `X-KMHub-Profile: money` header.
-  The query string wins if both are present. The profile is read from the request and passed
-  down by argument, so the server stays stateless and two tenants can hold two different
-  profiles at the same moment.
-- **Local stdio**: the `KMHUB_PROFILE` env var.
-
-`GET /health` reports the families that loaded and the tool count for each profile.
-
-## Setup - local stdio (`index.mjs`)
-1. In KM Hub: **Settings > Developer & API** -> create an API key (`kmh_live_...`).
-   Read tools need the `read` scope, create tools need `write` (a read-only key
-   gets 403 on writes).
-2. Install deps in this folder:
-   ```
-   npm install
-   ```
-3. Add to your MCP client.
-
-   Claude Code (one command):
-   ```
-   claude mcp add kmhub -e KMHUB_API_KEY=kmh_live_xxxxxxxx -- node /absolute/path/to/kmhub/mcp-server/index.mjs
-   ```
-
-   Claude Desktop `claude_desktop_config.json`:
-   ```json
-   {
-     "mcpServers": {
-       "kmhub": {
-         "command": "node",
-         "args": ["/absolute/path/to/kmhub/mcp-server/index.mjs"],
-         "env": { "KMHUB_API_KEY": "kmh_live_xxxxxxxx", "KMHUB_PROFILE": "full" }
-       }
-     }
-   }
-   ```
-   (Override the API base with `KMHUB_API_BASE` if self-hosting. `KMHUB_PROFILE` is optional
-   and defaults to `full`.)
-
-## Setup - remote Streamable HTTP (`remote.mjs`)
-
-No local install for the user - they point their client at the hosted VPS endpoint and
-authenticate with their own KM Hub key as a header. One server process serves every org;
-each request is scoped to the token it carries. Operators: see
-[DEPLOY-VPS.md](./DEPLOY-VPS.md) (pm2 `kmhub-mcp`, port `8830`,
-`https://mcp.kivimedia.co/mcp`).
-
-Claude Code (one command):
-
-```bash
-claude mcp add --transport http kmhub https://mcp.kivimedia.co/mcp \
-  --header "Authorization: Bearer kmh_live_xxxxxxxx"
-```
-
-Add `?profile=core` to the URL to load a smaller tool set:
-
-```bash
-claude mcp add --transport http kmhub "https://mcp.kivimedia.co/mcp?profile=core" \
-  --header "Authorization: Bearer kmh_live_xxxxxxxx"
-```
-
-Claude Desktop / config-file clients:
-
-```json
-{
-  "mcpServers": {
-    "kmhub": {
-      "type": "streamable-http",
-      "url": "https://mcp.kivimedia.co/mcp",
-      "headers": {
-        "Authorization": "Bearer kmh_live_xxxxxxxx",
-        "X-KMHub-Profile": "full"
-      }
-    }
-  }
-}
-```
-
-Health check (no auth): `GET https://mcp.kivimedia.co/health`.
-
-## Adding tools
-
-See [tools/README.md](./tools/README.md) for the family contract. Short version: drop a new
-`tools/<family>.mjs` exporting `FAMILY`, `TOOLS`, `register(server, call, helpers)` and an
-optional `PROFILES`, and it loads itself. You never edit `tools.mjs`, so parallel work on
-different families cannot collide. A family that fails to load, or claims a tool name another
-family already took, is skipped with a warning on stderr; the rest of the server carries on.
-
-## Notes
-This is the same org-scoped, key-authed substrate the Telegram bot and Zapier use - one
-auth surface for all machine access. Everything is scoped to the key's workspace; a key
-can never reach another tenant's data. The API rate-limits each key to 60 reads and 20
-writes per minute (429 + `retry-after` beyond that). Writes land in the AI activity log;
-outreach drafts additionally wait for human approval in the Approval Queue before any send.
-
-**Lapsed subscription (402).** If the API answers `402 subscription_inactive`, every tool in
-every family returns a plain-English message instead of a raw JSON blob: the subscription is
-not active, nothing in the workspace changed, and here is where to restart it. That is handled
-once in the shared `out()` helper in `tools.mjs`, so it covers families that do not exist yet.
-Other statuses keep the raw JSON body, which is what the model needs to reason about validation
-errors.
+# kmhub-mcp
+
+A standalone [MCP](https://modelcontextprotocol.io) server for KM Hub. It exposes your
+workspace to any MCP client (Claude Desktop, Claude Code, IDEs, agents) using a KM Hub
+API key, by wrapping the public REST API (`kmhub-api`).
+
+It ships in two transports that share the exact same tool set (`tools.mjs` plus the
+family modules in `tools/`):
+
+- **Local stdio** (`index.mjs`) - the client spawns the process; the org key comes from
+  the `KMHUB_API_KEY` env var. One process = one workspace. Best for a single power user
+  on their own machine.
+- **Remote Streamable HTTP** (`remote.mjs`) - one long-running server (hosted on the VPS)
+  serves many orgs with zero local install. Each request authenticates with its own KM Hub
+  key sent as a `Authorization: Bearer kmh_live_...` header, and is scoped to that org only.
+  Deploy runbook: [DEPLOY-VPS.md](./DEPLOY-VPS.md).
+
+## Tools
+
+Tools are grouped into **families**, one file per family in [`tools/`](./tools/README.md).
+`tools.mjs` discovers them at load time, so a new family is a new file and nothing else.
+
+### `core` - orientation and the CRM essentials
+- `km_me` - the connected workspace (id, name, plan) + the key's scopes
+- `km_waiting` - what needs you (approvals, enquiries, tasks, invoices, contracts)
+- `km_list_clients` - recent clients / leads (optional `limit`)
+- `km_create_lead` - create a lead (`first_name`, `last_name`, `company`, `email`, `phone`, `notes`)
+- `km_list_deals` - pipeline deals (optional `limit`, `stage`, `status`)
+- `km_list_events` - calendar events (optional `limit`, `from`/`to` start-date range)
+- `km_list_bookings` - recent bookings (optional `limit`, `status`, `from`/`to` event-date range)
+- `km_create_inquiry` - log an enquiry + its client (`client_name` required; `event_type`, `event_date`, `budget_cents`, `notes`, ...). Opens a pipeline deal automatically. Audited + undoable in the AI activity log.
+- `km_create_booking` - create a real booking + its client (`client_name` and `event_date` required; optional `status`: `pending` default or `confirmed`). Opens a pipeline deal at booked/won. Audited + undoable.
+- `km_create_outreach_draft` - queue an outreach message as a DRAFT (`body` required; optional `subject`, `channel` email/linkedin/ig/sms_whatsapp, `deal_id`, `contact_id`). It only QUEUES: a human approves the draft in the Approval Queue before anything can send. Audited.
+
+### `meta` - keeping the connection current
+- `km_check_updates` - asks KM Hub what it publishes today (`GET /version` returns
+  `api_version`, `rules_version`, `tools_version`, `min_client`, `changelog_url`) and answers
+  in plain language. Two judgements: is this connector still above `min_client` (the build
+  KM Hub refuses to serve below), and is the rules file on disk still the published
+  `rules_version`? Pass the local one in as `rules_version`. The rules pack carries a content
+  hash after a `+`, and the two endpoints do not always both publish it, so the semver base
+  and the hash are judged separately rather than looping on a suffix that proves nothing.
+- `km_fetch_rules` - downloads the current KM Hub operating rules (`GET /rules`) and returns
+  `{ version, markdown, sha256, bytes, instructions }`. The model is instructed to write that
+  markdown verbatim over the user's global rules file (for Claude Code, their `CLAUDE.md`),
+  replacing any older KM Hub block, and then to tell the user it did so.
+
+Both meta tools degrade gracefully: if your KM Hub has not shipped `/version` or `/rules` yet
+they say "your KM Hub does not support update checks yet" and report success, rather than
+failing. The checksum is computed locally from the bytes that actually arrived; if KM Hub also
+sends one and the two differ, the response carries a warning instead of a silent bad write.
+
+## Profiles
+
+Every tool schema is loaded into every turn, so a big tool set is a real context tax. A
+profile loads only the families you want:
+
+| Profile | Loads |
+|---|---|
+| `core` | orientation + CRM essentials, plus `meta` |
+| `outreach` | `core` + the outreach families |
+| `money` | `core` + the billing families |
+| `content` | `core` + the content families |
+| `coach` | Fully Booked Coach operations, client delivery, acquisition, and content requests |
+| `full` | everything (**default**) |
+
+`full` is the default, so nothing changes for an existing connection. An unknown profile name
+falls back to `full` rather than erroring: a typo in a config file should never cost someone
+their tools.
+
+- **Remote**: per request, `POST /mcp?profile=money` or an `X-KMHub-Profile: money` header.
+  The query string wins if both are present. The profile is read from the request and passed
+  down by argument, so the server stays stateless and two tenants can hold two different
+  profiles at the same moment.
+- **Local stdio**: the `KMHUB_PROFILE` env var.
+
+`GET /health` reports the families that loaded and the tool count for each profile.
+
+## Setup - local stdio (`index.mjs`)
+1. In KM Hub: **Settings > Developer & API** -> create an API key (`kmh_live_...`).
+   Read tools need the `read` scope, create tools need `write` (a read-only key
+   gets 403 on writes).
+2. Install deps in this folder:
+   ```
+   npm install
+   ```
+3. Add to your MCP client.
+
+   Claude Code (one command):
+   ```
+   claude mcp add kmhub -e KMHUB_API_KEY=kmh_live_xxxxxxxx -- node /absolute/path/to/kmhub/mcp-server/index.mjs
+   ```
+
+   Claude Desktop `claude_desktop_config.json`:
+   ```json
+   {
+     "mcpServers": {
+       "kmhub": {
+         "command": "node",
+         "args": ["/absolute/path/to/kmhub/mcp-server/index.mjs"],
+         "env": { "KMHUB_API_KEY": "kmh_live_xxxxxxxx", "KMHUB_PROFILE": "full" }
+       }
+     }
+   }
+   ```
+   (Override the API base with `KMHUB_API_BASE` if self-hosting. `KMHUB_PROFILE` is optional
+   and defaults to `full`.)
+
+## Setup - remote Streamable HTTP (`remote.mjs`)
+
+No local install for the user - they point their client at the hosted VPS endpoint and
+authenticate with their own KM Hub key as a header. One server process serves every org;
+each request is scoped to the token it carries. Operators: see
+[DEPLOY-VPS.md](./DEPLOY-VPS.md) (pm2 `kmhub-mcp`, port `8830`,
+`https://mcp.kivimedia.co/mcp`).
+
+Claude Code (one command):
+
+```bash
+claude mcp add --transport http kmhub https://mcp.kivimedia.co/mcp \
+  --header "Authorization: Bearer kmh_live_xxxxxxxx"
+```
+
+Add `?profile=core` to the URL to load a smaller tool set:
+
+```bash
+claude mcp add --transport http kmhub "https://mcp.kivimedia.co/mcp?profile=core" \
+  --header "Authorization: Bearer kmh_live_xxxxxxxx"
+```
+
+Claude Desktop / config-file clients:
+
+```json
+{
+  "mcpServers": {
+    "kmhub": {
+      "type": "streamable-http",
+      "url": "https://mcp.kivimedia.co/mcp",
+      "headers": {
+        "Authorization": "Bearer kmh_live_xxxxxxxx",
+        "X-KMHub-Profile": "full"
+      }
+    }
+  }
+}
+```
+
+Health check (no auth): `GET https://mcp.kivimedia.co/health`.
+
+## Adding tools
+
+See [tools/README.md](./tools/README.md) for the family contract. Short version: drop a new
+`tools/<family>.mjs` exporting `FAMILY`, `TOOLS`, `register(server, call, helpers)` and an
+optional `PROFILES`, and it loads itself. You never edit `tools.mjs`, so parallel work on
+different families cannot collide. A family that fails to load, or claims a tool name another
+family already took, is skipped with a warning on stderr; the rest of the server carries on.
+
+## Notes
+This is the same org-scoped, key-authed substrate the Telegram bot and Zapier use - one
+auth surface for all machine access. Everything is scoped to the key's workspace; a key
+can never reach another tenant's data. The API rate-limits each key to 60 reads and 20
+writes per minute (429 + `retry-after` beyond that). Writes land in the AI activity log;
+outreach drafts additionally wait for human approval in the Approval Queue before any send.
+
+**Lapsed subscription (402).** If the API answers `402 subscription_inactive`, every tool in
+every family returns a plain-English message instead of a raw JSON blob: the subscription is
+not active, nothing in the workspace changed, and here is where to restart it. That is handled
+once in the shared `out()` helper in `tools.mjs`, so it covers families that do not exist yet.
+Other statuses keep the raw JSON body, which is what the model needs to reason about validation
+errors.