@shipstatic/mcp 1.10.2 → 1.11.0-beta.1

package/README.md

@@ -139,7 +139,7 @@ All fifteen tools are on both doors. What changes is not which tools exist, but
 | `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) |
+| `domains_dns` | The DNS provider recorded for a domain, if known (e.g. Cloudflare, Namecheap) |
 | `domains_share` | Get a shareable link so someone else can see the required DNS records |
 | `domains_validate` | Check if a domain name is valid and available before connecting it |
 | `domains_verify` | Check if DNS is configured correctly after you set up the records |
@@ -149,7 +149,7 @@ All fifteen tools are on both doors. What changes is not which tools exist, but
 
 | Tool | Description |
 |------|-------------|
-| `whoami` | Get your account details including email, plan, and usage |
+| `whoami` | Your account's email, name, plan, current usage and plan caps |
 
 ### Paging long lists
 

package/dist/index.d.ts

@@ -26,8 +26,10 @@
  * 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).
+ * again, `TOOLS` and `annotate` replaced four annotation classes plus a
+ * hand-annotated upload on each transport plus a separate list for the auth
+ * need (three owners for one tool's facts, 1.11.0), 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
@@ -62,5 +64,5 @@
  */
 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, titled, UPLOAD_TOOL_NAME, UPLOAD_TOOL_TITLE, } from './vocabulary.js';
+export { ACCOUNT_TOOL_NAMES, type AccountToolName, registerAccountTools, TOOLS, type ToolName, } from './tools.js';
+export { annotate, DESCRIPTION_BLOCKS, INSTRUCTION_BLOCKS, PARAM_DESCRIPTIONS, PUBLIC_EXPIRY, SERVER_NAME, type ToolContract, titled, UPLOAD_TOOL_NAME, UPLOAD_TOOL_TITLE, } from './vocabulary.js';

package/dist/index.js

@@ -26,8 +26,10 @@
  * 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).
+ * again, `TOOLS` and `annotate` replaced four annotation classes plus a
+ * hand-annotated upload on each transport plus a separate list for the auth
+ * need (three owners for one tool's facts, 1.11.0), 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
@@ -62,5 +64,5 @@
  */
 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, titled, UPLOAD_TOOL_NAME, UPLOAD_TOOL_TITLE, } from './vocabulary.js';
+export { ACCOUNT_TOOL_NAMES, registerAccountTools, TOOLS, } from './tools.js';
+export { annotate, DESCRIPTION_BLOCKS, INSTRUCTION_BLOCKS, PARAM_DESCRIPTIONS, PUBLIC_EXPIRY, SERVER_NAME, titled, UPLOAD_TOOL_NAME, UPLOAD_TOOL_TITLE, } from './vocabulary.js';

package/dist/server.js

@@ -2,12 +2,8 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { DeploymentVia, MY_API_KEY_URL } from '@shipstatic/types';
 import { z } from 'zod';
 import { call } from './call.js';
-import { registerAccountTools } from './tools.js';
-import { ANNOTATIONS, DESCRIPTION_BLOCKS, INSTRUCTION_BLOCKS, PARAM_DESCRIPTIONS, PUBLIC_EXPIRY, SERVER_NAME, titled, UPLOAD_TOOL_NAME, UPLOAD_TOOL_TITLE, } from './vocabulary.js';
-// Destructured so the fifteen registrations below read as they always have.
-// The definitions live in `vocabulary.ts` because the hosted transport speaks
-// the same ones — that file records what is shared, what is not, and why.
-const { CREATE } = ANNOTATIONS;
+import { registerAccountTools, TOOLS } from './tools.js';
+import { annotate, DESCRIPTION_BLOCKS, INSTRUCTION_BLOCKS, PARAM_DESCRIPTIONS, PUBLIC_EXPIRY, SERVER_NAME, titled, UPLOAD_TOOL_NAME, UPLOAD_TOOL_TITLE, } from './vocabulary.js';
 const B = INSTRUCTION_BLOCKS;
 const D = DESCRIPTION_BLOCKS;
 // Composed from the shared blocks plus the two sentences that are genuinely
@@ -41,8 +37,12 @@ export function createServer(ship, options) {
     // Deployments
     server.registerTool(UPLOAD_TOOL_NAME, titled({
         title: UPLOAD_TOOL_TITLE,
-        description: `Deploy a static site instantly — ${D.free}. Returns the live URL, file count, and size. Without SHIP_TOKEN, the response includes a claim URL (site expires in ${PUBLIC_EXPIRY}) — always show both the deployment URL and claim URL to the user. ${D.password}`,
-        annotations: CREATE,
+        // Describes the tool and instructs nobody: what an agent should DO with
+        // the claim URL and a password is the INSTRUCTIONS' job, stated once
+        // above. The annotations come from the registry row this transport
+        // shares with the hosted one; only the input schema is this door's own.
+        description: `Deploy a static site instantly: ${D.free}. Returns the live URL, file count, and size. Without SHIP_TOKEN, the response also includes a one-time claim URL, and the site expires in ${PUBLIC_EXPIRY} unless claimed. ${D.password}`,
+        annotations: annotate(TOOLS[UPLOAD_TOOL_NAME]),
         inputSchema: {
             path: z
                 .string()

package/dist/tools.d.ts

@@ -40,23 +40,118 @@ import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type Ship from '@shipstatic/ship';
 import type { CallFn } from './call.js';
 /**
- * The fourteen, by name, in registration order.
+ * THE REGISTRY: one row per tool, every fact about it that a host reads.
+ *
+ * Fifteen rows, in registration order, `deployments_upload` included even
+ * though each transport authors that registration itself: its INPUT differs
+ * per transport, its contract does not. Everything else is derived from
+ * here. `annotate(row)` is every registration's `annotations`;
+ * `ACCOUNT_TOOL_NAMES` is the rows whose `auth` is `required`, and the
+ * hosted door reads the same column for `securitySchemes`; the listing
+ * repo's justifications are held to the hints these rows produce.
+ *
+ * The rows are DATA the registrations read, not a table they are generated
+ * from, and that is deliberate: a `Record<name, factory>` would cost the
+ * zod→handler inference every one-liner below relies on (`({ deployment })
+ * => …` is typed from the `inputSchema` literal in the same call). A row
+ * without a registration, a registration without a row, and a typo in
+ * either all turn `tests/server.test.ts` red, through a real `tools/list`.
+ *
+ * Two rows are worth a second look, because their names suggest otherwise:
+ * `domains_dns` READS the provider the platform recorded when the domain
+ * was created (nothing is looked up on call), and `domains_validate` and
+ * `domains_share` persist nothing.
+ */
+export declare const TOOLS: {
+    readonly deployments_upload: {
+        readonly auth: "optional";
+        readonly mutation: "add";
+        readonly reach: "public";
+    };
+    readonly deployments_list: {
+        readonly auth: "required";
+        readonly mutation: "none";
+        readonly reach: "account";
+    };
+    readonly deployments_get: {
+        readonly auth: "required";
+        readonly mutation: "none";
+        readonly reach: "account";
+    };
+    readonly deployments_set: {
+        readonly auth: "required";
+        readonly mutation: "replace";
+        readonly reach: "account";
+    };
+    readonly deployments_delete: {
+        readonly auth: "required";
+        readonly mutation: "remove";
+        readonly reach: "public";
+    };
+    readonly domains_set: {
+        readonly auth: "required";
+        readonly mutation: "replace";
+        readonly reach: "public";
+    };
+    readonly domains_list: {
+        readonly auth: "required";
+        readonly mutation: "none";
+        readonly reach: "account";
+    };
+    readonly domains_get: {
+        readonly auth: "required";
+        readonly mutation: "none";
+        readonly reach: "account";
+    };
+    readonly domains_records: {
+        readonly auth: "required";
+        readonly mutation: "none";
+        readonly reach: "account";
+    };
+    readonly domains_dns: {
+        readonly auth: "required";
+        readonly mutation: "none";
+        readonly reach: "account";
+    };
+    readonly domains_share: {
+        readonly auth: "required";
+        readonly mutation: "none";
+        readonly reach: "account";
+    };
+    readonly domains_validate: {
+        readonly auth: "required";
+        readonly mutation: "none";
+        readonly reach: "account";
+    };
+    readonly domains_verify: {
+        readonly auth: "required";
+        readonly mutation: "add";
+        readonly reach: "public";
+    };
+    readonly domains_delete: {
+        readonly auth: "required";
+        readonly mutation: "remove";
+        readonly reach: "public";
+    };
+    readonly whoami: {
+        readonly auth: "required";
+        readonly mutation: "none";
+        readonly reach: "account";
+    };
+};
+export type ToolName = keyof typeof TOOLS;
+/** The names whose row says an account is required. */
+export type AccountToolName = {
+    [N in ToolName]: (typeof TOOLS)[N]['auth'] extends 'required' ? N : never;
+}[ToolName];
+/**
+ * The fourteen, derived from the registry rather than listed beside it.
  *
  * Exported so a second transport can state its expected catalogue as
- * `[UPLOAD_TOOL_NAME, ...ACCOUNT_TOOL_NAMES]` instead of listing fifteen
- * strings it would then have to keep in agreement with this file — the hosted
- * parity fence is the consumer, and "fifteen" is otherwise a number two repos
- * count separately.
- *
- * **Deliberately a list beside the registrations rather than a table they are
- * generated from.** A `Record<name, factory>` would make the pairing
- * structural, and it would cost the zod→handler inference every one of the
- * fourteen one-liners below relies on: `({ deployment }) => …` is typed today
- * from the `inputSchema` literal in the same call, and a loop over a
- * heterogeneous table cannot correlate the two. The same guarantee costs
- * nothing as a set comparison, and `tests/server.test.ts` makes it — through a
- * real `tools/list`, so a registration without a name, a name without a
- * registration, and a typo in either all turn it red.
+ * `[UPLOAD_TOOL_NAME, ...ACCOUNT_TOOL_NAMES]` instead of counting to fifteen
+ * in a second repo. It was a hand-written list until 1.11.0, which made the
+ * auth need a second owner beside the annotations; a row is now the only
+ * place a tool's account requirement is stated.
  */
-export declare const ACCOUNT_TOOL_NAMES: readonly ["deployments_list", "deployments_get", "deployments_set", "deployments_delete", "domains_set", "domains_list", "domains_get", "domains_records", "domains_dns", "domains_share", "domains_validate", "domains_verify", "domains_delete", "whoami"];
+export declare const ACCOUNT_TOOL_NAMES: AccountToolName[];
 export declare function registerAccountTools(server: McpServer, ship: Ship, call: CallFn): void;

package/dist/tools.js

@@ -37,43 +37,70 @@
  * every tool, so the next one cannot be added without one.
  */
 import { z } from 'zod';
-import { ANNOTATIONS, titled } from './vocabulary.js';
-const { READ, WRITE, DESTRUCTIVE } = ANNOTATIONS;
+import { annotate, titled, UPLOAD_TOOL_NAME } from './vocabulary.js';
 /**
- * The fourteen, by name, in registration order.
+ * THE REGISTRY: one row per tool, every fact about it that a host reads.
+ *
+ * Fifteen rows, in registration order, `deployments_upload` included even
+ * though each transport authors that registration itself: its INPUT differs
+ * per transport, its contract does not. Everything else is derived from
+ * here. `annotate(row)` is every registration's `annotations`;
+ * `ACCOUNT_TOOL_NAMES` is the rows whose `auth` is `required`, and the
+ * hosted door reads the same column for `securitySchemes`; the listing
+ * repo's justifications are held to the hints these rows produce.
+ *
+ * The rows are DATA the registrations read, not a table they are generated
+ * from, and that is deliberate: a `Record<name, factory>` would cost the
+ * zod→handler inference every one-liner below relies on (`({ deployment })
+ * => …` is typed from the `inputSchema` literal in the same call). A row
+ * without a registration, a registration without a row, and a typo in
+ * either all turn `tests/server.test.ts` red, through a real `tools/list`.
+ *
+ * Two rows are worth a second look, because their names suggest otherwise:
+ * `domains_dns` READS the provider the platform recorded when the domain
+ * was created (nothing is looked up on call), and `domains_validate` and
+ * `domains_share` persist nothing.
+ */
+export const TOOLS = {
+    [UPLOAD_TOOL_NAME]: { auth: 'optional', mutation: 'add', reach: 'public' },
+    deployments_list: { auth: 'required', mutation: 'none', reach: 'account' },
+    deployments_get: { auth: 'required', mutation: 'none', reach: 'account' },
+    deployments_set: { auth: 'required', mutation: 'replace', reach: 'account' },
+    deployments_delete: { auth: 'required', mutation: 'remove', reach: 'public' },
+    domains_set: { auth: 'required', mutation: 'replace', reach: 'public' },
+    domains_list: { auth: 'required', mutation: 'none', reach: 'account' },
+    domains_get: { auth: 'required', mutation: 'none', reach: 'account' },
+    domains_records: { auth: 'required', mutation: 'none', reach: 'account' },
+    domains_dns: { auth: 'required', mutation: 'none', reach: 'account' },
+    domains_share: { auth: 'required', mutation: 'none', reach: 'account' },
+    domains_validate: { auth: 'required', mutation: 'none', reach: 'account' },
+    domains_verify: { auth: 'required', mutation: 'add', reach: 'public' },
+    domains_delete: { auth: 'required', mutation: 'remove', reach: 'public' },
+    whoami: { auth: 'required', mutation: 'none', reach: 'account' },
+};
+/**
+ * The fourteen, derived from the registry rather than listed beside it.
  *
  * Exported so a second transport can state its expected catalogue as
- * `[UPLOAD_TOOL_NAME, ...ACCOUNT_TOOL_NAMES]` instead of listing fifteen
- * strings it would then have to keep in agreement with this file — the hosted
- * parity fence is the consumer, and "fifteen" is otherwise a number two repos
- * count separately.
+ * `[UPLOAD_TOOL_NAME, ...ACCOUNT_TOOL_NAMES]` instead of counting to fifteen
+ * in a second repo. It was a hand-written list until 1.11.0, which made the
+ * auth need a second owner beside the annotations; a row is now the only
+ * place a tool's account requirement is stated.
+ */
+export const ACCOUNT_TOOL_NAMES = Object.keys(TOOLS).filter((name) => TOOLS[name].auth === 'required');
+/**
+ * What `whoami` answers: exactly the keys its description names.
  *
- * **Deliberately a list beside the registrations rather than a table they are
- * generated from.** A `Record<name, factory>` would make the pairing
- * structural, and it would cost the zod→handler inference every one of the
- * fourteen one-liners below relies on: `({ deployment }) => …` is typed today
- * from the `inputSchema` literal in the same call, and a loop over a
- * heterogeneous table cannot correlate the two. The same guarantee costs
- * nothing as a set comparison, and `tests/server.test.ts` makes it — through a
- * real `tools/list`, so a registration without a name, a name without a
- * registration, and a typo in either all turn it red.
+ * `Account` also carries billing state, the API-key hint, the picture and
+ * timestamps, none of which the description mentions and none of which an
+ * agent acts on. A tool's result is the shape its description states; this
+ * is the one tool where the wire's own entity said more than the sentence.
+ * `suspended` is deliberately out: it means every write is refused, and the
+ * refusal says so itself at the moment it matters.
  */
-export const ACCOUNT_TOOL_NAMES = [
-    'deployments_list',
-    'deployments_get',
-    'deployments_set',
-    'deployments_delete',
-    'domains_set',
-    'domains_list',
-    'domains_get',
-    'domains_records',
-    'domains_dns',
-    'domains_share',
-    'domains_validate',
-    'domains_verify',
-    'domains_delete',
-    'whoami',
-];
+function accountSummary({ email, name, plan, usage, caps }) {
+    return { email, name, plan, usage, caps };
+}
 /**
  * The pagination surface, shared by every list tool because it is one
  * contract, not two. A list answers `{<collection>, cursor}` and nothing
@@ -106,13 +133,13 @@ export function registerAccountTools(server, ship, call) {
     server.registerTool('deployments_list', titled({
         title: 'List Deployments',
         description: `List all deployments with their URLs, status, labels, and password protection state.${PAGING_NOTE}`,
-        annotations: READ,
+        annotations: annotate(TOOLS.deployments_list),
         inputSchema: PAGINATION_INPUT,
     }), ({ limit, cursor }) => call(() => ship.deployments.list({ limit, cursor })));
     server.registerTool('deployments_get', titled({
         title: 'Get Deployment',
         description: 'Get deployment details including URL, status, file count, size, labels, and password protection state.',
-        annotations: READ,
+        annotations: annotate(TOOLS.deployments_get),
         inputSchema: {
             deployment: z
                 .string()
@@ -122,7 +149,7 @@ export function registerAccountTools(server, ship, call) {
     server.registerTool('deployments_set', titled({
         title: 'Update Deployment Labels',
         description: 'Update deployment labels. Replaces all existing labels.',
-        annotations: WRITE,
+        annotations: annotate(TOOLS.deployments_set),
         inputSchema: {
             deployment: z
                 .string()
@@ -134,8 +161,8 @@ export function registerAccountTools(server, ship, call) {
     }), ({ deployment, labels }) => call(() => ship.deployments.set(deployment, { labels })));
     server.registerTool('deployments_delete', titled({
         title: 'Delete Deployment',
-        description: 'Permanently delete a deployment and its files. You MUST confirm with the user before calling this tool, referencing the deployment.',
-        annotations: DESTRUCTIVE,
+        description: 'Permanently deletes a deployment and its files.',
+        annotations: annotate(TOOLS.deployments_delete),
         inputSchema: {
             deployment: z
                 .string()
@@ -145,8 +172,8 @@ export function registerAccountTools(server, ship, call) {
     // Domains
     server.registerTool('domains_set', titled({
         title: 'Connect Custom Domain',
-        description: 'Create or update a custom domain. Can reserve a name (omit deployment), link it to a deployment, switch deployments, or update labels. After creating, call domains_records and show the DNS records to the user.',
-        annotations: WRITE,
+        description: 'Create or update a custom domain. Can reserve a name (omit deployment), link it to a deployment, switch deployments, or update labels. domains_records then returns the DNS records to configure.',
+        annotations: annotate(TOOLS.domains_set),
         inputSchema: {
             domain: z.string().describe('Domain name (e.g. "www.example.com" or "blog.example.com")'),
             deployment: z
@@ -162,13 +189,13 @@ export function registerAccountTools(server, ship, call) {
     server.registerTool('domains_list', titled({
         title: 'List Domains',
         description: `List all domains with their URLs, linked deployment, and verification status.${PAGING_NOTE}`,
-        annotations: READ,
+        annotations: annotate(TOOLS.domains_list),
         inputSchema: PAGINATION_INPUT,
     }), ({ limit, cursor }) => call(() => ship.domains.list({ limit, cursor })));
     server.registerTool('domains_get', titled({
         title: 'Get Domain',
         description: 'Get domain details including URL, linked deployment, verification status, and labels.',
-        annotations: READ,
+        annotations: annotate(TOOLS.domains_get),
         inputSchema: {
             domain: z
                 .string()
@@ -177,8 +204,8 @@ export function registerAccountTools(server, ship, call) {
     }), ({ domain }) => call(() => ship.domains.get(domain)));
     server.registerTool('domains_records', titled({
         title: 'Get DNS Records',
-        description: 'Get the DNS records the user needs to configure at their DNS provider. Call after domains_set. You MUST show the returned records to the user.',
-        annotations: READ,
+        description: "Returns the DNS records to configure at the domain's DNS provider. Call after domains_set.",
+        annotations: annotate(TOOLS.domains_records),
         inputSchema: {
             domain: z
                 .string()
@@ -186,19 +213,19 @@ export function registerAccountTools(server, ship, call) {
         },
     }), ({ domain }) => call(() => ship.domains.records(domain)));
     server.registerTool('domains_dns', titled({
-        title: 'Look Up DNS Provider',
-        description: 'Look up the DNS provider for a domain (e.g. Cloudflare, Namecheap). Helps the user know where to configure their DNS records.',
-        annotations: READ,
+        title: 'Get DNS Provider',
+        description: 'Returns the DNS provider recorded for the domain, if known (e.g. Cloudflare, Namecheap): where its DNS records are configured.',
+        annotations: annotate(TOOLS.domains_dns),
         inputSchema: {
             domain: z
                 .string()
-                .describe('Domain name to look up DNS provider for (e.g. "www.example.com")'),
+                .describe('Domain name (e.g. "www.example.com"). Must be a domain previously created with domains_set.'),
         },
     }), ({ domain }) => call(() => ship.domains.dns(domain)));
     server.registerTool('domains_share', titled({
         title: 'Share DNS Setup',
-        description: 'Get a shareable DNS setup link for a domain. Share the link with the user so they, or whoever manages their DNS, can view the required records without needing an API key.',
-        annotations: READ,
+        description: "Returns a shareable DNS setup URL that needs no API key, for whoever manages the domain's DNS.",
+        annotations: annotate(TOOLS.domains_share),
         inputSchema: {
             domain: z
                 .string()
@@ -208,7 +235,7 @@ export function registerAccountTools(server, ship, call) {
     server.registerTool('domains_validate', titled({
         title: 'Check Domain Availability',
         description: 'Check if a domain name is valid and available before creating it. Returns the normalized form and availability.',
-        annotations: READ,
+        annotations: annotate(TOOLS.domains_validate),
         inputSchema: {
             domain: z
                 .string()
@@ -218,7 +245,7 @@ export function registerAccountTools(server, ship, call) {
     server.registerTool('domains_verify', titled({
         title: 'Verify Domain DNS',
         description: 'Trigger DNS verification for a custom domain. Call after the user has configured DNS records from domains_records. Verification is asynchronous — the domain status updates once DNS propagates.',
-        annotations: WRITE,
+        annotations: annotate(TOOLS.domains_verify),
         inputSchema: {
             domain: z
                 .string()
@@ -227,8 +254,8 @@ export function registerAccountTools(server, ship, call) {
     }), ({ domain }) => call(() => ship.domains.verify(domain)));
     server.registerTool('domains_delete', titled({
         title: 'Delete Domain',
-        description: 'Permanently delete a domain. You MUST confirm with the user before calling this tool, referencing the domain name.',
-        annotations: DESTRUCTIVE,
+        description: 'Permanently deletes a domain.',
+        annotations: annotate(TOOLS.domains_delete),
         inputSchema: {
             domain: z.string().describe('Domain name to delete (e.g. "www.example.com")'),
         },
@@ -236,7 +263,7 @@ export function registerAccountTools(server, ship, call) {
     // Account
     server.registerTool('whoami', titled({
         title: 'Show Account',
-        description: 'Show authenticated account details including email, plan, and usage.',
-        annotations: READ,
-    }), () => call(() => ship.whoami()));
+        description: "Returns the account's email, name, plan, current usage and plan caps.",
+        annotations: annotate(TOOLS.whoami),
+    }), () => call(() => ship.whoami().then(accountSummary)));
 }

package/dist/vocabulary.d.ts

@@ -103,43 +103,53 @@ export declare const UPLOAD_TOOL_TITLE = "Deploy Static Site";
  */
 export declare const PUBLIC_EXPIRY: string;
 /**
- * MCP tool annotations by kind of operation. An agent reads these to decide
- * whether it may call speculatively (`readOnlyHint`), whether a retry is free
- * (`idempotentHint`), and whether it must confirm with the user first
- * (`destructiveHint`).
- *
- * **`CREATE` carries no `idempotentHint`, deliberately.** A deploy creates a
- * new deployment on every call. `idempotencyKey` makes a retry replay the
- * original instead — but that property is conditional on an argument the
- * caller may not pass, while the annotation is static per tool. Advertising it
- * would promise every agent that any retry is free, which is exactly false for
- * the keyless caller, and an annotation an agent trusts wrongly is worse than
- * one it never reads.
+ * What is true of one tool, on the three axes a host reads.
+ *
+ * One row per tool lives in the registry (`tools.ts`, `TOOLS`), and every
+ * other statement about the tool is derived from it: the MCP annotations
+ * (`annotate`), the account-tool set (and so the hosted door's
+ * `securitySchemes` and challenge scope), the listing justifications in
+ * `integrations/gpt`, and the catalogue tests. Until 1.11.0 these facts had
+ * three owners: four annotation classes here, a hand-written name list for
+ * the auth need, and the upload tool annotated by hand on both transports.
+ * Three owners for facts about one tool is how the classes came to spread
+ * `openWorldHint: true` over ten reads that touch nothing public.
+ */
+export interface ToolContract {
+    /** `optional`: works without an account, does more with one. */
+    auth: 'optional' | 'required';
+    /**
+     * What a call does to the platform's state. `add` creates something new
+     * on every call; `replace` overwrites what is there; `remove` deletes it.
+     */
+    mutation: 'none' | 'add' | 'replace' | 'remove';
+    /** Whether the call changes public internet state, or only the account's. */
+    reach: 'account' | 'public';
+}
+/**
+ * The MCP annotations a tool's contract implies. An agent reads them to
+ * decide whether it may call speculatively (`readOnlyHint`), whether it must
+ * confirm with the user first (`destructiveHint`), whether a retry is free
+ * (`idempotentHint`), and whether the call reaches beyond the account
+ * (`openWorldHint`). Both hosts read the same four: Anthropic's review asks
+ * for an accurate `readOnlyHint` and `destructiveHint`, OpenAI additionally
+ * reads `openWorldHint` as "can change public state".
+ *
+ * **`idempotentHint` is promised only for a remove**, the one mutation where
+ * a repeat is MEASURED to have no further effect (both deletes are fenced in
+ * the API: a repeat neither flips state nor writes an audit row). A replace
+ * writes an activity row per call, and `domains_set` notifies and may enqueue
+ * DNS work besides, so it is not claimed. An add creates on every call, and
+ * `idempotencyKey` cannot rescue the claim: that property is conditional on
+ * an argument the caller may not pass, while the annotation is static per
+ * tool. Reads carry none because the spec defines the hint only for tools
+ * that mutate.
  */
-export declare const ANNOTATIONS: {
-    readonly READ: {
-        readonly openWorldHint: true;
-        readonly readOnlyHint: true;
-        readonly destructiveHint: false;
-        readonly idempotentHint: true;
-    };
-    readonly CREATE: {
-        readonly openWorldHint: true;
-        readonly readOnlyHint: false;
-        readonly destructiveHint: false;
-    };
-    readonly WRITE: {
-        readonly openWorldHint: true;
-        readonly readOnlyHint: false;
-        readonly destructiveHint: false;
-        readonly idempotentHint: true;
-    };
-    readonly DESTRUCTIVE: {
-        readonly openWorldHint: true;
-        readonly readOnlyHint: false;
-        readonly destructiveHint: true;
-        readonly idempotentHint: true;
-    };
+export declare function annotate({ mutation, reach }: ToolContract): {
+    readonly openWorldHint: boolean;
+    readonly idempotentHint?: boolean | undefined;
+    readonly readOnlyHint: boolean;
+    readonly destructiveHint: boolean;
 };
 /**
  * One title, two wire slots: project a tool config's top-level `title` into
@@ -178,7 +188,14 @@ export declare function titled<C extends {
  */
 export declare const INSTRUCTION_BLOCKS: {
     readonly opening: "ShipStatic deploys static websites instantly. Free, no account required.";
-    readonly liveAndPassword: "The site is live immediately. To make the site private, pass `password` — visitors must unlock before viewing, including on any custom domains pointing at it.";
+    /**
+     * The password read-back rule lives HERE and not in the upload
+     * description: a password the user never sees locks them out, and
+     * `instructions` is the one place a server may say what an agent should
+     * do. A tool description describes the tool; both listing reviews reject
+     * one that instructs the model, and the catalogue tests grep for it.
+     */
+    readonly liveAndPassword: "The site is live immediately. To make the site private, pass `password`; visitors must unlock before viewing, including on any custom domains pointing at it. Tell the user any password you set, since one they never see locks them out.";
     readonly claim: "The response includes a claim URL — always show the deployment URL and the claim URL to the user so they can keep the site permanently.";
     readonly conceptsHeader: "Concepts:";
     readonly deploymentConcept: "- Deployment: an immutable set of files with an instant URL (e.g. happy-cat-abc1234.shipstatic.com). No setup needed.";
@@ -201,8 +218,12 @@ export declare const INSTRUCTION_BLOCKS: {
 export declare const DESCRIPTION_BLOCKS: {
     /** The no-account promise, mid-sentence in both openings. */
     readonly free: "free, no account or API key required";
-    /** The password read-back rule — a password the user never sees locks them out. */
-    readonly password: "To make the site private, pass `password`; always show the password to the user if you set one.";
+    /**
+     * The option, stated as a capability. The read-back rule that used to
+     * follow it ("always show the password to the user") is behavioural
+     * guidance, which belongs to `INSTRUCTION_BLOCKS.liveAndPassword`.
+     */
+    readonly password: "Pass `password` to make the site private.";
 };
 /**
  * Deploy-parameter descriptions shared by both transports.

package/dist/vocabulary.js

@@ -104,27 +104,33 @@ export const UPLOAD_TOOL_TITLE = 'Deploy Static Site';
  * sentence someone must rewrite, not a number that silently rounds.
  */
 export const PUBLIC_EXPIRY = `${PUBLIC_DEPLOYMENT_TTL_SECONDS / 86_400} days`;
-const OPEN_WORLD = { openWorldHint: true };
 /**
- * MCP tool annotations by kind of operation. An agent reads these to decide
- * whether it may call speculatively (`readOnlyHint`), whether a retry is free
- * (`idempotentHint`), and whether it must confirm with the user first
- * (`destructiveHint`).
- *
- * **`CREATE` carries no `idempotentHint`, deliberately.** A deploy creates a
- * new deployment on every call. `idempotencyKey` makes a retry replay the
- * original instead — but that property is conditional on an argument the
- * caller may not pass, while the annotation is static per tool. Advertising it
- * would promise every agent that any retry is free, which is exactly false for
- * the keyless caller, and an annotation an agent trusts wrongly is worse than
- * one it never reads.
+ * The MCP annotations a tool's contract implies. An agent reads them to
+ * decide whether it may call speculatively (`readOnlyHint`), whether it must
+ * confirm with the user first (`destructiveHint`), whether a retry is free
+ * (`idempotentHint`), and whether the call reaches beyond the account
+ * (`openWorldHint`). Both hosts read the same four: Anthropic's review asks
+ * for an accurate `readOnlyHint` and `destructiveHint`, OpenAI additionally
+ * reads `openWorldHint` as "can change public state".
+ *
+ * **`idempotentHint` is promised only for a remove**, the one mutation where
+ * a repeat is MEASURED to have no further effect (both deletes are fenced in
+ * the API: a repeat neither flips state nor writes an audit row). A replace
+ * writes an activity row per call, and `domains_set` notifies and may enqueue
+ * DNS work besides, so it is not claimed. An add creates on every call, and
+ * `idempotencyKey` cannot rescue the claim: that property is conditional on
+ * an argument the caller may not pass, while the annotation is static per
+ * tool. Reads carry none because the spec defines the hint only for tools
+ * that mutate.
  */
-export const ANNOTATIONS = {
-    READ: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, ...OPEN_WORLD },
-    CREATE: { readOnlyHint: false, destructiveHint: false, ...OPEN_WORLD },
-    WRITE: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, ...OPEN_WORLD },
-    DESTRUCTIVE: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, ...OPEN_WORLD },
-};
+export function annotate({ mutation, reach }) {
+    return {
+        readOnlyHint: mutation === 'none',
+        destructiveHint: mutation === 'replace' || mutation === 'remove',
+        ...(mutation === 'remove' ? { idempotentHint: true } : {}),
+        openWorldHint: reach === 'public',
+    };
+}
 /**
  * One title, two wire slots: project a tool config's top-level `title` into
  * `annotations.title` at registration.
@@ -161,7 +167,14 @@ export function titled(config) {
  */
 export const INSTRUCTION_BLOCKS = {
     opening: 'ShipStatic deploys static websites instantly. Free, no account required.',
-    liveAndPassword: 'The site is live immediately. To make the site private, pass `password` — visitors must unlock before viewing, including on any custom domains pointing at it.',
+    /**
+     * The password read-back rule lives HERE and not in the upload
+     * description: a password the user never sees locks them out, and
+     * `instructions` is the one place a server may say what an agent should
+     * do. A tool description describes the tool; both listing reviews reject
+     * one that instructs the model, and the catalogue tests grep for it.
+     */
+    liveAndPassword: 'The site is live immediately. To make the site private, pass `password`; visitors must unlock before viewing, including on any custom domains pointing at it. Tell the user any password you set, since one they never see locks them out.',
     claim: 'The response includes a claim URL — always show the deployment URL and the claim URL to the user so they can keep the site permanently.',
     conceptsHeader: 'Concepts:',
     deploymentConcept: '- Deployment: an immutable set of files with an instant URL (e.g. happy-cat-abc1234.shipstatic.com). No setup needed.',
@@ -184,8 +197,12 @@ export const INSTRUCTION_BLOCKS = {
 export const DESCRIPTION_BLOCKS = {
     /** The no-account promise, mid-sentence in both openings. */
     free: 'free, no account or API key required',
-    /** The password read-back rule — a password the user never sees locks them out. */
-    password: 'To make the site private, pass `password`; always show the password to the user if you set one.',
+    /**
+     * The option, stated as a capability. The read-back rule that used to
+     * follow it ("always show the password to the user") is behavioural
+     * guidance, which belongs to `INSTRUCTION_BLOCKS.liveAndPassword`.
+     */
+    password: 'Pass `password` to make the site private.',
 };
 /**
  * Deploy-parameter descriptions shared by both transports.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipstatic/mcp",
-  "version": "1.10.2",
+  "version": "1.11.0-beta.1",
   "mcpName": "com.shipstatic/mcp",
   "description": "Deploy static websites, landing pages, and prototypes instantly from AI agents. Start with the hosted endpoint at mcp.shipstatic.com (no install, no signup, no API key), or install this package to deploy folders from your own machine. The same fifteen tools either way.",
   "type": "module",