@awesomate/hosting-mcp 0.1.0

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@awesomate/hosting-mcp",
+  "version": "0.1.0",
+  "description": "Awesomate Hosting MCP server — lets Claude manage your Awesomate WordPress hosting, plan, and limits",
+  "license": "UNLICENSED",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "awesomate-hosting-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "skill",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "esbuild src/index.ts --bundle --platform=node --target=node18 --format=esm --outfile=dist/index.js --banner:js='#!/usr/bin/env node' --external:node:*",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run typecheck && npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.3",
+    "esbuild": "^0.25.0",
+    "typescript": "^6.0.3"
+  }
+}

package/skill/awesomate-hosting/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: awesomate-hosting
+description: >
+  Manage, build, and grow your Awesomate WordPress hosting from Claude. Use when
+  the user mentions their Awesomate site or hosting, cPanel, a site on
+  *.awesomate.io or a custom domain hosted with Awesomate, WordPress admin,
+  installing a plugin/theme, running WP-CLI, "my site is slow / out of space /
+  broke", snapshotting or rolling back a site, deploying from a local WordPress
+  Studio site to live, checking hosting stats or how close they are to a plan
+  limit, workflow or AI-editor credits, or upgrading/downgrading their Awesomate
+  plan. Trigger phrases: "my awesomate site", "connect my hosting", "spin up a
+  wordpress site", "install wordpress", "add my domain", "why is my site slow",
+  "am I near my limit", "snapshot my site", "roll back my site", "deploy to
+  live", "run wp-cli", "upgrade my plan", "how many sites can I have".
+---
+
+# Awesomate Hosting
+
+You are helping the user run their **Awesomate-hosted WordPress** through the
+**Awesomate Hosting MCP** (tools prefixed `awesomate_`). This skill is the thin
+hosting/account/deploy/plan layer — for WordPress theming, blocks, and content
+generation, defer to WordPress Studio and any installed WordPress skills
+(`WordPress/agent-skills`, respira). Don't reimplement those.
+
+## 0. First run — orient before acting
+
+On the first hosting request in a session, call **`awesomate_get_context`** once
+(then `awesomate_get_limits` if you're about to create/change anything). From the
+context note three things and cache them for the session:
+
+- **`plan`** and **`capabilities.shell`** — this decides which branch below you're on.
+- **`patExpiresAt`** — if it's within ~7 days, tell the user to open
+  **hub.awesomate.ai/sites → Connect Claude Code** and re-run the setup prompt to
+  refresh the token. If any tool returns a 401, do the same.
+- **`cpanel`** routing (host/user), present once hosting is provisioned.
+
+If `awesomate_get_context` fails with a connectivity error, it's the user's
+network or the API base — not an auth problem; say so.
+
+## 1. The plan model (so your nudges are accurate)
+
+| Plan | WP sites | Custom domains | Shell / Claude Code | Notes |
+|---|---|---|---|---|
+| **Essentials** | 1 | 0 | **No** | read/status + upgrade nudges only |
+| **Support Plus** | (per plan) | ≥1 | **Yes** | shell, WP-CLI, snapshot/rollback, deploy |
+| **Pro** | more | more | **Yes** | + higher limits |
+| **Embedded** | ∞ | ∞ | **Yes** | agency tier |
+
+Authoritative limits are always what `awesomate_get_limits` returns for THIS
+account — never quote the table above as fact; use it only to explain upgrades.
+
+## 2. Branch by capability
+
+### Essentials (no shell) — read, report, nudge
+
+Allowed: `awesomate_get_context`, `_get_hosting_status`, `_get_hosting_account`,
+`_list_sites`, `_list_domains`, `_get_limits`, `_get_plan` / `_get_plan_features`,
+`_get_hosting_stats`, `_get_grafana_url`, `_get_credit_balance`, the billing
+preview/deep-link tools, and 1-click WP-admin / cPanel SSO links.
+
+Never attempt SSH, WP-CLI, snapshot/rollback, deploy, multi-site, or custom
+domains — those tools will 403. Instead, surface the specific limit and what
+Support Plus/Pro unlocks (see §4), and offer to preview the upgrade.
+
+### Support Plus and above (shell) — full workflow
+
+You additionally have: jailed SSH to the client's own cPanel account, WP-CLI
+(`awesomate_run_wp_cli` or raw SSH via `scripts/ssh-connect.sh`),
+snapshot/rollback, and the local-first deploy flow (§5). Golden rule, always:
+
+> **Local first, live never — and snapshot before you touch live.**
+
+## 3. Safety rules (non-negotiable)
+
+- **Before ANY change to a live site** — plugin/theme/core update, `search-replace`,
+  bulk edit, deploy — call **`awesomate_snapshot_site`** first and tell the user the
+  `snapshotId`. If it goes wrong, `awesomate_rollback_site` restores files + DB.
+- **Confirm before destructive actions**: `awesomate_uninstall_site`,
+  `awesomate_rollback_site`, dropping tables, `wp db reset`, deleting content.
+  State exactly what will be lost and wait for an explicit "yes".
+- Prefer building/testing in **WordPress Studio locally**, then deploy (§5).
+- Dry-run risky WP-CLI where the command supports it before the real run.
+
+## 4. Limits & upgrade etiquette
+
+Before any create action (install a site, add a domain, a heavy build) call
+`awesomate_get_limits`. If a dimension is `approaching`/`exceeded`, or a tool
+returns 403 for a plan reason:
+
+1. Explain plainly what they've hit and what the next plan unlocks (use the
+   nudge's `recommendedPlan`).
+2. If they want to upgrade, **preview first** with the billing preview tool and
+   show the exact prorated cost.
+3. Only proceed to an execute/upgrade tool after an explicit in-chat "yes".
+   **Never** trigger a charge, downgrade, or cancellation on your own —
+   downgrades/cancels always go to the hub billing page via the deep-link tool.
+
+## 5. Local-first deploy (Support Plus+)
+
+The build happens in **WordPress Studio** on the user's machine; going live,
+today, is a guided manual flow (a one-command `deploy.sh` is the next increment):
+
+1. **Snapshot the live site first** — `awesomate_snapshot_site`. Never skip this.
+2. Push the local Studio site to live over the jailed SSH:
+   - Files: `rsync` the Studio site's `wp-content` (and any changed root files)
+     to the live docroot via `scripts/ssh-connect.sh`.
+   - Database: export the Studio DB, import it live, then
+     `wp.sh <live-docroot> search-replace <studio-url> <live-url> --all-tables`.
+3. Verify the live site loads. If anything's wrong,
+   `awesomate_rollback_site` to the snapshot from step 1 (the current state was
+   also auto-snapshotted, so the rollback is itself reversible).
+
+To start FROM an existing live site, pull it down: snapshot, then `rsync` the
+docroot + `wp db export` down into a new Studio site.
+
+Because deploy overwrites a live site, always snapshot first and verify before
+telling the user it's done.
+
+## 6. Bundled scripts (`scripts/`)
+
+- `bootstrap.mjs` — one-time setup: redeems the hub setup code for a scoped
+  access token, stores it locally (chmod 600), generates an SSH keypair and
+  registers the public key (Support Plus+), and registers the MCP server. The
+  Connect-Claude-Code prompt from the hub runs this.
+- `ssh-connect.sh` — open a jailed SSH session (or run one remote command).
+- `wp.sh` — run a WP-CLI command against a live site over that SSH.
+
+A one-command `deploy.sh` / `pull-live.sh` (Studio↔live) is the next increment;
+until then use the guided flow in §5. All scripts read
+`~/.awesomate/credentials.json`; none take secrets on the command line.

package/skill/awesomate-hosting/scripts/bootstrap.mjs

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+/**
+ * Awesomate Hosting — one-time bootstrap.
+ *
+ * Redeems the single-use setup code from the hub's "Connect Claude Code" prompt
+ * for a durable, scoped access token; stores it locally; and (on Support Plus+)
+ * generates an SSH keypair and authorizes the PUBLIC key on the client's own
+ * cPanel account. The private key never leaves this machine; the setup code is
+ * the only secret that ever crossed the clipboard, and it's single-use + short-
+ * lived.
+ *
+ * Usage (Claude runs this — the user doesn't touch a terminal):
+ *   node bootstrap.mjs --code amt_bs_XXXX [--api https://hub.awesomate.ai]
+ *
+ * Dependency-free: Node 18+ built-ins only (global fetch, node:fs/os/path,
+ * child_process for ssh-keygen).
+ */
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, writeFileSync, chmodSync, readFileSync } from 'node:fs';
+import { homedir, hostname } from 'node:os';
+import { join } from 'node:path';
+
+function arg(name, fallback) {
+  const i = process.argv.indexOf(`--${name}`);
+  return i >= 0 && process.argv[i + 1] ? process.argv[i + 1] : fallback;
+}
+
+const code = arg('code');
+const apiBase = (arg('api', 'https://hub.awesomate.ai')).replace(/\/$/, '');
+if (!code || !code.startsWith('amt_bs_')) {
+  console.error('Missing/invalid --code. Copy a fresh setup prompt from hub.awesomate.ai/sites.');
+  process.exit(1);
+}
+
+const dir = join(homedir(), '.awesomate');
+const keysDir = join(dir, 'keys');
+const credPath = join(dir, 'credentials.json');
+const keyPath = join(keysDir, 'id_ed25519');
+
+async function post(path, { body, token } = {}) {
+  const headers = { 'Content-Type': 'application/json' };
+  if (token) headers.Authorization = `Bearer ${token}`;
+  const res = await fetch(`${apiBase}${path}`, { method: 'POST', headers, body: JSON.stringify(body ?? {}) });
+  const text = await res.text();
+  let json;
+  try { json = text ? JSON.parse(text) : null; } catch { json = text; }
+  if (!res.ok) {
+    const msg = json && typeof json === 'object' && json.error ? json.error : `HTTP ${res.status}`;
+    throw new Error(`${path} failed: ${msg}`);
+  }
+  return json;
+}
+
+function writeCreds(creds) {
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  chmodSync(dir, 0o700);
+  writeFileSync(credPath, JSON.stringify(creds, null, 2));
+  chmodSync(credPath, 0o600);
+}
+
+async function main() {
+  console.log(`Redeeming setup code against ${apiBase} …`);
+  const redeemed = await post('/api/hosting-access/redeem', {
+    body: { code, machineLabel: `Claude Code on ${hostname()}` },
+  });
+
+  const creds = {
+    apiBase,
+    pat: redeemed.pat,
+    contactId: redeemed.contactId,
+    slug: redeemed.slug ?? null,
+    plan: redeemed.plan,
+    cpanel: redeemed.cpanel ?? null,
+    expiresAt: redeemed.expiresAt ?? null,
+  };
+  writeCreds(creds);
+  console.log(`✓ Access token stored at ${credPath} (chmod 600). Plan: ${redeemed.plan}.`);
+
+  if (redeemed.shellAccess) {
+    if (!existsSync(keyPath)) {
+      mkdirSync(keysDir, { recursive: true, mode: 0o700 });
+      execFileSync('ssh-keygen', ['-t', 'ed25519', '-f', keyPath, '-N', '', '-C', `awesomate:${redeemed.slug ?? 'site'}`], { stdio: 'ignore' });
+      chmodSync(keyPath, 0o600);
+    }
+    const publicKey = readFileSync(`${keyPath}.pub`, 'utf8').trim();
+    const reg = await post('/api/hosting-access/ssh-keys', {
+      token: redeemed.pat,
+      body: { publicKey, label: `Claude Code on ${hostname()}` },
+    });
+    creds.ssh = { host: reg.sshHost, user: reg.sshUser, port: reg.sshPort ?? 22, keyPath, fingerprint: reg.fingerprint };
+    writeCreds(creds);
+    console.log(`✓ SSH key authorized on ${reg.sshUser}@${reg.sshHost} (jailed to your account).`);
+  } else {
+    console.log('• Plan has no shell access — read/status mode. Upgrade to Support Plus for SSH + deploy.');
+  }
+
+  // Register the MCP server. Prefer the Claude CLI if present; otherwise print
+  // the config for Claude to apply.
+  const env = `AWESOMATE_PAT=${redeemed.pat} AWESOMATE_API_BASE=${apiBase}`;
+  const cmd = `claude mcp add awesomate-hosting --env AWESOMATE_PAT=${redeemed.pat} --env AWESOMATE_API_BASE=${apiBase} -- npx -y @awesomate/hosting-mcp`;
+  let registered = false;
+  try {
+    execFileSync('claude', ['mcp', 'add', 'awesomate-hosting', '--env', `AWESOMATE_PAT=${redeemed.pat}`, '--env', `AWESOMATE_API_BASE=${apiBase}`, '--', 'npx', '-y', '@awesomate/hosting-mcp'], { stdio: 'ignore' });
+    registered = true;
+    console.log('✓ Registered the Awesomate Hosting MCP server with Claude Code.');
+  } catch {
+    console.log('\nAdd the Awesomate Hosting MCP server to this project — run:');
+    console.log(`  ${cmd}`);
+    console.log('…or add to .mcp.json:');
+    console.log(JSON.stringify({ mcpServers: { 'awesomate-hosting': { command: 'npx', args: ['-y', '@awesomate/hosting-mcp'], env: { AWESOMATE_PAT: redeemed.pat, AWESOMATE_API_BASE: apiBase } } } }, null, 2));
+  }
+
+  console.log('\nSetup complete. Next: ask me to read your plan, list your sites, and tell you what we can do.');
+  if (!registered) console.log('(Restart Claude Code first so it picks up the new MCP server.)');
+}
+
+main().catch((err) => {
+  console.error('Bootstrap failed:', err.message);
+  console.error('If the code expired or was already used, grab a fresh one from hub.awesomate.ai/sites.');
+  process.exit(1);
+});

package/skill/awesomate-hosting/scripts/ssh-connect.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# Open a jailed SSH session to the client's own cPanel account, using the key
+# provisioned by bootstrap.mjs. Any extra args are run as a remote command
+# (non-interactive); with none, opens an interactive shell.
+#   ssh-connect.sh                 # interactive shell
+#   ssh-connect.sh 'wp --info'     # one-off command
+set -euo pipefail
+CRED="$HOME/.awesomate/credentials.json"
+[ -f "$CRED" ] || { echo "Not connected. Run bootstrap first (Connect Claude Code on hub.awesomate.ai/sites)."; exit 1; }
+
+# Parse the ssh block with node (present wherever the MCP runs via npx).
+eval "$(node -e '
+const c = require(process.env.HOME + "/.awesomate/credentials.json");
+if (!c.ssh) { console.error("Your plan does not include shell access (Support Plus+ required)."); process.exit(2); }
+const q = (s) => "'"'"'" + String(s).replace(/'"'"'/g, "") + "'"'"'";
+console.log(`H=${q(c.ssh.host)}; U=${q(c.ssh.user)}; P=${q(c.ssh.port||22)}; K=${q(c.ssh.keyPath)}`);
+')"
+
+exec ssh -i "$K" -p "$P" -o StrictHostKeyChecking=accept-new "$U@$H" "$@"

package/skill/awesomate-hosting/scripts/wp.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+# Run a WP-CLI command on the live site over the jailed SSH connection.
+# Pass the WordPress path for the target site and the wp args.
+#   wp.sh /home/<user>/public_html plugin list
+#   wp.sh /home/<user>/public_html option get siteurl
+# (Or use the awesomate_run_wp_cli MCP tool, which is audited server-side.)
+set -euo pipefail
+here="$(cd "$(dirname "$0")" && pwd)"
+[ "$#" -ge 2 ] || { echo "Usage: wp.sh <wp-path> <wp args...>"; exit 1; }
+WP_PATH="$1"; shift
+# Delegate the connection to ssh-connect.sh; run wp in the given path.
+exec "$here/ssh-connect.sh" "wp --path=$(printf %q "$WP_PATH") $*"