@shipstatic/mcp 1.0.0-beta.3 → 1.0.0-beta.5

package/dist/index.d.ts

@@ -1,21 +1,34 @@
 /**
  * The library entry — importing this file has NO side effects.
  *
- * That is the whole point of it: `bin.ts` is the executable, and this is what
- * a consumer imports. Today there is exactly one such consumer, the hosted
- * Streamable-HTTP transport in the platform's private `cloudflare/mcp`, which
- * takes the vocabulary below rather than re-authoring the strings an agent
- * reads. "One product, two transports" is only true if one of them can import
- * the other.
+ * `bin.ts` is the executable; this is what a consumer imports. Today there is
+ * one such consumer, the hosted Streamable-HTTP transport in the platform's
+ * private `cloudflare/mcp`, and both transports are converging on the same
+ * product: the complete toolset for authenticated callers, the anonymous
+ * deploy for everyone else. "One product, two transports" is only true if one
+ * of them can import the other.
  *
- * **The surface is curated, not swept.** Every export here is a deliberate
- * public commitment under semver; the modules behind it hold plenty that is
- * not (`toErrorResult`, `safeStringify`, the INSTRUCTIONS template, every tool
- * registration). `export *` would publish implementation detail and make the
- * next refactor a breaking change. `tests/index.test.ts` fences both
- * directions — nothing missing, nothing extra.
+ * **The surface is exactly what a SECOND TRANSPORT needs — nothing more.**
+ * That is the rule, and it is stricter than "curated". `createServer` and the
+ * configured `call` are deliberately NOT here: they are stdio's own
+ * composition, they have no consumer outside `bin.ts`, and `createServer` in
+ * particular builds a tool whose input is a filesystem PATH — a footgun to
+ * offer a Worker. Exporting them would make this package's API "stdio's
+ * internals, plus some shared bits" instead of a contract.
+ *
+ * Every name below answers a question the second transport must otherwise
+ * answer for itself, and each admission was a restatement deleted, not a
+ * convenience added: `SERVER_NAME` and `UPLOAD_TOOL_NAME` were literals in two
+ * repos (the first also correlates the Apps-SDK widget to the connector),
+ * `PUBLIC_EXPIRY` was the same duration written out eight times,
+ * `DESCRIPTION_BLOCKS` the fragments two tool descriptions genuinely share,
+ * and `ACCOUNT_TOOL_NAMES` is what lets the hosted catalogue fence name the
+ * fourteen without counting them again.
+ *
+ * `tests/index.test.ts` fences both directions — nothing missing, nothing
+ * extra — because adding an export is the quiet failure: everything published
+ * becomes a breaking change to remove.
  */
-export { type CallFn, type CallOptions, call, createCall, type ErrorHints } from './call.js';
-export { createServer } from './server.js';
-export { registerAccountTools } from './tools.js';
-export { ANNOTATIONS, PARAM_DESCRIPTIONS } from './vocabulary.js';
+export { type CallFn, type CallOptions, createCall, type ErrorHints } from './call.js';
+export { ACCOUNT_TOOL_NAMES, registerAccountTools } from './tools.js';
+export { ANNOTATIONS, DESCRIPTION_BLOCKS, INSTRUCTION_BLOCKS, PARAM_DESCRIPTIONS, PUBLIC_EXPIRY, SERVER_NAME, UPLOAD_TOOL_NAME, } from './vocabulary.js';

package/dist/index.js

@@ -1,21 +1,34 @@
 /**
  * The library entry — importing this file has NO side effects.
  *
- * That is the whole point of it: `bin.ts` is the executable, and this is what
- * a consumer imports. Today there is exactly one such consumer, the hosted
- * Streamable-HTTP transport in the platform's private `cloudflare/mcp`, which
- * takes the vocabulary below rather than re-authoring the strings an agent
- * reads. "One product, two transports" is only true if one of them can import
- * the other.
+ * `bin.ts` is the executable; this is what a consumer imports. Today there is
+ * one such consumer, the hosted Streamable-HTTP transport in the platform's
+ * private `cloudflare/mcp`, and both transports are converging on the same
+ * product: the complete toolset for authenticated callers, the anonymous
+ * deploy for everyone else. "One product, two transports" is only true if one
+ * of them can import the other.
  *
- * **The surface is curated, not swept.** Every export here is a deliberate
- * public commitment under semver; the modules behind it hold plenty that is
- * not (`toErrorResult`, `safeStringify`, the INSTRUCTIONS template, every tool
- * registration). `export *` would publish implementation detail and make the
- * next refactor a breaking change. `tests/index.test.ts` fences both
- * directions — nothing missing, nothing extra.
+ * **The surface is exactly what a SECOND TRANSPORT needs — nothing more.**
+ * That is the rule, and it is stricter than "curated". `createServer` and the
+ * configured `call` are deliberately NOT here: they are stdio's own
+ * composition, they have no consumer outside `bin.ts`, and `createServer` in
+ * particular builds a tool whose input is a filesystem PATH — a footgun to
+ * offer a Worker. Exporting them would make this package's API "stdio's
+ * internals, plus some shared bits" instead of a contract.
+ *
+ * Every name below answers a question the second transport must otherwise
+ * answer for itself, and each admission was a restatement deleted, not a
+ * convenience added: `SERVER_NAME` and `UPLOAD_TOOL_NAME` were literals in two
+ * repos (the first also correlates the Apps-SDK widget to the connector),
+ * `PUBLIC_EXPIRY` was the same duration written out eight times,
+ * `DESCRIPTION_BLOCKS` the fragments two tool descriptions genuinely share,
+ * and `ACCOUNT_TOOL_NAMES` is what lets the hosted catalogue fence name the
+ * fourteen without counting them again.
+ *
+ * `tests/index.test.ts` fences both directions — nothing missing, nothing
+ * extra — because adding an export is the quiet failure: everything published
+ * becomes a breaking change to remove.
  */
-export { call, createCall } from './call.js';
-export { createServer } from './server.js';
-export { registerAccountTools } from './tools.js';
-export { ANNOTATIONS, PARAM_DESCRIPTIONS } from './vocabulary.js';
+export { createCall } from './call.js';
+export { ACCOUNT_TOOL_NAMES, registerAccountTools } from './tools.js';
+export { ANNOTATIONS, DESCRIPTION_BLOCKS, INSTRUCTION_BLOCKS, PARAM_DESCRIPTIONS, PUBLIC_EXPIRY, SERVER_NAME, UPLOAD_TOOL_NAME, } from './vocabulary.js';

package/dist/server.js

@@ -1,26 +1,31 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { IDEMPOTENCY_KEY_CONSTRAINTS } from '@shipstatic/ship';
 import { z } from 'zod';
 import { call } from './call.js';
 import { registerAccountTools } from './tools.js';
-import { ANNOTATIONS, PARAM_DESCRIPTIONS } from './vocabulary.js';
+import { ANNOTATIONS, DESCRIPTION_BLOCKS, INSTRUCTION_BLOCKS, PARAM_DESCRIPTIONS, PUBLIC_EXPIRY, SERVER_NAME, UPLOAD_TOOL_NAME, } from './vocabulary.js';
 // Destructured so the fifteen registrations below read as they always have.
 // The definitions live in `vocabulary.ts` because the hosted transport speaks
 // the same ones — that file records what is shared, what is not, and why.
 const { CREATE } = ANNOTATIONS;
-const INSTRUCTIONS = `ShipStatic deploys static websites instantly. Free, no account required.
+const B = INSTRUCTION_BLOCKS;
+const D = DESCRIPTION_BLOCKS;
+// Composed from the shared blocks plus the two sentences that are genuinely
+// stdio's: how files arrive (a filesystem path) and how a caller
+// authenticates (`SHIP_TOKEN`). The hosted transport composes the same blocks
+// around its own two.
+const INSTRUCTIONS = `${B.opening}
 
-To deploy: call deployments_upload with the build output directory path. The site is live immediately. To make the site private, pass \`password\` — visitors must unlock before viewing, including on any custom domains pointing at it.
+To deploy: call deployments_upload with the build output directory path. ${B.liveAndPassword}
 
-Without SHIP_TOKEN, deployments are public and expire in 3 days. The response includes a claim URL — always show the deployment URL and the claim URL to the user so they can keep the site permanently.
+Without SHIP_TOKEN, deployments are public and expire in ${PUBLIC_EXPIRY}. ${B.claim}
 
 With SHIP_TOKEN configured, deployments go to the user's account and never expire. Listing, managing, and domain operations also require SHIP_TOKEN.
 
-Concepts:
-- Deployment: an immutable set of files with an instant URL (e.g. happy-cat-abc1234.shipstatic.com). No setup needed.
-- Domain: a custom domain (e.g. www.example.com) pointing to a deployment. Optional. Subdomains only — not apex domains.
+${B.conceptsHeader}
+${B.deploymentConcept}
+${B.domainConcept}
 
-To add a custom domain: domains_validate → domains_set → domains_records (show DNS records to user) → user configures DNS → domains_verify.`;
+${B.domainWorkflow}`;
 /**
  * Builds the stdio server's full 15-tool surface over an injected client.
  *
@@ -31,14 +36,14 @@ To add a custom domain: domains_validate → domains_set → domains_records (sh
  */
 export function createServer(ship, version) {
     const server = new McpServer({
-        name: 'shipstatic',
+        name: SERVER_NAME,
         version,
     }, {
         instructions: INSTRUCTIONS,
     });
     // Deployments
-    server.registerTool('deployments_upload', {
-        description: 'Deploy a static site instantly — free, no account or API key required. Returns the live URL, file count, and size. Without SHIP_TOKEN, the response includes a claim URL (site expires in 3 days) — always show both the deployment URL and claim URL to the user. To make the site private, pass `password`; always show the password to the user if you set one.',
+    server.registerTool(UPLOAD_TOOL_NAME, {
+        description: `Deploy a static site instantly — ${D.free}. Returns the live URL, file count, and size. Without SHIP_TOKEN, the response includes a claim URL (site expires in ${PUBLIC_EXPIRY}) — always show both the deployment URL and claim URL to the user. ${D.password}`,
         annotations: CREATE,
         inputSchema: {
             path: z
@@ -46,10 +51,7 @@ export function createServer(ship, version) {
                 .describe('Absolute path to the build output directory to deploy (e.g. "/Users/me/project/dist")'),
             labels: z.array(z.string()).optional().describe(PARAM_DESCRIPTIONS.labels),
             password: z.string().optional().describe(PARAM_DESCRIPTIONS.password),
-            idempotencyKey: z
-                .string()
-                .optional()
-                .describe(`Makes this deploy replayable instead of repeatable. A deploy is not naturally idempotent: if a call times out you cannot tell "it never landed" from "it landed and the response was lost", and retrying creates a second deployment. Send the same key on the retry and the original deployment is replayed instead (within ${IDEMPOTENCY_KEY_CONSTRAINTS.WINDOW_SECONDS / 3600} hours). Key the ATTEMPT — a run id, a commit sha, a uuid minted before the first try — never one minted fresh on each retry, which would defeat the point.`),
+            idempotencyKey: z.string().optional().describe(PARAM_DESCRIPTIONS.idempotencyKey),
         },
     }, ({ path, labels, password, idempotencyKey }) => call(() => ship.deployments.upload(path, { labels, password, idempotencyKey, via: 'mcp' })));
     // The other fourteen. Identical on every transport, so they live in the

package/dist/tools.d.ts

@@ -30,4 +30,24 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type Ship from '@shipstatic/ship';
 import type { CallFn } from './call.js';
+/**
+ * The fourteen, by name, in registration order.
+ *
+ * Exported so a second transport can state its expected catalogue as
+ * `[UPLOAD_TOOL_NAME, ...ACCOUNT_TOOL_NAMES]` instead of listing fifteen
+ * strings it would then have to keep in agreement with this file — the hosted
+ * parity fence is the consumer, and "fifteen" is otherwise a number two repos
+ * count separately.
+ *
+ * **Deliberately a list beside the registrations rather than a table they are
+ * generated from.** A `Record<name, factory>` would make the pairing
+ * structural, and it would cost the zod→handler inference every one of the
+ * fourteen one-liners below relies on: `({ deployment }) => …` is typed today
+ * from the `inputSchema` literal in the same call, and a loop over a
+ * heterogeneous table cannot correlate the two. The same guarantee costs
+ * nothing as a set comparison, and `tests/server.test.ts` makes it — through a
+ * real `tools/list`, so a registration without a name, a name without a
+ * registration, and a typo in either all turn it red.
+ */
+export declare const ACCOUNT_TOOL_NAMES: readonly ["deployments_list", "deployments_get", "deployments_set", "deployments_delete", "domains_set", "domains_list", "domains_get", "domains_records", "domains_dns", "domains_share", "domains_validate", "domains_verify", "domains_delete", "whoami"];
 export declare function registerAccountTools(server: McpServer, ship: Ship, call: CallFn): void;

package/dist/tools.js

@@ -30,6 +30,41 @@
 import { z } from 'zod';
 import { ANNOTATIONS } from './vocabulary.js';
 const { READ, WRITE, DESTRUCTIVE } = ANNOTATIONS;
+/**
+ * The fourteen, by name, in registration order.
+ *
+ * Exported so a second transport can state its expected catalogue as
+ * `[UPLOAD_TOOL_NAME, ...ACCOUNT_TOOL_NAMES]` instead of listing fifteen
+ * strings it would then have to keep in agreement with this file — the hosted
+ * parity fence is the consumer, and "fifteen" is otherwise a number two repos
+ * count separately.
+ *
+ * **Deliberately a list beside the registrations rather than a table they are
+ * generated from.** A `Record<name, factory>` would make the pairing
+ * structural, and it would cost the zod→handler inference every one of the
+ * fourteen one-liners below relies on: `({ deployment }) => …` is typed today
+ * from the `inputSchema` literal in the same call, and a loop over a
+ * heterogeneous table cannot correlate the two. The same guarantee costs
+ * nothing as a set comparison, and `tests/server.test.ts` makes it — through a
+ * real `tools/list`, so a registration without a name, a name without a
+ * registration, and a typo in either all turn it red.
+ */
+export const ACCOUNT_TOOL_NAMES = [
+    'deployments_list',
+    'deployments_get',
+    'deployments_set',
+    'deployments_delete',
+    'domains_set',
+    'domains_list',
+    'domains_get',
+    'domains_records',
+    'domains_dns',
+    'domains_share',
+    'domains_validate',
+    'domains_verify',
+    'domains_delete',
+    'whoami',
+];
 /**
  * The pagination surface, shared by every list tool because it is one
  * contract, not two. A list answers `{<collection>, cursor}` and nothing

package/dist/vocabulary.d.ts

@@ -16,9 +16,10 @@
  *
  *   - **The file-input schema.** A filesystem path here, inline content there:
  *     Workers has no filesystem. Structurally forced apart.
- *   - **Tool descriptions.** Deliberately rewritten hosted-side for an
- *     Apps-SDK caller that must be told not to base64-encode text — a failure
- *     mode the filesystem path does not have.
+ *   - **Tool descriptions**, as whole strings. They are deliberately rewritten
+ *     hosted-side for an Apps-SDK caller that must be told not to base64-encode
+ *     text — a failure mode the filesystem path does not have. What genuinely
+ *     overlaps is exported as `DESCRIPTION_BLOCKS` and composed per transport.
  *   - **Anything Apps-SDK** (widget, `_meta`, `outputSchema`): hosted-only by
  *     nature.
  *
@@ -26,6 +27,37 @@
  * Everything else should be here, and adding a shared fact anywhere else is
  * how the next year's drift starts.
  */
+/**
+ * The server name every transport reports in `serverInfo`.
+ *
+ * Shared because it is not only prose: the Apps-SDK widget's bridge handshake
+ * sends `appInfo.name`, which the HOST correlates against `serverInfo.name` to
+ * tie the rendered view to the connector. Two literals kept equal by comment
+ * is exactly the shape this package exists to delete.
+ */
+export declare const SERVER_NAME = "shipstatic";
+/**
+ * The one tool authored per transport — its INPUT differs (a filesystem path
+ * over stdio, inline bytes over HTTP), its NAME must not. Exported so the
+ * hosted parity fence can build the expected catalogue as
+ * `[UPLOAD_TOOL_NAME, ...ACCOUNT_TOOL_NAMES]` rather than counting to fifteen.
+ */
+export declare const UPLOAD_TOOL_NAME = "deployments_upload";
+/**
+ * How long an anonymous deployment lives, in the words an agent reads.
+ *
+ * **The fact is owned by `cloudflare/api` (`DEPLOYMENT.PUBLIC_TTL`), which
+ * `@shipstatic/types` does not yet export** — so this is a restatement, and it
+ * is deliberately the ONLY one. It previously appeared in eight places across
+ * the two servers and the widget; a TTL change had to find all eight. When
+ * types exports the constant, this line becomes a derivation and nothing above
+ * it moves.
+ *
+ * A phrase rather than a number because every consumer is prose: the value has
+ * to carry its own unit, and `PUBLIC_TTL / 86400` interpolated at eight sites
+ * would restate the unit eight times instead of the number.
+ */
+export declare const PUBLIC_EXPIRY = "3 days";
 /**
  * MCP tool annotations by kind of operation. An agent reads these to decide
  * whether it may call speculatively (`readOnlyHint`), whether a retry is free
@@ -65,6 +97,47 @@ export declare const ANNOTATIONS: {
         readonly idempotentHint: true;
     };
 };
+/**
+ * INSTRUCTIONS sentences both transports say.
+ *
+ * `initialize`'s instructions are the other half of what an agent reads
+ * before acting (the catalogue is the first). Each transport composes its own
+ * from these blocks plus the two things that are genuinely its own: how files
+ * arrive, and how a caller authenticates.
+ *
+ * Three of these are duplicated prose TODAY, kept equal by review. The last
+ * two are stdio-only only because the hosted transport has no domain tools
+ * yet — when it gains them with OAuth they become shared too, which is
+ * precisely when someone would otherwise copy them across.
+ */
+export declare const INSTRUCTION_BLOCKS: {
+    readonly opening: "ShipStatic deploys static websites instantly. Free, no account required.";
+    readonly liveAndPassword: "The site is live immediately. To make the site private, pass `password` — visitors must unlock before viewing, including on any custom domains pointing at it.";
+    readonly claim: "The response includes a claim URL — always show the deployment URL and the claim URL to the user so they can keep the site permanently.";
+    readonly conceptsHeader: "Concepts:";
+    readonly deploymentConcept: "- Deployment: an immutable set of files with an instant URL (e.g. happy-cat-abc1234.shipstatic.com). No setup needed.";
+    readonly domainConcept: "- Domain: a custom domain (e.g. www.example.com) pointing to a deployment. Optional. Subdomains only — not apex domains.";
+    readonly domainWorkflow: "To add a custom domain: domains_validate → domains_set → domains_records (show DNS records to user) → user configures DNS → domains_verify.";
+};
+/**
+ * The fragments of the upload tool's description that both transports say.
+ *
+ * The surrounding descriptions diverge on purpose — hosted opens for an
+ * Apps-SDK caller and spends a paragraph on plain-text-vs-base64, stdio takes
+ * a filesystem path and has no such hazard — so what is shared is smaller than
+ * a sentence in one case and exactly a sentence in the other. Both were pinned
+ * by a `toContain` on each side, which meant three copies of each fragment
+ * (two sources and a test literal) held equal by nobody.
+ *
+ * Same reasoning as `INSTRUCTION_BLOCKS`, one altitude down: blocks are shared,
+ * composition is per transport.
+ */
+export declare const DESCRIPTION_BLOCKS: {
+    /** The no-account promise, mid-sentence in both openings. */
+    readonly free: "free, no account or API key required";
+    /** The password read-back rule — a password the user never sees locks them out. */
+    readonly password: "To make the site private, pass `password`; always show the password to the user if you set one.";
+};
 /**
  * Deploy-parameter descriptions shared by both transports.
  *
@@ -76,4 +149,11 @@ export declare const ANNOTATIONS: {
 export declare const PARAM_DESCRIPTIONS: {
     readonly labels: "Labels for organizing deployments (e.g. [\"production\", \"v1.2\"]). Lowercase, 3-25 chars, allows . _ - separators. Up to 10.";
     readonly password: "Optional password to gate the deployment behind an unlock prompt (6–128 characters; whitespace significant). Visitors must enter this password before viewing the site, including on any custom domains pointing at it.";
+    /**
+     * Shared even though only stdio offers the option today: the hosted door
+     * gains it with OAuth (it can scope a replay per user once callers have an
+     * identity), and the law this teaches — key the ATTEMPT, never the try — is
+     * the same one on both. The window is derived, never typed out.
+     */
+    readonly idempotencyKey: `Makes this deploy replayable instead of repeatable. A deploy is not naturally idempotent: if a call times out you cannot tell "it never landed" from "it landed and the response was lost", and retrying creates a second deployment. Send the same key on the retry and the original deployment is replayed instead (within ${number} hours). Key the ATTEMPT \u2014 a run id, a commit sha, a uuid minted before the first try \u2014 never one minted fresh on each retry, which would defeat the point.`;
 };

package/dist/vocabulary.js

@@ -16,9 +16,10 @@
  *
  *   - **The file-input schema.** A filesystem path here, inline content there:
  *     Workers has no filesystem. Structurally forced apart.
- *   - **Tool descriptions.** Deliberately rewritten hosted-side for an
- *     Apps-SDK caller that must be told not to base64-encode text — a failure
- *     mode the filesystem path does not have.
+ *   - **Tool descriptions**, as whole strings. They are deliberately rewritten
+ *     hosted-side for an Apps-SDK caller that must be told not to base64-encode
+ *     text — a failure mode the filesystem path does not have. What genuinely
+ *     overlaps is exported as `DESCRIPTION_BLOCKS` and composed per transport.
  *   - **Anything Apps-SDK** (widget, `_meta`, `outputSchema`): hosted-only by
  *     nature.
  *
@@ -26,7 +27,38 @@
  * Everything else should be here, and adding a shared fact anywhere else is
  * how the next year's drift starts.
  */
-import { LABEL_CONSTRAINTS, PASSWORD_CONSTRAINTS } from '@shipstatic/ship';
+import { IDEMPOTENCY_KEY_CONSTRAINTS, LABEL_CONSTRAINTS, PASSWORD_CONSTRAINTS, } from '@shipstatic/ship';
+/**
+ * The server name every transport reports in `serverInfo`.
+ *
+ * Shared because it is not only prose: the Apps-SDK widget's bridge handshake
+ * sends `appInfo.name`, which the HOST correlates against `serverInfo.name` to
+ * tie the rendered view to the connector. Two literals kept equal by comment
+ * is exactly the shape this package exists to delete.
+ */
+export const SERVER_NAME = 'shipstatic';
+/**
+ * The one tool authored per transport — its INPUT differs (a filesystem path
+ * over stdio, inline bytes over HTTP), its NAME must not. Exported so the
+ * hosted parity fence can build the expected catalogue as
+ * `[UPLOAD_TOOL_NAME, ...ACCOUNT_TOOL_NAMES]` rather than counting to fifteen.
+ */
+export const UPLOAD_TOOL_NAME = 'deployments_upload';
+/**
+ * How long an anonymous deployment lives, in the words an agent reads.
+ *
+ * **The fact is owned by `cloudflare/api` (`DEPLOYMENT.PUBLIC_TTL`), which
+ * `@shipstatic/types` does not yet export** — so this is a restatement, and it
+ * is deliberately the ONLY one. It previously appeared in eight places across
+ * the two servers and the widget; a TTL change had to find all eight. When
+ * types exports the constant, this line becomes a derivation and nothing above
+ * it moves.
+ *
+ * A phrase rather than a number because every consumer is prose: the value has
+ * to carry its own unit, and `PUBLIC_TTL / 86400` interpolated at eight sites
+ * would restate the unit eight times instead of the number.
+ */
+export const PUBLIC_EXPIRY = '3 days';
 const OPEN_WORLD = { openWorldHint: true };
 /**
  * MCP tool annotations by kind of operation. An agent reads these to decide
@@ -48,6 +80,47 @@ export const ANNOTATIONS = {
     WRITE: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, ...OPEN_WORLD },
     DESTRUCTIVE: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, ...OPEN_WORLD },
 };
+/**
+ * INSTRUCTIONS sentences both transports say.
+ *
+ * `initialize`'s instructions are the other half of what an agent reads
+ * before acting (the catalogue is the first). Each transport composes its own
+ * from these blocks plus the two things that are genuinely its own: how files
+ * arrive, and how a caller authenticates.
+ *
+ * Three of these are duplicated prose TODAY, kept equal by review. The last
+ * two are stdio-only only because the hosted transport has no domain tools
+ * yet — when it gains them with OAuth they become shared too, which is
+ * precisely when someone would otherwise copy them across.
+ */
+export const INSTRUCTION_BLOCKS = {
+    opening: 'ShipStatic deploys static websites instantly. Free, no account required.',
+    liveAndPassword: 'The site is live immediately. To make the site private, pass `password` — visitors must unlock before viewing, including on any custom domains pointing at it.',
+    claim: 'The response includes a claim URL — always show the deployment URL and the claim URL to the user so they can keep the site permanently.',
+    conceptsHeader: 'Concepts:',
+    deploymentConcept: '- Deployment: an immutable set of files with an instant URL (e.g. happy-cat-abc1234.shipstatic.com). No setup needed.',
+    domainConcept: '- Domain: a custom domain (e.g. www.example.com) pointing to a deployment. Optional. Subdomains only — not apex domains.',
+    domainWorkflow: 'To add a custom domain: domains_validate → domains_set → domains_records (show DNS records to user) → user configures DNS → domains_verify.',
+};
+/**
+ * The fragments of the upload tool's description that both transports say.
+ *
+ * The surrounding descriptions diverge on purpose — hosted opens for an
+ * Apps-SDK caller and spends a paragraph on plain-text-vs-base64, stdio takes
+ * a filesystem path and has no such hazard — so what is shared is smaller than
+ * a sentence in one case and exactly a sentence in the other. Both were pinned
+ * by a `toContain` on each side, which meant three copies of each fragment
+ * (two sources and a test literal) held equal by nobody.
+ *
+ * Same reasoning as `INSTRUCTION_BLOCKS`, one altitude down: blocks are shared,
+ * composition is per transport.
+ */
+export const DESCRIPTION_BLOCKS = {
+    /** The no-account promise, mid-sentence in both openings. */
+    free: 'free, no account or API key required',
+    /** The password read-back rule — a password the user never sees locks them out. */
+    password: 'To make the site private, pass `password`; always show the password to the user if you set one.',
+};
 /**
  * Deploy-parameter descriptions shared by both transports.
  *
@@ -59,4 +132,11 @@ export const ANNOTATIONS = {
 export const PARAM_DESCRIPTIONS = {
     labels: `Labels for organizing deployments (e.g. ["production", "v1.2"]). Lowercase, ${LABEL_CONSTRAINTS.MIN_LENGTH}-${LABEL_CONSTRAINTS.MAX_LENGTH} chars, allows . _ - separators. Up to ${LABEL_CONSTRAINTS.MAX_COUNT}.`,
     password: `Optional password to gate the deployment behind an unlock prompt (${PASSWORD_CONSTRAINTS.MIN_LENGTH}–${PASSWORD_CONSTRAINTS.MAX_LENGTH} characters; whitespace significant). Visitors must enter this password before viewing the site, including on any custom domains pointing at it.`,
+    /**
+     * Shared even though only stdio offers the option today: the hosted door
+     * gains it with OAuth (it can scope a replay per user once callers have an
+     * identity), and the law this teaches — key the ATTEMPT, never the try — is
+     * the same one on both. The window is derived, never typed out.
+     */
+    idempotencyKey: `Makes this deploy replayable instead of repeatable. A deploy is not naturally idempotent: if a call times out you cannot tell "it never landed" from "it landed and the response was lost", and retrying creates a second deployment. Send the same key on the retry and the original deployment is replayed instead (within ${IDEMPOTENCY_KEY_CONSTRAINTS.WINDOW_SECONDS / 3600} hours). Key the ATTEMPT — a run id, a commit sha, a uuid minted before the first try — never one minted fresh on each retry, which would defeat the point.`,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipstatic/mcp",
-  "version": "1.0.0-beta.3",
+  "version": "1.0.0-beta.5",
   "mcpName": "com.shipstatic/mcp",
   "description": "ShipStatic MCP — deploy static websites from AI agents. Full toolset incl. custom domains. Free hosted endpoint at mcp.shipstatic.com — no install.",
   "type": "module",
@@ -24,6 +24,7 @@
     "typecheck": "tsc -p tsconfig.check.json --noEmit",
     "lint": "biome check .",
     "format": "biome format --write .",
+    "smoke": "node smoke.mjs",
     "coverage": "vitest --run --coverage"
   },
   "files": [