@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/`.

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