@shipstatic/mcp 1.1.1 → 1.2.0

package/README.md

@@ -1,15 +1,15 @@
-# @shipstatic/mcp
-
-ShipStatic MCP — deploy static websites, landing pages, and prototypes from AI agents.
+# ShipStatic MCP
 
 **One URL. Your agent ships.**
 
+Give your AI a publish button for the internet: ask it to put your site online, and get back a real, shareable link in seconds. Landing pages, prototypes, portfolios — any static site.
+
 [![smithery badge](https://smithery.ai/badge/shipstatic/ship)](https://smithery.ai/servers/shipstatic/ship)
 [![glama badge](https://img.shields.io/badge/glama-MCP%20server-1f7ade)](https://glama.ai/mcp/servers/shipstatic/mcp)
 
-## Hosted — no install
+## Hosted — nothing to install
 
-Drop this URL into any MCP client. Your agent can publish a website in its next message — free, no install, no signup, no API key.
+Drop `https://mcp.shipstatic.com` into any MCP client. No install, no signup, no API key — your agent can publish a website in its next message.
 
 ```
 https://mcp.shipstatic.com
@@ -21,6 +21,10 @@ https://mcp.shipstatic.com
 claude mcp add --transport http shipstatic https://mcp.shipstatic.com
 ```
 
+### Claude Desktop and claude.ai
+
+**Settings → Connectors → Add custom connector**, paste `https://mcp.shipstatic.com`, save.
+
 ### Cursor, Antigravity, Windsurf, Zed — anywhere with `mcp.json`
 
 ```json
@@ -33,20 +37,31 @@ claude mcp add --transport http shipstatic https://mcp.shipstatic.com
 }
 ```
 
-### Claude Desktop, Claude.ai web
+### Then just ask
+
+> "Put my site online."
 
-Add a custom connector pointing at `https://mcp.shipstatic.com`.
+Your agent publishes the files and answers with two links:
 
-The hosted endpoint exposes one tool: `deployments_upload`. Public deployments expire in 3 days unless claimed — the response includes a claim URL the user can visit to keep the site permanently. Set a `password` arg to gate the deployment behind an unlock prompt.
+- **The live site** — a real URL you can share right away.
+- **A claim link** — the site stays live for 3 days; open the claim link to keep it forever. A free account is all it takes.
 
-## Local — full toolset
+Want the site private? Ask for a password — visitors must enter it before they can see anything.
 
-Install this package when you need to manage deployments, link custom domains, or use account-tied operations.
+## Local — the full toolset
+
+The hosted URL does one thing: publish. Install this package for the full toolset (custom domains, listing, account-tied ops) — see everything you've shipped, connect your own domain, and publish sites that stay up permanently.
+
+The config asks for one thing: `SHIP_TOKEN`. **Its value is your API key** — one credential, two names. The console mints it as an *API key* (it looks like `ship-...`), and the setting that carries it is called the *token*. Get yours free at [my.shipstatic.com/api-key](https://my.shipstatic.com/api-key), paste it where the snippets below show `ship-...`, and every site you publish lands in your account, never expires, and gets bigger limits.
+
+The key is optional: leave it out and the local server behaves exactly like the hosted one (public sites, claim links, live for 3 days).
+
+The server runs with `npx`, which ships with [Node.js](https://nodejs.org) (20.19 or newer).
 
 ### Claude Code
 
 ```bash
-claude mcp add shipstatic -- npx @shipstatic/mcp
+claude mcp add shipstatic -e SHIP_TOKEN=ship-... -- npx -y @shipstatic/mcp
 ```
 
 ### Cursor
@@ -58,7 +73,8 @@ Add to `~/.cursor/mcp.json`:
   "mcpServers": {
     "shipstatic": {
       "command": "npx",
-      "args": ["@shipstatic/mcp"]
+      "args": ["-y", "@shipstatic/mcp"],
+      "env": { "SHIP_TOKEN": "ship-..." }
     }
   }
 }
@@ -73,7 +89,8 @@ Add to `~/.gemini/antigravity/mcp_config.json`:
   "mcpServers": {
     "shipstatic": {
       "command": "npx",
-      "args": ["@shipstatic/mcp"]
+      "args": ["-y", "@shipstatic/mcp"],
+      "env": { "SHIP_TOKEN": "ship-..." }
     }
   }
 }
@@ -81,17 +98,11 @@ Add to `~/.gemini/antigravity/mcp_config.json`:
 
 ### Windsurf, Zed, and other MCP clients
 
-Same config format — `npx @shipstatic/mcp`. Works with any MCP-compatible client.
-
-## Free API key — permanent deployments
+Same config shape — `npx -y @shipstatic/mcp`, with `SHIP_TOKEN` in `env`. Works with any MCP-compatible client.
 
-`SHIP_TOKEN` is optional. Without it, deploys behave like the hosted endpoint (public, claim URL, expire in 3 days). With it, you get permanent deployments, the full toolset, and bigger limits.
+### VS Code
 
-Get a free API key at [my.shipstatic.com/api-key](https://my.shipstatic.com/api-key):
-
-```bash
-claude mcp add shipstatic -e SHIP_TOKEN=ship-... -- npx @shipstatic/mcp
-```
+Prefer an editor extension? [ShipStatic for VS Code](https://marketplace.visualstudio.com/items?itemName=shipstatic.shipstatic) has this server built in — no config at all.
 
 ## Tools
 
@@ -127,7 +138,7 @@ The hosted endpoint exposes `deployments_upload` only. The local install exposes
 |------|-------------|
 | `whoami` | Get your account details including email, plan, and usage |
 
-### Paging
+### Paging long lists
 
 `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.
 
@@ -137,9 +148,19 @@ The hosted endpoint exposes `deployments_upload` only. The local install exposes
 
 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.
 
+### Deployments that clean themselves up
+
+`deployments_upload` accepts a `ttl` in seconds. The deployment expires when the time is up and the platform reclaims it — handy for previews and throwaway iterations you would otherwise have to remember to delete.
+
+```json
+{ "path": "/path/to/dist", "ttl": 3600 }
+```
+
+It needs `SHIP_TOKEN` (your API key): a keyless deploy already expires on the platform's schedule, so a `ttl` on one is refused rather than ignored. A deployment carrying a `ttl` cannot be linked to a custom domain — deploy without one when the site needs a domain.
+
 ## 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.
+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 whichever fits their environment.
 
 ## License
 

package/dist/call.js

@@ -1,4 +1,5 @@
 import { ErrorType, isShipError } from '@shipstatic/ship';
+import { MY_API_KEY_URL } from '@shipstatic/types';
 /**
  * The two CREDENTIAL arms that earn a per-transport hint. Everything else
  * relays verbatim — a credential hint on any other type sends the agent
@@ -152,9 +153,17 @@ function safeStringify(value) {
         return String(value);
     }
 }
-/** stdio's hints: this package owns `SHIP_TOKEN` and is the only side that may name it. */
+/**
+ * stdio's hints: this package owns `SHIP_TOKEN` and is the only side that may
+ * name it. The authentication hint carries the whole chain on purpose — the
+ * variable, what its value IS (the API key; the console and the config use two
+ * words for one credential, and this sentence is where an agent learns they
+ * are the same), and where it is minted. It fires at exactly the moment a
+ * user is missing one, so a hint that names the slot without naming the value
+ * strands them holding an "API key" a config asks for as a "token".
+ */
 const STDIO_HINTS = {
-    authentication: 'Set a free SHIP_TOKEN environment variable in your MCP server configuration.',
+    authentication: `Set the SHIP_TOKEN environment variable in your MCP server configuration — its value is the user's API key, free at ${MY_API_KEY_URL}.`,
     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/server.js

@@ -1,5 +1,5 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { DeploymentVia } from '@shipstatic/types';
+import { DeploymentVia, MY_API_KEY_URL } from '@shipstatic/types';
 import { z } from 'zod';
 import { call } from './call.js';
 import { registerAccountTools } from './tools.js';
@@ -20,7 +20,7 @@ To deploy: call ${UPLOAD_TOOL_NAME} with the build output directory path. ${B.li
 
 Without SHIP_TOKEN, deployments are public and expire in ${PUBLIC_EXPIRY}. ${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.
+With SHIP_TOKEN configured — its value is the user's API key, free at ${MY_API_KEY_URL} — deployments go to the user's account and never expire; pass \`ttl\` (seconds) to ${UPLOAD_TOOL_NAME} for one that expires on its own. Listing, managing, and domain operations also require SHIP_TOKEN.
 
 ${B.conceptsHeader}
 ${B.deploymentConcept}
@@ -50,8 +50,15 @@ export function createServer(ship, options) {
             labels: z.array(z.string()).optional().describe(PARAM_DESCRIPTIONS.labels),
             password: z.string().optional().describe(PARAM_DESCRIPTIONS.password),
             idempotencyKey: z.string().optional().describe(PARAM_DESCRIPTIONS.idempotencyKey),
+            // A bare `z.number()`, and the absences are the point. `.min()`/`.max()`
+            // would restate `TTL_CONSTRAINTS`, and `.int()` would restate the
+            // fraction rule — all three owned by `validateTtl`, which the SDK runs
+            // in-process before a byte is uploaded and which answers in the
+            // constitution's own words. A second validator here could only ever
+            // disagree with the first, silently; its absence fails loudly instead.
+            ttl: z.number().optional().describe(PARAM_DESCRIPTIONS.ttl),
         },
-    }, ({ path, labels, password, idempotencyKey }) => call(() => ship.deployments.upload(path, { labels, password, idempotencyKey, via })));
+    }, ({ path, labels, password, idempotencyKey, ttl }) => call(() => ship.deployments.upload(path, { labels, password, idempotencyKey, ttl, via })));
     // 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.

package/dist/vocabulary.d.ts

@@ -200,4 +200,20 @@ export declare const PARAM_DESCRIPTIONS: {
      * the same one on both. The window is derived, never typed out.
      */
     readonly idempotencyKey: `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 ${number} hours). Key the ATTEMPT \u2014 a run id, a commit sha, a uuid minted before the first try \u2014 never one minted fresh on each retry, which would defeat the point.`;
+    /**
+     * Shared one door ahead of its offer, for the same reason `idempotencyKey`
+     * is: only stdio declares `ttl` today (`cloudflare/mcp/CLAUDE.md`'s
+     * divergence table records the hosted deferral and its trigger), and the two
+     * refusals this teaches belong to the platform, so they read identically on
+     * every door.
+     *
+     * **Two things are deliberately absent, and both are the same rule.** The
+     * RANGE, because `@shipstatic/ship` validates it in-process before a byte is
+     * uploaded and relays the constitution's own sentence — a second copy here
+     * could only ever disagree with it. And the name of any credential: stdio
+     * owns `SHIP_TOKEN`, the hosted door owns "connect an account", and a SHARED
+     * string that named either would put one door's fact in the other's mouth.
+     * `tests/vocabulary.test.ts` fences the second half for every member.
+     */
+    readonly ttl: "Seconds until this deployment expires and the platform reclaims it; omit for one that never does. Only for authenticated deploys — an anonymous deployment already expires on the platform's schedule, and a requested ttl on one is refused. A deployment carrying a ttl cannot be linked to a custom domain: deploy without one if the site needs a domain.";
 };

package/dist/vocabulary.js

@@ -184,4 +184,20 @@ export const PARAM_DESCRIPTIONS = {
      * the same one on both. The window is derived, never typed out.
      */
     idempotencyKey: `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.`,
+    /**
+     * Shared one door ahead of its offer, for the same reason `idempotencyKey`
+     * is: only stdio declares `ttl` today (`cloudflare/mcp/CLAUDE.md`'s
+     * divergence table records the hosted deferral and its trigger), and the two
+     * refusals this teaches belong to the platform, so they read identically on
+     * every door.
+     *
+     * **Two things are deliberately absent, and both are the same rule.** The
+     * RANGE, because `@shipstatic/ship` validates it in-process before a byte is
+     * uploaded and relays the constitution's own sentence — a second copy here
+     * could only ever disagree with it. And the name of any credential: stdio
+     * owns `SHIP_TOKEN`, the hosted door owns "connect an account", and a SHARED
+     * string that named either would put one door's fact in the other's mouth.
+     * `tests/vocabulary.test.ts` fences the second half for every member.
+     */
+    ttl: "Seconds until this deployment expires and the platform reclaims it; omit for one that never does. Only for authenticated deploys — an anonymous deployment already expires on the platform's schedule, and a requested ttl on one is refused. A deployment carrying a ttl cannot be linked to a custom domain: deploy without one if the site needs a domain.",
 };

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@shipstatic/mcp",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "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.",
+  "description": "Deploy static websites from AI agents. Free hosted endpoint at mcp.shipstatic.com — no install, no signup. Install for the full toolset: custom domains, listing, account operations.",
   "type": "module",
   "main": "./dist/index.js",
   "sideEffects": [