@awesomate/hosting-mcp/README.md

Awesomate MCP server — lets Claude manage your Awesomate WordPress hosting, plan, limits, n8n automations, and build Node/static apps + databases

# @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 `awesomate-*` skills that teach Claude how to use it.

**Docs: https://hub.awesomate.ai/docs/mcp/** (a quickstart, how it works, a guide
per area, and a reference generated from this server's own `tools/list`). Its
sister site documents the SDK: https://hub.awesomate.ai/docs/sdk/.

## 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

Every tool, with its inputs and whether it reads, changes or can delete, is in
the generated reference: https://hub.awesomate.ai/docs/mcp/reference/account/.
The docs build fails if a tool is missing from it, so it cannot fall behind.
Every response is stamped `account: <slug>` so a session talking to the wrong
account is impossible to miss.

## Security posture

- **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.

## 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 run typecheck
npm test                          # builds, then boot-smoke + resolution + skills + knowledge suites
node scripts/build-docs.mjs --check   # the docs checks (also in CI and the hub's web build)
```

A change to `src/` or `skill/` needs a new version and a `skill/CHANGELOG.json`
entry at the top, and a new tool needs a place in `docs/reference.json` and,
where it changes what someone can ask for, a line in the right guide under `docs/`.

`test/tools-list.snapshot.json` is what the built server's `tools/list`, resource
list and prompt list return, byte for byte (each sorted by name), and `npm test`
fails when it differs. A change meant to show (a new tool, a new argument, new
wording) refreshes it in the same PR with
`npm run build && node scripts/tools-list-snapshot.mjs --write`; a change that
only moves code must leave it as it is. The snapshot also records what the MCP SDK
adds to each tool, so a lockfile bump that changes it refreshes the snapshot too.

### Where a tool is registered

Tools are moving out of `src/index.ts` into a shared registry, one group at a
time, so the same tools can later serve Claude chat as well as this npx server
(remote-mcp plan, Part B). `src/tools/groups.json` names every tool's group and
the surfaces that offer it; a new tool needs a line there or `npm test` fails.

- A group that has moved lives in `src/tools/<group>.ts`, inside
  `register<Group>(r)`. Register through `r`: `r.registerTool`, `r.readTool`,
  `r.registerResource`, and `r.config()` for the account (never
  `requireConfig()`, which only index.ts has).
- A group that has not moved yet is still registered in `src/index.ts`.
- Titles, the annotation kinds and the result shapes (`TITLES`, `annotate`,
  `READ_ONLY`, `textResult`, `errorResult` and the rest) are in `src/tools/kit.ts`.
- `whoami`, `get_context`, `skill_update` and `design_system_package` stay in
  index.ts (group `host`): they read the credentials file and the installed
  skills, or write files on the user's machine, which only the npx server can.

A group moves with `node scripts/registry-slice.mjs --group <group>`, which
moves the code verbatim and checks it reads back byte for byte. Each move is
merged inside an announced hold on `src/index.ts`; `--check` proves the
committed move is exactly the script's output on fresh main.

Publishing is CI-only: any `mcp/**` change merged to main with a bumped
version publishes via `publish-mcp.yml`. Never `npm publish` by hand.