@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:

claude mcp add awesomate-hosting -- npx -y --package=@awesomate/hosting-mcp awesomate-hosting-mcp

Development

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 live in a shared registry, one file per group, so the same tools can 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.

• Each group except host lives in src/tools/<group>.ts (account, website, apps, automations, knowledge, contacts, help), 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).
• 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.
• The chat connector (Claude on claude.ai, ChatGPT) serves the tools whose surface includes chat, from src/chat.ts: the hub's api bundles it (npm run build:chat) and makes one server per request over the caller's own token. A host tool it offers (get_context) has its chat variant there. To put a tool in chat, add chat to its surface; test/chat.test.mjs checks the chat server lists exactly that set, read-only, with titles and no confirm argument.

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.

Read tools and change tools

A tool that both reads and writes is split in two (remote-mcp plan, steps 25 to 29), because Claude's directory refuses a tool that does both, and a read-only tool runs without a permission prompt. The read tool keeps the old name and is READ_ONLY ("Read your ..."); the writes move to <name>_change, MUTATING ("Change your ..."). Each half's action is splitActions(own, moved, otherTool) from src/tools/kit.ts, so an action sent to the wrong half is refused with a sentence naming the right tool, and each half needs its own TITLES, groups.json, TOOL_SCOPE and TOOL_FEATURE entry.

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