@shipstatic/mcp 1.0.0-beta.4 → 1.0.0-beta.6

package/README.md

@@ -85,7 +85,7 @@ Same config format — `npx @shipstatic/mcp`. Works with any MCP-compatible clie
 
 ## Free API key — permanent deployments
 
-`SHIP_TOKEN` is optional. Without it, deploys behave like the hosted endpoint (public, claim URL, 3-day expiry). With it, you get permanent deployments, the full toolset, and bigger limits.
+`SHIP_TOKEN` is optional. Without it, deploys behave like the hosted endpoint (public, claim URL, expire in 3 days). With it, you get permanent deployments, the full toolset, and bigger limits.
 
 Get a free API key at [my.shipstatic.com/api-key](https://my.shipstatic.com/api-key):
 

package/dist/index.d.ts

@@ -16,10 +16,19 @@
  * 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, createCall, type ErrorHints } from './call.js';
-export { registerAccountTools } from './tools.js';
-export { ANNOTATIONS, INSTRUCTION_BLOCKS, PARAM_DESCRIPTIONS } from './vocabulary.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

@@ -16,10 +16,19 @@
  * 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 { createCall } from './call.js';
-export { registerAccountTools } from './tools.js';
-export { ANNOTATIONS, INSTRUCTION_BLOCKS, PARAM_DESCRIPTIONS } from './vocabulary.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,23 +1,23 @@
 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, INSTRUCTION_BLOCKS, 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 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. ${B.liveAndPassword}
+To deploy: call ${UPLOAD_TOOL_NAME} with the build output directory path. ${B.liveAndPassword}
 
-Without SHIP_TOKEN, deployments are public and expire in 3 days. ${B.claim}
+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.
 
@@ -36,14 +36,14 @@ ${B.domainWorkflow}`;
  */
 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
@@ -51,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,14 +97,6 @@ export declare const ANNOTATIONS: {
         readonly idempotentHint: true;
     };
 };
-/**
- * Deploy-parameter descriptions shared by both transports.
- *
- * The numbers interpolate from `@shipstatic/types` rather than being written
- * out, so a platform constraint change reaches every agent-facing string
- * without anyone editing prose — the same reason the API and the SDK import
- * them instead of restating them.
- */
 /**
  * INSTRUCTIONS sentences both transports say.
  *
@@ -95,7 +119,41 @@ export declare const INSTRUCTION_BLOCKS: {
     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.
+ *
+ * The numbers interpolate from `@shipstatic/types` rather than being written
+ * out, so a platform constraint change reaches every agent-facing string
+ * without anyone editing prose — the same reason the API and the SDK import
+ * them instead of restating them.
+ */
 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,14 +80,6 @@ export const ANNOTATIONS = {
     WRITE: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, ...OPEN_WORLD },
     DESTRUCTIVE: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, ...OPEN_WORLD },
 };
-/**
- * Deploy-parameter descriptions shared by both transports.
- *
- * The numbers interpolate from `@shipstatic/types` rather than being written
- * out, so a platform constraint change reaches every agent-facing string
- * without anyone editing prose — the same reason the API and the SDK import
- * them instead of restating them.
- */
 /**
  * INSTRUCTIONS sentences both transports say.
  *
@@ -78,7 +102,41 @@ export const INSTRUCTION_BLOCKS = {
     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.
+ *
+ * The numbers interpolate from `@shipstatic/types` rather than being written
+ * out, so a platform constraint change reaches every agent-facing string
+ * without anyone editing prose — the same reason the API and the SDK import
+ * them instead of restating them.
+ */
 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.4",
+  "version": "1.0.0-beta.6",
   "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": [