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

package/dist/call.d.ts

@@ -16,6 +16,12 @@ export interface ErrorHints {
     /** 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;
     /**
@@ -37,5 +43,5 @@ export interface CallOptions {
  * 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>;
+export declare function createCall(options: CallOptions): CallFn;
+export declare const call: CallFn;

package/dist/index.d.ts

@@ -1,20 +1,25 @@
 /**
  * The library entry — importing this file has NO side effects.
  *
- * That is the whole point of it: `bin.ts` is the executable, and this is what
- * a consumer imports. Today there is exactly one such consumer, the hosted
- * Streamable-HTTP transport in the platform's private `cloudflare/mcp`, which
- * takes the vocabulary below rather than re-authoring the strings an agent
- * reads. "One product, two transports" is only true if one of them can import
- * the other.
+ * `bin.ts` is the executable; this is what a consumer imports. Today there is
+ * one such consumer, the hosted Streamable-HTTP transport in the platform's
+ * private `cloudflare/mcp`, and both transports are converging on the same
+ * product: the complete toolset for authenticated callers, the anonymous
+ * deploy for everyone else. "One product, two transports" is only true if one
+ * of them can import the other.
  *
- * **The surface is curated, not swept.** Every export here is a deliberate
- * public commitment under semver; the modules behind it hold plenty that is
- * not (`toErrorResult`, `safeStringify`, the INSTRUCTIONS template, every tool
- * registration). `export *` would publish implementation detail and make the
- * next refactor a breaking change. `tests/index.test.ts` fences both
- * directions — nothing missing, nothing extra.
+ * **The surface is exactly what a SECOND TRANSPORT needs — nothing more.**
+ * That is the rule, and it is stricter than "curated". `createServer` and the
+ * configured `call` are deliberately NOT here: they are stdio's own
+ * composition, they have no consumer outside `bin.ts`, and `createServer` in
+ * particular builds a tool whose input is a filesystem PATH — a footgun to
+ * offer a Worker. Exporting them would make this package's API "stdio's
+ * internals, plus some shared bits" instead of a contract.
+ *
+ * `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 CallOptions, call, createCall, type ErrorHints } from './call.js';
-export { createServer } from './server.js';
-export { ANNOTATIONS, PARAM_DESCRIPTIONS } from './vocabulary.js';
+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';

package/dist/index.js

@@ -1,20 +1,25 @@
 /**
  * The library entry — importing this file has NO side effects.
  *
- * That is the whole point of it: `bin.ts` is the executable, and this is what
- * a consumer imports. Today there is exactly one such consumer, the hosted
- * Streamable-HTTP transport in the platform's private `cloudflare/mcp`, which
- * takes the vocabulary below rather than re-authoring the strings an agent
- * reads. "One product, two transports" is only true if one of them can import
- * the other.
+ * `bin.ts` is the executable; this is what a consumer imports. Today there is
+ * one such consumer, the hosted Streamable-HTTP transport in the platform's
+ * private `cloudflare/mcp`, and both transports are converging on the same
+ * product: the complete toolset for authenticated callers, the anonymous
+ * deploy for everyone else. "One product, two transports" is only true if one
+ * of them can import the other.
  *
- * **The surface is curated, not swept.** Every export here is a deliberate
- * public commitment under semver; the modules behind it hold plenty that is
- * not (`toErrorResult`, `safeStringify`, the INSTRUCTIONS template, every tool
- * registration). `export *` would publish implementation detail and make the
- * next refactor a breaking change. `tests/index.test.ts` fences both
- * directions — nothing missing, nothing extra.
+ * **The surface is exactly what a SECOND TRANSPORT needs — nothing more.**
+ * That is the rule, and it is stricter than "curated". `createServer` and the
+ * configured `call` are deliberately NOT here: they are stdio's own
+ * composition, they have no consumer outside `bin.ts`, and `createServer` in
+ * particular builds a tool whose input is a filesystem PATH — a footgun to
+ * offer a Worker. Exporting them would make this package's API "stdio's
+ * internals, plus some shared bits" instead of a contract.
+ *
+ * `tests/index.test.ts` fences both directions — nothing missing, nothing
+ * extra — because adding an export is the quiet failure: everything published
+ * becomes a breaking change to remove.
  */
-export { call, createCall } from './call.js';
-export { createServer } from './server.js';
-export { ANNOTATIONS, PARAM_DESCRIPTIONS } from './vocabulary.js';
+export { createCall } from './call.js';
+export { registerAccountTools } from './tools.js';
+export { ANNOTATIONS, INSTRUCTION_BLOCKS, PARAM_DESCRIPTIONS } from './vocabulary.js';

package/dist/server.js

@@ -2,49 +2,30 @@ 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 { ANNOTATIONS, PARAM_DESCRIPTIONS } from './vocabulary.js';
+import { registerAccountTools } from './tools.js';
+import { ANNOTATIONS, INSTRUCTION_BLOCKS, 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.
+const { CREATE } = ANNOTATIONS;
+const B = INSTRUCTION_BLOCKS;
+// Composed from the shared blocks plus the two sentences that are genuinely
+// stdio's: how files arrive (a filesystem path) and how a caller
+// authenticates (`SHIP_TOKEN`). The hosted transport composes the same blocks
+// around its own two.
+const INSTRUCTIONS = `${B.opening}
 
-To deploy: call deployments_upload with the build output directory path. The site is live immediately. To make the site private, pass \`password\` — visitors must unlock before viewing, including on any custom domains pointing at it.
+To deploy: call deployments_upload with the build output directory path. ${B.liveAndPassword}
 
-Without SHIP_TOKEN, deployments are public and expire in 3 days. The response includes a claim URL — always show the deployment URL and the claim URL to the user so they can keep the site permanently.
+Without SHIP_TOKEN, deployments are public and expire in 3 days. ${B.claim}
 
 With SHIP_TOKEN configured, deployments go to the user's account and never expire. Listing, managing, and domain operations also require SHIP_TOKEN.
 
-Concepts:
-- Deployment: an immutable set of files with an instant URL (e.g. happy-cat-abc1234.shipstatic.com). No setup needed.
-- Domain: a custom domain (e.g. www.example.com) pointing to a deployment. Optional. Subdomains only — not apex domains.
+${B.conceptsHeader}
+${B.deploymentConcept}
+${B.domainConcept}
 
-To add a custom domain: domains_validate → domains_set → domains_records (show DNS records to user) → user configures DNS → domains_verify.`;
+${B.domainWorkflow}`;
 /**
  * Builds the stdio server's full 15-tool surface over an injected client.
  *
@@ -76,127 +57,9 @@ export function createServer(ship, version) {
                 .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

@@ -73,6 +73,28 @@ export declare const ANNOTATIONS: {
  * without anyone editing prose — the same reason the API and the SDK import
  * them instead of restating them.
  */
+/**
+ * INSTRUCTIONS sentences both transports say.
+ *
+ * `initialize`'s instructions are the other half of what an agent reads
+ * before acting (the catalogue is the first). Each transport composes its own
+ * from these blocks plus the two things that are genuinely its own: how files
+ * arrive, and how a caller authenticates.
+ *
+ * Three of these are duplicated prose TODAY, kept equal by review. The last
+ * two are stdio-only only because the hosted transport has no domain tools
+ * yet — when it gains them with OAuth they become shared too, which is
+ * precisely when someone would otherwise copy them across.
+ */
+export declare const INSTRUCTION_BLOCKS: {
+    readonly opening: "ShipStatic deploys static websites instantly. Free, no account required.";
+    readonly liveAndPassword: "The site is live immediately. To make the site private, pass `password` — visitors must unlock before viewing, including on any custom domains pointing at it.";
+    readonly claim: "The response includes a claim URL — always show the deployment URL and the claim URL to the user so they can keep the site permanently.";
+    readonly conceptsHeader: "Concepts:";
+    readonly deploymentConcept: "- Deployment: an immutable set of files with an instant URL (e.g. happy-cat-abc1234.shipstatic.com). No setup needed.";
+    readonly domainConcept: "- Domain: a custom domain (e.g. www.example.com) pointing to a deployment. Optional. Subdomains only — not apex domains.";
+    readonly domainWorkflow: "To add a custom domain: domains_validate → domains_set → domains_records (show DNS records to user) → user configures DNS → domains_verify.";
+};
 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

@@ -56,6 +56,28 @@ export const ANNOTATIONS = {
  * without anyone editing prose — the same reason the API and the SDK import
  * them instead of restating them.
  */
+/**
+ * INSTRUCTIONS sentences both transports say.
+ *
+ * `initialize`'s instructions are the other half of what an agent reads
+ * before acting (the catalogue is the first). Each transport composes its own
+ * from these blocks plus the two things that are genuinely its own: how files
+ * arrive, and how a caller authenticates.
+ *
+ * Three of these are duplicated prose TODAY, kept equal by review. The last
+ * two are stdio-only only because the hosted transport has no domain tools
+ * yet — when it gains them with OAuth they become shared too, which is
+ * precisely when someone would otherwise copy them across.
+ */
+export const INSTRUCTION_BLOCKS = {
+    opening: 'ShipStatic deploys static websites instantly. Free, no account required.',
+    liveAndPassword: 'The site is live immediately. To make the site private, pass `password` — visitors must unlock before viewing, including on any custom domains pointing at it.',
+    claim: 'The response includes a claim URL — always show the deployment URL and the claim URL to the user so they can keep the site permanently.',
+    conceptsHeader: 'Concepts:',
+    deploymentConcept: '- Deployment: an immutable set of files with an instant URL (e.g. happy-cat-abc1234.shipstatic.com). No setup needed.',
+    domainConcept: '- Domain: a custom domain (e.g. www.example.com) pointing to a deployment. Optional. Subdomains only — not apex domains.',
+    domainWorkflow: 'To add a custom domain: domains_validate → domains_set → domains_records (show DNS records to user) → user configures DNS → domains_verify.',
+};
 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,6 +1,6 @@
 {
   "name": "@shipstatic/mcp",
-  "version": "1.0.0-beta.2",
+  "version": "1.0.0-beta.4",
   "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",