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

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

@@ -15,6 +15,7 @@
  * 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 { 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

@@ -17,4 +17,5 @@
  */
 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.js

@@ -2,36 +2,12 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { IDEMPOTENCY_KEY_CONSTRAINTS } from '@shipstatic/ship';
 import { z } from 'zod';
 import { call } from './call.js';
+import { registerAccountTools } from './tools.js';
 import { ANNOTATIONS, PARAM_DESCRIPTIONS } from './vocabulary.js';
 // 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 { 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.
@@ -76,127 +52,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipstatic/mcp",
-  "version": "1.0.0-beta.2",
+  "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",