@shipstatic/mcp 1.0.0-beta.12 → 1.0.0-beta.14

package/dist/call.d.ts

@@ -1,15 +1,4 @@
 import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
-/**
- * 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;
@@ -37,6 +26,56 @@ export interface CallOptions {
      * failure has exactly one published shape, and no schema to keep in step.
      */
     structuredContent?: boolean;
+    /**
+     * Called when the API refuses on CREDENTIAL grounds — and only then.
+     *
+     * An HTTP transport has an obligation stdio does not: a client learns it
+     * must authenticate from a real `401` with a `WWW-Authenticate` header, and
+     * ignores that header entirely on a `200`. So a tool error saying "please
+     * authenticate" is, on that transport, a dead end — the caller is told
+     * something it has no way to act on.
+     *
+     * This is the seam that lets the transport answer properly, and the
+     * decision of WHAT counts as a credential failure stays here, beside the
+     * hints, rather than being made a second time by each consumer:
+     *
+     * - **Authentication** always reports. The credential was absent, malformed,
+     *   unknown, or expired — the transport cannot tell which, and does not
+     *   need to.
+     * - **Forbidden reports only when it carries `requiredScope`.** That field
+     *   is the API's own signal that a valid grant simply lacks a permission,
+     *   which re-consent can fix. Every other refusal on that arm — plan limits,
+     *   a terminated account, an action no scope can authorize — is a genuine
+     *   answer to the question asked, and stays an ordinary in-band tool error.
+     *
+     * The result is unchanged either way: the agent still receives the full
+     * text envelope, hints included. This is a notification, not a substitution.
+     *
+     * Why an observer at all, rather than the transport inspecting the request:
+     * peeking at a JSON-RPC body to guess whether a call needs a credential
+     * means parsing it twice — on the deploy path, that is tens of megabytes of
+     * base64 re-parsed before the size caps run — and it can only ever guess at
+     * PRESENCE, so an EXPIRED token would answer in-band and a connected client
+     * would never refresh. Reporting what the API actually answered costs
+     * nothing and is correct for both.
+     */
+    onAuthFailure?: (failure: AuthFailure) => void;
+}
+/**
+ * What a credential refusal was, in the only two shapes a transport acts on
+ * differently.
+ *
+ * Deliberately not an HTTP status or an RFC 6750 error code: those are the
+ * consuming transport's vocabulary, and stdio — which also builds a `call` —
+ * has neither. The presence of `requiredScope` is the whole discriminator, so
+ * there is no second field restating it.
+ */
+export interface AuthFailure {
+    /**
+     * The scope the grant is missing, from the API's `details.requiredScope`.
+     * Absent when the credential itself was refused rather than its permissions.
+     */
+    requiredScope?: string;
 }
 /**
  * Builds the `call()` wrapper both transports use: SDK promise in, MCP

package/dist/call.js

@@ -1,4 +1,33 @@
 import { ErrorType, isShipError } from '@shipstatic/ship';
+/**
+ * The two CREDENTIAL arms that earn a per-transport hint. Everything else
+ * relays verbatim — a credential hint on any other type sends the agent
+ * chasing a problem it does not have.
+ *
+ * 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).
+ *
+ * A third arm — maintenance — is hinted too, but it is NOT a member here: a
+ * closed platform is closed identically on every transport, so its text is a
+ * module constant (`MAINTENANCE_HINT`) rather than a per-transport argument.
+ * The membership test for this interface is "does the text differ per
+ * transport?", not "does the arm get a hint?".
+ */
+/**
+ * The maintenance hint — a CONSTANT, for the reason stated on `ErrorHints`:
+ * this text does not differ per transport, so making it an argument would ask
+ * two callers to agree on one sentence forever.
+ *
+ * The instruction to an agent matters more here than on any other arm. A tool
+ * failure normally invites a retry, and retrying is exactly wrong against a
+ * platform that is closed on purpose: the loop cannot succeed, and it spends
+ * the caller's budget discovering that. So the hint leads with the refusal to
+ * retry and closes with the reassurance the agent should relay to its user.
+ */
+const MAINTENANCE_HINT = 'The platform is temporarily closed for scheduled maintenance. Do not retry in a loop — wait and try again later. Deployed sites are unaffected and stay online.';
 /**
  * Builds the `call()` wrapper both transports use: SDK promise in, MCP
  * `CallToolResult` out.
@@ -9,7 +38,7 @@ import { ErrorType, isShipError } from '@shipstatic/ship';
  * kept equal by review.
  */
 export function createCall(options) {
-    const { hints, structuredContent = false } = options;
+    const { hints, structuredContent = false, onAuthFailure } = options;
     return async function call(fn) {
         try {
             const result = await fn();
@@ -28,10 +57,23 @@ export function createCall(options) {
             };
         }
         catch (error) {
-            return toErrorResult(error, hints);
+            return toErrorResult(error, hints, onAuthFailure);
         }
     };
 }
+/**
+ * Read the API's `details.requiredScope`, if this refusal carries one.
+ *
+ * `details` is `unknown` on the wire by design — every arm shapes it
+ * differently — so the read is a narrowing rather than a cast, and anything
+ * that is not a non-empty string means "no scope was named".
+ */
+function requiredScopeOf(details) {
+    if (!details || typeof details !== 'object')
+        return undefined;
+    const scope = details.requiredScope;
+    return typeof scope === 'string' && scope ? scope : undefined;
+}
 function isPlainObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -63,14 +105,27 @@ function isPlainObject(value) {
  * governs success shapes, where the schema-twin objection lives. A failure has
  * one published shape on every transport.
  */
-function toErrorResult(error, hints) {
+function toErrorResult(error, hints, onAuthFailure) {
     if (isShipError(error)) {
         let message = error.message;
+        // First, because it is the one arm that is not about this caller at all:
+        // the platform is closed, nothing the agent sends can succeed, and the
+        // useful instruction is to stop rather than to fix something.
+        if (error.isType(ErrorType.Maintenance)) {
+            message += `\n\nHint: ${MAINTENANCE_HINT}`;
+        }
         if (error.isType(ErrorType.Authentication)) {
             message += `\n\nHint: ${hints.authentication}`;
+            onAuthFailure?.({});
         }
         if (error.isType(ErrorType.Forbidden)) {
             message += `\n\nHint: ${hints.forbidden}`;
+            // Only a MISSING SCOPE is a credential problem. The same arm carries
+            // plan limits and terminated accounts, which re-consenting cannot fix
+            // and which the caller should read as the answer it is.
+            const requiredScope = requiredScopeOf(error.details);
+            if (requiredScope)
+                onAuthFailure?.({ requiredScope });
         }
         if (error.isType(ErrorType.Validation) && error.details) {
             message += `\n\nDetails: ${safeStringify(error.details)}`;

package/dist/index.d.ts

@@ -60,7 +60,7 @@
  * 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 { type AuthFailure, 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, UPLOAD_TOOL_TITLE, } from './vocabulary.js';

package/dist/index.js

@@ -60,7 +60,7 @@
  * extra — because adding an export is the quiet failure: everything published
  * becomes a breaking change to remove.
  */
-export { createCall } from './call.js';
+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, UPLOAD_TOOL_TITLE, } from './vocabulary.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipstatic/mcp",
-  "version": "1.0.0-beta.12",
+  "version": "1.0.0-beta.14",
   "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",
@@ -66,8 +66,8 @@
   "license": "MIT",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "@shipstatic/ship": "2.0.0-beta.18",
-    "@shipstatic/types": "2.5.0-beta.22",
+    "@shipstatic/ship": "2.0.0-beta.20",
+    "@shipstatic/types": "2.5.0-beta.23",
     "zod": "^4.4.3"
   },
   "devDependencies": {