AI-331: bridge 3.0.4 - pretty slugs, dxt packing fix + latest refresh, dispatch-only npm STAGE (OIDC) (#29)

3.0.4 metadata (canonical docs slugs, DXT manifest version sync) plus release-flow hardening: fix the .dxt packing so the extension contains its entry point (with a CI integrity gate), create bridge releases with --latest=false and auto-refresh the .dxt on the latest release, carry the .dxt forward onto new plugin releases, and a dispatch-only OIDC npm STAGE job (CI can stage but never release). npm 3.0.4 was already published from a byte-verified tarball. AI-331.

Author: wyatt-shippo

.github/workflows/publish-shippo-mcp.yml

@@ -1,12 +1,25 @@
 name: Release @shippo/shippo-mcp (.dxt)
 on:
   workflow_dispatch:
+    inputs:
+      npm_tag:
+        description: "Existing shippo-mcp-v* tag to publish to npm (empty = verify only, no publish)"
+        required: false
+        default: ''
   push:
     tags: ['shippo-mcp-v*']
-# npm publishing is intentionally NOT automated: the maintainer runs
-# `npm publish` manually from a verified local checkout. This workflow only
-# verifies the tagged code and publishes the GitHub release with the .dxt,
-# which the README's "Add to Claude Desktop" button links to.
+# Tag push = release ONLY: verify the tagged code, attach the .dxt to the
+# GitHub release (the README's "Add to Claude Desktop" button), and refresh
+# the .dxt on the "latest" release for the docs download URL.
+# CI NEVER releases to npm. The npm-stage job runs only when a maintainer
+# manually dispatches this workflow with the npm_tag input set, then pauses
+# at the npm-stage-publish environment for required-reviewer approval, and the
+# npm Trusted Publisher (goshippo/ai + this filename + environment
+# npm-stage-publish) is restricted to the STAGE action: the upload lands as a
+# staged version that a maintainer must release on npmjs.com. Triple gate,
+# no long-lived npm token anywhere. Staging must be dispatched ON the tag ref
+# itself (guard-enforced), so the ref the release job verified, the packed
+# content, and the provenance attestation all describe the same commit.
 # contents: write so the tagged run can create that release.
 permissions:
   contents: write
@@ -27,14 +40,99 @@ jobs:
       - run: npm run build
       # Build the Desktop Extension and publish it as the tag's release asset, so
       # the README download button (releases/download/<tag>/shippo.dxt) resolves.
-      # Only on a tag push (a release needs a tag); skipped on workflow_dispatch.
-      - if: startsWith(github.ref, 'refs/tags/')
+      # --latest=false: the repo's "latest" release must stay the shippo-plugin
+      # release (docs.goshippo.com deep-links releases/latest/download/ for the
+      # plugin zip, knowledge pack, and shippo.dxt); a bridge release taking
+      # "latest" 404s those links (happened 2026-07-17, fixed 2026-07-22).
+      # Only on the tag-push EVENT: a workflow_dispatch never touches release
+      # assets, even when dispatched on a tag ref (npm staging requires that).
+      - if: github.event_name == 'push'
         run: npm run build-dxt
-      - if: startsWith(github.ref, 'refs/tags/')
+      # Refuse to distribute a broken extension: the packer must have included
+      # the bundled entry point (3.0.3's .dxtignore excluded dxt-dist/, so its
+      # shippo.dxt could not launch in Claude Desktop).
+      - if: github.event_name == 'push'
+        run: unzip -l shippo.dxt | grep -q 'dxt-dist/index.js'
+      - if: github.event_name == 'push'
         env:
           GH_TOKEN: ${{ github.token }}
         run: |
-          gh release create "$GITHUB_REF_NAME" shippo.dxt \
+          gh release create "$GITHUB_REF_NAME" shippo.dxt --latest=false \
             --title "@shippo/shippo-mcp $GITHUB_REF_NAME" \
             --notes "Local bridge to the hosted Shippo MCP server. To install in Claude Desktop, download shippo.dxt and open it." \
           || gh release upload "$GITHUB_REF_NAME" shippo.dxt --clobber
+      # Keep the docs' stable URL fresh: docs.goshippo.com's download button
+      # links releases/latest/download/shippo.dxt, and "latest" is pinned to
+      # the shippo-plugin release (see --latest=false above). Clobber this
+      # build's .dxt onto whatever release is currently "latest" so the docs
+      # always serve the newest bridge, with no manual refresh step.
+      - if: github.event_name == 'push'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          LATEST=$(gh release view --json tagName --jq .tagName 2>/dev/null || true)
+          if [ -n "$LATEST" ] && [ "$LATEST" != "$GITHUB_REF_NAME" ]; then
+            gh release upload "$LATEST" shippo.dxt --clobber
+          fi
+  npm-stage:
+    # Dispatch-only, triple-gated: (1) a maintainer must manually run this
+    # workflow with npm_tag set; (2) the npm-stage-publish environment's required
+    # reviewer must approve the job; (3) the npm Trusted Publisher's allowed
+    # action is STAGE only, so this job cannot release: it stages the version
+    # and a maintainer releases it on npmjs.com. Guards: the input tag must
+    # match the checked-out package.json version, and an already-released
+    # version is skipped cleanly (e.g. one that was published manually).
+    needs: release
+    if: github.event_name == 'workflow_dispatch' && inputs.npm_tag != ''
+    runs-on: ubuntu-latest
+    environment: npm-stage-publish
+    permissions:
+      contents: read
+      id-token: write
+    defaults:
+      run:
+        working-directory: tools/modelcontextprotocol
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.npm_tag }}
+      # Node 24 bundles npm 11.16+: OIDC trusted publishing needs npm >= 11.5.1
+      # and the npm stage command needs >= 11.15.0. Node 22 bundles npm 10.x,
+      # which supports neither (the job would fail auth with no token to fall
+      # back on). The release job stays on 22 to match .node-version.
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+          registry-url: 'https://registry.npmjs.org'
+      - run: npm ci
+      - id: guard
+        env:
+          NPM_TAG: ${{ inputs.npm_tag }}
+        run: |
+          # The dispatch must be run ON the tag itself ("Use workflow from" ->
+          # the tag). Then the release job (needs) typechecked/tested/built this
+          # exact content, and the provenance attestation records the same ref
+          # that was packed. Release-asset steps stay untouched either way
+          # (they are gated on the push event).
+          if [ "$GITHUB_REF" != "refs/tags/$NPM_TAG" ]; then
+            echo "Dispatch this workflow ON the tag: pick '$NPM_TAG' in the 'Use workflow from' picker (run ref is '$GITHUB_REF')."
+            exit 1
+          fi
+          PKG_VER=$(node -p "require('./package.json').version")
+          TAG_VER="${NPM_TAG#shippo-mcp-v}"
+          if [ "$PKG_VER" != "$TAG_VER" ]; then
+            echo "package.json version ($PKG_VER) does not match tag ($TAG_VER)"; exit 1
+          fi
+          if npm view "@shippo/shippo-mcp@$PKG_VER" version >/dev/null 2>&1; then
+            echo "@shippo/shippo-mcp@$PKG_VER already on the registry; skipping publish"
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+          fi
+      # npm stage publish uploads a STAGED version (provenance is generated
+      # automatically under trusted publishing). It cannot release: the Trusted
+      # Publisher's only allowed action is stage; a maintainer releases via
+      # npm stage approve (or the Staged Packages tab on npmjs.com) with 2FA.
+      # NOTE: a pending staged version is invisible to npm view, so the guard
+      # above cannot skip it; re-dispatching while a stage awaits approval
+      # fails loudly here. Approve or reject the pending stage first.
+      - if: steps.guard.outputs.skip != 'true'
+        run: npm stage publish

.github/workflows/release.yml

@@ -105,6 +105,26 @@ jobs:
             dist/app-plugin/shippo-plugin.zip
             dist/shippo-knowledge-pack.md
 
+      - name: Carry forward shippo.dxt from the current latest release
+        # This new plugin release becomes the repo's "latest" when published,
+        # and docs.goshippo.com deep-links releases/latest/download/shippo.dxt
+        # (the Claude Desktop button). Fetch the bridge .dxt from the CURRENT
+        # latest (still the previous plugin release at this point) so the new
+        # latest carries all three assets; skip cleanly on bootstrap (no dxt
+        # anywhere yet). gh release download fails on a missing asset, so a
+        # 404 HTML page can never be uploaded as shippo.dxt.
+        if: steps.gate.outputs.release == 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          mkdir -p dist
+          if gh release download --pattern shippo.dxt --output dist/shippo.dxt 2>/dev/null; then
+            unzip -l dist/shippo.dxt | grep -q 'manifest.json' || { echo "carried shippo.dxt is not a valid archive"; exit 1; }
+            echo "will carry shippo.dxt onto the new release"
+          else
+            echo "no shippo.dxt on the current latest release; skipping carry"
+          fi
+
       - name: Publish GitHub Release
         if: steps.gate.outputs.release == 'true'
         env:
@@ -118,4 +138,8 @@ jobs:
           fi
           # --clobber so re-runs replace the same-named asset idempotently.
           gh release upload "$TAG" dist/app-plugin/shippo-plugin.zip dist/shippo-knowledge-pack.md --clobber
+          if [ -f dist/shippo.dxt ]; then
+            gh release upload "$TAG" dist/shippo.dxt --clobber
+            echo "Carried shippo.dxt onto release $TAG."
+          fi
           echo "Published shippo-plugin.zip and shippo-knowledge-pack.md to release $TAG."

tools/modelcontextprotocol/.dxtignore

@@ -1,7 +1,7 @@
 node_modules/
 src/
 test/
-dist/
+dist/**
 tsconfig.json
 tsup.config.ts
 build-dxt.js

tools/modelcontextprotocol/README.md

@@ -9,7 +9,7 @@ You must register for a [Shippo account](https://apps.goshippo.com/join) to use
 You sign in through your browser (OAuth), so there is no API key to manage.
 
 <!-- API-KEY-AUTH (hidden until the hosted key door ships; the code path stays live, this is docs-only):
-For headless or automation use (CI, cron, service accounts) you can supply a Shippo [API token](https://docs.goshippo.com/docs/guides_general/authentication/) instead. A `shippo_test_` key runs in test mode and produces test labels; a `shippo_live_` key runs on your live account, where buying a label is billable.
+For headless or automation use (CI, cron, service accounts) you can supply a Shippo [API token](https://docs.goshippo.com/guides/authentication) instead. A `shippo_test_` key runs in test mode and produces test labels; a `shippo_live_` key runs on your live account, where buying a label is billable.
 -->
 
 ## Summary

tools/modelcontextprotocol/manifest.json

@@ -2,13 +2,13 @@
   "dxt_version": "0.1",
   "name": "@shippo/shippo-mcp",
   "display_name": "Shippo",
-  "version": "3.0.0",
+  "version": "3.0.4",
   "description": "Multi-carrier shipping for AI agents: compare rates, buy labels, track packages, and validate addresses. Local bridge to the hosted Shippo MCP server.",
   "author": {
     "name": "Shippo",
     "email": "support@goshippo.com"
   },
-  "documentation": "https://docs.goshippo.com/docs/Guides_general/MCPServer",
+  "documentation": "https://docs.goshippo.com/guides/mcp-server",
   "server": {
     "type": "node",
     "entry_point": "dxt-dist/index.js",

tools/modelcontextprotocol/package-lock.json

@@ -1,15 +1,15 @@
 {
   "name": "@shippo/shippo-mcp",
   "mcpName": "com.shippo/shippo-mcp",
-  "version": "3.0.3",
+  "version": "3.0.4",
   "description": "Multi-carrier shipping for AI agents: compare rates, buy labels, track packages, validate addresses. Local bridge to the hosted Shippo MCP server.",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/goshippo/ai.git",
     "directory": "tools/modelcontextprotocol"
   },
-  "homepage": "https://docs.goshippo.com/docs/Guides_general/MCPServer",
+  "homepage": "https://docs.goshippo.com/guides/mcp-server",
   "bugs": "https://github.com/goshippo/ai/issues",
   "type": "module",
   "bin": {