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

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,47 @@
 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;
+}
+/**
+ * The wrapper every tool handler delegates to. Named because the shared
+ * toolset takes it as an argument: the tools are identical across transports,
+ * the hints inside `call` are not.
+ */
+export type CallFn = <T>(fn: () => Promise<T>) => Promise<CallToolResult>;
+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): CallFn;
+export declare const call: CallFn;

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,21 @@
-#!/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 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';

package/dist/index.js

@@ -1,22 +1,21 @@
-#!/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 { registerAccountTools } from './tools.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,63 +1,13 @@
-import { createRequire } from 'node:module';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { IDEMPOTENCY_KEY_CONSTRAINTS, 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,
-};
-/**
- * Deploys carry no `idempotentHint`, and that stays true now that
- * `idempotencyKey` exists. The annotation is a STATIC per-tool claim; the
- * property it would assert is per-CALL — true only when the caller supplies a
- * key, false for the keyless caller, who is the common one. Advertising it
- * would tell every agent that any retry is free, which is exactly wrong for
- * the majority. An annotation an agent trusts wrongly is worse than one it
- * never reads.
- */
-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,
-};
-/**
- * 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.";
+import { registerAccountTools } from './tools.js';
+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 { CREATE } = ANNOTATIONS;
 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.
@@ -71,7 +21,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,
@@ -86,141 +44,17 @@ 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. Up to ${LABEL_CONSTRAINTS.MAX_COUNT}.`),
-            password: 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.`),
+            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.`),
         },
     }, ({ 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.${PAGING_NOTE}`,
-        annotations: READ,
-        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,
-        inputSchema: {
-            deployment: z
-                .string()
-                .describe('Deployment hostname (e.g. "happy-cat-abc1234.shipstatic.com"). Returned by deployments_upload or deployments_list.'),
-        },
-    }, ({ deployment }) => call(() => ship.deployments.get(deployment)));
-    server.registerTool('deployments_set', {
-        description: 'Update deployment labels. Replaces all existing labels.',
-        annotations: WRITE,
-        inputSchema: {
-            deployment: z
-                .string()
-                .describe('Deployment hostname (e.g. "happy-cat-abc1234.shipstatic.com"). Use deployments_list to find deployments.'),
-            labels: z
-                .array(z.string())
-                .describe('Labels to set. Replaces all existing labels. Pass empty array to clear.'),
-        },
-    }, ({ deployment, labels }) => call(() => ship.deployments.set(deployment, { labels })));
-    server.registerTool('deployments_delete', {
-        description: 'Permanently delete a deployment and its files. You MUST confirm with the user before calling this tool, referencing the deployment.',
-        annotations: DESTRUCTIVE,
-        inputSchema: {
-            deployment: z
-                .string()
-                .describe('Deployment hostname to delete (e.g. "happy-cat-abc1234.shipstatic.com")'),
-        },
-    }, ({ deployment }) => call(() => ship.deployments.delete(deployment)));
-    // Domains
-    server.registerTool('domains_set', {
-        description: 'Create or update a custom domain. Can reserve a name (omit deployment), link it to a deployment, switch deployments, or update labels. After creating, call domains_records and show the DNS records to the user.',
-        annotations: WRITE,
-        inputSchema: {
-            domain: z.string().describe('Domain name (e.g. "www.example.com" or "blog.example.com")'),
-            deployment: z
-                .string()
-                .optional()
-                .describe('Deployment to serve on this domain (e.g. "happy-cat-abc1234.shipstatic.com"). Omit to reserve the domain without linking.'),
-            labels: z
-                .array(z.string())
-                .optional()
-                .describe('Labels for organizing domains (e.g. ["production"]).'),
-        },
-    }, ({ 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.${PAGING_NOTE}`,
-        annotations: READ,
-        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,
-        inputSchema: {
-            domain: z
-                .string()
-                .describe('Domain name (e.g. "www.example.com"). Use domains_list to find names.'),
-        },
-    }, ({ domain }) => call(() => ship.domains.get(domain)));
-    server.registerTool('domains_records', {
-        description: 'Get the DNS records the user needs to configure at their DNS provider. Call after domains_set. You MUST show the returned records to the user.',
-        annotations: READ,
-        inputSchema: {
-            domain: z
-                .string()
-                .describe('Domain name. Must be a domain previously created with domains_set.'),
-        },
-    }, ({ domain }) => call(() => ship.domains.records(domain)));
-    server.registerTool('domains_dns', {
-        description: 'Look up the DNS provider for a domain (e.g. Cloudflare, Namecheap). Helps the user know where to configure their DNS records.',
-        annotations: READ,
-        inputSchema: {
-            domain: z
-                .string()
-                .describe('Domain name to look up DNS provider for (e.g. "www.example.com")'),
-        },
-    }, ({ domain }) => call(() => ship.domains.dns(domain)));
-    server.registerTool('domains_share', {
-        description: 'Get a shareable DNS setup hash for a domain. The hash can be shared with the user so they can view the required DNS records without needing an API key.',
-        annotations: READ,
-        inputSchema: {
-            domain: z
-                .string()
-                .describe('Domain name to generate a share link for. Must be a domain previously created with domains_set.'),
-        },
-    }, ({ domain }) => call(() => ship.domains.share(domain)));
-    server.registerTool('domains_validate', {
-        description: 'Check if a domain name is valid and available before creating it. Returns the normalized form and availability.',
-        annotations: READ,
-        inputSchema: {
-            domain: z
-                .string()
-                .describe('Domain name to check (e.g. "www.example.com"). Call before domains_set to check availability.'),
-        },
-    }, ({ domain }) => call(() => ship.domains.validate(domain)));
-    server.registerTool('domains_verify', {
-        description: 'Trigger DNS verification for a custom domain. Call after the user has configured DNS records from domains_records. Verification is asynchronous — the domain status updates once DNS propagates.',
-        annotations: WRITE,
-        inputSchema: {
-            domain: z
-                .string()
-                .describe('Domain name to verify DNS for. Must be a domain previously created with domains_set.'),
-        },
-    }, ({ domain }) => call(() => ship.domains.verify(domain)));
-    server.registerTool('domains_delete', {
-        description: 'Permanently delete a domain. You MUST confirm with the user before calling this tool, referencing the domain name.',
-        annotations: DESTRUCTIVE,
-        inputSchema: {
-            domain: z.string().describe('Domain name to delete (e.g. "www.example.com")'),
-        },
-    }, ({ domain }) => call(() => ship.domains.delete(domain)));
-    // Debugging
-    server.registerTool('whoami', {
-        description: 'Show authenticated account details including email, plan, and usage.',
-        annotations: READ,
-    }, () => call(() => ship.whoami()));
+    // The other fourteen. Identical on every transport, so they live in the
+    // shared package rather than here — see tools.ts for why upload is not
+    // among them.
+    registerAccountTools(server, ship, call);
     return server;
 }

package/dist/tools.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The account-tied toolset — fourteen tools, identical on every transport.
+ *
+ * `deployments_upload` is not here, and the split is exactly the product's
+ * own shape rather than a convenience:
+ *
+ *   - **Upload is the anonymous door.** It is the one operation that works
+ *     with no account, and it is the one whose INPUT differs by transport —
+ *     a filesystem path over stdio, inline bytes over HTTP, because a Worker
+ *     has no filesystem. It also carries the Apps-SDK widget hosted-side.
+ *     So it is authored per transport, in each `server.ts`.
+ *   - **Everything else needs an identity**, and once a transport has one,
+ *     nothing about these fourteen depends on how the bytes arrived. Same
+ *     names, same schemas, same prose, same 1:1 SDK calls.
+ *
+ * That is why they live in the shared package: when the hosted transport
+ * gains OAuth it registers this function and has the complete toolset, rather
+ * than someone copying fourteen definitions into a second repo — which is the
+ * moment the two surfaces would begin to drift. The cost of doing it after
+ * the copy is a de-duplication under deadline; the cost of doing it before is
+ * this file.
+ *
+ * **The catalogue is static; identity decides what SUCCEEDS.** These are
+ * registered whether or not a credential is present — an anonymous caller
+ * sees them and gets a typed authentication error naming how to authenticate
+ * on *this* transport (the hint is `createCall`'s one per-transport argument).
+ * A tool list that changes shape under the caller would be a second, dynamic
+ * contract for an agent to track, and MCP clients cache the catalogue.
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type Ship from '@shipstatic/ship';
+import type { CallFn } from './call.js';
+export declare function registerAccountTools(server: McpServer, ship: Ship, call: CallFn): void;

package/dist/tools.js

@@ -0,0 +1,184 @@
+/**
+ * The account-tied toolset — fourteen tools, identical on every transport.
+ *
+ * `deployments_upload` is not here, and the split is exactly the product's
+ * own shape rather than a convenience:
+ *
+ *   - **Upload is the anonymous door.** It is the one operation that works
+ *     with no account, and it is the one whose INPUT differs by transport —
+ *     a filesystem path over stdio, inline bytes over HTTP, because a Worker
+ *     has no filesystem. It also carries the Apps-SDK widget hosted-side.
+ *     So it is authored per transport, in each `server.ts`.
+ *   - **Everything else needs an identity**, and once a transport has one,
+ *     nothing about these fourteen depends on how the bytes arrived. Same
+ *     names, same schemas, same prose, same 1:1 SDK calls.
+ *
+ * That is why they live in the shared package: when the hosted transport
+ * gains OAuth it registers this function and has the complete toolset, rather
+ * than someone copying fourteen definitions into a second repo — which is the
+ * moment the two surfaces would begin to drift. The cost of doing it after
+ * the copy is a de-duplication under deadline; the cost of doing it before is
+ * this file.
+ *
+ * **The catalogue is static; identity decides what SUCCEEDS.** These are
+ * registered whether or not a credential is present — an anonymous caller
+ * sees them and gets a typed authentication error naming how to authenticate
+ * on *this* transport (the hint is `createCall`'s one per-transport argument).
+ * A tool list that changes shape under the caller would be a second, dynamic
+ * contract for an agent to track, and MCP clients cache the catalogue.
+ */
+import { z } from 'zod';
+import { ANNOTATIONS } from './vocabulary.js';
+const { READ, 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.";
+/** The deployment argument, described identically wherever it is accepted. */
+const DEPLOYMENT_EXAMPLE = 'happy-cat-abc1234.shipstatic.com';
+export function registerAccountTools(server, ship, call) {
+    // Deployments
+    server.registerTool('deployments_list', {
+        description: `List all deployments with their URLs, status, labels, and password protection state.${PAGING_NOTE}`,
+        annotations: READ,
+        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,
+        inputSchema: {
+            deployment: z
+                .string()
+                .describe(`Deployment hostname (e.g. "${DEPLOYMENT_EXAMPLE}"). Returned by deployments_upload or deployments_list.`),
+        },
+    }, ({ deployment }) => call(() => ship.deployments.get(deployment)));
+    server.registerTool('deployments_set', {
+        description: 'Update deployment labels. Replaces all existing labels.',
+        annotations: WRITE,
+        inputSchema: {
+            deployment: z
+                .string()
+                .describe(`Deployment hostname (e.g. "${DEPLOYMENT_EXAMPLE}"). Use deployments_list to find deployments.`),
+            labels: z
+                .array(z.string())
+                .describe('Labels to set. Replaces all existing labels. Pass empty array to clear.'),
+        },
+    }, ({ deployment, labels }) => call(() => ship.deployments.set(deployment, { labels })));
+    server.registerTool('deployments_delete', {
+        description: 'Permanently delete a deployment and its files. You MUST confirm with the user before calling this tool, referencing the deployment.',
+        annotations: DESTRUCTIVE,
+        inputSchema: {
+            deployment: z
+                .string()
+                .describe(`Deployment hostname to delete (e.g. "${DEPLOYMENT_EXAMPLE}")`),
+        },
+    }, ({ deployment }) => call(() => ship.deployments.delete(deployment)));
+    // Domains
+    server.registerTool('domains_set', {
+        description: 'Create or update a custom domain. Can reserve a name (omit deployment), link it to a deployment, switch deployments, or update labels. After creating, call domains_records and show the DNS records to the user.',
+        annotations: WRITE,
+        inputSchema: {
+            domain: z.string().describe('Domain name (e.g. "www.example.com" or "blog.example.com")'),
+            deployment: z
+                .string()
+                .optional()
+                .describe(`Deployment to serve on this domain (e.g. "${DEPLOYMENT_EXAMPLE}"). Omit to reserve the domain without linking.`),
+            labels: z
+                .array(z.string())
+                .optional()
+                .describe('Labels for organizing domains (e.g. ["production"]).'),
+        },
+    }, ({ 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.${PAGING_NOTE}`,
+        annotations: READ,
+        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,
+        inputSchema: {
+            domain: z
+                .string()
+                .describe('Domain name (e.g. "www.example.com"). Use domains_list to find names.'),
+        },
+    }, ({ domain }) => call(() => ship.domains.get(domain)));
+    server.registerTool('domains_records', {
+        description: 'Get the DNS records the user needs to configure at their DNS provider. Call after domains_set. You MUST show the returned records to the user.',
+        annotations: READ,
+        inputSchema: {
+            domain: z
+                .string()
+                .describe('Domain name. Must be a domain previously created with domains_set.'),
+        },
+    }, ({ domain }) => call(() => ship.domains.records(domain)));
+    server.registerTool('domains_dns', {
+        description: 'Look up the DNS provider for a domain (e.g. Cloudflare, Namecheap). Helps the user know where to configure their DNS records.',
+        annotations: READ,
+        inputSchema: {
+            domain: z
+                .string()
+                .describe('Domain name to look up DNS provider for (e.g. "www.example.com")'),
+        },
+    }, ({ domain }) => call(() => ship.domains.dns(domain)));
+    server.registerTool('domains_share', {
+        description: 'Get a shareable DNS setup hash for a domain. The hash can be shared with the user so they can view the required DNS records without needing an API key.',
+        annotations: READ,
+        inputSchema: {
+            domain: z
+                .string()
+                .describe('Domain name to generate a share link for. Must be a domain previously created with domains_set.'),
+        },
+    }, ({ domain }) => call(() => ship.domains.share(domain)));
+    server.registerTool('domains_validate', {
+        description: 'Check if a domain name is valid and available before creating it. Returns the normalized form and availability.',
+        annotations: READ,
+        inputSchema: {
+            domain: z
+                .string()
+                .describe('Domain name to check (e.g. "www.example.com"). Call before domains_set to check availability.'),
+        },
+    }, ({ domain }) => call(() => ship.domains.validate(domain)));
+    server.registerTool('domains_verify', {
+        description: 'Trigger DNS verification for a custom domain. Call after the user has configured DNS records from domains_records. Verification is asynchronous — the domain status updates once DNS propagates.',
+        annotations: WRITE,
+        inputSchema: {
+            domain: z
+                .string()
+                .describe('Domain name to verify DNS for. Must be a domain previously created with domains_set.'),
+        },
+    }, ({ domain }) => call(() => ship.domains.verify(domain)));
+    server.registerTool('domains_delete', {
+        description: 'Permanently delete a domain. You MUST confirm with the user before calling this tool, referencing the domain name.',
+        annotations: DESTRUCTIVE,
+        inputSchema: {
+            domain: z.string().describe('Domain name to delete (e.g. "www.example.com")'),
+        },
+    }, ({ domain }) => call(() => ship.domains.delete(domain)));
+    // Account
+    server.registerTool('whoami', {
+        description: 'Show authenticated account details including email, plan, and usage.',
+        annotations: READ,
+    }, () => call(() => ship.whoami()));
+}

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.1",
+  "version": "1.0.0-beta.3",
   "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",