hostinger-api-mcp 1.63.4 → 2.0.0

package/CHANGELOG.md

@@ -4,6 +4,16 @@ Generated at release time from the diff between the previous and current
 build. Tool changes are listed individually; everything else is summarised
 by area.
 
+## v2.0.0 — 2026-09-28
+
+### Also in this release
+
+- Documentation: `README.md`
+- Dependencies: `package-lock.json`
+- Bundled agent skills: 6 files
+- Server instructions: `src/core/instructions.js`, `src/core/instructions.ts`
+- Request handling and authentication: 4 files
+
 ## v1.63.4 — 2026-09-25
 
 ### Tools

package/README.md

@@ -16,7 +16,7 @@ https://mcp.hostinger.com
 claude mcp add --transport http hostinger https://mcp.hostinger.com
 ```
 
-This opens a browser window to authorize via OAuth. Once approved, all tools below are available in your session.
+This opens a browser window to authorize via OAuth. Once approved, the operations below are reachable through `execute` in your session.
 
 ### Other MCP-compatible clients
 
@@ -69,20 +69,20 @@ pnpm update -g @hostinger/mcp
 
 This package installs the following MCP server commands:
 
-- `hostinger-api-mcp` — unified server with every tool (401 total)
-- `hostinger-agency-hosting-mcp` — 42 tools for agency-hosting
-- `hostinger-billing-mcp` — 9 tools for billing
-- `hostinger-dns-mcp` — 8 tools for dns
-- `hostinger-domains-mcp` — 41 tools for domains
-- `hostinger-ecommerce-mcp` — 29 tools for ecommerce
-- `hostinger-horizons-mcp` — 6 tools for horizons
-- `hostinger-hosting-mcp` — 74 tools for hosting
-- `hostinger-mail-mcp` — 38 tools for mail
-- `hostinger-reach-mcp` — 52 tools for reach
-- `hostinger-vps-mcp` — 64 tools for vps
-- `hostinger-wordpress-mcp` — 38 tools for wordpress
-
-Pick the binary that matches your agent's scope. `hostinger-api-mcp` remains the backwards-compatible default.
+- `hostinger-api-mcp` — unified server over every operation (401 total)
+- `hostinger-agency-hosting-mcp` — 42 operations for agency-hosting
+- `hostinger-billing-mcp` — 9 operations for billing
+- `hostinger-dns-mcp` — 8 operations for dns
+- `hostinger-domains-mcp` — 41 operations for domains
+- `hostinger-ecommerce-mcp` — 29 operations for ecommerce
+- `hostinger-horizons-mcp` — 6 operations for horizons
+- `hostinger-hosting-mcp` — 74 operations for hosting
+- `hostinger-mail-mcp` — 38 operations for mail
+- `hostinger-reach-mcp` — 52 operations for reach
+- `hostinger-vps-mcp` — 64 operations for vps
+- `hostinger-wordpress-mcp` — 38 operations for wordpress
+
+Every binary exposes the same three tools; a scoped binary only searches and executes its own group's operations. `hostinger-api-mcp` remains the backwards-compatible default.
 
 ## Configuration
 
@@ -210,17 +210,25 @@ await client.connect(transport);
 const { tools } = await client.listTools();
 console.log("Available tools:", tools);
 
-// Call a tool
+// Execute an operation
 const result = await client.callTool({
-  name: "billing_getCatalogItemListV1",
-  arguments: { category: "DOMAIN" }
+  name: "execute",
+  arguments: { operation: "billing_getCatalogItemListV1", params: { category: "DOMAIN" } }
 });
 console.log("Tool result:", result);
 ```
 
-## Available Tools
+## Tools
 
-This MCP server provides the following tools:
+Every server exposes three tools:
+
+- `search` — find operations by keyword; returns each match with its `inputSchema`.
+- `execute` — run one operation: `{ "operation": "<name>", "params": { ... } }`.
+- `multi-execute` — run up to 20 operations in order, stopping at the first failure. A params value that is exactly `"$steps.<i>.<path>"` is replaced by that value from an earlier step's result.
+
+## Operations
+
+The operations reachable through `execute`, by binary:
 
 ### `hostinger-agency-hosting-mcp`
 

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "hostinger-api-mcp",
-  "version": "1.63.4",
+  "version": "2.0.0",
   "description": "Hostinger API — manage domains, DNS, hosting, VPS, billing and more from Gemini CLI.",
   "mcpServers": {
     "hostinger": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hostinger-api-mcp",
-  "version": "1.63.4",
+  "version": "2.0.0",
   "mcpName": "io.github.hostinger/hostinger-api-mcp",
   "description": "MCP server for Hostinger API",
   "repository": {

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/hostinger/api-mcp-server",
     "source": "github"
   },
-  "version": "1.63.4",
+  "version": "2.0.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@hostinger/mcp",
-      "version": "1.63.4",
+      "version": "2.0.0",
       "transport": {
         "type": "stdio"
       },

package/skills/headless/SKILL.md

@@ -12,7 +12,7 @@ The frontend is built ad-hoc to the user's intent — there is no template libra
 ## Preconditions
 
 1. An authenticated Hostinger MCP session — the entry skill's bootstrap handled this. If MCP tools fail with auth errors, send the user back through `entry/skill.md`.
-2. The Hostinger MCP tools for **hosting** (plus **ecommerce** when the run involves a store, and **wordpress** when it involves a content backend). Tool availability varies per user — product groups can be toggled in the Hostinger Connector, and some clients cap the number of exposed tools. When a needed tool is missing, ask the user to enable that product group (or configure the scoped binary, e.g. `hostinger-hosting-mcp`) rather than improvising around it.
+2. The Hostinger MCP operations for **hosting** (plus **ecommerce** when the run involves a store, and **wordpress** when it involves a content backend). Operation availability varies per user — product groups can be toggled in the Hostinger Connector. When search cannot find a needed operation, ask the user to enable that product group (or configure the scoped binary, e.g. `hostinger-hosting-mcp`) rather than improvising around it.
 3. An active hosting plan (checked in Setup §1). Hostinger hosting is a paid product: if the account has no usable plan, inform the user plainly that a subscription is required, link them to https://www.hostinger.com/web-hosting, and pause until they confirm the purchase. Do not treat this as an error — it is a normal step for new accounts. Everything that doesn't need hosting (planning, building the frontend locally) can proceed while they decide.
 
 ## Resolving the operation
@@ -32,7 +32,7 @@ If signals conflict, ask the user — don't guess.
 3. **Store** (`references/STORE.md`, only when commerce is needed) — resolve or create the store and its `custom` sales channel, seed products/shipping/payment, and note the `sales_channel_id` for the frontend.
 4. **Content backend** (`references/WORDPRESS.md`, only when owner-managed content is needed) — install WordPress on a dedicated subdomain, wait until it's ready, and hand the owner a wp-admin login link. The frontend reads it through the public WP REST API.
 5. **Build** — create or wire the frontend. For store runs, follow the frontend contract in `references/STORE.md` (catalog fetched at runtime from the public Storefront API, cart in `localStorage`, client-side checkout — never embed an API token in the site). For content runs, follow the frontend contract in `references/WORDPRESS.md` (posts fetched at runtime from the WP REST API, rendered HTML bodies, graceful empty states). When the app needs MySQL, follow `references/DATABASE.md` (which host each runtime connects to, credentials via env vars or a server-side config file, never in the frontend).
-6. **Deploy** (`references/DEPLOYMENT.md`) — archive and deploy via the matching hosting tool, polling build logs for Node.js runs.
+6. **Deploy** (`references/DEPLOYMENT.md`) — archive and deploy via the matching hosting operation, polling build logs for Node.js runs.
 7. **Verify** — curl the live URL for a 200 and a piece of real page copy; for store runs, confirm a checkout POST returns a redirect URL; for content runs, confirm the WP REST API returns 200 and the frontend renders posts. Show the user the live URL and where to manage things (hPanel: https://hpanel.hostinger.com, the store dashboard for commerce, wp-admin for content).
 8. **Record** — write `.hostinger/site.json` into the project: `{ "domain", "username", "type": "static"|"nodejs", "sales_channel_id"?, "store_id"?, "cms_domain"? }`. This is what makes future runs resolve as `iterate`.
 
@@ -50,7 +50,7 @@ Run non-interactively wherever possible. The exceptions that must involve the us
 
 ## Where the how comes from
 
-The MCP tool descriptions are authoritative for request shapes — read them before calling. Two live sources supersede anything written here when they disagree:
+The inputSchema returned by search is authoritative for request shapes — read it before calling. Two live sources supersede anything written here when they disagree:
 
-- The ecommerce MCP tool `ecommerce_getCustomStorefrontSetupInstructionsV1` returns the current storefront integration guide from the server — call it at the start of any store run.
-- The Hostinger API reference at https://developers.hostinger.com describes every endpoint behind the tools.
+- The ecommerce operation `ecommerce_getCustomStorefrontSetupInstructionsV1` returns the current storefront integration guide from the server — execute it at the start of any store run.
+- The Hostinger API reference at https://developers.hostinger.com describes every endpoint behind the operations.

package/skills/headless/references/DATABASE.md

@@ -1,11 +1,11 @@
 # Database and runtime — MySQL hosts, env vars, and what to poll
 
-Use this when the app needs MySQL, or when a deploy "succeeded" but the app cannot reach its database. Everything here uses the **hosting** MCP tools; Agency Plan differences are at the end.
+Use this when the app needs MySQL, or when a deploy "succeeded" but the app cannot reach its database. Everything here uses the **hosting** MCP operations; Agency Plan differences are at the end.
 
 ## 1. Create the database
 
 1. `hosting_createAccountDatabaseV1` on the site's `username` with a database name, a user and a password you generate — name and user are prefixed with the account username automatically.
-2. Read the full, prefixed `name` and `user` back from `hosting_listAccountDatabasesV1`; every other database tool wants the full name.
+2. Read the full, prefixed `name` and `user` back from `hosting_listAccountDatabasesV1`; every other database operation wants the full name.
 3. Do not print the password to the user once it is stored, and never commit it.
 
 ## 2. Which host the app connects to

package/skills/headless/references/DEPLOYMENT.md

@@ -18,7 +18,7 @@ For anything that needs a server or a server-side build (Express, Next.js, NestJ
 - Hard cap: **50 MB** archive.
 - The upload starts a build. Track it with `hosting_listJsDeployments`; on failure pull `hosting_showJsDeploymentLogs`, fix, and redeploy. Poll with backoff — builds take minutes, not seconds.
 
-## WordPress → `hosting_importWordpressWebsite` / plugin & theme tools
+## WordPress → `hosting_importWordpressWebsite` / plugin & theme operations
 
 Only when the user explicitly wants a WordPress *site* migrated or themed. Site imports take an archive plus a `.sql` dump and can run for several minutes. (WordPress as a headless content backend behind an agent-built frontend is a different flow — that's `WORDPRESS.md`, installed fresh via the API, not imported here.)
 

package/skills/headless/references/SETUP.md

@@ -1,6 +1,6 @@
 # Setup — plan check and website provisioning
 
-Everything here uses the **hosting** MCP tools. If they're missing, ask the user to enable the Websites product group in the Hostinger Connector (or use the `hostinger-hosting-mcp` scoped binary).
+Everything here uses the **hosting** MCP operations. If they're missing, ask the user to enable the Websites product group in the Hostinger Connector (or use the `hostinger-hosting-mcp` scoped binary).
 
 ## 1. Plan check (gate — run this first)
 
@@ -24,11 +24,11 @@ Generating a subdomain does **not** create a website — deploying straight to i
 
 1. `hosting_createWebsiteV1 { domain, order_id }` — `datacenter_code` is required only for the first website on a brand-new plan (pick the first entry from `hosting_listAvailableDatacentersV1`).
 2. **Poll** `hosting_listWebsitesV1` filtered by the domain until the site appears. Creation takes up to a few minutes — poll with backoff, don't fail fast.
-3. Note the site's `username` — deployment and database tools are keyed on it.
+3. Note the site's `username` — deployment and database operations are keyed on it.
 
 If the domain already has a website (an `iterate` run, or the user pointed at an existing site), skip creation entirely.
 
 ## 4. Optional extras (only when the run needs them)
 
 - **Database:** when the app needs MySQL, follow `DATABASE.md` — creating it, which host each runtime connects to (Node.js must use `127.0.0.1`), and handing the credentials to the app without hard-coding them.
-- **DNS records:** the DNS tools (`DNS_updateDNSRecordsV1` etc.) for custom-domain records; take a snapshot (`DNS_getDNSSnapshotListV1` context) before destructive changes.
+- **DNS records:** the DNS operations (`DNS_updateDNSRecordsV1` etc.) for custom-domain records; take a snapshot (`DNS_getDNSSnapshotListV1` context) before destructive changes.

package/skills/headless/references/STORE.md

@@ -1,6 +1,6 @@
 # Store — Hostinger Ecommerce with a custom storefront
 
-**Primary source:** call `ecommerce_getCustomStorefrontSetupInstructionsV1` at the start of every store run — it returns the current, server-maintained integration guide, and it supersedes this file wherever they disagree. This file carries the essentials so the run can be planned before that call, and a fallback when the ecommerce tools aren't enabled.
+**Primary source:** execute `ecommerce_getCustomStorefrontSetupInstructionsV1` at the start of every store run — it returns the current, server-maintained integration guide, and it supersedes this file wherever they disagree. This file carries the essentials so the run can be planned before that call, and a fallback when the ecommerce operations aren't enabled.
 
 ## Mental model
 
@@ -21,7 +21,7 @@ Two API surfaces — don't mix them:
 2. For checkout to work the store needs all three: ≥ 1 product, ≥ 1 payment method, ≥ 1 shipping zone. Payment, shipping, and currency are store-level — check `ecommerce_getStoreMetadataV1` (`has_payment_methods` and `has_shipping` must be `true`; the same response carries `default_currency` with `code`, `decimal_digits`, `template` — read it here rather than guessing). Products are **per sales channel** — verify by listing products for the resolved channel on the Storefront API and confirming the list is non-empty. Seed what's missing with `ecommerce_createPhysicalProductV1` / `ecommerce_createDigitalProductV1`, `ecommerce_enableManualPaymentMethodV1`, and `ecommerce_setStoreShippingV1` (price `0` = free shipping) — confirming with the user before writing to a store that already has real data.
 3. After deploy, point the channel at the live site: `ecommerce_updateSalesChannelV1 { store_id, sales_channel_id, url }`.
 
-If the ecommerce tools aren't available, ask the user to enable the Ecommerce product group in the Hostinger Connector — or to provide the `sales_channel_id` directly, after which the public endpoints suffice for the frontend work.
+If the ecommerce operations aren't available, ask the user to enable the Ecommerce product group in the Hostinger Connector — or to provide the `sales_channel_id` directly, after which the public endpoints suffice for the frontend work.
 
 ## Frontend contract
 

package/skills/headless/references/WORDPRESS.md

@@ -4,7 +4,7 @@ Use WordPress when the site has **owner-managed content**: a blog, news, article
 
 **When NOT to use this:** static copy that rarely changes (an about page, a services list, a brochure site) — bake that into the frontend. Installing WordPress for content the owner will never edit adds a moving part for nothing. Any buy/sell intent is `STORE.md`, not this file.
 
-Everything in Setup uses the **hosting** and **wordpress** MCP tool groups; ask the user to enable them in the Hostinger Connector if tools are missing.
+Everything in Setup uses the **hosting** and **wordpress** MCP operation groups; ask the user to enable them in the Hostinger Connector if operations are missing.
 
 ## Mental model
 

package/src/core/catalog.js

@@ -0,0 +1,183 @@
+// Meta-tool logic for the consolidated MCP surface: search, execute and
+// multi-execute over a catalog of API operations. Pure functions only; the
+// runtime supplies the catalog and the function that performs a call.
+// Keep in sync with catalog.ts and with api-remote-mcp's PHP implementation.
+
+export const DEFAULT_SEARCH_LIMIT = 5;
+export const MAX_SEARCH_LIMIT = 20;
+export const MAX_STEPS = 20;
+
+const STEP_REF = /^\$steps\.(\d+)((?:\.[^.]+)*)$/;
+
+/** Bad input from the model: reported as an isError result, never a protocol error. */
+export class ToolInputError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ToolInputError';
+    }
+}
+
+const meta = (name, title, description, inputSchema, readOnly) => ({
+    name,
+    title,
+    description,
+    inputSchema,
+    annotations: { title, readOnlyHint: readOnly, destructiveHint: !readOnly },
+});
+
+export const META_TOOLS = [
+    meta('search', 'Search API operations',
+        "Find API operations by keyword. Returns the best matches, each with its operation name, hints and inputSchema. Pass a result's operation and params matching its inputSchema to execute or multi-execute.",
+        {
+            type: 'object',
+            properties: {
+                query: { type: 'string', description: 'Keywords, e.g. "list vps" or "dns records".' },
+                limit: { type: 'integer', minimum: 1, maximum: MAX_SEARCH_LIMIT, default: DEFAULT_SEARCH_LIMIT, description: 'Maximum number of results.' },
+            },
+            required: ['query'],
+        },
+        true),
+    meta('execute', 'Execute an API operation',
+        "Run one API operation found with search. params is a flat object holding the operation's path, query and body parameters as described by its inputSchema.",
+        {
+            type: 'object',
+            properties: {
+                operation: { type: 'string', description: 'Operation name returned by search.' },
+                params: { type: 'object', description: 'Parameters matching the operation inputSchema.' },
+            },
+            required: ['operation'],
+        },
+        false),
+    meta('multi-execute', 'Execute API operations in sequence',
+        'Run up to 20 API operations in order, stopping at the first failure. A params value that is exactly "$steps.<i>.<path>" is replaced by that value from the result of earlier step <i> (dot-separated keys; numbers index arrays), e.g. "$steps.0.0.id".',
+        {
+            type: 'object',
+            properties: {
+                steps: {
+                    type: 'array',
+                    minItems: 1,
+                    maxItems: MAX_STEPS,
+                    items: {
+                        type: 'object',
+                        properties: {
+                            operation: { type: 'string', description: 'Operation name returned by search.' },
+                            params: { type: 'object', description: 'Parameters; may contain "$steps.<i>.<path>" references.' },
+                        },
+                        required: ['operation'],
+                    },
+                },
+            },
+            required: ['steps'],
+        },
+        false),
+];
+
+const byteOrder = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+
+function toSummary(op) {
+    return {
+        operation: op.name,
+        title: op.title ?? op.name,
+        description: op.description ?? '',
+        group: op.group ?? null,
+        readOnly: op.annotations?.readOnlyHint === true,
+        destructive: op.annotations?.destructiveHint === true,
+        inputSchema: op.inputSchema,
+    };
+}
+
+export function searchOperations(operations, query, limit = DEFAULT_SEARCH_LIMIT) {
+    if (typeof query !== 'string') throw new ToolInputError('query must be a string');
+    const tokens = query.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+    if (tokens.length === 0) throw new ToolInputError('query must contain at least one letter or digit');
+    if (!Number.isInteger(limit) || limit < 1 || limit > MAX_SEARCH_LIMIT) {
+        throw new ToolInputError(`limit must be an integer from 1 to ${MAX_SEARCH_LIMIT}`);
+    }
+
+    return operations
+        .map(op => {
+            const name = op.name.toLowerCase();
+            const group = (op.group ?? '').toLowerCase();
+            const title = (op.title ?? '').toLowerCase();
+            const description = (op.description ?? '').toLowerCase();
+            let score = 0;
+            for (const t of tokens) {
+                if (name.includes(t)) score += 3;
+                if (group.includes(t)) score += 2;
+                if (title.includes(t)) score += 2;
+                if (description.includes(t)) score += 1;
+            }
+            return { op, score };
+        })
+        .filter(s => s.score > 0)
+        .sort((a, b) => b.score - a.score || byteOrder(a.op.name, b.op.name))
+        .slice(0, limit)
+        .map(s => toSummary(s.op));
+}
+
+export function renderSearch(query, results) {
+    return results.length > 0
+        ? JSON.stringify(results)
+        : `No operations matched "${query}". Try broader or different terms.`;
+}
+
+export function findOperation(operations, name, params) {
+    if (typeof name !== 'string' || !operations.has(name)) {
+        throw new ToolInputError(`Unknown operation "${name}". Use search to find operations.`);
+    }
+    if (params === null || typeof params !== 'object' || Array.isArray(params)) {
+        throw new ToolInputError('params must be an object');
+    }
+    const op = operations.get(name);
+    const missing = (op.inputSchema?.required ?? []).filter(k => params[k] === undefined || params[k] === null);
+    if (missing.length > 0) {
+        throw new ToolInputError(`Missing required parameter(s) for ${name}: ${missing.join(', ')}`);
+    }
+    return op;
+}
+
+export function resolveRefs(value, results, stepIndex) {
+    if (typeof value === 'string') {
+        const m = STEP_REF.exec(value);
+        if (!m) return value;
+        const i = Number(m[1]);
+        if (i >= stepIndex) {
+            throw new ToolInputError(`${value}: references must point to an earlier step`);
+        }
+        let current = results[i];
+        for (const segment of m[2].split('.').slice(1)) {
+            if (current === null || typeof current !== 'object' || !Object.hasOwn(current, segment)) {
+                throw new ToolInputError(`${value}: path not found in the result of step ${i}`);
+            }
+            current = current[segment];
+        }
+        return current;
+    }
+    if (Array.isArray(value)) return value.map(v => resolveRefs(v, results, stepIndex));
+    if (value !== null && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, resolveRefs(v, results, stepIndex)]));
+    }
+    return value;
+}
+
+export async function runSteps(steps, runOne, formatError) {
+    if (!Array.isArray(steps) || steps.length === 0 || steps.length > MAX_STEPS) {
+        throw new ToolInputError(`steps must be an array of 1 to ${MAX_STEPS} items`);
+    }
+    const raw = [];
+    const results = [];
+    for (const [i, step] of steps.entries()) {
+        try {
+            if (step === null || typeof step !== 'object' || typeof step.operation !== 'string') {
+                throw new ToolInputError(`step ${i}: operation must be a string`);
+            }
+            const params = resolveRefs(step.params ?? {}, raw, i);
+            const result = await runOne(step.operation, params);
+            raw.push(result);
+            results.push({ step: i, operation: step.operation, result });
+        } catch (error) {
+            return { results, error: { step: i, message: formatError(error) } };
+        }
+    }
+    return { results };
+}

package/src/core/catalog.ts

@@ -0,0 +1,207 @@
+// Typed mirror of catalog.js. Keep both files, and api-remote-mcp's PHP
+// implementation, behaviourally identical.
+
+export const DEFAULT_SEARCH_LIMIT = 5;
+export const MAX_SEARCH_LIMIT = 20;
+export const MAX_STEPS = 20;
+
+const STEP_REF = /^\$steps\.(\d+)((?:\.[^.]+)*)$/;
+
+export interface CatalogOperation {
+  name: string;
+  title?: string;
+  description?: string;
+  group?: string;
+  annotations?: { readOnlyHint?: boolean; destructiveHint?: boolean; [key: string]: unknown };
+  inputSchema: { type: 'object'; properties?: Record<string, unknown>; required?: string[]; [key: string]: unknown };
+}
+
+export interface OperationSummary {
+  operation: string;
+  title: string;
+  description: string;
+  group: string | null;
+  readOnly: boolean;
+  destructive: boolean;
+  inputSchema: CatalogOperation['inputSchema'];
+}
+
+export interface StepResult { step: number; operation: string; result: unknown }
+export interface BatchResult { results: StepResult[]; error?: { step: number; message: string } }
+
+export class ToolInputError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ToolInputError';
+  }
+}
+
+const meta = (name: string, title: string, description: string, inputSchema: CatalogOperation['inputSchema'], readOnly: boolean) => ({
+  name,
+  title,
+  description,
+  inputSchema,
+  annotations: { title, readOnlyHint: readOnly, destructiveHint: !readOnly },
+});
+
+export const META_TOOLS = [
+  meta('search', 'Search API operations',
+    "Find API operations by keyword. Returns the best matches, each with its operation name, hints and inputSchema. Pass a result's operation and params matching its inputSchema to execute or multi-execute.",
+    {
+      type: 'object',
+      properties: {
+        query: { type: 'string', description: 'Keywords, e.g. "list vps" or "dns records".' },
+        limit: { type: 'integer', minimum: 1, maximum: MAX_SEARCH_LIMIT, default: DEFAULT_SEARCH_LIMIT, description: 'Maximum number of results.' },
+      },
+      required: ['query'],
+    },
+    true),
+  meta('execute', 'Execute an API operation',
+    "Run one API operation found with search. params is a flat object holding the operation's path, query and body parameters as described by its inputSchema.",
+    {
+      type: 'object',
+      properties: {
+        operation: { type: 'string', description: 'Operation name returned by search.' },
+        params: { type: 'object', description: 'Parameters matching the operation inputSchema.' },
+      },
+      required: ['operation'],
+    },
+    false),
+  meta('multi-execute', 'Execute API operations in sequence',
+    'Run up to 20 API operations in order, stopping at the first failure. A params value that is exactly "$steps.<i>.<path>" is replaced by that value from the result of earlier step <i> (dot-separated keys; numbers index arrays), e.g. "$steps.0.0.id".',
+    {
+      type: 'object',
+      properties: {
+        steps: {
+          type: 'array',
+          minItems: 1,
+          maxItems: MAX_STEPS,
+          items: {
+            type: 'object',
+            properties: {
+              operation: { type: 'string', description: 'Operation name returned by search.' },
+              params: { type: 'object', description: 'Parameters; may contain "$steps.<i>.<path>" references.' },
+            },
+            required: ['operation'],
+          },
+        },
+      },
+      required: ['steps'],
+    },
+    false),
+];
+
+const byteOrder = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);
+
+function toSummary(op: CatalogOperation): OperationSummary {
+  return {
+    operation: op.name,
+    title: op.title ?? op.name,
+    description: op.description ?? '',
+    group: op.group ?? null,
+    readOnly: op.annotations?.readOnlyHint === true,
+    destructive: op.annotations?.destructiveHint === true,
+    inputSchema: op.inputSchema,
+  };
+}
+
+export function searchOperations(operations: CatalogOperation[], query: unknown, limit: unknown = DEFAULT_SEARCH_LIMIT): OperationSummary[] {
+  if (typeof query !== 'string') throw new ToolInputError('query must be a string');
+  const tokens = query.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+  if (tokens.length === 0) throw new ToolInputError('query must contain at least one letter or digit');
+  if (typeof limit !== 'number' || !Number.isInteger(limit) || limit < 1 || limit > MAX_SEARCH_LIMIT) {
+    throw new ToolInputError(`limit must be an integer from 1 to ${MAX_SEARCH_LIMIT}`);
+  }
+
+  return operations
+    .map(op => {
+      const name = op.name.toLowerCase();
+      const group = (op.group ?? '').toLowerCase();
+      const title = (op.title ?? '').toLowerCase();
+      const description = (op.description ?? '').toLowerCase();
+      let score = 0;
+      for (const t of tokens) {
+        if (name.includes(t)) score += 3;
+        if (group.includes(t)) score += 2;
+        if (title.includes(t)) score += 2;
+        if (description.includes(t)) score += 1;
+      }
+      return { op, score };
+    })
+    .filter(s => s.score > 0)
+    .sort((a, b) => b.score - a.score || byteOrder(a.op.name, b.op.name))
+    .slice(0, limit)
+    .map(s => toSummary(s.op));
+}
+
+export function renderSearch(query: string, results: OperationSummary[]): string {
+  return results.length > 0
+    ? JSON.stringify(results)
+    : `No operations matched "${query}". Try broader or different terms.`;
+}
+
+export function findOperation<T extends CatalogOperation>(operations: Map<string, T>, name: unknown, params: unknown): T {
+  const op = typeof name === 'string' ? operations.get(name) : undefined;
+  if (!op) {
+    throw new ToolInputError(`Unknown operation "${String(name)}". Use search to find operations.`);
+  }
+  if (params === null || typeof params !== 'object' || Array.isArray(params)) {
+    throw new ToolInputError('params must be an object');
+  }
+  const given = params as Record<string, unknown>;
+  const missing = (op.inputSchema?.required ?? []).filter(k => given[k] === undefined || given[k] === null);
+  if (missing.length > 0) {
+    throw new ToolInputError(`Missing required parameter(s) for ${op.name}: ${missing.join(', ')}`);
+  }
+  return op;
+}
+
+export function resolveRefs(value: unknown, results: unknown[], stepIndex: number): unknown {
+  if (typeof value === 'string') {
+    const m = STEP_REF.exec(value);
+    if (!m) return value;
+    const i = Number(m[1]);
+    if (i >= stepIndex) {
+      throw new ToolInputError(`${value}: references must point to an earlier step`);
+    }
+    let current: unknown = results[i];
+    for (const segment of m[2].split('.').slice(1)) {
+      if (current === null || typeof current !== 'object' || !Object.hasOwn(current, segment)) {
+        throw new ToolInputError(`${value}: path not found in the result of step ${i}`);
+      }
+      current = (current as Record<string, unknown>)[segment];
+    }
+    return current;
+  }
+  if (Array.isArray(value)) return value.map(v => resolveRefs(v, results, stepIndex));
+  if (value !== null && typeof value === 'object') {
+    return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, resolveRefs(v, results, stepIndex)]));
+  }
+  return value;
+}
+
+export async function runSteps(
+  steps: unknown,
+  runOne: (operation: string, params: Record<string, unknown>) => Promise<unknown>,
+  formatError: (error: unknown) => string,
+): Promise<BatchResult> {
+  if (!Array.isArray(steps) || steps.length === 0 || steps.length > MAX_STEPS) {
+    throw new ToolInputError(`steps must be an array of 1 to ${MAX_STEPS} items`);
+  }
+  const raw: unknown[] = [];
+  const results: StepResult[] = [];
+  for (const [i, step] of steps.entries()) {
+    try {
+      if (step === null || typeof step !== 'object' || typeof step.operation !== 'string') {
+        throw new ToolInputError(`step ${i}: operation must be a string`);
+      }
+      const params = resolveRefs(step.params ?? {}, raw, i) as Record<string, unknown>;
+      const result = await runOne(step.operation, params);
+      raw.push(result);
+      results.push({ step: i, operation: step.operation, result });
+    } catch (error) {
+      return { results, error: { step: i, message: formatError(error) } };
+    }
+  }
+  return { results };
+}

package/src/core/instructions.js

@@ -1,2 +1,2 @@
 // Auto-generated server instructions
-export default "Hostinger API notes for agents. Tool descriptions are authoritative for request shapes; read them before calling.\n\nDatabases (web hosting, hosting_* tools)\n- MySQL runs on the same server as the website. From the deployed app connect to host 127.0.0.1, port 3306. PHP may also use localhost (Unix socket). Node.js should use 127.0.0.1: localhost can resolve to IPv6 (::1) and not every database user has that grant.\n- The `host` from hosting_listAccountDatabasesV1 (srvNNNN.hstgr.io) is only for connections from outside Hostinger, after hosting_createDatabaseRemoteConnectionV1. Never use it from the app.\n- Agency Plan (agency-hosting_* tools) database users are created for localhost; the PHP app connects there.\n\nAsynchronous operations\n- A success response often means \"queued\", not \"done\". Poll the matching read tool with backoff (seconds, then minutes). Never re-send the write.\n- hosting_createWebsiteV1 -> poll hosting_listWebsitesV1 until the domain appears (a few minutes).\n- hosting_startNode_jsBuildV1 -> hosting_getNode_jsBuildDetailsV1; logs via hosting_getNodeJSBuildLogsV1; on failure hosting_analyseFailedNode_jsBuildV1.\n- hosting_installWordPressV1 and WordPress plugin/theme/core jobs -> poll hosting_listWordPressInstallationsV1.\n- agency-hosting_createANewWebsiteV1 -> poll agency-hosting_getWebsiteSetupStatusV1 with setup_uuid; other Agency Plan jobs -> agency-hosting_listWebsiteProcessesV1.\n- Website deletion, database repair and domain contact changes finish in the background.\n\nCredentials\n- Never write database passwords or API tokens into source code, client-side JavaScript or committed .env files.\n- Node.js apps read them from environment variables: set the full set with hosting_replaceNode_jsEnvironmentVariablesV1 (full replace; values are masked on read). Build-time variables (Next.js) need a new build afterwards.\n- PHP apps read them from a config file on the server, outside the repository.\n- Generate strong passwords and do not echo them back once stored.\n\nFor end-to-end site builds install the headless skill: npx skills add hostinger/api-mcp-server";
+export default "Hostinger API notes for agents. Find operations with search; the inputSchema it returns is authoritative for request shapes. Run one with execute, or chain several with multi-execute.\n\nDatabases (web hosting, hosting_* operations)\n- MySQL runs on the same server as the website. From the deployed app connect to host 127.0.0.1, port 3306. PHP may also use localhost (Unix socket). Node.js should use 127.0.0.1: localhost can resolve to IPv6 (::1) and not every database user has that grant.\n- The `host` from hosting_listAccountDatabasesV1 (srvNNNN.hstgr.io) is only for connections from outside Hostinger, after hosting_createDatabaseRemoteConnectionV1. Never use it from the app.\n- Agency Plan (agency-hosting_* operations) database users are created for localhost; the PHP app connects there.\n\nAsynchronous operations\n- A success response often means \"queued\", not \"done\". Poll the matching read operation with backoff (seconds, then minutes). Never re-send the write.\n- hosting_createWebsiteV1 -> poll hosting_listWebsitesV1 until the domain appears (a few minutes).\n- hosting_startNode_jsBuildV1 -> hosting_getNode_jsBuildDetailsV1; logs via hosting_getNodeJSBuildLogsV1; on failure hosting_analyseFailedNode_jsBuildV1.\n- hosting_installWordPressV1 and WordPress plugin/theme/core jobs -> poll hosting_listWordPressInstallationsV1.\n- agency-hosting_createANewWebsiteV1 -> poll agency-hosting_getWebsiteSetupStatusV1 with setup_uuid; other Agency Plan jobs -> agency-hosting_listWebsiteProcessesV1.\n- Website deletion, database repair and domain contact changes finish in the background.\n\nCredentials\n- Never write database passwords or API tokens into source code, client-side JavaScript or committed .env files.\n- Node.js apps read them from environment variables: set the full set with hosting_replaceNode_jsEnvironmentVariablesV1 (full replace; values are masked on read). Build-time variables (Next.js) need a new build afterwards.\n- PHP apps read them from a config file on the server, outside the repository.\n- Generate strong passwords and do not echo them back once stored.\n\nFor end-to-end site builds install the headless skill: npx skills add hostinger/api-mcp-server";