@shipstatic/mcp 1.0.0-beta.0 → 1.0.0-beta.2

package/README.md

@@ -102,7 +102,7 @@ The hosted endpoint exposes `deployments_upload` only. The local install exposes
 | Tool | Description | Hosted |
 |------|-------------|:---:|
 | `deployments_upload` | Publish files and get a live URL instantly, optionally protected by a password | ✓ |
-| `deployments_list` | List all deployments with their URLs, status, labels, and password protection state | |
+| `deployments_list` | List all deployments with their URLs, status, labels, and password protection state. Pages with `limit` and `cursor` | |
 | `deployments_get` | Get deployment details including URL, status, file count, size, labels, and password protection state | |
 | `deployments_set` | Update the labels on a deployment for organization and filtering | |
 | `deployments_delete` | Permanently delete a deployment and all its files | |
@@ -112,7 +112,7 @@ The hosted endpoint exposes `deployments_upload` only. The local install exposes
 | Tool | Description |
 |------|-------------|
 | `domains_set` | Connect a custom domain to your site, switch deployments, or update labels |
-| `domains_list` | List all domains with their linked deployment and verification status |
+| `domains_list` | List all domains with their linked deployment and verification status. Pages with `limit` and `cursor` |
 | `domains_get` | Get domain details including linked deployment, verification status, and labels |
 | `domains_records` | Get the DNS records you need to configure at your DNS provider |
 | `domains_dns` | Look up which DNS provider hosts a domain (e.g. Cloudflare, Namecheap) |
@@ -127,6 +127,16 @@ The hosted endpoint exposes `deployments_upload` only. The local install exposes
 |------|-------------|
 | `whoami` | Get your account details including email, plan, and usage |
 
+### Paging
+
+`deployments_list` and `domains_list` accept `limit` and `cursor`. Each response carries a `cursor` — pass it back to fetch the next page; `null` means you are on the last one.
+
+### Retrying a deploy safely
+
+`deployments_upload` accepts an `idempotencyKey`. If a deploy times out you cannot tell "it never landed" from "it landed and the response was lost", and retrying without a key creates a second site. Send the same key on the retry and the original deployment is returned instead.
+
+Key the *attempt*, not the try — a run id, a commit sha, or a uuid generated before the first call. A key that changes on every retry does nothing.
+
 ## Registry
 
 Published to the [MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers?search=com.shipstatic/mcp) as `com.shipstatic/mcp`. Registry-aware clients see both the hosted endpoint and the local install and pick the right transport for their environment.

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+/**
+ * THE EXECUTABLE — `dist/bin.js`, the file `npx @shipstatic/mcp` runs. It is
+ * the only module here with side effects on import.
+ *
+ * `index.ts` beside it is a library and stays inert, which is what lets the
+ * hosted transport import this package's vocabulary instead of re-authoring
+ * it. The two used to be one file: `main` and `bin` in `package.json` both
+ * pointed at `index.ts`, so importing the package started a stdio server and,
+ * on failure, called `process.exit` in its consumer. Nothing could be shared
+ * because there was nothing importable to share. `npm/ship` split the same
+ * knot the same way (`bin.ts` executable, `index.ts` library) — a module
+ * boundary says the same thing to every caller.
+ */
+import { createRequire } from 'node:module';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import Ship from '@shipstatic/ship';
+import { createServer } from './server.js';
+// The executable knows its own manifest; the library it drives does not have
+// to. `createServer` takes the version as an argument precisely so no module
+// below this one needs `node:module` in its import graph.
+const { version } = createRequire(import.meta.url)('../package.json');
+async function main() {
+    // SHIP_TOKEN is optional — without it, deployments are public (3-day expiry).
+    // The SDK coerces empty strings to undefined, so we can pass through directly.
+    //
+    // One credential slot, any platform token: the value's prefix says what it
+    // is (`ship-` API key, `deploy-` deploy token, anything else an opaque
+    // bearer) and the server classifies it. MCP never has to know which kind it
+    // holds.
+    const ship = new Ship({ token: process.env.SHIP_TOKEN });
+    const server = createServer(ship, version);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('ShipStatic MCP Server running on stdio');
+}
+main().catch((error) => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+});

package/dist/call.d.ts

@@ -1,2 +1,41 @@
 import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
-export declare function call<T>(fn: () => Promise<T>): Promise<CallToolResult>;
+/**
+ * The two error arms that earn a hint. Everything else relays verbatim — a
+ * hint on any other type sends the agent chasing a credential that is not the
+ * problem.
+ *
+ * They are ARGUMENTS rather than constants because they are the one part of
+ * the mapping that legitimately differs per transport: stdio can name the
+ * environment variable it owns, and the hosted endpoint deliberately cannot
+ * (it has no configuration of its own, and naming another package's variable
+ * is how this pair silently desynchronised once already).
+ */
+export interface ErrorHints {
+    /** Appended after `Hint: ` when the SDK rejects the credential. */
+    authentication: string;
+    /** Appended after `Hint: ` when the platform refuses an authenticated call. */
+    forbidden: string;
+}
+export interface CallOptions {
+    hints: ErrorHints;
+    /**
+     * Attach a plain-object result as `structuredContent` beside the text.
+     * Hosted-only today: it is what feeds the Apps-SDK widget, and the MCP spec
+     * pairs it with an `outputSchema`, which is a hand-maintained zod twin of a
+     * published type. One such twin is worth it for a widget; fifteen would be a
+     * drift surface with no consumer asking for it. See
+     * `cloudflare/mcp/CLAUDE.md`, "What deliberately differs".
+     */
+    structuredContent?: boolean;
+}
+/**
+ * Builds the `call()` wrapper both transports use: SDK promise in, MCP
+ * `CallToolResult` out.
+ *
+ * The success envelope, the `'Done.'` sentinel for a void result, the order
+ * the error arms are tested in, and the `Details:` appendix are all wire
+ * facts an agent observes — so they live here once, rather than in two files
+ * kept equal by review.
+ */
+export declare function createCall(options: CallOptions): <T>(fn: () => Promise<T>) => Promise<CallToolResult>;
+export declare const call: <T>(fn: () => Promise<T>) => Promise<CallToolResult>;

package/dist/call.js

@@ -1,24 +1,48 @@
 import { ErrorType, isShipError } from '@shipstatic/ship';
-export async function call(fn) {
-    try {
-        const result = await fn();
-        const text = result === undefined ? 'Done.' : JSON.stringify(result, null, 2);
-        return { content: [{ type: 'text', text }] };
-    }
-    catch (error) {
-        return handleError(error);
-    }
+/**
+ * Builds the `call()` wrapper both transports use: SDK promise in, MCP
+ * `CallToolResult` out.
+ *
+ * The success envelope, the `'Done.'` sentinel for a void result, the order
+ * the error arms are tested in, and the `Details:` appendix are all wire
+ * facts an agent observes — so they live here once, rather than in two files
+ * kept equal by review.
+ */
+export function createCall(options) {
+    const { hints, structuredContent = false } = options;
+    return async function call(fn) {
+        try {
+            const result = await fn();
+            // A void SDK method has nothing to serialize; every other result is the
+            // wire shape verbatim, because an agent reads exactly what the API sent.
+            if (result === undefined) {
+                return { content: [{ type: 'text', text: 'Done.' }] };
+            }
+            const text = JSON.stringify(result, null, 2);
+            const structured = structuredContent && isPlainObject(result)
+                ? result
+                : undefined;
+            return {
+                content: [{ type: 'text', text }],
+                ...(structured ? { structuredContent: structured } : {}),
+            };
+        }
+        catch (error) {
+            return toErrorResult(error, hints);
+        }
+    };
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
-function handleError(error) {
+function toErrorResult(error, hints) {
     if (isShipError(error)) {
         let message = error.message;
         if (error.isType(ErrorType.Authentication)) {
-            message +=
-                '\n\nHint: Set a free SHIP_TOKEN environment variable in your MCP server configuration.';
+            message += `\n\nHint: ${hints.authentication}`;
         }
         if (error.isType(ErrorType.Forbidden)) {
-            message +=
-                '\n\nHint: This action is not permitted. Likely cause: plan limits reached or the account is terminated. Stop retrying — the user needs to upgrade or contact support at https://my.shipstatic.com.';
+            message += `\n\nHint: ${hints.forbidden}`;
         }
         if (error.isType(ErrorType.Validation) && error.details) {
             message += `\n\nDetails: ${safeStringify(error.details)}`;
@@ -42,3 +66,9 @@ function safeStringify(value) {
         return String(value);
     }
 }
+/** stdio's hints: this package owns `SHIP_TOKEN` and is the only side that may name it. */
+const STDIO_HINTS = {
+    authentication: 'Set a free SHIP_TOKEN environment variable in your MCP server configuration.',
+    forbidden: 'This action is not permitted. Likely cause: plan limits reached or the account is terminated. Stop retrying — the user needs to upgrade or contact support at https://my.shipstatic.com.',
+};
+export const call = createCall({ hints: STDIO_HINTS });

package/dist/index.d.ts

@@ -1,2 +1,20 @@
-#!/usr/bin/env node
-export {};
+/**
+ * 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.
+ *
+ * **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.
+ */
+export { type CallOptions, call, createCall, type ErrorHints } from './call.js';
+export { createServer } from './server.js';
+export { ANNOTATIONS, PARAM_DESCRIPTIONS } from './vocabulary.js';

package/dist/index.js

@@ -1,22 +1,20 @@
-#!/usr/bin/env node
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import Ship from '@shipstatic/ship';
-import { createServer } from './server.js';
-async function main() {
-    // SHIP_TOKEN is optional — without it, deployments are public (3-day expiry).
-    // The SDK coerces empty strings to undefined, so we can pass through directly.
-    //
-    // One credential slot, any platform token: the value's prefix says what it
-    // is (`ship-` API key, `deploy-` deploy token, anything else an opaque
-    // bearer) and the server classifies it. MCP never has to know which kind it
-    // holds.
-    const ship = new Ship({ token: process.env.SHIP_TOKEN });
-    const server = createServer(ship);
-    const transport = new StdioServerTransport();
-    await server.connect(transport);
-    console.error('ShipStatic MCP Server running on stdio');
-}
-main().catch((error) => {
-    console.error('Fatal error:', error);
-    process.exit(1);
-});
+/**
+ * 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.
+ *
+ * **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.
+ */
+export { call, createCall } from './call.js';
+export { createServer } from './server.js';
+export { ANNOTATIONS, PARAM_DESCRIPTIONS } from './vocabulary.js';

package/dist/server.d.ts

@@ -1,3 +1,11 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type Ship from '@shipstatic/ship';
-export declare function createServer(ship: Ship): McpServer;
+/**
+ * Builds the stdio server's full 15-tool surface over an injected client.
+ *
+ * `version` is a parameter rather than something this module reads for itself:
+ * the executable knows its own package manifest, a library must not assume it
+ * has one, and reaching for `node:module` here would put a Node builtin in the
+ * import graph of a module the Workers-hosted transport also loads.
+ */
+export declare function createServer(ship: Ship, version: string): McpServer;

package/dist/server.js

@@ -1,29 +1,37 @@
-import { createRequire } from 'node:module';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { LABEL_CONSTRAINTS, PASSWORD_CONSTRAINTS } from '@shipstatic/ship';
+import { IDEMPOTENCY_KEY_CONSTRAINTS } from '@shipstatic/ship';
 import { z } from 'zod';
 import { call } from './call.js';
-const { version } = createRequire(import.meta.url)('../package.json');
-const OPEN_WORLD = { openWorldHint: true };
-const READ = {
-    readOnlyHint: true,
-    destructiveHint: false,
-    idempotentHint: true,
-    ...OPEN_WORLD,
-};
-const CREATE = { readOnlyHint: false, destructiveHint: false, ...OPEN_WORLD };
-const WRITE = {
-    readOnlyHint: false,
-    destructiveHint: false,
-    idempotentHint: true,
-    ...OPEN_WORLD,
-};
-const DESTRUCTIVE = {
-    readOnlyHint: false,
-    destructiveHint: true,
-    idempotentHint: true,
-    ...OPEN_WORLD,
+import { ANNOTATIONS, PARAM_DESCRIPTIONS } 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 { READ, CREATE, WRITE, DESTRUCTIVE } = ANNOTATIONS;
+/**
+ * The pagination surface, shared by every list tool because it is one
+ * contract, not two. A list answers `{<collection>, cursor}` and nothing
+ * else — `cursor` carries the whole has-more signal and is null on the last
+ * page, so there is no `total` to ask for and no has-more boolean.
+ *
+ * No upper bound is stated here on purpose. The API clamps an unusable
+ * `limit` server-side and owns that number; restating a cap in the tool
+ * schema would give one fact two owners and let them drift. `min(1)` is not
+ * a cap — it rejects a value that could never mean anything.
+ */
+const PAGINATION_INPUT = {
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .optional()
+        .describe('Maximum number of items to return in one page. Omit for the server default.'),
+    cursor: z
+        .string()
+        .optional()
+        .describe("Opaque position from the previous response's `cursor` field; omit for the first page."),
 };
+/** Appended to every list tool's description — the paging contract, stated once. */
+const PAGING_NOTE = " The response's `cursor` is null on the last page; pass it back as `cursor` to fetch the next.";
 const INSTRUCTIONS = `ShipStatic deploys static websites instantly. Free, no account required.
 
 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.
@@ -37,7 +45,15 @@ Concepts:
 - Domain: a custom domain (e.g. www.example.com) pointing to a deployment. Optional. Subdomains only — not apex domains.
 
 To add a custom domain: domains_validate → domains_set → domains_records (show DNS records to user) → user configures DNS → domains_verify.`;
-export function createServer(ship) {
+/**
+ * Builds the stdio server's full 15-tool surface over an injected client.
+ *
+ * `version` is a parameter rather than something this module reads for itself:
+ * the executable knows its own package manifest, a library must not assume it
+ * has one, and reaching for `node:module` here would put a Node builtin in the
+ * import graph of a module the Workers-hosted transport also loads.
+ */
+export function createServer(ship, version) {
     const server = new McpServer({
         name: 'shipstatic',
         version,
@@ -52,20 +68,19 @@ export function createServer(ship) {
             path: z
                 .string()
                 .describe('Absolute path to the build output directory to deploy (e.g. "/Users/me/project/dist")'),
-            labels: z
-                .array(z.string())
-                .optional()
-                .describe(`Labels for organizing deployments (e.g. ["production", "v1.2"]). Lowercase, ${LABEL_CONSTRAINTS.MIN_LENGTH}-${LABEL_CONSTRAINTS.MAX_LENGTH} chars, allows . _ - separators.`),
-            password: z
+            labels: z.array(z.string()).optional().describe(PARAM_DESCRIPTIONS.labels),
+            password: z.string().optional().describe(PARAM_DESCRIPTIONS.password),
+            idempotencyKey: z
                 .string()
                 .optional()
-                .describe(`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.`),
+                .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.`),
         },
-    }, ({ path, labels, password }) => call(() => ship.deployments.upload(path, { labels, password, via: 'mcp' })));
+    }, ({ path, labels, password, idempotencyKey }) => call(() => ship.deployments.upload(path, { labels, password, idempotencyKey, via: 'mcp' })));
     server.registerTool('deployments_list', {
-        description: 'List all deployments with their URLs, status, labels, and password protection state.',
+        description: `List all deployments with their URLs, status, labels, and password protection state.${PAGING_NOTE}`,
         annotations: READ,
-    }, () => call(() => ship.deployments.list()));
+        inputSchema: PAGINATION_INPUT,
+    }, ({ limit, cursor }) => call(() => ship.deployments.list({ limit, cursor })));
     server.registerTool('deployments_get', {
         description: 'Get deployment details including URL, status, file count, size, labels, and password protection state.',
         annotations: READ,
@@ -113,9 +128,10 @@ export function createServer(ship) {
         },
     }, ({ domain, deployment, labels }) => call(() => ship.domains.set(domain, { deployment, labels })));
     server.registerTool('domains_list', {
-        description: 'List all domains with their URLs, linked deployment, and verification status.',
+        description: `List all domains with their URLs, linked deployment, and verification status.${PAGING_NOTE}`,
         annotations: READ,
-    }, () => call(() => ship.domains.list()));
+        inputSchema: PAGINATION_INPUT,
+    }, ({ limit, cursor }) => call(() => ship.domains.list({ limit, cursor })));
     server.registerTool('domains_get', {
         description: 'Get domain details including URL, linked deployment, verification status, and labels.',
         annotations: READ,

package/dist/vocabulary.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The vocabulary both transports speak.
+ *
+ * `@shipstatic/mcp` (stdio) and the hosted Streamable-HTTP server are one
+ * product with two doors in. Everything an agent observes that is NOT forced
+ * apart by the transport lives here and is IMPORTED by both — because a fact
+ * with two owners is a fact that drifts. This pair kept ten such strings
+ * byte-identical by hand for a year, and the hand slipped: a tool description
+ * diverged unnoticed, a one-word correction had to be applied at three sites,
+ * and a test mock invented constraint numbers production never used. A
+ * coordination table written in prose is a specification for drift, not a
+ * defence against it.
+ *
+ * What belongs here: anything true of a ShipStatic deploy regardless of how
+ * the bytes arrived. What does not, and why:
+ *
+ *   - **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.
+ *   - **Anything Apps-SDK** (widget, `_meta`, `outputSchema`): hosted-only by
+ *     nature.
+ *
+ * Each of those is recorded in `cloudflare/mcp/CLAUDE.md`'s divergence table.
+ * Everything else should be here, and adding a shared fact anywhere else is
+ * how the next year's drift starts.
+ */
+/**
+ * MCP tool annotations by kind of operation. An agent reads these to decide
+ * whether it may call speculatively (`readOnlyHint`), whether a retry is free
+ * (`idempotentHint`), and whether it must confirm with the user first
+ * (`destructiveHint`).
+ *
+ * **`CREATE` carries no `idempotentHint`, deliberately.** A deploy creates a
+ * new deployment on every call. `idempotencyKey` makes a retry replay the
+ * original instead — but that property is conditional on an argument the
+ * caller may not pass, while the annotation is static per tool. Advertising it
+ * would promise every agent that any retry is free, which is exactly false for
+ * the keyless caller, and an annotation an agent trusts wrongly is worse than
+ * one it never reads.
+ */
+export declare const ANNOTATIONS: {
+    readonly READ: {
+        readonly openWorldHint: true;
+        readonly readOnlyHint: true;
+        readonly destructiveHint: false;
+        readonly idempotentHint: true;
+    };
+    readonly CREATE: {
+        readonly openWorldHint: true;
+        readonly readOnlyHint: false;
+        readonly destructiveHint: false;
+    };
+    readonly WRITE: {
+        readonly openWorldHint: true;
+        readonly readOnlyHint: false;
+        readonly destructiveHint: false;
+        readonly idempotentHint: true;
+    };
+    readonly DESTRUCTIVE: {
+        readonly openWorldHint: true;
+        readonly readOnlyHint: false;
+        readonly destructiveHint: true;
+        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.
+ */
+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.";
+};

package/dist/vocabulary.js

@@ -0,0 +1,62 @@
+/**
+ * The vocabulary both transports speak.
+ *
+ * `@shipstatic/mcp` (stdio) and the hosted Streamable-HTTP server are one
+ * product with two doors in. Everything an agent observes that is NOT forced
+ * apart by the transport lives here and is IMPORTED by both — because a fact
+ * with two owners is a fact that drifts. This pair kept ten such strings
+ * byte-identical by hand for a year, and the hand slipped: a tool description
+ * diverged unnoticed, a one-word correction had to be applied at three sites,
+ * and a test mock invented constraint numbers production never used. A
+ * coordination table written in prose is a specification for drift, not a
+ * defence against it.
+ *
+ * What belongs here: anything true of a ShipStatic deploy regardless of how
+ * the bytes arrived. What does not, and why:
+ *
+ *   - **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.
+ *   - **Anything Apps-SDK** (widget, `_meta`, `outputSchema`): hosted-only by
+ *     nature.
+ *
+ * Each of those is recorded in `cloudflare/mcp/CLAUDE.md`'s divergence table.
+ * 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';
+const OPEN_WORLD = { openWorldHint: true };
+/**
+ * MCP tool annotations by kind of operation. An agent reads these to decide
+ * whether it may call speculatively (`readOnlyHint`), whether a retry is free
+ * (`idempotentHint`), and whether it must confirm with the user first
+ * (`destructiveHint`).
+ *
+ * **`CREATE` carries no `idempotentHint`, deliberately.** A deploy creates a
+ * new deployment on every call. `idempotencyKey` makes a retry replay the
+ * original instead — but that property is conditional on an argument the
+ * caller may not pass, while the annotation is static per tool. Advertising it
+ * would promise every agent that any retry is free, which is exactly false for
+ * the keyless caller, and an annotation an agent trusts wrongly is worse than
+ * one it never reads.
+ */
+export const ANNOTATIONS = {
+    READ: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, ...OPEN_WORLD },
+    CREATE: { readOnlyHint: false, destructiveHint: false, ...OPEN_WORLD },
+    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.
+ */
+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.`,
+};

package/package.json

@@ -1,13 +1,20 @@
 {
   "name": "@shipstatic/mcp",
-  "version": "1.0.0-beta.0",
+  "version": "1.0.0-beta.2",
   "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",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
   "bin": {
-    "shipstatic-mcp": "./dist/index.js"
+    "shipstatic-mcp": "./dist/bin.js"
   },
   "scripts": {
     "build": "tsc",