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

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):
 

package/dist/index.d.ts

@@ -1,34 +1,57 @@
 /**
  * The library entry — importing this file has NO side effects.
  *
- * `bin.ts` is the executable; this is what a consumer imports. Today there is
- * one such consumer, the hosted Streamable-HTTP transport in the platform's
- * private `cloudflare/mcp`, and both transports are converging on the same
- * product: the complete toolset for authenticated callers, the anonymous
- * deploy for everyone else. "One product, two transports" is only true if one
- * of them can import the other.
+ * `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 TRANSPORT needs — nothing more.**
- * That is the rule, and it is stricter than "curated". `createServer` and the
- * configured `call` are deliberately NOT here: they are stdio's own
- * composition, they have no consumer outside `bin.ts`, and `createServer` in
- * particular builds a tool whose input is a filesystem PATH — a footgun to
- * offer a Worker. Exporting them would make this package's API "stdio's
- * internals, plus some shared bits" instead of a contract.
+ * **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 the second transport 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,
- * and `ACCOUNT_TOOL_NAMES` is what lets the hosted catalogue fence name the
- * fourteen without counting them again.
+ * 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
+ * fifteen-line entry point calling `createServer(ship, version)` 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.
+ *
+ * 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,34 +1,57 @@
 /**
  * The library entry — importing this file has NO side effects.
  *
- * `bin.ts` is the executable; this is what a consumer imports. Today there is
- * one such consumer, the hosted Streamable-HTTP transport in the platform's
- * private `cloudflare/mcp`, and both transports are converging on the same
- * product: the complete toolset for authenticated callers, the anonymous
- * deploy for everyone else. "One product, two transports" is only true if one
- * of them can import the other.
+ * `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 TRANSPORT needs — nothing more.**
- * That is the rule, and it is stricter than "curated". `createServer` and the
- * configured `call` are deliberately NOT here: they are stdio's own
- * composition, they have no consumer outside `bin.ts`, and `createServer` in
- * particular builds a tool whose input is a filesystem PATH — a footgun to
- * offer a Worker. Exporting them would make this package's API "stdio's
- * internals, plus some shared bits" instead of a contract.
+ * **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 the second transport 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,
- * and `ACCOUNT_TOOL_NAMES` is what lets the hosted catalogue fence name the
- * fourteen without counting them again.
+ * 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
+ * fifteen-line entry point calling `createServer(ship, version)` 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.
+ *
+ * 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.js

@@ -15,7 +15,7 @@ const D = DESCRIPTION_BLOCKS;
 // around its own two.
 const INSTRUCTIONS = `${B.opening}
 
-To deploy: call deployments_upload with the build output directory path. ${B.liveAndPassword}
+To deploy: call ${UPLOAD_TOOL_NAME} with the build output directory path. ${B.liveAndPassword}
 
 Without SHIP_TOKEN, deployments are public and expire in ${PUBLIC_EXPIRY}. ${B.claim}
 

package/dist/vocabulary.d.ts

@@ -27,6 +27,23 @@
  * Everything else should be here, and adding a shared fact anywhere else is
  * how the next year's drift starts.
  */
+/**
+ * Two packages, and the split is a rule rather than an accident: **read a
+ * constant from whatever will act on it.**
+ *
+ * The label, password and idempotency-key constraints come from
+ * `@shipstatic/ship` because the SDK is what validates a value against them
+ * before it reaches the wire — describing a bound the client in the same
+ * process will not honour is the drift that matters, and reading both from one
+ * module makes it impossible. `@shipstatic/types` declares them, but ship
+ * bundles its own copy, so importing them from types here would let a describe
+ * advertise a limit the validator beside it rejects.
+ *
+ * The public-deploy lifetime is the other kind of fact. Ship never reads it —
+ * the API stamps it — so there is no validator to agree with, and taking it
+ * from the package that merely forwards it would mean a ship release every
+ * time the platform's own vocabulary grows.
+ */
 /**
  * The server name every transport reports in `serverInfo`.
  *
@@ -46,18 +63,25 @@ export declare const UPLOAD_TOOL_NAME = "deployments_upload";
 /**
  * How long an anonymous deployment lives, in the words an agent reads.
  *
- * **The fact is owned by `cloudflare/api` (`DEPLOYMENT.PUBLIC_TTL`), which
- * `@shipstatic/types` does not yet export** — so this is a restatement, and it
- * is deliberately the ONLY one. It previously appeared in eight places across
- * the two servers and the widget; a TTL change had to find all eight. When
- * types exports the constant, this line becomes a derivation and nothing above
- * it moves.
+ * **Derived, since `@shipstatic/types@2.5.0-beta.19`.** It was a restatement
+ * until then, and deliberately the only one — the duration had appeared in
+ * eight places across the two servers and the widget, so a TTL change had to
+ * find all eight. Both halves of the fix landed together: types declares the
+ * number and `cloudflare/api` imports it back, because exporting without the
+ * import-back would have given the fact two owners instead of ending the
+ * duplication.
  *
  * A phrase rather than a number because every consumer is prose: the value has
- * to carry its own unit, and `PUBLIC_TTL / 86400` interpolated at eight sites
- * would restate the unit eight times instead of the number.
+ * to carry its own unit, and dividing by 86400 at eight sites would restate the
+ * unit eight times instead of the number.
+ *
+ * The unit stays literal, and that is the one assumption here: this reads
+ * correctly while the TTL is a whole number of days, which it has always been.
+ * A TTL of hours would need the prose reviewed anyway — the widget's own
+ * `formatExpires` speaks in days and hours too — so the honest failure is a
+ * sentence someone must rewrite, not a number that silently rounds.
  */
-export declare const PUBLIC_EXPIRY = "3 days";
+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

package/dist/vocabulary.js

@@ -28,6 +28,24 @@
  * how the next year's drift starts.
  */
 import { IDEMPOTENCY_KEY_CONSTRAINTS, LABEL_CONSTRAINTS, PASSWORD_CONSTRAINTS, } from '@shipstatic/ship';
+import { PUBLIC_DEPLOYMENT_TTL_SECONDS } from '@shipstatic/types';
+/**
+ * Two packages, and the split is a rule rather than an accident: **read a
+ * constant from whatever will act on it.**
+ *
+ * The label, password and idempotency-key constraints come from
+ * `@shipstatic/ship` because the SDK is what validates a value against them
+ * before it reaches the wire — describing a bound the client in the same
+ * process will not honour is the drift that matters, and reading both from one
+ * module makes it impossible. `@shipstatic/types` declares them, but ship
+ * bundles its own copy, so importing them from types here would let a describe
+ * advertise a limit the validator beside it rejects.
+ *
+ * The public-deploy lifetime is the other kind of fact. Ship never reads it —
+ * the API stamps it — so there is no validator to agree with, and taking it
+ * from the package that merely forwards it would mean a ship release every
+ * time the platform's own vocabulary grows.
+ */
 /**
  * The server name every transport reports in `serverInfo`.
  *
@@ -47,18 +65,25 @@ export const UPLOAD_TOOL_NAME = 'deployments_upload';
 /**
  * How long an anonymous deployment lives, in the words an agent reads.
  *
- * **The fact is owned by `cloudflare/api` (`DEPLOYMENT.PUBLIC_TTL`), which
- * `@shipstatic/types` does not yet export** — so this is a restatement, and it
- * is deliberately the ONLY one. It previously appeared in eight places across
- * the two servers and the widget; a TTL change had to find all eight. When
- * types exports the constant, this line becomes a derivation and nothing above
- * it moves.
+ * **Derived, since `@shipstatic/types@2.5.0-beta.19`.** It was a restatement
+ * until then, and deliberately the only one — the duration had appeared in
+ * eight places across the two servers and the widget, so a TTL change had to
+ * find all eight. Both halves of the fix landed together: types declares the
+ * number and `cloudflare/api` imports it back, because exporting without the
+ * import-back would have given the fact two owners instead of ending the
+ * duplication.
  *
  * A phrase rather than a number because every consumer is prose: the value has
- * to carry its own unit, and `PUBLIC_TTL / 86400` interpolated at eight sites
- * would restate the unit eight times instead of the number.
+ * to carry its own unit, and dividing by 86400 at eight sites would restate the
+ * unit eight times instead of the number.
+ *
+ * The unit stays literal, and that is the one assumption here: this reads
+ * correctly while the TTL is a whole number of days, which it has always been.
+ * A TTL of hours would need the prose reviewed anyway — the widget's own
+ * `formatExpires` speaks in days and hours too — so the honest failure is a
+ * sentence someone must rewrite, not a number that silently rounds.
  */
-export const PUBLIC_EXPIRY = '3 days';
+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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipstatic/mcp",
-  "version": "1.0.0-beta.5",
+  "version": "1.0.0-beta.7",
   "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",
@@ -64,11 +64,11 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
     "@shipstatic/ship": "2.0.0-beta.15",
+    "@shipstatic/types": "2.5.0-beta.20",
     "zod": "^4.4.3"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.5",
-    "@shipstatic/types": "2.5.0-beta.18",
     "@types/node": "^25.9.5",
     "@vitest/coverage-v8": "4.1.10",
     "typescript": "^6.0.3",