Follow these steps to release a new version of stackql, as hardware tokens and 2FA is involved in several steps, end to end automation is not possible.

Push a tag using the semver, v{major}.{minor}.{build_number}, for example v0.12.718

The build_number is the latest successful GitHub Actions build number for the build job on a merge to main

git tag v0.12.718
git push origin v0.12.718

Create a release from the tag (set to latest)

Download the following artifacts from the latest build on the main branch including:

• amd64-artifact-deb
• arm64-artifact-deb
• stackql_linux_amd64
• stackql_linux_arm64
• stackql_windows_amd64 (used in step 4)
• stackql_windows_arm64 (used in step 4)

• amd64-artifact-deb (downloaded in step 2)
• arm64-artifact-deb (downloaded in step 2)
• stackql_linux_amd64.zip (downloaded in step 2)
• stackql_linux_arm64.zip (downloaded in step 2)

Using the stackql/stackql-windows-installer project along with a Microsoft Authenticode CodeSigning hardware token, create the windows packages:

• stackql_windows_amd64.msi
• stackql_windows_amd64.zip
• stackql_windows_arm64.msi
• stackql_windows_arm64.zip

place the stackql_windows_amd64.zip and stackql_windows_arm64.zip files from step 2 (both from the same build) in the downloaded directory of the stackql-windows-installer project, then run the following via PowerShell:

.\build.ps1 true

then run the following to publish the MSI and ZIP assets for both architectures to the corresponding release (the get-stackql.io PowerShell installer downloads stackql_windows_arm64.zip on ARM64 machines, so every release needs it):

.\release.ps1

Using a Mac with the correct certificate chain configured (MacInCloud), from the stackql/stackql-mac-installer repo, run the following:

sh create-installer.sh {build_number}
# for instance
sh create-installer.sh 718

this will create a signed, notarized package file stackql_darwin_multiarch.pkg and add it to the relase assets.

Invoke the mcp-packaging workflow in stackql/stackql

The mcp-packaging workflow does the following:

• attaches the .mcpb bundles (and .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

requires secrets: CARGO_REGISTRY_TOKEN, NUGET_API_KEY, SDK_MIRROR_TOKEN

manual fallback:

cd packaging/mcpb
make cargo-publish  VERSION=X.Y.Z   # CARGO_REGISTRY_TOKEN
make go-publish     VERSION=X.Y.Z   # SDK_MIRROR_TOKEN, or an already-authorised git
make dotnet-publish VERSION=X.Y.Z   # NUGET_API_KEY

Push a tag to releases.stackql.io, eg:

note: the tag needs to match the tag for the release

git tag v0.12.718 && git push origin v0.12.718

Export the end vars packaging/mcpb/.env first

Requires an npm login session as a user with publish rights on the @stackql scope; the publish prompts for an OTP.

cd packaging/mcpb
make npm-pack VERSION=X.Y.Z
cd npm
npm publish stackql-mcp-server-X.Y.Z.tgz --access public

Requires a PyPI API token with upload rights on the project; twine username is __token__, password is the token. On Debian/Ubuntu (including WSL) pip install outside a venv is blocked by PEP 668, hence the venv.

cd packaging/mcpb
python3 -m venv ~/.venvs/pypi-pub && source ~/.venvs/pypi-pub/bin/activate
pip install --upgrade build twine
make pypi-build VERSION=X.Y.Z
python -m twine check pypi/dist/*
python -m twine upload pypi/dist/*

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

Requires the latest mcp-publisher CLI and a classic GitHub PAT (scope read:org only, no repo scopes) created by a stackql org Owner at https://github.com/settings/tokens/new. The server.json renderer reads the five .sha256 files from the local dist/ directory, so download the published checksum files from the release first.

Install/upgrade the CLI (linux amd64 shown; assets exist per platform):

curl -fsSL "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_linux_amd64.tar.gz" | tar xz mcp-publisher
sudo install -m 0755 mcp-publisher /usr/local/bin/mcp-publisher

Publish:

cd packaging/mcpb
for t in linux-x64 linux-arm64 windows-x64 windows-arm64 darwin-universal; do
  curl -fsSL -o dist/stackql-mcp-$t.mcpb.sha256 \
    "https://github.com/stackql/stackql/releases/download/vX.Y.Z/stackql-mcp-$t.mcpb.sha256"
done
export MCP_GITHUB_TOKEN=<classic PAT with read:org scope>
mcp-publisher login github
make registry-publish VERSION=X.Y.Z

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:

npm view @stackql/mcp-server@X.Y.Z version
python3 packaging/openai-plugin/scripts/validate.py
python3 packaging/openai-plugin/scripts/smoke-test.py

The marketplace entry is version-independent. This step does not change the MCPB, Anthropic, PyPI, OCI, or MCP Registry artifacts. See packaging/mcpb/README.md for the detailed addendum.

To ensure the mcp server for latest release is published across all surfaces run:

# from within a python venv created previously
# in the `packaging/mcpb` directory, run...
make check-published