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

package/README.md

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

package/dist/server.js

@@ -1,6 +1,6 @@
 import { createRequire } from 'node:module';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { LABEL_CONSTRAINTS, PASSWORD_CONSTRAINTS } from '@shipstatic/ship';
+import { IDEMPOTENCY_KEY_CONSTRAINTS, LABEL_CONSTRAINTS, PASSWORD_CONSTRAINTS, } from '@shipstatic/ship';
 import { z } from 'zod';
 import { call } from './call.js';
 const { version } = createRequire(import.meta.url)('../package.json');
@@ -11,6 +11,15 @@ const READ = {
     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,
@@ -24,6 +33,31 @@ const DESTRUCTIVE = {
     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.";
 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.
@@ -55,17 +89,22 @@ export function createServer(ship) {
             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.`),
+                .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.`),
+            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 }) => call(() => ship.deployments.upload(path, { labels, password, via: 'mcp' })));
+    }, ({ path, labels, password, idempotencyKey }) => call(() => ship.deployments.upload(path, { labels, password, idempotencyKey, via: 'mcp' })));
     server.registerTool('deployments_list', {
-        description: 'List all deployments with their URLs, status, labels, and password protection state.',
+        description: `List all deployments with their URLs, status, labels, and password protection state.${PAGING_NOTE}`,
         annotations: READ,
-    }, () => call(() => ship.deployments.list()));
+        inputSchema: PAGINATION_INPUT,
+    }, ({ limit, cursor }) => call(() => ship.deployments.list({ limit, cursor })));
     server.registerTool('deployments_get', {
         description: 'Get deployment details including URL, status, file count, size, labels, and password protection state.',
         annotations: READ,
@@ -113,9 +152,10 @@ export function createServer(ship) {
         },
     }, ({ domain, deployment, labels }) => call(() => ship.domains.set(domain, { deployment, labels })));
     server.registerTool('domains_list', {
-        description: 'List all domains with their URLs, linked deployment, and verification status.',
+        description: `List all domains with their URLs, linked deployment, and verification status.${PAGING_NOTE}`,
         annotations: READ,
-    }, () => call(() => ship.domains.list()));
+        inputSchema: PAGINATION_INPUT,
+    }, ({ limit, cursor }) => call(() => ship.domains.list({ limit, cursor })));
     server.registerTool('domains_get', {
         description: 'Get domain details including URL, linked deployment, verification status, and labels.',
         annotations: READ,

package/package.json

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