Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
54 commits
Select commit Hold shift + click to select a range
6f2c32d
Initial commit
jeffreyaven Jun 12, 2026
51db6c7
Initial commit
jeffreyaven Jun 12, 2026
b5c2159
Initial commit
jeffreyaven Jun 12, 2026
07c1b1c
Initial commit
jeffreyaven Jun 12, 2026
ee9c6b7
Add crate core: sidecar acquisition, builder API, rmcp client
jeffreyaven Jun 13, 2026
aedbed3
Add auditron demo app and vendored single-binary build path
jeffreyaven Jun 13, 2026
61db835
Prepare crates.io release: package metadata, badges, launch kit
jeffreyaven Jun 13, 2026
c12ef5a
embed package, sandboxctl demo, conformance tests, CI
jeffreyaven Jun 13, 2026
6cc2741
ci: run go generate before vet/tests
jeffreyaven Jun 13, 2026
26c9d49
minor ci updates
jeffreyaven Jun 13, 2026
b5ac9c6
ci: trigger on PRs to main and release tags
jeffreyaven Jun 13, 2026
89542d8
ci: bump actions/checkout to v6
jeffreyaven Jun 13, 2026
68b79a9
ci updates
jeffreyaven Jun 13, 2026
7b5ec28
Embed StackQL MCP server for Kotlin/JVM plus the costgate demo
jeffreyaven Jun 13, 2026
98314ee
Make gradlew executable so CI works on Linux and macOS
jeffreyaven Jun 13, 2026
3310072
feat: SwiftPM package StackQLMCP with embedded server, conformance te…
jeffreyaven Jun 13, 2026
4724cb1
fix(ci): build with Swift 6.1 (Xcode 16.4); the MCP SDK is a 6.1 package
jeffreyaven Jun 13, 2026
17464cc
fix: flatten try? double-optional in resolvePin (Swift build error)
jeffreyaven Jun 13, 2026
7da9563
fix(resolver): treat empty binaryOverride as no override
jeffreyaven Jun 13, 2026
9e9db6c
Merge pull request #1 from stackql/feature/embedded-swift-mcp
jeffreyaven Jun 13, 2026
af08738
Initial commit
jeffreyaven Jun 13, 2026
f625df2
Add StackQL embedded MCP library, Agent Framework connector, driftwat…
jeffreyaven Jun 13, 2026
2209bdd
Initial commit
jeffreyaven Jun 13, 2026
3e9947a
Add library core, conformance test, and cross-platform CI
jeffreyaven Jun 13, 2026
ec8d4c9
Fix CI: align gleam_json with mcp_client, pin setup-beam for win25
jeffreyaven Jun 13, 2026
c119607
Apply gleam format and pin Windows runner to windows-2022
jeffreyaven Jun 13, 2026
72c8233
Fix ServerConfig construction and force LF for format-check on Windows
jeffreyaven Jun 13, 2026
ae4156a
Commit manifest.toml lockfile for deterministic builds
jeffreyaven Jun 13, 2026
98467a3
Feature/cloudlens demo app (#4)
jeffreyaven Jun 13, 2026
ecb7478
docs: state the .NET 8+ runtime requirement in the README
jeffreyaven Jun 13, 2026
37ce849
Add stackql-agent demo + self-healing bundle cache; talk kit
jeffreyaven Jun 17, 2026
f53e469
demo updates
jeffreyaven Jun 17, 2026
b4a88cc
Bump pinned stackql release to v0.10.601; crate 0.1.1
jeffreyaven Aug 18, 2026
97a22bf
import stackql-mcp-go@feature/embedded-go-mcp as packaging/mcpb/go
jeffreyaven Aug 18, 2026
66362d4
import stackql-mcp-dotnet@feature/library-core as packaging/mcpb/dotnet
jeffreyaven Aug 18, 2026
c8f4254
import stackql-mcp-gleam@feature/library-core-and-ci as packaging/mcp…
jeffreyaven Aug 18, 2026
d457721
import stackql-mcp-kotlin@feature/embedded-kotlin-mcp as packaging/mc…
jeffreyaven Aug 18, 2026
699f753
import stackql-mcp-rs@b4a88cc (0.1.1) as packaging/mcpb/cargo
jeffreyaven Aug 18, 2026
adddfb6
import stackql-mcp-swift@origin/main (98467a3) as packaging/mcpb/swift
jeffreyaven Aug 18, 2026
3c5b062
packaging/mcpb: drop demo apps and per-repo CI from imported SDK subt…
jeffreyaven Aug 18, 2026
4ef25d4
packaging/mcpb: shared render-platforms.sh renderer; cargo vector on …
jeffreyaven Aug 18, 2026
e248e4f
packaging/mcpb/go: pins from embedded platforms.json, sidecar path, l…
jeffreyaven Aug 18, 2026
3b669e5
packaging/mcpb/dotnet: platforms.json embedded resource, Launcher sam…
jeffreyaven Aug 18, 2026
3a8f2d9
packaging/mcpb/gleam: sidecar acquisition, rendered pins module, laun…
jeffreyaven Aug 18, 2026
d12ee6a
packaging/mcpb/kotlin: pins from platforms.json resource, launcher mo…
jeffreyaven Aug 18, 2026
0e86063
packaging/mcpb/kotlin: sign only when a key is configured; LF-normali…
jeffreyaven Aug 18, 2026
209d3d8
packaging/mcpb/swift: platforms.json resource, STACKQL_MCP_BIN/BUNDLE…
jeffreyaven Aug 18, 2026
159a714
packaging/mcpb: Makefile targets for the SDK vectors; publish-mirror.sh
jeffreyaven Aug 18, 2026
c7be46e
mcp-packaging: sdk validation matrix + per-vector publish jobs; docs
jeffreyaven Aug 18, 2026
2f6cc9f
packaging/mcpb: neutral version fixtures in cache-path unit tests
jeffreyaven Aug 18, 2026
315650e
packaging/mcpb: gleam publish reads HEXPM_API_KEY
jeffreyaven Aug 18, 2026
2f36e4d
packaging/mcpb: Windows fixes - ./gradlew.bat under make, LF gitattri…
jeffreyaven Aug 18, 2026
cbe6c1d
packaging/mcpb: tier the SDK vectors - published (cargo, go, dotnet) …
jeffreyaven Aug 18, 2026
7044c78
mcp-packaging: NuGet publish via Trusted Publishing (OIDC), no NUGET_…
jeffreyaven Aug 18, 2026
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
161 changes: 161 additions & 0 deletions .github/workflows/mcp-packaging.yml
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,13 @@
# 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 six embedded SDK wrappers (cargo, go, dotnet, gleam, kotlin, swift) 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 downloads through releases.stackql.io.
# Only the published tier (cargo, go, dotnet) then publishes from repo
# secrets (see the sdk / *-publish jobs); gleam, kotlin and swift are the
# preview tier: in tree and CI-validated, not published.
# The MCP Registry entry is published LAST, via the separate
# mcp-registry-publish workflow: the registry validates that the npm/PyPI/OCI
# packages already exist at the exact version, so it cannot run from here.
Expand Down Expand Up @@ -225,3 +232,157 @@ jobs:
echo "$DOCKERHUB_TOKEN" | docker login -u "$DOCKERHUB_USERNAME" --password-stdin
docker buildx create --use
make oci-push VERSION=${{ needs.version.outputs.version }}

# --- embedded SDK wrappers -------------------------------------------------
# One job per (vector, runner). Each: toolchain, render platforms.json for
# the version under test (needs the .mcpb.sha256 assets on the release, so
# on dispatch this runs after 'publish'), lint + unit tests + package, then
# scripts/smoke-test.py --cmd against the vector's launcher. On PRs the
# launcher extracts the bundle built by this run (STACKQL_MCP_BUNDLE, no
# network); on dispatch it downloads through releases.stackql.io and
# verifies the pin for real.
sdk:
name: sdk ${{ matrix.vector }} (${{ matrix.runner }})
needs: [version, bundle, bundle-windows, publish]
# 'publish' is skipped on PRs; run when it succeeded or was skipped.
if: >-
!cancelled()
&& needs.bundle.result == 'success'
&& needs.bundle-windows.result == 'success'
&& (needs.publish.result == 'success' || needs.publish.result == 'skipped')
strategy:
fail-fast: false
matrix:
include:
- { vector: cargo, runner: ubuntu-latest, target: linux-x64, py: python3 }
- { vector: cargo, runner: windows-latest, target: windows-x64, py: python }
- { vector: cargo, runner: macos-latest, target: darwin-universal, py: python3 }
- { vector: go, runner: ubuntu-latest, target: linux-x64, py: python3 }
- { vector: go, runner: windows-latest, target: windows-x64, py: python }
- { vector: dotnet, runner: ubuntu-latest, target: linux-x64, py: python3 }
- { vector: dotnet, runner: windows-latest, target: windows-x64, py: python }
- { vector: gleam, runner: ubuntu-latest, target: linux-x64, py: python3 }
- { vector: kotlin, runner: ubuntu-latest, target: linux-x64, py: python3 }
- { vector: swift, runner: macos-latest, target: darwin-universal, py: python3 }
runs-on: ${{ matrix.runner }}
env:
VERSION: ${{ needs.version.outputs.version }}
steps:
- uses: actions/checkout@v6
- name: Download this run's bundle (PR smoke input)
uses: actions/download-artifact@v8
with:
name: stackql-mcp-${{ matrix.target }}
path: packaging/mcpb/dist
- name: Point the launcher at the local bundle on PRs
if: needs.version.outputs.is_publish != 'true'
shell: bash
run: echo "STACKQL_MCP_BUNDLE=${{ github.workspace }}/packaging/mcpb/dist/stackql-mcp-${{ matrix.target }}.mcpb" >> "$GITHUB_ENV"
- name: GNU make (windows)
if: runner.os == 'Windows'
shell: bash
run: choco install make -y --no-progress
# toolchains
- if: matrix.vector == 'cargo'
uses: dtolnay/rust-toolchain@stable
with:
components: rustfmt, clippy
- if: matrix.vector == 'cargo'
uses: Swatinem/rust-cache@v2
with:
workspaces: packaging/mcpb/cargo
- if: matrix.vector == 'go'
uses: actions/setup-go@v6
with:
go-version: '1.25'
cache-dependency-path: packaging/mcpb/go/go.sum
- if: matrix.vector == 'dotnet'
uses: actions/setup-dotnet@v5
with:
dotnet-version: |
8.0.x
9.0.x
- if: matrix.vector == 'gleam'
uses: erlef/setup-beam@v1
with:
otp-version: '27'
gleam-version: '1.17.0'
- if: matrix.vector == 'kotlin'
uses: actions/setup-java@v5
with:
distribution: temurin
java-version: '21'
- if: matrix.vector == 'kotlin'
uses: gradle/actions/setup-gradle@v4
- if: matrix.vector == 'swift'
name: Select Xcode (Swift 6.1+)
run: |
if [ -d /Applications/Xcode_16.4.app ]; then sudo xcode-select -s /Applications/Xcode_16.4.app; fi
swift --version
# render -> build/test/lint/package -> smoke
- name: Render platforms.json + version stamp
shell: bash
run: make ${{ matrix.vector }}-manifest VERSION="$VERSION"
- name: Build, lint, unit tests, package
shell: bash
run: make ${{ matrix.vector }}-build VERSION="$VERSION"
- name: Smoke test (launcher via scripts/smoke-test.py --cmd)
shell: bash
run: make ${{ matrix.vector }}-smoke VERSION="$VERSION" PYTHON=${{ matrix.py }}

# --- SDK publish (dispatch only, after every sdk slice is green) ----------
# Published tier only: cargo, go, dotnet. (gleam/kotlin/swift have
# 'make <vector>-publish' targets for an out-of-band publish, no CI job.)
# Idempotent where the registry allows (skip if the version already exists);
# each prints the resulting coordinate. Ordering vs the registry entry is
# unchanged: mcp-registry-publish still runs last (it does not reference
# these packages; server.json package types are npm/pypi/oci/mcpb only).
cargo-publish:
name: publish cargo (crates.io)
if: needs.version.outputs.is_publish == 'true'
needs: [version, sdk]
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: dtolnay/rust-toolchain@stable
- env:
CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
run: make cargo-publish VERSION=${{ needs.version.outputs.version }}

# NuGet Trusted Publishing (OIDC): the nuget.org policy "stackql-mcp-packaging"
# (owner stackql, repo stackql/stackql, workflow mcp-packaging.yml) exchanges
# this job's GitHub OIDC token for a short-lived push key. No stored secret.
dotnet-publish:
name: publish dotnet (NuGet)
if: needs.version.outputs.is_publish == 'true'
needs: [version, sdk]
runs-on: ubuntu-latest
permissions:
contents: read
id-token: write
steps:
- uses: actions/checkout@v6
- uses: actions/setup-dotnet@v5
with:
dotnet-version: |
8.0.x
9.0.x
- name: NuGet login (trusted publishing)
id: nuget-login
uses: NuGet/login@v1
with:
user: stackql
- env:
NUGET_API_KEY: ${{ steps.nuget-login.outputs.NUGET_API_KEY }}
run: make dotnet-publish VERSION=${{ needs.version.outputs.version }}

go-publish:
name: publish go (mirror stackql-mcp-go, tag)
if: needs.version.outputs.is_publish == 'true'
needs: [version, sdk]
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- env:
SDK_MIRROR_TOKEN: ${{ secrets.SDK_MIRROR_TOKEN }}
run: make go-publish VERSION=${{ needs.version.outputs.version }}
33 changes: 30 additions & 3 deletions docs/stackql release process.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,11 +64,13 @@ git tag v0.10.591 && git push origin v0.10.591

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

The `mcp-packaging` workflow attaches the `.mcpb` bundles (and `.sha256` files) to the release and pushes the multi-arch OCI image to Docker Hub automatically. The npm and PyPI wrappers need interactive (2FA) credentials, so they are published from a local clone using the steps below (a Linux/WSL/macOS shell, from the repo root). The MCP Registry entry is then published by dispatching the `mcp-registry-publish` workflow (7c).
The `mcp-packaging` workflow attaches the `.mcpb` bundles (and `.sha256` files) to the release, pushes the multi-arch OCI image to Docker Hub, validates the six embedded SDK wrappers, and publishes the three in the published tier (7d-7f) automatically from repo secrets. The npm and PyPI wrappers need interactive (2FA) credentials, so they are published from a local clone using the steps below (a Linux/WSL/macOS shell, from the repo root). The MCP Registry entry is then published by dispatching the `mcp-registry-publish` workflow (7c).

Order matters and is strictly one-way: 7a and 7b (either order) only after step 6 completes, and 7c strictly last. The registry validates every package entry in server.json against its upstream registry at the exact version when publishing - if the npm or PyPI wrapper (or the OCI image) for the version is not live yet, the registry publish is rejected. There is no cycle: nothing references the registry entry, it references everything else.
Order matters and is strictly one-way: 7a, 7b and 7d-7f (any order among themselves) only after step 6 completes, and 7c strictly last. The registry validates every package entry in server.json against its upstream registry at the exact version when publishing - if the npm or PyPI wrapper (or the OCI image) for the version is not live yet, the registry publish is rejected. There is no cycle: nothing references the registry entry, it references everything else. The lettering is kept stable for cross-references; the textual order below is the execution order.

The render targets (`make npm-pack` / `make pypi-build`) consume the published `.sha256` release assets, so run them only after step 6 completes. The renderers also stamp the version into `packaging/mcpb/npm/package.json` and `packaging/mcpb/pypi/pyproject.toml` in place - commit or revert the stamps afterwards.
Every wrapper follows one contract: wrapper version == stackql release version, and its per-platform sha256 pins are data in a `platforms.json` rendered by `packaging/mcpb/scripts/render-platforms.sh` (`make manifests VERSION=X.Y.Z` renders all nine vectors, `make <vector>-manifest` one) from the published `.sha256` release assets - so render only after step 6 completes, and never pin locally built bundle hashes. The renderer also stamps the version into each vector's manifest file (`npm/package.json`, `pypi/pyproject.toml`, `cargo/Cargo.toml`, `dotnet/Directory.Build.props`, `gleam/gleam.toml`, `kotlin/gradle.properties`, `swift/Sources/StackQLMCP/Version.swift`) in place - commit or revert the stamps afterwards.

Standing rule: release assets are immutable once a wrapper has pinned them. If a `.mcpb` bundle must be rebuilt, cut a new patch release; never re-upload over an existing asset (the v0.10.500 re-upload of 2026-06-20 broke every published sidecar wrapper's sha256 check at once).

7a. npm (`@stackql/mcp-server`)

Expand All @@ -94,6 +96,31 @@ python -m twine check pypi/dist/*
python -m twine upload pypi/dist/*
```

7d-7f. Embedded SDK wrappers, published tier (cargo, go, dotnet) - dispatch handles it

The `mcp-packaging` dispatch from step 6 runs the `sdk` matrix for all six SDK vectors (render pins for the version, lint, unit tests, package, then `scripts/smoke-test.py --cmd` against each launcher with a real download through `releases.stackql.io`) and, when every slice is green, one publish job per published-tier vector from repo secrets:

| Step | Vector | Registry / coordinate | Secret(s) | Verify |
|---|---|---|---|---|
| 7d | cargo | crates.io `stackql-mcp` | `CARGO_REGISTRY_TOKEN` | `cargo info stackql-mcp` |
| 7e | go | mirror `stackql/stackql-mcp-go`, tag `vX.Y.Z` | `SDK_MIRROR_TOKEN` | `go list -m github.com/stackql/stackql-mcp-go@vX.Y.Z` |
| 7f | dotnet | NuGet `StackQL.Mcp` + `StackQL.Mcp.AgentFramework` | none - NuGet Trusted Publishing (OIDC) policy `stackql-mcp-packaging` on nuget.org; manual fallback needs a scoped API key in `NUGET_API_KEY` | `nuget list StackQL.Mcp` |

The publish jobs are idempotent where the registry allows (they skip when the version already exists) and each prints the resulting coordinate. `SDK_MIRROR_TOKEN` is a fine-grained PAT with `contents: write` on `stackql/stackql-mcp-go`.

Preview tier (gleam, kotlin, swift): in tree, rendered and CI-validated by the same `sdk` matrix on every packaging PR and dispatch, but NOT published and not part of the release train. `make gleam-publish` / `make kotlin-publish` / `make swift-publish` exist for a deliberate out-of-band publish (hex key; Central Portal + GPG; mirror push to `stackql/stackql-mcp-swift`) - if a preview vector is promoted, add its publish job to `mcp-packaging.yml` and its row above.

Manual fallback (a workflow failure, or an out-of-band publish) - the same Makefile targets from a local clone, with the credentials in the environment:

```
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
```

Each `<vector>-publish` target renders the manifest for `VERSION` first, so it also carries the ordering rule (after step 6). Validate before publishing with `make <vector>-build VERSION=X.Y.Z` and `make <vector>-smoke VERSION=X.Y.Z` (Swift needs a Mac).

7c. Official MCP Registry (`io.github.stackql/stackql-mcp`) - dispatch last

After 7a and 7b are live, dispatch the `mcp-registry-publish` workflow in [stackql/stackql](https://github.com/stackql/stackql) with the version. It needs no credentials: it authenticates with `mcp-publisher login github-oidc` (the registry grants `io.github.<repository_owner>/*` to GitHub Actions OIDC tokens, so no secret is stored) and renders server.json from the release `.sha256` assets. A preflight step fails fast with a pointer to the missing step if the npm, PyPI or OCI package for the version is not yet live.
Expand Down
Loading
Loading