@kivimedia/kmhub 2.0.0

package/README.md

@@ -0,0 +1,169 @@
+# 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 |
+| `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://kmhub-mcp.104-200-30-37.sslip.io/mcp`).
+
+Claude Code (one command):
+
+```bash
+claude mcp add --transport http kmhub https://kmhub-mcp.104-200-30-37.sslip.io/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://kmhub-mcp.104-200-30-37.sslip.io/mcp?profile=core" \
+  --header "Authorization: Bearer kmh_live_xxxxxxxx"
+```
+
+Claude Desktop / config-file clients:
+
+```json
+{
+  "mcpServers": {
+    "kmhub": {
+      "type": "streamable-http",
+      "url": "https://kmhub-mcp.104-200-30-37.sslip.io/mcp",
+      "headers": {
+        "Authorization": "Bearer kmh_live_xxxxxxxx",
+        "X-KMHub-Profile": "full"
+      }
+    }
+  }
+}
+```
+
+Health check (no auth): `GET https://kmhub-mcp.104-200-30-37.sslip.io/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.