@hostinger/mcp 3.2.2 → 3.3.1

package/skills/headless/connect/tools/codex.md

@@ -0,0 +1,48 @@
+---
+name: headless-connect-codex
+description: "Specific Codex Hostinger MCP Server connection instructions for the Hostinger Headless flow."
+---
+
+## Goals
+
+- Make Hostinger MCP tools and Skills available in Codex.
+- Don't provision hosting, create stores, install WordPress, or deploy by hand here — the skill does all of that. This entry stops at signed in and checking that Hostinger MCP and skills are reachable.
+
+## Step 1 — Make the connector callable (no restart needed)
+
+The later stages drive the Hostinger connector. If its Hostinger tools already respond in this
+session, use them and move on.
+
+If they don't, **don't rely on registering the server and restarting** — Codex loads MCP servers when
+it starts, and you can't restart it mid-run. The Hostinger MCP runs as a local **stdio** process and the
+bootstrap already signed you in, so talk to it directly for this run: spawn `npx -y @hostinger/mcp@latest`
+and speak newline-delimited JSON-RPC 2.0 over its stdin/stdout (`initialize` →
+`notifications/initialized` → `tools/call`). It reuses your cached sign-in automatically
+(`~/.config/hostinger-mcp/credentials.json`, or `HOSTINGER_API_TOKEN`) — no tokens to handle. It
+exposes `search`, `execute`, `multi-execute`; everything the stages need goes through `execute`, and a
+result is in `reply.result.content[0].text`. Write the little client yourself (~20 lines), keep one
+process alive for the whole run, and use it wherever a stage calls the connector.
+
+**To persist it for future Codex sessions** (optional), register the server with
+`codex mcp add hostinger -- npx -y @hostinger/mcp@latest`, or add it to `~/.codex/config.toml`, then
+restart Codex so it loads:
+
+```toml
+[mcp_servers.hostinger]
+command = "npx"
+args = ["-y", "@hostinger/mcp@latest"]
+```
+
+## Step 2 — Install the skills and hand off
+
+Download the Hostinger skills locally so your agent reads the files directly with no further network
+calls. The repo is **public**, so fetch just the skill folder over HTTPS — no git, no credentials (see
+`connect/tools/claude-code.md` for the full tarball command):
+
+```bash
+# macOS/Linux — downloads only skills/headless from the public repo
+curl -fsSL https://codeload.github.com/hostinger/api-mcp-server/tar.gz/refs/heads/main \
+  | tar -xz --strip-components=2 'api-mcp-server-main/skills/headless'
+```
+
+Then open `headless/SKILL.md` and follow its steps. That skill owns the rest of the run.

package/skills/headless/connect/tools/cursor.md

@@ -0,0 +1,109 @@
+---
+name: headless-connect-cursor
+description: "Specific Cursor Hostinger MCP Server connection instructions for the Hostinger Headless flow."
+---
+
+## Goals
+
+- Install (or reach) the Hostinger MCP in Cursor.
+- Sign the user in with OAuth 2.0 PKCE — the MCP opens a browser so they only need to log in.
+- Don't provision hosting, create stores, install WordPress, or deploy by hand here — the skill does all of that. This entry stops at signed in and checking that Hostinger MCP and skills are reachable.
+
+## Step 1 — Install / reach Hostinger MCP
+
+**Prerequisite:** Node.js 20 or newer on `PATH` (`node -v`). The published package engines require `>=20`; use Node 24 if you follow the package README.
+
+The Hostinger MCP is the npm package `@hostinger/mcp`. You do **not** need a global install — Cursor (and this session) can run it through `npx`. Prefer the unified binary `hostinger-api-mcp` (every operation). Scoped binaries such as `hostinger-hosting-mcp` are optional.
+
+### Option A — no global install (recommended)
+
+```bash
+# Verify the package/binary is reachable
+npx --yes --package=@hostinger/mcp@latest hostinger-api-mcp --version
+```
+
+### Option B — global install
+
+```bash
+npm install -g @hostinger/mcp
+# or: yarn global add @hostinger/mcp
+# or: pnpm add -g @hostinger/mcp
+
+hostinger-api-mcp --version
+```
+
+### Persist for future Cursor sessions (optional)
+
+Register the server in `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global), then fully quit and reopen Cursor once so it loads. **Do not** put `HOSTINGER_API_TOKEN` in this file when you want OAuth — leave the token unset so stdio OAuth can run:
+
+```json
+{
+  "mcpServers": {
+    "hostinger": {
+      "command": "npx",
+      "args": ["--yes", "--package=@hostinger/mcp@latest", "hostinger-api-mcp"]
+    }
+  }
+}
+```
+
+If Hostinger MCP tools are already in this session (`mcp__hostinger__*` / `mcp__hostinger-*__*`), skip ahead to Step 2 only if you still need sign-in; otherwise go to Step 3.
+
+## Step 2 — Authenticate with OAuth (browser opens)
+
+Prefer OAuth for interactive Cursor use. OAuth works only in **stdio** mode (Cursor's default for this local server). Skip this step if `HOSTINGER_API_TOKEN` is already set in the environment (that bypasses OAuth entirely).
+
+If the connect bootstrap already emitted `logged_in` / `success`, credentials are already on disk — continue to Step 3.
+
+Otherwise run the login command. It registers a dynamic OAuth client (once per machine), **opens the user's browser** to Hostinger's authorization page, listens on a localhost callback, stores tokens, and exits:
+
+```bash
+npx --yes --package=@hostinger/mcp@latest hostinger-api-mcp --login
+```
+
+(With a global install: `hostinger-api-mcp --login`.)
+
+What to tell the user:
+
+1. A browser window should open automatically for Hostinger sign-in.
+2. If it does not, the process prints `[OAuth] Opening browser for sign-in:` plus the URL on stderr — show that URL and ask them to open it on **this same machine** (the callback is `http://127.0.0.1:<ephemeral-port>/oauth/callback`).
+3. Wait until the command prints that sign-in succeeded and exits 0.
+
+Credentials are stored and reused automatically:
+
+- macOS / Linux: `~/.config/hostinger-mcp/credentials.json` (mode 0600)
+- Windows: `%APPDATA%\hostinger-mcp\credentials.json`
+
+They are shared across every Hostinger MCP binary. Expired access tokens refresh on their own; a revoked refresh token re-triggers the browser flow.
+
+To sign out later:
+
+```bash
+npx --yes --package=@hostinger/mcp@latest hostinger-api-mcp --logout
+```
+
+**API token (optional, CI / scripts):** set `HOSTINGER_API_TOKEN` in the environment before launching Cursor. When present it always wins and no OAuth code runs. Do not commit the token.
+
+## Step 3 — Use the connector in this run (no Cursor restart)
+
+Cursor only loads registered MCP servers when the editor starts, so a mid-run `.cursor/mcp.json` change will not attach tools to **this** session. For the rest of this run, talk to the local stdio server directly: spawn
+
+```bash
+npx --yes --package=@hostinger/mcp@latest hostinger-api-mcp
+```
+
+and speak newline-delimited JSON-RPC 2.0 over its stdin/stdout (`initialize` → `notifications/initialized` → `tools/call`). It reuses the cached sign-in from Step 2 (or `HOSTINGER_API_TOKEN`) — no tokens to handle in chat. It exposes `search`, `execute`, and `multi-execute`; everything the stages need goes through `execute`, and a result is in `reply.result.content[0].text`. Keep one process alive for the whole run.
+
+## Step 4 — Install the skills and hand off
+
+Download the Hostinger skills locally so your agent reads the files directly with no further network
+calls. The repo is **public**, so fetch just the skill folder over HTTPS — no git, no credentials (see
+`connect/tools/claude-code.md` for the full tarball command):
+
+```bash
+# macOS/Linux — downloads only skills/headless from the public repo
+curl -fsSL https://codeload.github.com/hostinger/api-mcp-server/tar.gz/refs/heads/main \
+  | tar -xz --strip-components=2 'api-mcp-server-main/skills/headless'
+```
+
+Then open `headless/SKILL.md` and follow its steps. That skill owns the rest of the run.

package/skills/headless/connect/tools/devin.md

@@ -0,0 +1,50 @@
+---
+name: headless-connect-devin
+description: "Specific Devin Hostinger MCP Server connection instructions for the Hostinger Headless flow."
+---
+
+## Goals
+
+- Make Hostinger MCP tools and Skills available in Devin.
+- Don't provision hosting, create stores, install WordPress, or deploy by hand here — the skill does all of that. This entry stops at signed in and checking that Hostinger MCP and skills are reachable.
+
+## Step 1 — Make the connector callable
+
+The later stages drive the Hostinger connector. If its Hostinger tools already respond in this
+session, use them and move on.
+
+If they don't, register the Hostinger MCP server for Devin. The local MCP runs as a **stdio** process
+and the bootstrap already signed you in, so it reuses your cached sign-in automatically
+(`~/.config/hostinger-mcp/credentials.json`, or `HOSTINGER_API_TOKEN`) — no tokens to handle.
+
+- **Devin CLI:** `devin mcp add hostinger -- npx -y @hostinger/mcp@latest`
+- **Devin app:** Settings → MCP Marketplace → **Add Your Own**, transport **STDIO**, with:
+
+  ```json
+  {
+    "command": "npx",
+    "args": ["-y", "@hostinger/mcp@latest"]
+  }
+  ```
+
+On Devin Desktop, fully quit and reopen the app once after adding the server so it loads.
+
+If you can't reach the registered server from this run, drive `npx -y @hostinger/mcp@latest` directly
+over stdio instead: spawn it and speak newline-delimited JSON-RPC 2.0 over its stdin/stdout
+(`initialize` → `notifications/initialized` → `tools/call`). It exposes `search`, `execute`,
+`multi-execute`; everything the stages need goes through `execute`, and a result is in
+`reply.result.content[0].text`.
+
+## Step 2 — Install the skills and hand off
+
+Download the Hostinger skills locally so your agent reads the files directly with no further network
+calls. The repo is **public**, so fetch just the skill folder over HTTPS — no git, no credentials (see
+`connect/tools/claude-code.md` for the full tarball command):
+
+```bash
+# macOS/Linux — downloads only skills/headless from the public repo
+curl -fsSL https://codeload.github.com/hostinger/api-mcp-server/tar.gz/refs/heads/main \
+  | tar -xz --strip-components=2 'api-mcp-server-main/skills/headless'
+```
+
+Then open `headless/SKILL.md` and follow its steps. That skill owns the rest of the run.

package/skills/headless/connect/tools/vscode.md

@@ -0,0 +1,57 @@
+---
+name: headless-connect-vscode
+description: "Specific VS Code Hostinger MCP Server connection instructions for the Hostinger Headless flow."
+---
+
+## Goals
+
+- Make Hostinger MCP tools and Skills available in VS Code (GitHub Copilot / agent mode).
+- Don't provision hosting, create stores, install WordPress, or deploy by hand here — the skill does all of that. This entry stops at signed in and checking that Hostinger MCP and skills are reachable.
+
+## Step 1 — Make the connector callable
+
+The later stages drive the Hostinger connector. If its Hostinger tools already respond in this
+session, use them and move on.
+
+If they don't, register the Hostinger MCP server for VS Code. The local MCP runs as a **stdio**
+process and the bootstrap already signed you in, so it reuses your cached sign-in automatically
+(`~/.config/hostinger-mcp/credentials.json`, or `HOSTINGER_API_TOKEN`) — no tokens to handle. Add it to
+`.vscode/mcp.json` (workspace) or your user `settings.json` under `mcp`:
+
+```json
+// .vscode/mcp.json
+{
+  "servers": {
+    "hostinger": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@hostinger/mcp@latest"]
+    }
+  }
+}
+```
+
+Or add it in one command: `code --add-mcp '{"name":"hostinger","command":"npx","args":["-y","@hostinger/mcp@latest"]}'`.
+VS Code picks up the server and its tools become available immediately — no editor restart needed.
+(Alternatively, the official Hostinger Connector extension installs the same server:
+`code --install-extension hostinger-official.hostinger-connector`.)
+
+If you can't reach the registered server from this run, drive `npx -y @hostinger/mcp@latest` directly
+over stdio instead: spawn it and speak newline-delimited JSON-RPC 2.0 over its stdin/stdout
+(`initialize` → `notifications/initialized` → `tools/call`). It exposes `search`, `execute`,
+`multi-execute`; everything the stages need goes through `execute`, and a result is in
+`reply.result.content[0].text`.
+
+## Step 2 — Install the skills and hand off
+
+Download the Hostinger skills locally so your agent reads the files directly with no further network
+calls. The repo is **public**, so fetch just the skill folder over HTTPS — no git, no credentials (see
+`connect/tools/claude-code.md` for the full tarball command):
+
+```bash
+# macOS/Linux — downloads only skills/headless from the public repo
+curl -fsSL https://codeload.github.com/hostinger/api-mcp-server/tar.gz/refs/heads/main \
+  | tar -xz --strip-components=2 'api-mcp-server-main/skills/headless'
+```
+
+Then open `headless/SKILL.md` and follow its steps. That skill owns the rest of the run.

package/skills/headless/report.schema.json

@@ -0,0 +1,149 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Hostinger Headless build report",
+  "description": "Written by run-log.mjs at the end of every run (including early stops) to ~/.hostinger/<domain>/reports/<run>.json.",
+  "type": "object",
+  "required": ["schema_version", "generated_at", "consent", "run", "info", "timing", "tokens", "issues", "user_feedback", "skill_gaps", "what_went_well", "previous_runs"],
+  "properties": {
+    "schema_version": { "type": "string", "enum": ["1"] },
+    "generated_at": { "type": "string" },
+    "consent": {
+      "type": "object",
+      "required": ["sent"],
+      "properties": { "sent": { "type": "boolean" }, "note": { "type": "string" } }
+    },
+    "run": {
+      "type": "object",
+      "required": ["id", "kind"],
+      "properties": {
+        "id": { "type": "string" },
+        "kind": { "type": "string", "enum": ["build", "resume", "redesign", "iterate"] },
+        "skill": { "type": ["string", "null"] },
+        "follow_ups": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["resumed_at"],
+            "properties": { "resumed_at": { "type": "string" }, "after_report_at": { "type": ["string", "null"] }, "reason": { "type": ["string", "null"] } }
+          }
+        }
+      }
+    },
+    "info": {
+      "type": "object",
+      "required": ["domain", "tool", "outcome"],
+      "properties": {
+        "domain": { "type": "string" },
+        "tool": { "type": ["string", "null"] },
+        "model": { "type": ["string", "null"] },
+        "os": { "type": "string" },
+        "node": { "type": "string" },
+        "mcp": { "type": ["string", "null"] },
+        "backend": { "type": ["string", "null"] },
+        "frontend": { "type": ["string", "null"] },
+        "outcome": { "type": "string", "enum": ["live", "stopped", "failed", "abandoned"] },
+        "stopped_at": { "type": ["string", "null"] },
+        "live_url": { "type": ["string", "null"] },
+        "admin_url": { "type": ["string", "null"] }
+      }
+    },
+    "timing": {
+      "type": "object",
+      "required": ["started_at", "ended_at", "minutes_total", "stages"],
+      "properties": {
+        "started_at": { "type": "string" },
+        "ended_at": { "type": "string" },
+        "live_at": { "type": ["string", "null"] },
+        "minutes_total": { "type": ["number", "null"] },
+        "minutes_to_live": { "type": ["number", "null"] },
+        "stages": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["stage", "started_at", "ended_at", "result"],
+            "properties": {
+              "stage": { "type": "string", "enum": ["connect", "check_state", "refine", "provision", "content_model", "design", "frontend", "validate", "deploy", "done"] },
+              "phase": { "type": ["string", "null"] },
+              "started_at": { "type": "string" },
+              "ended_at": { "type": ["string", "null"] },
+              "result": { "type": ["string", "null"], "enum": ["ok", "ok_after_retries", "ok_with_fixups", "failed", "skipped", "stopped", null] },
+              "note": { "type": ["string", "null"] },
+              "minutes": { "type": ["number", "null"] },
+              "start_estimated": { "type": "boolean" }
+            }
+          }
+        }
+      }
+    },
+    "tokens": {
+      "description": "Only when the tool reports its own usage. Never read the user's transcripts to get it.",
+      "type": ["object", "null"],
+      "properties": {
+        "source": { "type": "string" },
+        "requests": { "type": "integer" },
+        "input": { "type": "integer" },
+        "output": { "type": "integer" },
+        "cache_read": { "type": "integer" },
+        "cache_write": { "type": "integer" },
+        "est_cost_usd": { "type": "number" }
+      }
+    },
+    "issues": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["stage", "symptom", "severity", "resolved", "user_had_to_intervene"],
+        "properties": {
+          "stage": { "type": "string" },
+          "symptom": { "type": "string" },
+          "cause": { "type": "string" },
+          "workaround": { "type": "string" },
+          "severity": { "type": "string", "enum": ["high", "medium", "low"] },
+          "resolved": { "type": "boolean" },
+          "user_had_to_intervene": { "type": "boolean" },
+          "logged_at": { "type": "string" }
+        }
+      }
+    },
+    "user_feedback": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["stage", "category", "paraphrase"],
+        "properties": { "stage": { "type": "string" }, "category": { "type": "string" }, "paraphrase": { "type": "string" }, "logged_at": { "type": "string" } }
+      }
+    },
+    "skill_gaps": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["skill", "gap"],
+        "properties": { "skill": { "type": "string" }, "gap": { "type": "string" }, "stage": { "type": "string" }, "logged_at": { "type": "string" } }
+      }
+    },
+    "what_went_well": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["text"],
+        "properties": { "text": { "type": "string" }, "stage": { "type": "string" }, "logged_at": { "type": "string" } }
+      }
+    },
+    "logging_gaps": {
+      "description": "Where the run log is missing or unsure: unfinished stages, estimated starts, zero-length entries, stages never logged on a live build.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["stage", "problem"],
+        "properties": { "stage": { "type": "string" }, "phase": { "type": ["string", "null"] }, "problem": { "type": "string" } }
+      }
+    },
+    "previous_runs": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": { "run": { "type": ["string", "null"] }, "kind": { "type": ["string", "null"] }, "outcome": { "type": ["string", "null"] }, "minutes": { "type": ["number", "null"] }, "html": { "type": "string" } }
+      }
+    }
+  }
+}