@awesomate/hosting-mcp 0.18.0 → 0.19.0

package/README.md

@@ -1,58 +1,85 @@
 # @awesomate/hosting-mcp
 
-MCP server that lets Claude read (and, in later releases, manage) your
-Awesomate WordPress hosting: provisioning status, sites, domains, plan,
-limits, and upgrade nudges.
-
-## Setup
-
-The intended path is the **Connect Claude Code** card on
-[hub.awesomate.ai/sites](https://hub.awesomate.ai/sites): it generates a
-one-time prompt that has Claude run the bundled `skill/awesomate-hosting/scripts/bootstrap.mjs`,
-which redeems a setup code for a scoped access token (stored at
-`~/.awesomate/credentials.json`, chmod 600), provisions an SSH key
-(Support Plus+), and registers this server. The **`awesomate-hosting` skill**
-(bundled under `skill/`) makes Claude plan-aware and enforces snapshot-before-change.
-
-Manual registration — add to `~/.claude.json` under `mcpServers` (the
-bootstrap does this automatically; never bake `AWESOMATE_PAT` into the env,
-that pins the registration to one stale account forever):
-
-```json
-"awesomate-hosting": {
-  "command": "npx",
-  "args": ["-y", "--package=@awesomate/hosting-mcp", "awesomate-hosting-mcp"]
-}
-```
+The MCP server that connects an Awesomate customer's own Claude Code to their
+Awesomate account: WordPress hosting, n8n automations, apps, and Knowledge
+Base. It authenticates to the Awesomate hub with a scoped Personal Access
+Token and ships the nine `awesomate-*` skills that teach Claude how to use it.
+
+## Install (customers)
+
+Don't install this by hand. Open **hub.awesomate.ai/claude** (or the Sites
+page) and click **Connect Claude Code** — it gives you a one-time command that:
+
+1. redeems a short-lived setup code for a scoped access token, born on your
+   machine (`~/.awesomate/credentials.json`, chmod 600 — it never traverses
+   the clipboard),
+2. installs the `awesomate-*` skills into `~/.claude/skills`,
+3. registers this server in Claude Code (user scope, no token in the
+   registration — see below).
+
+Then restart Claude Code and run `awesomate_whoami`.
+
+## What Claude can do with it
+
+Roughly 60 tools across five domains — the authoritative list is whatever
+`tools/list` returns from the version you're running (this server self-updates,
+so a hand-maintained table here would only ever be stale):
 
-If you use `claude mcp add` instead, keep the `--package=` form — the claude
-CLI pre-scans the whole argv for its own global `-p`/`--print` flag (even
-after `--`), so a bare `-p <pkg>` breaks its option parsing.
+- **Hosting & WordPress** — sites, domains, DNS checks, uptime, plan limits,
+  snapshots/rollback, `.dev` staging, allowlisted WP-CLI, structured post/page
+  writes (drafts first) and media import. Writes need Support Plus+.
+- **n8n automations** — full read surface on every plan (workflows, executions
+  with structural error decode, instance-wide error clusters, KPIs, storage
+  footprint, node docs); validate → draft → test → promote build loop on
+  Support Plus+; AI error-analyzer findings on Pro/Embedded.
+- **Apps** — scaffold, create, deploy-via-git, env vars, health, app Postgres.
+- **Knowledge Base** (Pro+) — provision, ingest sources, faceted search,
+  cited answers, agents, people/entities, business-data queries.
+- **Account** — context + attention digest (notifications, erroring workflows,
+  token expiry), plan features, upgrade nudges, support tickets, done-for-you
+  build requests (two-step credit confirmation; never spends without an
+  explicit yes).
 
-Account resolution: `AWESOMATE_PAT` env → `AWESOMATE_ACCOUNT` env →
-`.awesomate.json` folder pin → sole/default profile in
-`~/.awesomate/credentials.json` (multi-account since 0.7.0).
+Every response is stamped `account: <slug>` so a session talking to the wrong
+account is impossible to miss. Read tools carry `readOnlyHint`; destructive
+ones carry `destructiveHint` and confirm-before-acting instructions.
 
-## Tools (v0.1 — read-only)
+## Security posture
 
-| Tool | What it returns |
-|---|---|
-| `awesomate_get_context` | Plan, capabilities, scopes, token expiry, cPanel routing |
-| `awesomate_get_hosting_status` | Provisioning state, primary domain, DNS targets |
-| `awesomate_get_hosting_account` | cPanel package/server details |
-| `awesomate_list_sites` | WordPress sites with SSL/WP-version state |
-| `awesomate_list_domains` | Included + custom domains, DNS/SSL state |
-| `awesomate_get_limits` | Usage vs plan limits + upgrade nudges |
-| `awesomate_get_plan_features` | Static plan-ladder reference |
+- **No signup, no payment, no secrets through the model.** Purchases and
+  privacy toggles happen only in the hub UI. Secrets travel via the
+  secret-drop flow (`awesomate-credentials` skill), never the chat.
+- **Scopes ∩ live plan** are re-derived per request server-side; consent
+  toggles gate every read of instance data and every write is audited.
+- The registration is deliberately env-free: baking `AWESOMATE_PAT` into the
+  MCP registration pins it to one stale account forever. The token lives in
+  `~/.awesomate/credentials.json`; a `.awesomate.json` folder pin selects the
+  profile in multi-account setups.
 
-Access tokens are plan-scoped server-side: what the token can do always
-reflects the account's **live** plan. Tokens are revocable from the hub Sites
-page.
+## Updates
+
+The server self-updates: it's registered as unpinned `npx -y`, so every Claude
+Code restart runs the latest published version. The skill files update via the
+`awesomate_skill_update` tool — Claude notices the drift itself (it's stamped
+on every response) and offers the update with what's-new lines from
+`skill/CHANGELOG.json`, then hands over the exact restart step.
+
+## Manual registration (developers)
+
+Keep `--package=` with the `=` — the claude CLI's global-argv pre-scan chokes
+on a bare `-p`, and the package must be explicit because this package ships
+two bins:
+
+```bash
+claude mcp add awesomate-hosting -- npx -y --package=@awesomate/hosting-mcp awesomate-hosting-mcp
+```
 
 ## Development
 
 ```bash
-npm install
 npm run typecheck
-npm run build     # esbuild bundle → dist/index.js (single file, no runtime deps)
+npm test           # builds, then boot-smoke + resolution + skills + knowledge suites
 ```
+
+Publishing is CI-only: any `mcp/**` change merged to main with a bumped
+version publishes via `publish-mcp.yml`. Never `npm publish` by hand.