# SHD MCP plugin release checklist

This repository packages the client-side plugin. The authenticated MCP server
and its OAuth deployment are separate release surfaces.

## Local preflight

Run from the repository root:

```bash
python3 -m unittest discover -s tests -v
python3 scripts/check_skill_mcp_parity.py --strict
for checksum in plugins/shd-mcp-plugin/widgets/*/v1/SHA256SUMS; do
  (cd "$(dirname "$checksum")" && sha256sum --check SHA256SUMS)
done
```

The Codex plugin validator is an additional environment check when available:

```bash
python3 /home/vscode/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py \
  plugins/shd-mcp-plugin
```

## Widget changes

Every `ui://shd/<module>/v1.html` URI is a cache key. For a breaking HTML,
JavaScript or CSS change, create `v2/`, update the manifest and backend resource
registration together, then regenerate `SHA256SUMS`. Keep each widget useful
without ChatGPT-specific APIs: the MCP Apps bridge is the baseline and
`window.openai` is only a compatibility extension.

The public package also contains a one-way Skill-to-catalog parity check. The
catalog is a checked-in name snapshot, so a Skill cannot silently reference an
unpublished MCP tool. Refresh it from the backend catalog before publishing.

`scripts/mcp-runtime-smoke.mjs` checks OAuth metadata, authenticated MCP
negotiation and the active-projects/Documents/Tasks/Finance/CRM resources.
`scripts/mcp-oauth-e2e.mjs` is an opt-in Playwright check for the complete
authorization-code + PKCE exchange using an already authenticated storage
state. Neither script stores credentials or belongs in the static CI job.

The OAuth server metadata must advertise the token-endpoint methods used by the
ChatGPT CIMD document (`none` and `private_key_jwt`). Before a release, verify
that the server accepts the ChatGPT `RS256` client assertion, validates its
JWKS signature and rejects a repeated `jti`.

## Publish and deploy gates

1. Commit and push the same reviewed revision to the GitHub and Gitea mirrors.
2. Deploy the backend and ensure the widget artifact is available at the path
   used by `SHD_MCP_WIDGET_ROOT`, or at the repository path documented by the
   backend loader.
3. Run the backend MCP verification and a real authenticated OAuth/tool call.
4. Reconnect the custom ChatGPT app and test active projects, Documents, Tasks,
   Finance and CRM, including the plain structured fallback and each widget’s
   refresh/detail action.
5. Record the exact revision and any runtime/browser checks. Static tests do
   not prove OAuth, ACLs, production hosting or ChatGPT rendering.

Do not place tokens, cookies, client secrets or private host credentials in this
repository, its marketplace file or its documentation.