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

package/README.md

@@ -85,7 +85,7 @@ Same config format — `npx @shipstatic/mcp`. Works with any MCP-compatible clie
 
 ## Free API key — permanent deployments
 
-`SHIP_TOKEN` is optional. Without it, deploys behave like the hosted endpoint (public, claim URL, 3-day expiry). With it, you get permanent deployments, the full toolset, and bigger limits.
+`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):
 
@@ -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/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+/**
+ * THE EXECUTABLE — `dist/bin.js`, the file `npx @shipstatic/mcp` runs. It is
+ * the only module here with side effects on import.
+ *
+ * `index.ts` beside it is a library and stays inert, which is what lets the
+ * hosted transport import this package's vocabulary instead of re-authoring
+ * it. The two used to be one file: `main` and `bin` in `package.json` both
+ * pointed at `index.ts`, so importing the package started a stdio server and,
+ * on failure, called `process.exit` in its consumer. Nothing could be shared
+ * because there was nothing importable to share. `npm/ship` split the same
+ * knot the same way (`bin.ts` executable, `index.ts` library) — a module
+ * boundary says the same thing to every caller.
+ */
+import { createRequire } from 'node:module';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import Ship from '@shipstatic/ship';
+import { SHIP_ENV } from '@shipstatic/types';
+import { createServer } from './server.js';
+// The executable knows its own manifest; the library it drives does not have
+// to. `createServer` takes the version as an argument precisely so no module
+// below this one needs `node:module` in its import graph.
+const { version } = createRequire(import.meta.url)('../package.json');
+async function main() {
+    // SHIP_TOKEN is optional — without it, deployments are public (3-day expiry).
+    // The SDK coerces empty strings to undefined, so we can pass through directly.
+    //
+    // One credential slot, any platform token: the value's prefix says what it
+    // is (`ship-` API key, `deploy-` deploy token, anything else an opaque
+    // bearer) and the server classifies it. MCP never has to know which kind it
+    // holds.
+    const ship = new Ship({ token: process.env[SHIP_ENV.TOKEN] });
+    // No `via` — this executable IS the `mcp` origin, which is the default.
+    const server = createServer(ship, { version });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('ShipStatic MCP Server running on stdio');
+}
+main().catch((error) => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+});

package/dist/call.d.ts

@@ -1,2 +1,51 @@
 import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
-export declare function call<T>(fn: () => Promise<T>): Promise<CallToolResult>;
+/**
+ * The two error arms that earn a hint. Everything else relays verbatim — a
+ * hint on any other type sends the agent chasing a credential that is not the
+ * problem.
+ *
+ * They are ARGUMENTS rather than constants because they are the one part of
+ * the mapping that legitimately differs per transport: stdio can name the
+ * environment variable it owns, and the hosted endpoint deliberately cannot
+ * (it has no configuration of its own, and naming another package's variable
+ * is how this pair silently desynchronised once already).
+ */
+export interface ErrorHints {
+    /** Appended after `Hint: ` when the SDK rejects the credential. */
+    authentication: string;
+    /** 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;
+    /**
+     * Attach a plain-object SUCCESS result as `structuredContent` beside the
+     * text. Hosted-only: it is what feeds the Apps-SDK widget, and the MCP spec
+     * pairs it with an `outputSchema`, which is a hand-maintained zod twin of a
+     * published type. One such twin is worth it for a widget; fifteen would be a
+     * drift surface with no consumer asking for it. See
+     * `cloudflare/mcp/CLAUDE.md`, "What deliberately differs".
+     *
+     * It does NOT gate the ERROR envelope, which every transport carries — see
+     * `toErrorResult`. The objection above is about fifteen success shapes; a
+     * failure has exactly one published shape, and no schema to keep in step.
+     */
+    structuredContent?: boolean;
+}
+/**
+ * Builds the `call()` wrapper both transports use: SDK promise in, MCP
+ * `CallToolResult` out.
+ *
+ * The success envelope, the `'Done.'` sentinel for a void result, the order
+ * the error arms are tested in, and the `Details:` appendix are all wire
+ * facts an agent observes — so they live here once, rather than in two files
+ * kept equal by review.
+ */
+export declare function createCall(options: CallOptions): CallFn;
+export declare const call: CallFn;

package/dist/call.js

@@ -1,33 +1,88 @@
 import { ErrorType, isShipError } from '@shipstatic/ship';
-export async function call(fn) {
-    try {
-        const result = await fn();
-        const text = result === undefined ? 'Done.' : JSON.stringify(result, null, 2);
-        return { content: [{ type: 'text', text }] };
-    }
-    catch (error) {
-        return handleError(error);
-    }
+/**
+ * Builds the `call()` wrapper both transports use: SDK promise in, MCP
+ * `CallToolResult` out.
+ *
+ * The success envelope, the `'Done.'` sentinel for a void result, the order
+ * the error arms are tested in, and the `Details:` appendix are all wire
+ * facts an agent observes — so they live here once, rather than in two files
+ * kept equal by review.
+ */
+export function createCall(options) {
+    const { hints, structuredContent = false } = options;
+    return async function call(fn) {
+        try {
+            const result = await fn();
+            // A void SDK method has nothing to serialize; every other result is the
+            // wire shape verbatim, because an agent reads exactly what the API sent.
+            if (result === undefined) {
+                return { content: [{ type: 'text', text: 'Done.' }] };
+            }
+            const text = JSON.stringify(result, null, 2);
+            const structured = structuredContent && isPlainObject(result)
+                ? result
+                : undefined;
+            return {
+                content: [{ type: 'text', text }],
+                ...(structured ? { structuredContent: structured } : {}),
+            };
+        }
+        catch (error) {
+            return toErrorResult(error, hints);
+        }
+    };
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
-function handleError(error) {
+/**
+ * The failure envelope: authoritative prose, with the wire's own structure
+ * riding beside it.
+ *
+ * The TEXT is unchanged and stays the contract — hints included. It has to be:
+ * the API authors its messages for the end user at the throw site
+ * (`cloudflare/api/CLAUDE.md`, "Message authoring law"), so the sentence
+ * always contains what the agent needs, and a client that ignores everything
+ * else still works.
+ *
+ * `structuredContent` carries `ShipError.toResponse()` verbatim — the same
+ * `ErrorResponse` the wire itself uses. Until 1.0.0-beta.8 the typed contract
+ * terminated here: `status`, `ErrorType`, and every `details` payload except
+ * the Validation arm's were dropped, so the platform's own law — *clients
+ * branch on error type and status, never on message strings* — held for every
+ * consumer EXCEPT the one best equipped to obey it. The recorded bite was a
+ * 429: `details.expires` died at this boundary, leaving the caller most in
+ * need of a precise backoff to parse "try again in 9 minutes" out of English.
+ *
+ * Safe on every arm, and checked rather than assumed: the MCP SDK validates
+ * `structuredContent` only when a tool declares an `outputSchema`, and returns
+ * early again when `isError` is set. No tool here declares one. So this is
+ * additive for every client and invisible to any that does not look.
+ *
+ * It is deliberately NOT behind `CallOptions.structuredContent` — that flag
+ * governs success shapes, where the schema-twin objection lives. A failure has
+ * one published shape on every transport.
+ */
+function toErrorResult(error, hints) {
     if (isShipError(error)) {
         let message = error.message;
         if (error.isType(ErrorType.Authentication)) {
-            message +=
-                '\n\nHint: Set a free SHIP_TOKEN environment variable in your MCP server configuration.';
+            message += `\n\nHint: ${hints.authentication}`;
         }
         if (error.isType(ErrorType.Forbidden)) {
-            message +=
-                '\n\nHint: 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.';
+            message += `\n\nHint: ${hints.forbidden}`;
         }
         if (error.isType(ErrorType.Validation) && error.details) {
             message += `\n\nDetails: ${safeStringify(error.details)}`;
         }
         return {
             content: [{ type: 'text', text: message }],
+            structuredContent: { ...error.toResponse() },
             isError: true,
         };
     }
+    // No structure for a non-ShipError: there is no wire shape to report, and
+    // inventing one would tell an agent this failure came from the platform.
     const fallback = error instanceof Error ? error.message : 'An unexpected error occurred';
     return {
         content: [{ type: 'text', text: fallback }],
@@ -42,3 +97,9 @@ function safeStringify(value) {
         return String(value);
     }
 }
+/** stdio's hints: this package owns `SHIP_TOKEN` and is the only side that may name it. */
+const STDIO_HINTS = {
+    authentication: 'Set a free SHIP_TOKEN environment variable in your MCP server configuration.',
+    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/index.d.ts

@@ -1,2 +1,64 @@
-#!/usr/bin/env node
-export {};
+/**
+ * The library entry — importing this file has NO side effects.
+ *
+ * `bin.ts` is the executable; this is what a consumer imports. There are two
+ * such consumers: the hosted Streamable-HTTP transport in the platform's
+ * private `cloudflare/mcp`, and the VS Code extension
+ * (`integrations/vscode`), which bundles a stdio server into its `.vsix`.
+ * Both transports are converging on the same product — the complete toolset
+ * for authenticated callers, the anonymous deploy for everyone else — and
+ * "one product, two transports" is only true if one of them can import the
+ * other.
+ *
+ * **The surface is exactly what a SECOND CONSUMER needs — nothing more.**
+ * That is the rule, and it is stricter than "curated". It read "a second
+ * TRANSPORT" until 1.0.0-beta.7, when the VS Code extension arrived as a
+ * consumer that is not a transport: it wants stdio's own composition,
+ * verbatim, running on the user's machine. The wording widened; the strictness
+ * did not.
+ *
+ * Every name below answers a question a consumer must otherwise answer for
+ * itself, and each admission was a restatement deleted, not a convenience
+ * added: `SERVER_NAME` and `UPLOAD_TOOL_NAME` were literals in two repos (the
+ * first also correlates the Apps-SDK widget to the connector), `PUBLIC_EXPIRY`
+ * was the same duration written out eight times, `DESCRIPTION_BLOCKS` the
+ * fragments two tool descriptions genuinely share, `ACCOUNT_TOOL_NAMES` is
+ * what lets the hosted catalogue fence name the fourteen without counting them
+ * again, and `createServer` deleted three regexes in another repo's build (see
+ * below).
+ *
+ * **`createServer` is exported; the configured `call` is not.** The extension
+ * previously reached stdio's composition by REGEX-PATCHING this package's
+ * compiled `dist/` at bundle time — stripping `bin`'s shebang, and rewriting
+ * the `createRequire(import.meta.url)('../package.json')` line inside
+ * `server.js` to inline a version literal. Three hacks against another
+ * package's build output, each of which the 1.x library split broke. A short
+ * entry point calling `createServer(ship, { version, via })` replaces all of
+ * them, which is a restatement deleted rather than a convenience added.
+ * `call` stays internal because a consumer configures its own hints through
+ * `createCall`, and stdio's instance is not a contract anyone needs.
+ *
+ * Its second argument is the HOST's own facts — the version it reports and the
+ * deploy origin its uploads carry — because a library has no manifest to read
+ * and no idea which product it was installed inside. A `startStdio` absorbing
+ * the transport as well was proposed and rejected; `CLAUDE.md` records why, and
+ * `tests/architecture/worker-safety.test.ts` is the fence that makes the reason
+ * mechanical rather than remembered.
+ *
+ * The old reason for withholding `createServer` — that its upload tool takes a
+ * filesystem PATH, a footgun to offer a Worker — is still true and is now the
+ * CALLER's judgement rather than an absence: `cloudflare/mcp` must keep
+ * authoring its own upload tool, and does. An absence cannot express "correct
+ * for one consumer, wrong for another"; a documented rule can. What makes the
+ * export safe to publish at all is that `createServer` takes its `version` as
+ * an ARGUMENT — so exporting it adds no `node:module` to the import graph of a
+ * module the Workers-hosted transport loads.
+ *
+ * `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 CallFn, type CallOptions, createCall, type ErrorHints } from './call.js';
+export { createServer } from './server.js';
+export { ACCOUNT_TOOL_NAMES, registerAccountTools } from './tools.js';
+export { ANNOTATIONS, DESCRIPTION_BLOCKS, INSTRUCTION_BLOCKS, PARAM_DESCRIPTIONS, PUBLIC_EXPIRY, SERVER_NAME, UPLOAD_TOOL_NAME, } from './vocabulary.js';

package/dist/index.js

@@ -1,22 +1,64 @@
-#!/usr/bin/env node
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import Ship from '@shipstatic/ship';
-import { createServer } from './server.js';
-async function main() {
-    // SHIP_TOKEN is optional — without it, deployments are public (3-day expiry).
-    // The SDK coerces empty strings to undefined, so we can pass through directly.
-    //
-    // One credential slot, any platform token: the value's prefix says what it
-    // is (`ship-` API key, `deploy-` deploy token, anything else an opaque
-    // bearer) and the server classifies it. MCP never has to know which kind it
-    // holds.
-    const ship = new Ship({ token: process.env.SHIP_TOKEN });
-    const server = createServer(ship);
-    const transport = new StdioServerTransport();
-    await server.connect(transport);
-    console.error('ShipStatic MCP Server running on stdio');
-}
-main().catch((error) => {
-    console.error('Fatal error:', error);
-    process.exit(1);
-});
+/**
+ * The library entry — importing this file has NO side effects.
+ *
+ * `bin.ts` is the executable; this is what a consumer imports. There are two
+ * such consumers: the hosted Streamable-HTTP transport in the platform's
+ * private `cloudflare/mcp`, and the VS Code extension
+ * (`integrations/vscode`), which bundles a stdio server into its `.vsix`.
+ * Both transports are converging on the same product — the complete toolset
+ * for authenticated callers, the anonymous deploy for everyone else — and
+ * "one product, two transports" is only true if one of them can import the
+ * other.
+ *
+ * **The surface is exactly what a SECOND CONSUMER needs — nothing more.**
+ * That is the rule, and it is stricter than "curated". It read "a second
+ * TRANSPORT" until 1.0.0-beta.7, when the VS Code extension arrived as a
+ * consumer that is not a transport: it wants stdio's own composition,
+ * verbatim, running on the user's machine. The wording widened; the strictness
+ * did not.
+ *
+ * Every name below answers a question a consumer must otherwise answer for
+ * itself, and each admission was a restatement deleted, not a convenience
+ * added: `SERVER_NAME` and `UPLOAD_TOOL_NAME` were literals in two repos (the
+ * first also correlates the Apps-SDK widget to the connector), `PUBLIC_EXPIRY`
+ * was the same duration written out eight times, `DESCRIPTION_BLOCKS` the
+ * fragments two tool descriptions genuinely share, `ACCOUNT_TOOL_NAMES` is
+ * what lets the hosted catalogue fence name the fourteen without counting them
+ * again, and `createServer` deleted three regexes in another repo's build (see
+ * below).
+ *
+ * **`createServer` is exported; the configured `call` is not.** The extension
+ * previously reached stdio's composition by REGEX-PATCHING this package's
+ * compiled `dist/` at bundle time — stripping `bin`'s shebang, and rewriting
+ * the `createRequire(import.meta.url)('../package.json')` line inside
+ * `server.js` to inline a version literal. Three hacks against another
+ * package's build output, each of which the 1.x library split broke. A short
+ * entry point calling `createServer(ship, { version, via })` replaces all of
+ * them, which is a restatement deleted rather than a convenience added.
+ * `call` stays internal because a consumer configures its own hints through
+ * `createCall`, and stdio's instance is not a contract anyone needs.
+ *
+ * Its second argument is the HOST's own facts — the version it reports and the
+ * deploy origin its uploads carry — because a library has no manifest to read
+ * and no idea which product it was installed inside. A `startStdio` absorbing
+ * the transport as well was proposed and rejected; `CLAUDE.md` records why, and
+ * `tests/architecture/worker-safety.test.ts` is the fence that makes the reason
+ * mechanical rather than remembered.
+ *
+ * The old reason for withholding `createServer` — that its upload tool takes a
+ * filesystem PATH, a footgun to offer a Worker — is still true and is now the
+ * CALLER's judgement rather than an absence: `cloudflare/mcp` must keep
+ * authoring its own upload tool, and does. An absence cannot express "correct
+ * for one consumer, wrong for another"; a documented rule can. What makes the
+ * export safe to publish at all is that `createServer` takes its `version` as
+ * an ARGUMENT — so exporting it adds no `node:module` to the import graph of a
+ * module the Workers-hosted transport loads.
+ *
+ * `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 { createCall } from './call.js';
+export { createServer } from './server.js';
+export { ACCOUNT_TOOL_NAMES, registerAccountTools } from './tools.js';
+export { ANNOTATIONS, DESCRIPTION_BLOCKS, INSTRUCTION_BLOCKS, PARAM_DESCRIPTIONS, PUBLIC_EXPIRY, SERVER_NAME, UPLOAD_TOOL_NAME, } from './vocabulary.js';

package/dist/server.d.ts

@@ -1,3 +1,36 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type Ship from '@shipstatic/ship';
-export declare function createServer(ship: Ship): McpServer;
+import { type DeploymentViaType } from '@shipstatic/types';
+/**
+ * What the HOST knows about itself and this library must not assume.
+ *
+ * Both fields are the same category of fact, which is why they travel together
+ * rather than as a growing positional tail: a library has no manifest to read
+ * and no idea which product it was installed inside.
+ */
+export interface ServerOptions {
+    /**
+     * The server's reported `serverInfo.version`. A parameter rather than
+     * something this module reads for itself: the executable knows its own
+     * package manifest, a library must not assume it has one, and reaching for
+     * `node:module` here would put a Node builtin in the import graph of a
+     * module the Workers-hosted transport also loads.
+     */
+    version: string;
+    /**
+     * The deploy origin this server's uploads are attributed to. Defaults to
+     * `mcp` — an npx install in some MCP client, which is what this package is
+     * on its own.
+     *
+     * It is a parameter because `via` names the DISTRIBUTION SURFACE, not the
+     * protocol: the GitHub Action reports `git` whatever invoked the workflow,
+     * and the web apps report `web`. The VS Code extension bundles this server
+     * into its `.vsix`, so its agent-mode deploys are the extension's — it
+     * passes `vsc`, and `mcp` goes back to meaning what it says.
+     */
+    via?: DeploymentViaType;
+}
+/**
+ * Builds the stdio server's full 15-tool surface over an injected client.
+ */
+export declare function createServer(ship: Ship, options: ServerOptions): McpServer;