@shipstatic/mcp 1.0.0-beta.7 → 1.0.0-beta.8

package/dist/bin.js

@@ -29,7 +29,8 @@ async function main() {
     // 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, version);
+    // 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');

package/dist/call.d.ts

@@ -25,12 +25,16 @@ export type CallFn = <T>(fn: () => Promise<T>) => Promise<CallToolResult>;
 export interface CallOptions {
     hints: ErrorHints;
     /**
-     * Attach a plain-object result as `structuredContent` beside the text.
-     * Hosted-only today: it is what feeds the Apps-SDK widget, and the MCP spec
+     * 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;
 }

package/dist/call.js

@@ -35,6 +35,34 @@ export function createCall(options) {
 function isPlainObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
+/**
+ * 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;
@@ -49,9 +77,12 @@ function toErrorResult(error, hints) {
         }
         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 }],

package/dist/index.d.ts

@@ -32,12 +32,19 @@
  * 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
- * fifteen-line entry point calling `createServer(ship, version)` replaces all
- * of them, which is a restatement deleted rather than a convenience added.
+ * 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

package/dist/index.js

@@ -32,12 +32,19 @@
  * 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
- * fifteen-line entry point calling `createServer(ship, version)` replaces all
- * of them, which is a restatement deleted rather than a convenience added.
+ * 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

package/dist/server.d.ts

@@ -1,11 +1,36 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type Ship from '@shipstatic/ship';
+import { type DeploymentViaType } from '@shipstatic/types';
 /**
- * Builds the stdio server's full 15-tool surface over an injected client.
+ * What the HOST knows about itself and this library must not assume.
  *
- * `version` is 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.
+ * 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, version: string): McpServer;
+export declare function createServer(ship: Ship, options: ServerOptions): McpServer;

package/dist/server.js

@@ -1,4 +1,5 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { DeploymentVia } from '@shipstatic/types';
 import { z } from 'zod';
 import { call } from './call.js';
 import { registerAccountTools } from './tools.js';
@@ -28,13 +29,9 @@ ${B.domainConcept}
 ${B.domainWorkflow}`;
 /**
  * Builds the stdio server's full 15-tool surface over an injected client.
- *
- * `version` is 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.
  */
-export function createServer(ship, version) {
+export function createServer(ship, options) {
+    const { version, via = DeploymentVia.MCP } = options;
     const server = new McpServer({
         name: SERVER_NAME,
         version,
@@ -53,7 +50,7 @@ export function createServer(ship, version) {
             password: z.string().optional().describe(PARAM_DESCRIPTIONS.password),
             idempotencyKey: z.string().optional().describe(PARAM_DESCRIPTIONS.idempotencyKey),
         },
-    }, ({ path, labels, password, idempotencyKey }) => call(() => ship.deployments.upload(path, { labels, password, idempotencyKey, via: 'mcp' })));
+    }, ({ path, labels, password, idempotencyKey }) => call(() => ship.deployments.upload(path, { labels, password, idempotencyKey, 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipstatic/mcp",
-  "version": "1.0.0-beta.7",
+  "version": "1.0.0-beta.8",
   "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",
@@ -71,6 +71,7 @@
     "@biomejs/biome": "2.5.5",
     "@types/node": "^25.9.5",
     "@vitest/coverage-v8": "4.1.10",
+    "esbuild": "^0.25.12",
     "typescript": "^6.0.3",
     "vitest": "4.1.10"
   },