@shipstatic/mcp 1.2.0-beta.1 → 1.2.1

package/README.md

@@ -1,15 +1,17 @@
-# @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
+One product, two doors in. Drop `https://mcp.shipstatic.com` into any MCP client — no install, no signup, no API key — and connect your account when your client asks: the full toolset, custom domains, sites that never expire. Install `@shipstatic/mcp` when your agent needs to deploy a folder on your own machine, when you'd rather configure a token once than sign in, or when your client doesn't speak OAuth yet — the same fifteen tools, reached the other way.
+
+## 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 +23,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 +39,35 @@ claude mcp add --transport http shipstatic https://mcp.shipstatic.com
 }
 ```
 
-### Claude Desktop, Claude.ai web
+### Then just ask
+
+> "Put my site online."
+
+Your agent publishes the files and answers with two links:
+
+- **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.
+
+Want the site private? Ask for a password — visitors must enter it before they can see anything.
 
-Add a custom connector pointing at `https://mcp.shipstatic.com`.
+### Then connect, if you want more
 
-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.
+Everything above works with no account at all. Connect one when your client offers to sign you in, and the same URL answers with the rest: everything you've shipped, your own domains, and sites that stay up permanently. Nothing to install, no key to paste — your client starts the sign-in itself.
 
-## Local — full toolset
+## Local — the same tools, from your own machine
 
-Install this package when you need to manage deployments, link custom domains, or use account-tied operations.
+Install this package when your agent needs to deploy **a folder on your own machine** — the hosted endpoint takes files inline, so it has no path to read from — when you'd rather configure a token once than sign in, or when your MCP client doesn't speak OAuth yet.
+
+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 like the hosted endpoint with no account connected (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 +79,8 @@ Add to `~/.cursor/mcp.json`:
   "mcpServers": {
     "shipstatic": {
       "command": "npx",
-      "args": ["@shipstatic/mcp"]
+      "args": ["-y", "@shipstatic/mcp"],
+      "env": { "SHIP_TOKEN": "ship-..." }
     }
   }
 }
@@ -73,7 +95,8 @@ Add to `~/.gemini/antigravity/mcp_config.json`:
   "mcpServers": {
     "shipstatic": {
       "command": "npx",
-      "args": ["@shipstatic/mcp"]
+      "args": ["-y", "@shipstatic/mcp"],
+      "env": { "SHIP_TOKEN": "ship-..." }
     }
   }
 }
@@ -81,31 +104,25 @@ 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.
+Same config shape — `npx -y @shipstatic/mcp`, with `SHIP_TOKEN` in `env`. Works with any MCP-compatible client.
 
-## Free API key — permanent deployments
+### VS Code
 
-`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.
-
-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
 
-The hosted endpoint exposes `deployments_upload` only. The local install exposes everything below.
+All fifteen tools are on both doors. `deployments_upload` is the one that needs no account; connect on the hosted endpoint or set `SHIP_TOKEN` locally and the other fourteen answer too.
 
 ### Deployments
 
-| 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. 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 | |
+| Tool | Description |
+|------|-------------|
+| `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. 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 |
 
 ### Domains
 
@@ -127,7 +144,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.
 
@@ -145,11 +162,11 @@ Key the *attempt*, not the try — a run id, a commit sha, or a uuid generated b
 { "path": "/path/to/dist", "ttl": 3600 }
 ```
 
-It needs `SHIP_TOKEN`: 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.
+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 — pass \`ttl\` (seconds) to ${UPLOAD_TOOL_NAME} for one that expires on its own. 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}

package/dist/vocabulary.d.ts

@@ -201,11 +201,11 @@ export declare const PARAM_DESCRIPTIONS: {
      */
     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.
+     * Shared and spoken by BOTH doors — stdio declared it first (2026-08-13)
+     * and the hosted door converged the same day, importing this describe
+     * verbatim (its catalogue fence holds it to the import). 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

package/dist/vocabulary.js

@@ -185,11 +185,11 @@ export const PARAM_DESCRIPTIONS = {
      */
     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.
+     * Shared and spoken by BOTH doors — stdio declared it first (2026-08-13)
+     * and the hosted door converged the same day, importing this describe
+     * verbatim (its catalogue fence holds it to the import). 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

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@shipstatic/mcp",
-  "version": "1.2.0-beta.1",
+  "version": "1.2.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.",
+  "description": "Deploy static websites from AI agents. Free hosted endpoint at mcp.shipstatic.com — no install, no signup — or run it locally to deploy folders from your own machine. The same fifteen tools either way.",
   "type": "module",
   "main": "./dist/index.js",
   "sideEffects": [