mcplane 0.5.1 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.6.0
+
+New ChatGPT checks
+- `server.widget-domain` (blocks): tools with a UI name resources (`_meta.ui.resourceUri` or `openai/outputTemplate`), and each one must set a widget domain, which OpenAI requires before you can submit a plugin with UI. Preflight now reads those resources; one that needs sign-in is skipped unless you pass `--token`. `openai/widgetDomain` and `ui.domain` both count.
+- `tools.file-viewer-wording` (warning): a tool with a file entrypoint described as a command ("Opens an HTML file…"). The model then calls it with a file path and ChatGPT refuses the read ("MCP app cannot read resource outside its widget scope"), as Stacktree's viewer did on 6 October. Say the user opens the file and name the tool for content the model can read.
+- `tools.sensitive-inputs`: an input called `password` that's really a passcode for something the tool makes gets the advice to call it `passcode`. ChatGPT's approval panel files `password` under "Account passwords".
+
+ChatGPT pack
+- Upload a new version from the plugin's own page (**Upload new version**, or **Upload plugin to make changes**). The Plugins page's upload area creates a second plugin even when the package name matches, which is how Stacktree ended up with two.
+- Published tool changes don't arrive on cue: on 6 October a Rescan left a published plugin's tool table on its reviewed list, and a published plugin's MCP card has no Reconnect. Check the MCPs tab lists new tools before submitting test cases that use them.
+- Don't fix a duplicate by deleting and uploading again: deleting can reserve the plugin's name (openai/codex#39508).
+
+Fewer false alarms
+- `tools.destructive-overwrite` skips verbs whose subject is a sibling tool ("update_site replaces a page in place" in another tool's description) and, like `tools.destructive-option`, expiry on a tool that creates. Stacktree's publish_html, which passed ChatGPT's scan, no longer warns.
+
+README
+- 2026-07-28 cache hints: a `tools/list` that differs by caller should be `cacheScope: "private"`.
+
 ## 0.5.1
 
 New ChatGPT checks (warnings)

package/README.md

@@ -89,10 +89,10 @@ npx mcplane fleet --root ~/Projects
 
 Checks come from real rejections, most of them ours:
 
-- **Server**: `initialize`, `tools/list` and `ping` work. An OAuth server that initializes without a token also lists its tools without one (the half-way state leaves a new ChatGPT connector stuck on "no actions available"). Unknown methods return `-32601` (OpenAI's tool scan probes `server/discover` and gives up on a crash). The URL works with a trailing slash. CORS preflight answers. Automated clients aren't blocked by a bot filter. A TLS 1.2 client connects. DNS doesn't advertise Encrypted ClientHello, which review proxies reset without a trace in your logs.
+- **Server**: `initialize`, `tools/list` and `ping` work. An OAuth server that initializes without a token also lists its tools without one (the half-way state leaves a new ChatGPT connector stuck on "no actions available"). Unknown methods return `-32601` (OpenAI's tool scan probes `server/discover` and gives up on a crash). The URL works with a trailing slash. CORS preflight answers. Automated clients aren't blocked by a bot filter. A TLS 1.2 client connects. DNS doesn't advertise Encrypted ClientHello, which review proxies reset without a trace in your logs. Tools with a UI name resources that set a widget domain, which OpenAI requires before you can submit a plugin with UI.
 - **OAuth**: unauthenticated calls get `401` with `resource_metadata`. Protected-resource and authorization-server metadata resolve, and PKCE S256 is supported. With `--register`, Dynamic Client Registration is tested, including the `cursor://` and other native redirect schemes that locked out every desktop client for us.
 - **Sign-in chain**: plain GETs, the way a reviewer's browser goes: the authorization endpoint, the sign-in page it sends people to, and the identity-provider hosts that page loads. A bot challenge (`cf-mitigated: challenge`) or a 403 anywhere on it is flagged: every MCP check can pass while reviewers never reach your sign-in page. Nothing signs in and no client is registered, so an authorization server that wants a registered client stops the walk at its error page: name your sign-in pages in `server.signIn` (or `--sign-in <url>`) and they're checked too. A pass from your own network proves less than one from a cloud VM or CI.
-- **Tools**: every tool has a title and explicit `readOnlyHint`, `destructiveHint` and `openWorldHint`, and the hints are consistent. Tools declare `outputSchema`. Descriptions don't instruct the model. Writes aren't authorised by a token passed through the chat (Anthropic rejected exactly that). Hints follow OpenAI's current definitions: `openWorldHint` for public or open-ended destinations (read-only web search included; connectivity alone doesn't decide it), `destructiveHint` for messages that can't be unsent, for overwriting, revoking access or deleting, and for destructive options in the input schema (ChatGPT's scan flagged a non-destructive publish tool for offering `burn_after_read`). No catch-all request tools, no tool names over 64 characters, no sensitive inputs, no upgrade or pricing copy. Tools that move money or handle crypto wallets are flagged for ChatGPT, whose submit step has you attest to neither.
+- **Tools**: every tool has a title and explicit `readOnlyHint`, `destructiveHint` and `openWorldHint`, and the hints are consistent. Tools declare `outputSchema`. Descriptions don't instruct the model. Writes aren't authorised by a token passed through the chat (Anthropic rejected exactly that). Hints follow OpenAI's current definitions: `openWorldHint` for public or open-ended destinations (read-only web search included; connectivity alone doesn't decide it), `destructiveHint` for messages that can't be unsent, for overwriting, revoking access or deleting, and for destructive options in the input schema (ChatGPT's scan flagged a non-destructive publish tool for offering `burn_after_read`). No catch-all request tools, no tool names over 64 characters, no sensitive inputs, no upgrade or pricing copy. Tools that move money or handle crypto wallets are flagged for ChatGPT, whose submit step has you attest to neither. File viewers say the user opens the file: described as a command, the model calls one with a path and ChatGPT refuses the read.
 - **Listing**: the icon is square and at least 512px behind a direct link (PNG, JPEG, WebP or SVG, measured from the bytes), and `/favicon.ico` resolves. The privacy policy covers collection, retention and user controls. Support is a web page. Name, subtitle, one-liner, description and starter prompts fit each store's limits, including the 1,024 characters the ChatGPT package allows for its root description. Every test case uses tools the live server actually has. The ChatGPT domain challenge is served.
 - **Plugin repo**: public, on GitHub, with `.claude-plugin/plugin.json`, and no root `SKILL.md` shadowing the plugin's skills. Grok plugins come from an organisation.
 - **Vercel Connect**: what its [For Service Providers](https://vercel.com/docs/connect/providers) page asks for, read from your discovery documents alone (nothing is registered). Required items block: metadata served as JSON (at the path-suffixed form when the issuer has a path), `token_endpoint`, `grant_types_supported`, and OAuth and OpenID Connect documents that agree. Recommended items warn: DCR or CIMD so Connect can create the client, a `token_endpoint_auth_methods_supported` it can use, PKCE S256, refresh tokens. Optional ones are notes: protected-resource metadata, `revocation_endpoint`, `scopes_supported`. What needs a real token (`expires_in`, refresh rotation, the `https://connect.vercel.com/callback` redirect) is on the list of things to check yourself.
@@ -125,6 +125,8 @@ Readiness for MCP 2026-07-28 (never blocking)
 
 Servers behind sign-in need `--token` for the probes; the authorization checks run from the discovery documents either way.
 
+One thing preflight can't see: 2026-07-28 results carry cache hints, and `tools/list` is one of the results that must. If your list differs by caller, for example tools you hide from ChatGPT connections, mark it `cacheScope: "private"`, or a shared cache can hand one client another's list.
+
 ## ARD manifest
 
 `mcplane pack ard` writes `.mcplane/packs/ard/ard.json`: one entry for your server (`application/mcp-server-card+json`, pointing at your server card when you serve one), with representative queries from your prompts and tests and capabilities from your tool names. It validates against [ARD v0.91](https://agenticresourcediscovery.org/spec/) and against the older schema [Lighthouse 13.5](https://github.com/GoogleChrome/lighthouse/blob/v13.5.0/core/audits/agentic/ard-schema.js) audits. Serve it at `/.well-known/ard.json`, and either at `/.well-known/ai-catalog.json` too or from an `Agentmap:` line in robots.txt, which Lighthouse reads first. ARD is a proposal, so treat it as cheap insurance rather than a requirement.
@@ -197,7 +199,7 @@ Since DevDay (September 2026) ChatGPT takes a plugin ZIP. `mcplane pack chatgpt`
 - **Behind sign-in**: the ZIP doesn't need your tool list, so `pack chatgpt` builds without `--token` and says what it couldn't check. `--tools <file>` takes a saved `tools/list` result instead.
 - The ZIP is reproducible: entries are dated 1980-01-01 and carry Unix modes, so the same files give the same bytes.
 
-What stays with you: upload the ZIP, enter reviewer credentials and make the attestations. Bump `version` for every upload. Tool changes don't need a new ZIP; OpenAI's scans pick them up, and `drift` tracks extension metadata (sidebar, panels, file viewers) as part of each tool.
+What stays with you: upload the ZIP, enter reviewer credentials and make the attestations. Bump `version` for every upload, and upload a new version from the plugin's own page: the Plugins page's upload area makes a second plugin. Tool changes don't need a new ZIP; OpenAI says its scans pick them up after automated checks, though not on cue (check the MCPs tab before you submit test cases that use new tools), and `drift` tracks extension metadata (sidebar, panels, file viewers) as part of each tool.
 
 **Annotation rules.** OpenAI's [plugin guidelines](https://developers.openai.com/plugins/plugin-guidelines) now ask only for explicit `readOnlyHint`, `destructiveHint` and `openWorldHint` booleans on every tool; its automated review checks them, and you appeal if it flags one you believe is right. Justifications are no longer required, so the pack no longer drafts them: any you wrote in `mcplane.json` become optional appeal notes. Writes count as destructive unless they only add (overwriting, cancelling, revoking access and irreversible sends are all destructive, and an undo button doesn't change that), and preflight warns when a write that overwrites, revokes or deletes says `destructiveHint: false`, or offers an option that does. To keep such an option for other clients, stop advertising it in the schema you serve ChatGPT. `openWorldHint` is about where a tool reaches, not whether it calls an API. A hint change is a note in `drift`, not an action: OpenAI re-checks annotations itself, so `drift --ci` doesn't fail on one.
 

package/dist/checks/readiness.js

@@ -106,7 +106,7 @@ export function initializeCheck(r, era) {
 export function modernHeaderCheck(r) {
     const title = 'Accepts the Mcp-Method and Mcp-Name headers';
     return r && r.status < 300 && r.body?.result
-        ? check('headers', 'pass', title, { detail: 'a 2026-07-28 tools/list with Mcp-Method works (Mcp-Name only goes on tools/call, resources/read and prompts/get, which mcplane doesn’t call)' })
+        ? check('headers', 'pass', title, { detail: 'a 2026-07-28 tools/list with Mcp-Method works (Mcp-Name only goes on tools/call, resources/read and prompts/get, which this probe doesn’t send)' })
         : check('headers', 'warn', title, { detail: `a 2026-07-28 tools/list with Mcp-Method got ${said(r)}`, fix: 'Mcp-Method is required on every 2026-07-28 POST and must match the body’s method.' });
 }
 /** Legacy servers: the same tools/list with and without the new headers should get the same answer. */

package/dist/checks/server.js

@@ -60,6 +60,38 @@ export async function serverChecks(url, auth, token, extra = []) {
         checks.push(tools.length
             ? { id: 'server.tools', level: 'pass', title: 'tools/list returns tools', detail: tools.map((t) => t.name).join(', ') }
             : { id: 'server.tools', level: 'fail', title: 'tools/list returns tools', detail: `HTTP ${list?.status ?? 'error'}`, fix: 'Stores scan tools/list; with no tools there is nothing to list.' });
+        // Tools with UI name an MCP App resource (_meta.ui.resourceUri, or openai/outputTemplate). OpenAI requires a
+        // dedicated widget domain on each one when you submit a plugin with UI, unique per plugin. Set it as
+        // _meta["openai/widgetDomain"] on the resource: ui.domain also counts, but its format differs by host (Claude
+        // expects its own hash-derived domain there).
+        const uiUris = [...new Set(tools.flatMap((t) => {
+                const meta = (t._meta ?? {});
+                return [meta.ui?.resourceUri, meta['openai/outputTemplate']].filter((u) => typeof u === 'string');
+            }))];
+        if (uiUris.length) {
+            const missing = [];
+            const unread = [];
+            let denied = 0;
+            for (const uri of uiUris) {
+                const read = await client.request('resources/read', { uri }).catch(() => null);
+                if (read?.status === 401 || read?.status === 403) {
+                    denied++;
+                    continue;
+                }
+                const content = read?.body?.result?.contents?.[0];
+                if (!content)
+                    unread.push(uri);
+                else if (!content._meta?.['openai/widgetDomain'] && !content._meta?.ui?.domain)
+                    missing.push(uri);
+            }
+            checks.push(denied === uiUris.length
+                ? { id: 'server.widget-domain', level: 'skip', title: 'UI resources set a widget domain', detail: 'resources/read needs sign-in; run preflight with --token to check', stores: ['chatgpt'] }
+                : missing.length
+                    ? { id: 'server.widget-domain', level: 'fail', title: 'UI resources set a widget domain', detail: missing.join(', '), fix: 'Set _meta["openai/widgetDomain"] (for example "https://yourdomain.com") on each UI resource. OpenAI requires a dedicated, per-plugin widget domain to submit a plugin with UI.', stores: ['chatgpt'] }
+                    : unread.length === uiUris.length
+                        ? { id: 'server.widget-domain', level: 'warn', title: 'UI resources set a widget domain', detail: `resources/read gave nothing for ${unread.join(', ')}`, fix: 'Tools name UI resources that resources/read does not return. ChatGPT reads them the same way to show the UI.', stores: ['chatgpt'] }
+                        : { id: 'server.widget-domain', level: 'pass', title: 'UI resources set a widget domain', detail: uiUris.filter((u) => !unread.includes(u)).join(', '), stores: ['chatgpt'] });
+        }
         const ping = await client.request('ping').catch(() => null);
         checks.push({
             id: 'server.ping',

package/dist/checks/tools.js

@@ -34,18 +34,23 @@ const CRYPTO = /\b(crypto(?:currenc(?:y|ies))?|wallets?|on[\s-]?chain|blockchain
  * links aren't money movement, and neither is a purchase history or a hotel's check-out date.
  */
 const MONEY = /\b(transfer(?:s|ring)? (?:the |your )?(?:funds|money|payments?)|send(?:s|ing)? (?:a |the |your )?(?:money|funds|payments?)|(?:make|makes|making|complete|completes|process|processes|processing|submit|submits|execute|executes) (?:a |the )?(?:payments?|purchases?)|pay(?:s|ing)? (?:an? |the |your )?(?:invoices?|bills?)|charg(?:e|es|ing) (?:a |the |their |your )?(?:cards?|customers?)|refund(?:s|ing)? (?:an? |the |their |your )?(?:customers?|orders?|payments?|charges?)|issu(?:e|es|ing) (?:a )?refunds?|(?:withdraw|deposit)(?:s|ing)? (?:funds|money)|(?:purchas(?:e|es|ing)|buy(?:s|ing)?) (?:an?|the|this|it)|checkouts?(?![\s_-]*(?:date|time|day)))\b/gi;
-/** The words a pattern finds in text, skipping negated ones ("never overwrites"). */
-function mentions(text, re) {
+/**
+ * The words a pattern finds in text, skipping negated ones ("never overwrites") and ones whose subject is another
+ * tool: "(update_site replaces a page in place)" describes update_site, not the tool being checked.
+ */
+function mentions(text, re, others = []) {
     const found = new Set();
+    const subject = others.length ? new RegExp(`\\b(${others.map((n) => n.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|')})\\b(\\s+\\w+){0,2}\\s*$`, 'i') : null;
     for (const m of text.matchAll(re)) {
-        if (NEGATED.test(text.slice(Math.max(0, m.index - 40), m.index)))
+        const before = text.slice(Math.max(0, m.index - 40), m.index);
+        if (NEGATED.test(before) || subject?.test(before))
             continue;
         found.add(m[0].toLowerCase().replace(/\s+/g, ' '));
     }
     return [...found];
 }
-/** The destructive words in a tool's name, title and description. */
-const destructiveWords = (text) => mentions(text, DESTRUCTIVE);
+/** The destructive words in a tool's name, title and description, given the names of its sibling tools. */
+const destructiveWords = (text, others = []) => mentions(text, DESTRUCTIVE, others);
 /** A name as words: set_password and setPassword both read "set password". */
 const words = (name) => name.replace(/[_-]+/g, ' ').replace(/([a-z])([A-Z])/g, '$1 $2');
 /** A tool's input properties and the ones a level down (an object's properties, an array's items), by path. */
@@ -148,10 +153,14 @@ export function toolChecks(tools) {
     }
     // The same definition covers overwriting, revoking access and deleting; an undo doesn't change that.
     // Conservative: explicit write tools whose own words say so, negated mentions ("never overwrites") excluded.
+    // Expiry follows the destructive-option rule below: on a tool that creates, it bounds what the call adds.
+    // Stacktree's publish_html ("plan-aware expiry", "update_site replaces a page in place") passed ChatGPT's scan.
     const destroys = tools.flatMap((t) => {
         if (t.annotations?.readOnlyHint !== false || t.annotations?.destructiveHint !== false)
             return [];
-        const found = destructiveWords(`${words(t.name)} ${t.title ?? ''} ${t.description ?? ''}`);
+        const creates = CREATES.test(words(t.name));
+        const others = tools.filter((o) => o !== t).map((o) => o.name);
+        const found = destructiveWords(`${words(t.name)} ${t.title ?? ''} ${t.description ?? ''}`, others).filter((w) => !(creates && w.startsWith('expir')));
         return found.length ? [`${t.name} (${found.join(', ')})`] : [];
     });
     if (destroys.length) {
@@ -225,7 +234,10 @@ export function toolChecks(tools) {
         .filter((k) => /(ssn|social_security|passport|national_id|tax_id|credit_card|card_number|cvv|iban|password|mfa|otp|2fa|diagnos|medical|health_record|biometric|fingerprint)/i.test(k))
         .map((k) => `${t.name}.${k}`));
     if (sensitive.length) {
-        checks.push({ id: 'tools.sensitive-inputs', level: 'fail', title: 'Tools don’t ask for sensitive data', detail: sensitive.join(', '), fix: 'OpenAI flags inputs that request PHI, card data, SSNs, credentials, MFA codes, government IDs or biometrics unless strictly necessary. Remove them or justify them in the submission.', stores: ['chatgpt'] });
+        const passcode = sensitive.some((s) => /\.password$/i.test(s))
+            ? ' If a password input is really a passcode for a page or file the tool makes, name it passcode: ChatGPT’s approval panel files an argument called password under "Account passwords", which reads as a credential request. Accepting both names on the server keeps older clients working.'
+            : '';
+        checks.push({ id: 'tools.sensitive-inputs', level: 'fail', title: 'Tools don’t ask for sensitive data', detail: sensitive.join(', '), fix: `OpenAI flags inputs that request PHI, card data, SSNs, credentials, MFA codes, government IDs or biometrics unless strictly necessary. Remove them or justify them in the submission.${passcode}`, stores: ['chatgpt'] });
     }
     const upsell = tools.filter((t) => UPSELL.test(`${t.title ?? ''} ${t.annotations?.title ?? ''} ${t.description ?? ''}`));
     checks.push(upsell.length
@@ -235,5 +247,22 @@ export function toolChecks(tools) {
     const ext = tools.flatMap((t) => ((t._meta?.['openai/ui']?.entrypoints) ?? []).map((e) => `${t.name}: ${e.type}${e.extensions?.length ? ` (${e.extensions.join(', ')})` : ''}`));
     if (ext.length)
         checks.push({ id: 'tools.extensions', level: 'pass', title: 'ChatGPT extensions declared', detail: ext.join('; '), stores: ['chatgpt'] });
+    // A file viewer opens when the user opens a file, and ChatGPT passes it an opaque resource URI. Described as a command
+    // ("Opens an HTML file in…"), the model calls it itself with a file path, and ChatGPT refuses the read ("MCP app cannot
+    // read resource outside its widget scope"). Seen with Stacktree's open_html_file in ChatGPT desktop, 6 Oct 2026.
+    const fileViewers = tools.filter((t) => ((t._meta?.['openai/ui']?.entrypoints) ?? []).some((e) => e.type === 'file'));
+    if (fileViewers.length) {
+        const invites = fileViewers.filter((t) => !/(user opens|when (the |a )?user opens|path does not work|not a (file )?path|opaque)/i.test(t.description ?? ''));
+        checks.push(invites.length
+            ? {
+                id: 'tools.file-viewer-wording',
+                level: 'warn',
+                title: 'File viewers say the user opens the file',
+                detail: invites.map((t) => t.name).join(', '),
+                fix: 'Say that ChatGPT calls this when the user opens a file, that a file path does not work here, and which tool the model should use instead for a file it can read (Stacktree points at publish_html). Otherwise the model calls the viewer with a path and the user sees ChatGPT refuse the read.',
+                stores: ['chatgpt'],
+            }
+            : { id: 'tools.file-viewer-wording', level: 'pass', title: 'File viewers say the user opens the file', stores: ['chatgpt'] });
+    }
     return checks;
 }

package/dist/packs.js

@@ -289,7 +289,8 @@ export async function chatgptPack(m, opts = {}) {
     const steps = `# ChatGPT submission: ${m.title} ${m.version ?? ''}
 
 ## 1. Upload the package
-platform.openai.com/plugins → **Upload new or existing plugin** → choose your verified developer identity → upload \`${zipName}\`.
+- **First version:** platform.openai.com/plugins → **Upload new or existing plugin** → choose your verified developer identity → upload \`${zipName}\`.
+- **A new version of a plugin you already have:** open that plugin's page and use **Upload new version** (or **Upload plugin to make changes**). Uploading from the Plugins page instead creates a second plugin, even when the package name matches.
 It fills the listing, icons, test cases, demo video, release notes and translations${skills.names.length ? `, and adds ${skills.names.length === 1 ? 'the skill' : `${skills.names.length} skills:`} ${skills.names.join(', ')}` : ''}. To change any of them later, edit mcplane.json, bump "version" and run \`mcplane pack chatgpt\` again.${skills.names.length ? '\nSkills are scanned too, which can take up to 2 hours. If one is flagged, take it out of chatgpt.skills and upload again; skills can come back in a later version.' : ''}
 
 ## 2. Resolve findings
@@ -308,7 +309,8 @@ Hints need no justification: OpenAI's automated review checks readOnlyHint, dest
 ## Traps
 - One review can be active per plugin. To replace a package in review, cancel the review first.
 - "Submit for review" can show nothing for a while; confirm the status on the Plugins page.
-- Tool changes don't need a new package: OpenAI's scans pick them up once you're published. Listing changes do.
+- Tool changes don't need a new package: OpenAI says its scans pick them up once you're published, after automated checks. Listing changes do. Neither happens on cue: on 6 Oct 2026 a Rescan on a published plugin left its tools table at the reviewed list ("last checked yesterday") and the scanner never connected, and a published plugin's MCP card has no Reconnect. If a new version's test cases use tools added since the last review, wait until the MCPs tab lists them before you submit.
+- Don't fix a duplicate plugin by deleting it and uploading again: deleting can reserve the plugin's name for an unknown time (openai/codex#39508).
 - A rescan doesn't update a submission already in review: it keeps the tools it was submitted with. To change them, cancel the review (back to Draft), reconnect so ChatGPT rediscovers the tools, then resubmit.
 - The package takes icons up to 5 MiB, but developer mode's own icon upload (when you add the server by hand to record the demo) takes 10 KB at most.
 

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.5.1";
+export declare const VERSION = "0.6.0";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = '0.5.1';
+export const VERSION = '0.6.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcplane",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "fastlane for MCP servers: preflight against every store's rejection causes, publish where you can, prepare the rest, track every review.",
   "type": "module",
   "bin": {