Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 25 additions & 2 deletions .github/workflows/mcp-packaging.yml
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,9 @@
# (Authenticode-signed exe, notarised .pkg) are signed outside CI, so a
# release event fires before they exist. Flow:
# push tag -> create release -> attach signed assets -> dispatch.
# The npm / PyPI wrappers need interactive (2FA) credentials and are
# published from a local clone - see step 7 of docs/stackql_release_process.md.
# The npm wrapper is published by the npm-publish job (npm trusted publishing,
# OIDC). The PyPI wrapper needs interactive (2FA) credentials and is published
# from a local clone - see step 8 of docs/stackql_release_process.md.
# The three embedded SDK wrappers (cargo, go, dotnet) are validated here on
# every packaging PR (against the latest release, smoke tests fed the freshly
# built bundle via STACKQL_MCP_BUNDLE) and, on dispatch, validated with real
Expand Down Expand Up @@ -439,3 +440,25 @@ jobs:
- env:
SDK_MIRROR_TOKEN: ${{ secrets.SDK_MIRROR_TOKEN }}
run: make go-publish VERSION=${{ needs.version.outputs.version }}

# npm Trusted Publishing (OIDC): the npmjs.com trusted publisher on
# @stackql/mcp-server (owner stackql, repo stackql/stackql, workflow
# mcp-packaging.yml) exchanges this job's GitHub OIDC token for a
# short-lived publish token; npm attaches provenance. No stored secret.
# NODE_AUTH_TOKEN / NPM_TOKEN must NOT be set anywhere in this job.
npm-publish:
name: publish npm (@stackql/mcp-server)
if: needs.version.outputs.is_publish == 'true'
needs: [version, sdk]
runs-on: ubuntu-24.04
permissions:
contents: read
id-token: write
steps:
- uses: actions/checkout@v6
- uses: actions/setup-node@v7
with:
# October 2026 security release: TLS hostname CVEs, Brotli RCE, eMudhra CA removal
node-version: '24.22.1'
registry-url: 'https://registry.npmjs.org'
- run: make npm-publish VERSION=${{ needs.version.outputs.version }}
8 changes: 4 additions & 4 deletions .github/workflows/mcp-registry-publish.yml
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@
# for a released version. This is the FINAL publish step of a release: the
# registry validates every package entry in server.json against its upstream
# registry at the exact version, so the .mcpb release assets, the OCI image
# (mcp-packaging), and the npm + PyPI wrappers (manual, 2FA) must ALL be live
# before this runs. Dispatch it after steps 7a/7b of
# docs/stackql_release_process.md.
# (mcp-packaging), the npm wrapper (mcp-packaging) and the PyPI wrapper
# (manual, 2FA) must ALL be live before this runs. Dispatch it after step 8b
# of docs/stackql_release_process.md.
#
# Auth is GitHub Actions OIDC: the registry grants io.github.<owner>/* to
# OIDC tokens from this repo's workflows, so no secret is required.
Expand All @@ -15,7 +15,7 @@ on:
workflow_dispatch:
inputs:
version:
description: stackql release version without the leading v (e.g. 0.10.559); the .mcpb assets, OCI image, npm and PyPI wrappers must already be published
description: stackql release version without the leading v (e.g. 0.10.559); the .mcpb assets, OCI image and npm wrapper (mcp-packaging) and the PyPI wrapper (manual) must already be published
required: true
type: string

Expand Down
24 changes: 16 additions & 8 deletions docs/stackql_release_process.md
Original file line number Diff line number Diff line change
Expand Up @@ -92,9 +92,9 @@ It also creates `stackql-mcp-multiplatform.mcpb`, containing all five platform b
- smoke-tests the bundles and wrappers, including native Windows ARM64 on `windows-11-arm`
- attaches all six `.mcpb` bundles and their `.mcpb.sha256` files to the release
- pushes the multi-arch OCI image to Docker Hub
- publishes packages to crates.io (rust), nuget (dotnet), and the go mirror
- publishes packages to crates.io (rust), nuget (dotnet), the go mirror, and npm (`@stackql/mcp-server`)

Required repository secrets: `DOCKERHUB_USERNAME`, `DOCKERHUB_TOKEN`, `CARGO_REGISTRY_TOKEN`, and `SDK_MIRROR_TOKEN`. NuGet uses Trusted Publishing (OIDC); the manual fallback below uses `NUGET_API_KEY`.
Required repository secrets: `DOCKERHUB_USERNAME`, `DOCKERHUB_TOKEN`, `CARGO_REGISTRY_TOKEN`, and `SDK_MIRROR_TOKEN`. NuGet uses Trusted Publishing (OIDC); the manual fallback below uses `NUGET_API_KEY`. npm (`@stackql/mcp-server`) uses npm Trusted Publishing (OIDC) from `mcp-packaging.yml`; no secret.

manual fallback:

Expand All @@ -115,13 +115,21 @@ Push a tag to [releases.stackql.io](https://github.com/stackql/releases.stackql.
git tag v0.12.778 && git push origin v0.12.778
```

### 8. Publish the MCP wrapper packages (manual last mile)
### 8. Publish the PyPI wrapper (manual last mile)

Export the environment variables from `packaging/mcpb/.env` first. Run these steps after all five platform bundles and their checksums are published. The manifests pin the published checksums, including `windows-arm64`; npm and PyPI select the matching bundle for the runtime architecture.
The npm wrapper is now published by `mcp-packaging` (see 8a); only the PyPI wrapper remains a manual step. Export the environment variables from `packaging/mcpb/.env` first. Run these steps after all five platform bundles and their checksums are published. The manifests pin the published checksums, including `windows-arm64`; npm and PyPI select the matching bundle for the runtime architecture.

#### 8a. npm (`@stackql/mcp-server`)
#### 8a. npm (`@stackql/mcp-server`) - published by `mcp-packaging`

Requires an `npm login` session as a user with publish rights on the `@stackql` scope; the publish prompts for an OTP.
The `npm-publish` job publishes `@stackql/mcp-server@X.Y.Z` with npm trusted publishing (GitHub Actions OIDC) after the sdk slices pass; no `npm login`, OTP or token is involved, and npm attaches a provenance attestation. The trusted publisher configuration on npmjs.com (owner `stackql`, repo `stackql`, workflow `mcp-packaging.yml`, `npm publish` allowed) is permanent once validated by its first publish.

Verify:

```bash
npm view @stackql/mcp-server@X.Y.Z version dist.attestations.url
```

Manual fallback (publish rights on the `@stackql` scope; prompts for an OTP):

```bash
cd packaging/mcpb
Expand All @@ -145,7 +153,7 @@ python -m twine upload pypi/dist/*

### 9. Official MCP Registry (`io.github.stackql/stackql-mcp`) - dispatch last

Run [mcp-registry-publish](https://github.com/stackql/stackql/actions/workflows/mcp-registry-publish.yml) from `main` with the same version without `v`. The five platform MCPB packages (including `windows-arm64`), OCI image, npm package, and PyPI package must already be published at that version. The registry entry pins each platform bundle's published checksum.
Run [mcp-registry-publish](https://github.com/stackql/stackql/actions/workflows/mcp-registry-publish.yml) from `main` with the same version without `v`. The five platform MCPB packages (including `windows-arm64`), OCI image, npm package (published by `mcp-packaging`), and PyPI package must already be published at that version. The registry entry pins each platform bundle's published checksum.

Manual fallback (if the workflow fails or an out-of-band publish is needed):

Expand Down Expand Up @@ -174,7 +182,7 @@ make registry-publish VERSION=X.Y.Z

### 10. Commit the ChatGPT/Codex stdio plugin bump

`make npm-pack` in 8a also stamped the plugin: `version` in `packaging/openai-plugin/plugins/stackql/.codex-plugin/plugin.json` and the pinned `@stackql/mcp-server@X.Y.Z` in `packaging/openai-plugin/plugins/stackql/bin/stackql-mcp.js` (`make openai-plugin-manifest VERSION=X.Y.Z` stamps just those two). After 8a confirms `@stackql/mcp-server@X.Y.Z` is live, verify and commit them together with the `package.json` / `pyproject.toml` bumps; the plugin validator fails when the pin and `packaging/mcpb/npm/package.json` disagree:
Run `make npm-manifest VERSION=X.Y.Z` locally after the release; it stamps `packaging/mcpb/npm/package.json`, `packaging/openai-plugin/plugins/stackql/.codex-plugin/plugin.json` and the pinned `@stackql/mcp-server@X.Y.Z` in `packaging/openai-plugin/plugins/stackql/bin/stackql-mcp.js` (the `npm-publish` job's stamp lives only on the runner and is discarded; `make openai-plugin-manifest VERSION=X.Y.Z` stamps just the two plugin files). After 8a confirms `@stackql/mcp-server@X.Y.Z` is live, verify and commit them together with the `package.json` / `pyproject.toml` bumps; the plugin validator fails when the pin and `packaging/mcpb/npm/package.json` disagree:

```bash
npm view @stackql/mcp-server@X.Y.Z version
Expand Down
15 changes: 13 additions & 2 deletions packaging/mcpb/Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,7 @@ OCI_STAGE := .oci-stage
.PHONY: all check-version check-target download package combined one signed sign publish \
server-json registry-publish check-published clean clean-bin \
linux-x64 linux-arm64 windows-x64 windows-arm64 darwin-universal \
oci-stage oci oci-push npm-manifest npm-pack pypi-manifest pypi-build \
oci-stage oci oci-push npm-manifest npm-pack npm-publish pypi-manifest pypi-build \
openai-plugin-manifest \
list help

Expand Down Expand Up @@ -243,12 +243,23 @@ oci-push: oci-stage
npm-manifest: check-version openai-plugin-manifest
bash scripts/render-npm-manifest.sh --version $(VERSION)

# Build the publishable tarball. Publishing stays manual (npm 2FA):
# Build the publishable tarball. This is the LOCAL FALLBACK: CI publishes via
# 'npm-publish' (trusted publishing). To publish by hand (npm 2FA):
# cd npm && npm publish --access public
npm-pack: npm-manifest
cd npm && npm pack
@echo "tarball ready under npm/ - publish manually with: cd npm && npm publish --access public"

# Publish from CI via npm trusted publishing (GitHub Actions OIDC; no token).
# Provenance is attached automatically. Idempotent: skips if the version exists.
npm-publish: npm-manifest
@if curl -fsSL "https://registry.npmjs.org/@stackql/mcp-server/$(VERSION)" >/dev/null 2>&1; then \
echo "npm already has @stackql/mcp-server@$(VERSION) - skipping"; \
else \
cd npm && npm publish --dry-run --access public && npm publish --access public \
&& echo "published https://www.npmjs.com/package/@stackql/mcp-server/v/$(VERSION)"; \
fi

# --- ChatGPT/Codex stdio plugin -------------------------------------------------
# Stamp packaging/openai-plugin (plugin.json version + the @stackql/mcp-server
# pin in the launcher) so the plugin tracks the npm wrapper. Runs as part of
Expand Down
22 changes: 15 additions & 7 deletions packaging/mcpb/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -130,7 +130,7 @@ Two more vectors ship from the same pipeline:

- **OCI image** (`docker.io/stackql/stackql-mcp`): built and smoke-tested in PR CI; pushed multi-arch (amd64 + arm64) by the publish workflow when the `DOCKERHUB_USERNAME`/`DOCKERHUB_TOKEN` secrets are set (soft-skips otherwise). The image carries the `io.modelcontextprotocol.server.name` label the MCP Registry requires for oci package validation.
- **PyPI wrapper** (`stackql-mcp-server`): same launcher pattern in stdlib-only Python (uvx/pip), sharing the npm wrapper's binary cache. PR CI smoke-tests it; the publish workflow builds sdist+wheel as a run artifact. Publishing is manual (2FA): `make pypi-build VERSION=X.Y.Z` then `python -m twine upload pypi/dist/*`. The registry validates pypi packages via the `mcp-name:` marker in the README.
- **npm wrapper** (`@stackql/mcp-server`): an npx-able launcher that downloads the platform's published `.mcpb` (sha256-verified against pins baked into the package) and spawns the binary. PR CI tests the wrapper against a locally built bundle; the publish workflow renders the real pins from the published assets and uploads the tarball as a run artifact. Publishing to npmjs is deliberately manual (2FA): download the artifact or run `make npm-pack VERSION=X.Y.Z` locally, then `cd npm && npm publish --access public`. The package carries the `mcpName` field the MCP Registry requires for npm package validation.
- **npm wrapper** (`@stackql/mcp-server`): an npx-able launcher that downloads the platform's published `.mcpb` (sha256-verified against pins baked into the package) and spawns the binary. PR CI tests the wrapper against a locally built bundle; on dispatch the `npm-publish` job renders the real pins from the published assets and publishes the package. Published by the `npm-publish` job in `mcp-packaging` via npm trusted publishing (OIDC, provenance attached). Local fallback: `make npm-pack VERSION=X.Y.Z` then `cd npm && npm publish --access public` (prompts for 2FA). The package carries the `mcpName` field the MCP Registry requires for npm package validation.

A GitHub Action consumes these published bundles for CI: **[stackql/setup-stackql-mcp](https://github.com/stackql/setup-stackql-mcp)** installs the signed binary (sha256-verified at runtime against the release checksums) and emits an `mcpServers` config for agentic workflows (e.g. `anthropics/claude-code-action`). It lives in its own repo and tracks no version - `version: latest` by default, pin with `version: X.Y.Z` - so this packaging repo no longer carries the action source.

Expand Down Expand Up @@ -332,8 +332,10 @@ This is interactive (PIN prompt), so it is a local flow, not a CI step. Requires

## Publishing the wrapper packages (npm, PyPI, OCI)

Explicit command sequences for the three downstream package vectors. All are
manual publishes (2FA / tokens). The `make` targets are convenience wrappers;
Explicit command sequences for the three downstream package vectors. PyPI and
OCI are manual publishes (2FA / tokens); npm is published by the `npm-publish`
job in `mcp-packaging` (trusted publishing), so its sequence below is the
manual fallback. The `make` targets are convenience wrappers;
the raw commands below are what they run, useful on machines without `make`
(e.g. Git Bash / WSL on Windows). Run every command FROM THE REPO ROOT unless
a `cd` says otherwise.
Expand All @@ -342,7 +344,11 @@ Ordering rule for all three: the manifest/pin render steps fetch the canonical
`.sha256` files from the PUBLISHED GitHub release, so they must run AFTER the
`.mcpb` assets for the version are published. Never pin locally built hashes.

### npm (`@stackql/mcp-server`)
### npm (`@stackql/mcp-server`) - manual fallback

CI publishes this package from the `npm-publish` job in `mcp-packaging`
(npm trusted publishing, OIDC, provenance attached). Use the sequence below
only if that job fails or an out-of-band publish is needed.

```bash
# auth: browser-based login; account must have publish rights on @stackql
Expand All @@ -352,7 +358,7 @@ npm login
bash scripts/render-npm-manifest.sh --version X.Y.Z
cd npm && npm install --no-audit --no-fund
npm publish --dry-run --access public # confirm: 4 files, name, version, mcpName
npm publish --access public # the real publish (prompts for 2FA)
npm publish --access public # fallback manual publish (prompts for 2FA)
cd ..

# verify from a clean cache (forces download + sha256 verify of the bundle)
Expand Down Expand Up @@ -459,8 +465,10 @@ make sign envelope-sign dist/*.mcpb in place and regenerat
make oci VERSION=X.Y.Z build the stackql/stackql-mcp image locally (amd64)
make oci-push VERSION=X.Y.Z multi-arch image build + push (needs docker login)
make npm-manifest VERSION=X.Y.Z render npm/platforms.json from PUBLISHED .sha256s
make npm-pack VERSION=X.Y.Z build the @stackql/mcp-server tarball (publish is
manual: cd npm && npm publish --access public)
make npm-pack VERSION=X.Y.Z build the @stackql/mcp-server tarball (local
fallback: cd npm && npm publish --access public)
make npm-publish VERSION=X.Y.Z CI only: publish @stackql/mcp-server via npm
trusted publishing (OIDC); skips if version exists
make openai-plugin-manifest VERSION=X.Y.Z stamp the ChatGPT/Codex plugin pin
(also runs as part of npm-manifest)
make pypi-manifest VERSION=X.Y.Z render pypi platforms.json from PUBLISHED .sha256s
Expand Down
Loading