Summary

Supersedes #699, which tracked the original Apps SDK framing of this work. Depends on #892 (the annotation change must be in the release the plugin pins) and on stackql/stackql.io#305 (the terms and support URLs must resolve before submission).

OpenAI has invited StackQL into the ChatGPT plugin directory with an expedited review, target Friday 2026-11-13. The plugin under packaging/openai-plugin already works through the Codex repo marketplace. This issue covers what is needed to turn it into a directory submission: listing metadata, review metadata, an onboarding skill, a vendored launcher, a ZIP build target and CI.

Submission path for a local stdio server, per developers.openai.com/plugins/deploy/desktop-only: the org is allowlisted by the OpenAI representative, then the ZIP (including the local MCP config) is uploaded at platform.openai.com/plugins via Create plugin, Skills only. The listing carries a Desktop only badge, installs only from the ChatGPT desktop app, and is usable in threads that run locally.

Credential model stays as is: no secrets in the package or in env, provider credentials in ~/.stackql/.env sourced by the server at query time, reload_credentials to re-source. This is the same pattern as the Claude Desktop MCPB manifest and the only pattern the plugin format supports.

Changes

1. Listing metadata in the plugin manifest: shortDescription at most 30 characters (currently 47); add supportURL and termsOfServiceURL; keep displayName, category (Developer Tools), websiteURL, privacyPolicyURL, defaultPrompt, icons. Optional brandColor.
2. Review metadata: review.test_cases.positive (exactly 5) and review.test_cases.negative (exactly 3), review.demo_recording_url, publication.release_notes. All positive cases use credential-free providers (for example GitHub public data) so a reviewer with no cloud account can reproduce them. Negative cases: a mutation refused by the safe-mode gate, a request for a credential value answered with status only, an unrelated prompt with no tool call.
3. Onboarding skill (onboardingSkill): a packaged SKILL.md that walks a new user through creating ~/.stackql/.env, calling reload_credentials, and a first credential-free query. Skills are scanned at upload.
4. Vendor the npm wrapper: scripts/render-platforms.sh --vector openai-plugin copies packaging/mcpb/npm/bin/stackql-mcp.js, platforms.json and the adm-zip dependency into the plugin so the launcher needs only node, with no npx or npm at runtime. Download and SHA-256 verification of the pinned binary stay as they are. The npm package remains the single source; nothing is forked.
5. Manifest layout: prepare the portable Agent Plugins layout (root plugin.json with $schema and extensions.com.openai.*, root mcp.json with type: stdio and ${PLUGIN_ROOT}) alongside the current Codex layout (.codex-plugin/plugin.json and .mcp.json). The portal validator decides which one ships; validate.py enforces whichever is canonical and the repo marketplace install must keep working.
6. make openai-plugin-zip VERSION=X.Y.Z in packaging/mcpb/Makefile producing a ZIP with a single plugin root, no siblings, no hooks, no .app.json, no test_credentials, under the 100 MB compressed cap. A job in .github/workflows/openai-plugin.yml builds the ZIP and checks layout and size on every PR that touches the plugin.
7. validate.py: new checks for the listing field limits, the test-case counts, the onboarding skill path and the vendored launcher; existing parity check (plugin pin equals packaging/mcpb/npm/package.json version) retained.
8. Docs: docs/chatgpt-codex-plugin.md (directory install path, Work-mode note, ChatGPT Desktop: local MCP tools are discovered successfully but not exposed to Chat sessions openai/codex#38162 still open), packaging/openai-plugin/README.md, and the row in packaging/mcpb/listings.md.
9. Pin bump via make openai-plugin-manifest once the release carrying Explicit MCP tool annotations and titles for the ChatGPT plugin directory submission #892 is published to npm.

Must not break

• The existing repo marketplace route (codex plugin marketplace add stackql/stackql --sparse .agents/plugins --sparse packaging/openai-plugin, codex plugin marketplace upgrade stackql).
• packaging/mcpb/npm and pypi wrappers and the make npm-manifest chain, which already calls openai-plugin-manifest.
• Claude Desktop MCPB bundle and manifest.template.json, OCI, cargo, go and dotnet vectors, mcp-registry-publish.yml, and the release asset immutability rule in mcp-packaging.yml (never re-upload a pinned asset).
• The openai-plugin.yml matrix (ubuntu, macOS, windows x64, windows arm) stays green; the smoke test keeps using STACKQL_MCP_BIN.

Verification: python packaging/openai-plugin/scripts/validate.py, python packaging/openai-plugin/scripts/smoke-test.py, the workflow matrix, a fresh codex plugin marketplace add install on Windows and macOS, and a ChatGPT desktop Work-mode run of all eight test cases.

Carried over from #699

#699 framed this work as a hosted ChatGPT App built on the Apps SDK. The submission path is now the local stdio plugin described above (Desktop only). The items below are the parts of #699 not already covered by the numbered changes; everything else in #699 maps onto changes 1 to 9.

Context

Existing distribution channels, all live: Official MCP Registry, Anthropic Connector Directory, Cursor Directory, MCP Bundle (.mcpb), npm, PyPI, Docker Hub, GitHub Actions Marketplace, and several MCP aggregators. The ChatGPT directory is the next channel. It should give ChatGPT users a discovery and install experience comparable to the Anthropic Connector Directory, on the same StackQL MCP server, with no duplicate tool implementations.

Listing metadata (extends change 1)

• Keywords, if the manifest or portal accepts them.
• Documentation URL, pointing at the install guide on stackql.io.
• Icon and branding assets prepared for the listing.

Documentation (extends change 8)

• Extend the existing installation guide on stackql.io rather than duplicate it: installing from the ChatGPT directory, credential setup, and supported capabilities (tools, safe mode, reload_credentials).
• Document the relationship between the ChatGPT plugin and the other vectors: Anthropic Connector Directory, Official MCP Registry, npm, PyPI, Docker, .mcpb, GitHub Actions.

Success criteria

A ChatGPT user should be able to:

1. Open the plugin directory from the ChatGPT desktop app.
2. Search for StackQL.
3. Click Install.
4. Create ~/.stackql/.env with provider credentials (the onboarding skill walks through this) and call reload_credentials.
5. Immediately run StackQL queries from a local thread.

Submission checklist

In the repo:

• Plugin packaging complete (changes 1 to 7)
• Pin bumped to the release carrying Explicit MCP tool annotations and titles for the ChatGPT plugin directory submission #892 (change 9)
• Local testing completed: validate.py, smoke-test.py, workflow matrix, fresh codex plugin marketplace add install on Windows and macOS
• Credential flow verified in a ChatGPT desktop Work-mode run of all eight test cases (env file, reload_credentials, query)
• Documentation updated in this repo (change 8)

Outside the repo:

• Send the platform org ID to the OpenAI representative for local MCP allowlisting; complete business verification; confirm Apps Management Write.
• Upload a first ZIP early to read validator findings (allowlist status and accepted manifest layout).
• Icon and branding prepared.
• Privacy policy published.
• Terms of service published (Terms, support and OpenAI domain challenge pages for the ChatGPT plugin directory listing stackql.io#305).
• Support URL available (Terms, support and OpenAI domain challenge pages for the ChatGPT plugin directory listing stackql.io#305).
• Host the domain challenge token if the portal asks for it (Terms, support and OpenAI domain challenge pages for the ChatGPT plugin directory listing stackql.io#305).
• Record the demo video, fill release notes and attestations, submit.
• Installation documented on stackql.io.