openai-plugin-refresh - #806

Description

Refreshes the ChatGPT/Codex stdio plugin shipped in #703 and closes the gaps found while researching #699.

StackQL is not listed in OpenAI's public plugin directory and cannot be with a stdio server: public submission requires a public streamable-HTTP MCP endpoint, OAuth 2.1 and a domain token at /.well-known/openai-apps-challenge. The GitHub marketplace route from #703 is the supported path for a local server, so this PR makes that path current and keeps it current.

Changes:

• Pin @stackql/mcp-server 0.12.732 (was 0.10.591, four releases behind; the stale pin still shipped the retired describe_resource tool).
• Stamp the pin from the shared renderer: a new openai-plugin vector in packaging/mcpb/scripts/render-platforms.sh and make openai-plugin-manifest, which npm-manifest (and therefore npm-pack) now runs, so a release cannot skip it. Runbook step 10 and both READMEs reflect this.
• validate.py enforces pin == packaging/mcpb/npm/package.json version and that the icon assets exist. The openai-stdio-plugin workflow also triggers on package.json changes, so a release PR that bumps npm without the plugin fails CI.
• Add the plugin icon (composerIcon / logo, reusing the 180 px .mcpb icon; OpenAI requires square and at least 48 px).
• listings.md gains a row for the OpenAI plugin directory with the exact blocker and install command.
• docs/chatgpt-codex-plugin.md documents the open upstream bug ChatGPT Desktop: local MCP tools are discovered successfully but not exposed to Chat sessions openai/codex#38162 (desktop Chat sessions may not expose local MCP tools; Codex threads and CLI work).
• Carried release housekeeping from the working tree: npm and PyPI manifests 0.12.718 -> 0.12.732 (0.12.732 is already published to both registries), and removal of the 19.7 MB packaging/mcpb/mcp-publisher binary that c3aaa64 committed by accident, now gitignored.

Design choices for discussion:

• The pin is stamped, not @latest. Marketplace installs are served from main, so a stamped pin keeps installs reproducible and lets the validator prove parity with the npm wrapper.
• The pin is committed together with the package.json bump, after npm publish, in the same housekeeping commit. The renderer fetches the published .sha256 files first, so it cannot run before the release assets exist.

Type of change

• Bug fix (non-breaking change to fix a bug).
• Feature (non-breaking change to add functionality).
• Breaking change.
• Other (eg: documentation change). Packaging and release-process change; no stackql binary code is touched.

Issues referenced.

• [FEATURE] Add ChatGPT App (Apps SDK) packaging and submit StackQL to the ChatGPT App Directory #699 (stays open for the public directory listing, which needs either a hosted endpoint or an OpenAI-contact exception for local MCP)
• feat: add local ChatGPT and Codex stdio plugin #703
• ChatGPT Desktop: local MCP tools are discovered successfully but not exposed to Chat sessions openai/codex#38162

Evidence

Run on Windows 11 with Codex app 26.924 / codex-cli 0.158 and node 24:

• python packaging/openai-plugin/scripts/validate.py passes.
• Renderer round trip: render-platforms.sh --version 0.12.718 --vector openai-plugin stamps both files, validate.py then fails with plugin pin and packaging/mcpb/npm/package.json versions differ, re-stamping 0.12.732 restores the files to the committed bytes.
• make -n openai-plugin-manifest VERSION=0.12.732 and make -n npm-manifest VERSION=0.12.732 show the plugin stamp running ahead of the npm render.
• python packaging/openai-plugin/scripts/smoke-test.py with no STACKQL_MCP_BIN override, so the real npx @stackql/mcp-server@0.12.732 path: passed in 21.6 s (initialize, tools/list, GitHub and AWS provider pulls, reload_credentials).
• The marketplace install path was exercised end to end on the same machine: codex plugin marketplace add stackql/stackql --sparse .agents/plugins --sparse packaging/openai-plugin then codex plugin add stackql@stackql; first-run initialize plus tools/list completed in 12.6 s.
• bash -n on the renderer. The openai-stdio-plugin workflow matrix (ubuntu, macos, windows) runs on this PR.

Checklist:

• A full round of testing has been completed, and there are no test failures as a result of these changes.
• The changes are covered with functional and/or integration robot testing.
• The changes work on all supported platforms.
• Unit tests pass locally, as per the developer guide.
• Robot tests pass locally, as per the developer guide.
• Linter passes locally, as per the developer guide.

Variations

• No Go code changes, so unit tests, robot tests and golangci-lint are not affected and were not re-run. No user-visible query behaviour changes, so no robot scenario is added.
• Platform coverage comes from the openai-stdio-plugin workflow matrix on this PR; locally only Windows was exercised.

Tech Debt

None accrued. Follow-ups outside this repo: post a StackQL reproduction on openai/codex#38162; ask the OpenAI contact about the local MCP exception for the public directory (tracked in #699). Users who already installed the plugin pick up the new pin with codex plugin marketplace upgrade stackql.

🤖 Generated with Claude Code