embedded-mcp-packaging - #718

Milestone 1 of the embedded StackQL MCP server crate (stackql-mcp,
name verified free on crates.io):

- sidecar mode (default feature): downloads the platform .mcpb from the
  pinned stackql release (v0.10.500), verifies sha256 against pins baked
  from the release assets, extracts to the shared cache
  (~/.stackql/mcp-server-bin/<version>/<platform>/), spawns over stdio
- vendored feature: extract-on-first-run from caller-embedded bundle
  bytes (include_bytes!), keyed by content hash
- public API: StackqlMcp::builder().mode(Mode::ReadOnly).auth(json)
  .start() -> RunningServer exposing the child handle plus a connected
  rmcp client (Deref to the rmcp RunningService)
- canonical cwd-independent launch args per the packaging contract;
  modes read_only (default) / safe / delete_safe / full_access as
  defined by stackql's pkg/mcp_server policy
- env overrides STACKQL_MCP_BIN and STACKQL_MCP_BUNDLE, builder
  equivalents, and a sync Builder::command() escape hatch
- examples: minimal.rs (connected client) and launcher.rs (conformance
  launcher for the packaging repo smoke test)
- tests: unit (platform keys, pins, args, extract, sha256) plus a
  conformance integration test porting smoke-test.py (initialize,
  tools/list, pull_provider github, list_services github); passes
  against the real v0.10.500 bundle
- CI: fmt + clippy gates, linux/macos/windows test matrix including the
  conformance test

Deps held to the justified set: rmcp, zip, sha2, ureq (sidecar only),
serde/serde_json (already in rmcp's tree). MSRV 1.88, set by rmcp 1.x.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Milestone 2: the terminal compliance copilot demo plus the vendored
embedding story.

stackql-mcp:
- fetch_bundle(): download the pinned platform .mcpb into the shared
  cache (sha256-verified, idempotent) - the producer step for vendored
  builds; examples/fetch_bundle.rs prints the path for pipelines
- include_bundle! macro: embed the bundle named by the compile-time
  STACKQL_MCP_BUNDLE_FILE env var for Builder::bundle_bytes

auditron (workspace member, not published):
- scan: runs a YAML control pack through the embedded server in
  read_only mode; ratatui TUI streams pass/fail/error per control with
  the producing SQL always displayed; --no-tui line output for CI
  (exit 0 all pass, 2 any fail/error)
- press e on a finding: Claude (Messages API over ureq, pluggable
  Explainer trait) explains it and drafts remediation steps; without
  ANTHROPIC_API_KEY the SQL and a hint are shown instead
- evidence: re-runs the pack and writes an auditor-ready zip - run
  manifest (pack sha256, collector identity, server_info, timings),
  the exact pack source and per-control SQL, per-control CSVs
- controls/github-core.yaml: org security posture pack on the github
  provider in null_auth mode (zero credentials) - branch protection,
  default branch, descriptions, licenses, staleness, plus an inventory
  evidence control that doubles as the run canary (provider errors
  surface as empty result sets, which would silently pass no_rows
  controls but fail the canary)

Engine learnings baked into the pack authoring notes: tool results
carry the typed DTO in structuredContent (markdown in text content);
boolean storage varies per resource (compare = 0/1, never the strings
true/false); avoid OR and NOT in WHERE (pushdown quirks).

Verified end to end in WSL: live scan against the stackql org finds
real violations; evidence zip inspected; vendored release build (~80MB)
runs on a clean HOME with no downloads. CI extended for the workspace
including a vendored build check on all three OSes.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

- readme field and docs.rs all-features metadata; exclude the auditron
  demo, control packs, and launch kit from the published package
  (verified with cargo package --list)
- README badges for crates.io, docs.rs, and CI
- pr.md launch kit: docusaurus blog draft, r/rust and This Week in Rust
  posts, and a Rust meetup talk synopsis

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

- embed: go:embed vendoring kit for the signed stackql MCP server
  binary: sha256-verified extraction to the shared cache
  (~/.stackql/mcp-server-bin), canonical cwd-independent launch args,
  StartServer returning a connected modelcontextprotocol/go-sdk client
- cmd/stackql-mcp-fetch: go generate step that downloads the release
  .mcpb bundle, verifies the published pin, and writes go:embed glue
- conformance tests ported from stackql-mcpb-packaging smoke-test.py
  (github null_auth: initialize -> tools/list -> pull_provider ->
  list_services) plus a read_only mutation-refusal test
- cmd/sandboxctl: demo agent (anthropic-sdk-go + embedded server) that
  plans, prices, provisions, and reaps ephemeral GCP sandboxes with an
  approval gate; prints every SQL statement it runs
- CI matrix on linux/macos/windows; upstream pkg/mcpserver proposal
  draft in docs/

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

The sandboxctl go:embed glue and server binary are generated and
gitignored, so a fresh clone does not compile until
go generate ./cmd/sandboxctl runs. Generate first in CI and note the
step in the README testing section.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Day-to-day work happens on feature/embedded-go-mcp; checks run when a
PR to main is raised, and on v* tags for releases.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Library io.stackql:stackql-mcp acquires the signed stackql release binary
(env override -> shared cache -> sha256-pinned verified download), spawns it
as an MCP stdio server with the canonical cwd-independent launch arguments,
and returns a connected client built on the official MCP Kotlin SDK. Default
mode is read_only; escalation is an explicit opt-in. The binary cache is the
one shared with the npm/pypi wrappers.

Conformance tests mirror the packaging repo smoke test (initialize ->
tools/list -> pull_provider github null_auth -> list_services, plus a
read_only mutation-refusal check). Unit tests cover pins, platform, launch
args, and bundle extraction.

costgate, the demo, makes cloud cost a build check: a core engine prices a
declared resource intent against a pluggable pricing source (live stackql
SELECT, or a bundled offline rate card), totals it, and gates on a budget.
Shipped as a CLI (costgate check) and a Gradle plugin (the costgate task),
both emitting a console report (with --explain) and a JUnit-style XML report;
exit/build fails when over budget.

CI runs unit tests, the conformance sequence, and the offline costgate demo
on Linux, macOS, and Windows for every PR to main and every release tag.
Library publishes to Maven Central via the Central Portal; the plugin to the
Gradle Plugin Portal.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

The wrapper script was committed mode 100644; ./gradlew then fails with exit
126 (permission denied) on the Linux and macOS runners. Set the executable
bit in the index.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…sts, CI

Initial implementation of the Swift member of the StackQL embedded-MCP
family.

Package (Sources/StackQLMCP):
- Platform/Pins: packaging platform keys and per-version sha256 pins,
  mirroring the Go/Rust siblings and the packaging repo contract.
- LaunchArguments: the canonical, cwd-independent launch args
  (mcp --mcp.server.type=stdio --approot <abs> --mcp.config {...} [--auth]),
  default read_only mode, ~/.stackql approot and ~/.stackql/mcp-server-bin
  shared cache.
- BinaryResolver: locate-or-install in priority order - override env/path,
  bundled .app resource (Contents/Resources or Contents/Helpers), shared
  cache, then download. Atomic, sha-verified cache install.
- BundleFetcher: download the .mcpb release bundle, verify against the
  published pin (in-package table -> platforms.json -> .sha256 asset),
  extract the manifest entry_point with traversal guards.
- StackQLServer: spawn the binary over stdio via Foundation.Process, wire
  pipe FDs into the MCP SDK StdioTransport, connect a Client; convenience
  listToolNames/call wrappers. Quarantine cleared only on the download path.

Tests: offline unit suite (args, platform, pins, cache, sha,
bundle-extraction) plus a conformance integration suite gated on
STACKQL_MCP_INTEGRATION that mirrors the packaging repo smoke-test.py
(initialize -> tools/list -> pull_provider github null_auth ->
list_services) and asserts read_only refuses mutations.

CI runs on macOS runners on PRs to main, pushes to main, and v* tags:
build, offline unit tests, then the conformance suite.

Docs: bundling-and-notarisation.md (codesign/spctl/notarytool transcripts,
why --deep must not be used on the embedded binary, sandbox reality check)
and a rewritten README. Only dependency is modelcontextprotocol/swift-sdk.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

The first CI run failed in the swift-sdk dependency
(HTTPClientTransport.swift: "missing argument for parameter 'of'"), which is
the symptom of compiling its swift-tools-version 6.1 package with Swift 6.0.
The workflow had pinned Xcode_16.app (Swift 6.0). Select Xcode 16.4 (the
macos-15 default, Swift 6.1.2) instead, and bump our own manifest to
swift-tools-version 6.1 to document the real floor.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

An empty override string built URL(fileURLWithPath: "") which resolves to
the cwd; locateOffline then returned it instead of nil. Guard against empty.
Caught by testLocateOfflineReturnsNilWhenNothingPresent on CI.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Embedded StackQL MCP server for Swift/macOS (package, conformance tests, CI)

…ch sample, and CI

Library core (StackQL.Mcp):
- StackqlMcp.CreateBuilder() fluent builder with WithMode/WithAuth/WithBinary/
  WithBundlePath/WithApproot/WithCommand/StartAsync, idiomatic async + IAsyncDisposable
- StackqlMode enum (ReadOnly default; Safe/DeleteSafe/FullAccess explicit opt-in)
- Canonical cwd-independent launch args (mcp --mcp.server.type=stdio --approot
  <abs> --mcp.config {...}); audit disabled, read_only default
- Two acquisition modes: sidecar (download .mcpb, verify sha256 against embedded
  pins, extract to the shared ~/.stackql/mcp-server-bin/<ver>/<key>/ cache) and
  vendored (embed the bundle for single-file self-contained publish)
- STACKQL_MCP_BIN / STACKQL_MCP_BUNDLE overrides; zip-slip guarded extraction;
  StackqlServer.ResolveCommandAsync for harnesses that own the process
- Built on the official C# MCP SDK (ModelContextProtocol.Core 1.4.0); no other
  third-party deps

Agent Framework connector (StackQL.Mcp.AgentFramework, separate package):
- AsAgentToolsAsync() returns the StackQL tools as Microsoft.Extensions.AI
  AITool instances (McpClientTool : AIFunction : AITool), ready for an AIAgent's
  tools array. Core lib stays free of any Agent Framework dependency.

Sample (samples/driftwatch): Worker Service that embeds the read_only server,
runs a SQL drift suite on a schedule, and posts a Teams Adaptive Card with the
SQL behind each finding. Runs against the github null_auth fixture credential-free;
set up for single-file vendored publish.

Tests: 16 unit tests (launch-arg shape, mode wire values, pin parse, cache path,
platform key) plus the family conformance check (initialize -> tools/list ->
pull github -> list_services), skippable when no binary is present and verified
green locally against the real v0.10.500 bundle.

CI: GitHub Actions on PR + merge to main - dotnet format gate, 3-OS build/test
matrix (downloads the platform bundle to activate conformance), pack validation;
separate tag-driven manual NuGet publish workflow. Deterministic builds,
Source Link, embedded PDBs.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Scaffold the stackql_mcp Hex package: the embedded StackQL MCP server for
Gleam / BEAM. Erlang target only for v1 (the strategic thesis is the BEAM;
the JS target would just be a worse npm wrapper).

Library core:
- platform: shared cache path + platform-key resolution (the cross-family
  contract: ~/.stackql/mcp-server-bin/<version>/<platform-key>/)
- launch: canonical, cwd-independent argv (--approot is mandatory)
- mode: ReadOnly default; safe/delete_safe/full_access are explicit opt-ins
- auth: provider auth descriptors incl. the github null_auth fixture
- stackql_mcp: Config/default_config, resolve_command, start/list_tools/
  call_tool/stop, and child_spec for the BEAM-native supervised path
- mcp_client (0.1.x) owns the subprocess and JSON-RPC framing; this module
  builds the argv and wires the session

Tests (gleeunit):
- unit: launch-arg shape, cache-path layout, platform keys, resolve_command
  env precedence, auth rendering - all run with no stackql binary present
- conformance: the family handshake (initialize -> tools/list ->
  pull github null_auth -> list_services), self-gated on STACKQL_MCP_BIN so
  it logs and passes when no binary is available and runs for real in CI

CI: GitHub Actions matrix (ubuntu + macos + windows) running
gleam format --check, gleam check, gleam test. Triggers on pull_request to
main (PR raise/update) and push to main (merge). Windows is in the matrix
deliberately - Erlang ports there have sharp edges.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

First CI run surfaced two issues:
- mcp_client 0.1.x requires gleam_json >= 3.0.0; the previous < 3.0.0 pin
  made dependency resolution unsatisfiable. Track the 3.x major.
- erlef/setup-beam@v1 could not map the new win25-vs2026 runner image
  ("Tried to map a target OS from env. variable 'ImageOS'... but failed").
  Pin to @v1.24.0, which supports win25.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Second CI run surfaced:
- gleam format --check failed: canonicalize all src/test with gleam format.
- setup-beam still could not map the windows-latest ImageOS
  (win25-vs2026). Pin the Windows matrix leg to windows-2022 (ImageOS
  win22), which the action maps. Revisit when setup-beam supports win25.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Third CI run surfaced:
- Type check failed: `mcp_client.ServerConfig is a type constructor, it
  cannot be used as a value`. The value constructor lives in
  mcp_client/manager (mcp_client only re-exports the type alias). Construct
  manager.ServerConfig with manager.NoRetry.
- Windows format --check failed because the runner checks out CRLF
  (core.autocrlf=true) while gleam format emits LF. Add .gitattributes
  pinning .gleam/.erl/.toml/.yml/.md to eol=lf so the check is stable
  cross-platform.

Verified locally with gleam 1.17.0: gleam format --check passes; deps
resolve to gleam_json 3.1.0 / mcp_client 0.1.0 / envoy 1.2.0. (gleam check
needs Erlang, which is not installed locally - CI compiles.)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

gleam generated the lockfile pinning the resolved versions (gleam_json
3.1.0, mcp_client 0.1.0, envoy 1.2.0, gleam_stdlib 1.0.3, etc.). The file
itself instructs that it be checked in; doing so keeps CI from re-resolving
and matches the family stance of pinning every dependency.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* docs: correct Swift floor to 6.1 / macOS 13 in CLAUDE.md

The MCP swift-sdk is a swift-tools-version 6.1 package, so 6.1 (Xcode
16.3+) is the real minimum, not 5.10.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(cloudlens): menu bar cloud sentinel demo app (milestone 2)

CloudLens embeds the StackQL MCP server and runs a small read_only pulse
suite, surfacing state in the macOS menu bar with native notifications.

Structure (two SwiftPM targets so the logic is CI-testable without a GUI):

CloudLensCore (library, no SwiftUI):
- Finding/Severity/PulseKind/PulseResult domain model with the SQL behind
  each finding carried through to notifications.
- FindingDiff: pure menu-bar-state derivation and new-since-last-run diff.
- Pulse protocol + RowParser (parses StackQL JSON-array tool output) and
  three pulses: PosturePulse (github null_auth, the zero-cred demo pulse),
  SpendPulse and ExposurePulse (AWS, degrade to "not configured" without
  creds rather than a false all-calm).
- SentinelModel: @mainactor orchestrator - starts the embedded server, runs
  the suite, derives state, diffs, fires the new-findings hook.
- AnthropicAgent: URLSession Messages API client (no official Swift SDK),
  x-api-key + anthropic-version headers, claude-opus-4-8, key never bundled.
- Keychain: generic-password store for the Anthropic key.

CloudLens (executable, SwiftUI):
- MenuBarExtra app; icon reflects calm/attention/unknown; popover shows the
  three pulses with each finding's SQL (selectable). AppDelegate runs an
  initial check at launch then on a 15-minute schedule.
- Notifications: one native notification per new attention finding, body
  includes the SQL behind it.

Tests (CloudLensCoreTests, offline): finding diff/state, row parsing, each
pulse's finding generation and severity thresholds, agent prompt building and
response extraction. CI builds the CloudLens product explicitly and runs the
new test target (swift build/test already cover both).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* ci: trigger on feature/** pushes and any PR base

Long-lived feature branches may stack on each other (CloudLens is based on
the package branch, not main), so a PR whose base is another feature branch
never matched 'pull_request: branches: [main]' and got no CI. Run on every
PR and on pushes to main and feature/** so stacked branches are validated.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(cloudlens): wrap runtime String tool args as MCP Value

A [String: String] literal of runtime variables does not implicitly convert
to [String: Value] (Value's ExpressibleByStringLiteral only applies to string
literals). Add a call(_:stringArgs:) overload that maps via
Value(stringLiteral:) and use it from the pulses.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Add a Requirements section so the target framework is explicit rather than
inferred. Both packages ship net8.0 and net9.0; the .NET 8 floor is set by the
official C# MCP SDK. Notes that the sample/tests target net9.0 only and that this
does not raise the consumer floor.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

The v0.10.500 release assets were re-published upstream, so the sha256
pins baked into 0.1.0 no longer verify (conformance test fails with
ChecksumMismatch on all platforms). Re-pin to v0.10.601; all four pins
match the published .mcpb.sha256 assets.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

git-subtree-dir: packaging/mcpb/go
git-subtree-mainline: cbba228
git-subtree-split: 68b79a9

git-subtree-dir: packaging/mcpb/dotnet
git-subtree-mainline: 97a22bf
git-subtree-split: ecb7478

…b/gleam

git-subtree-dir: packaging/mcpb/gleam
git-subtree-mainline: 66362d4
git-subtree-split: ae4156a

…pb/kotlin

git-subtree-dir: packaging/mcpb/kotlin
git-subtree-mainline: c8f4254
git-subtree-split: 98314ee

git-subtree-dir: packaging/mcpb/cargo
git-subtree-mainline: d457721
git-subtree-split: b4a88cc

git-subtree-dir: packaging/mcpb/swift
git-subtree-mainline: 699f753
git-subtree-split: 98467a3

…rees

Demo apps (auditron, stackql-agent, controls, sandboxctl, driftwatch,
costgate*, CloudLens*) move to stackql-labs; each SDK's CI folds into
.github/workflows/mcp-packaging.yml.

…platforms.json

- scripts/render-platforms.sh: one renderer for all vectors (npm/pypi
  renderers now delegate to it; output byte-identical)
- cargo: pins rendered from platforms.json by build.rs (no hand table),
  proxy baseUrl, per-vector User-Agent, workspace/demo refs removed,
  crate version = stackql version

…auncher

- embed/platforms.json (go:embed) is the only pin source; DefaultVersion,
  BundlePins now derive from it; download from baseUrl (proxy) with
  per-vector User-Agent; no version override, no GitHub API calls
- sidecar acquisition (STACKQL_MCP_BIN / STACKQL_MCP_BUNDLE, shared cache,
  pin-verified download) when Options.Binary is unset
- cmd/stackql-mcp-launch for smoke-test.py --cmd; internal/fetch folded
  into embed; anthropic dep dropped with sandboxctl

…ple, version stamp

- pins.json (PLACEHOLDER) replaced by the rendered platforms.json resource;
  Pins parses version/baseUrl/platforms and is loaded once
- download from baseUrl (proxy) with per-vector User-Agent
- <Version> in Directory.Build.props stamped by the renderer
- samples/Launcher for smoke-test.py --cmd; driftwatch removed
- cache-hit lookup finds the bundle's server/<binary> entry (was
  re-downloading on every run)

…cher

- src/stackql_mcp/pins.gleam is generated by render-platforms.sh from
  platforms.json (replaces the stale v0.7.0 const); no other pin source
- stackql_mcp/acquire: STACKQL_MCP_BIN / STACKQL_MCP_BUNDLE, shared cache,
  httpc download from baseUrl with per-vector User-Agent, sha256 verify,
  entry-point extraction (Erlang FFI); start() now acquires
- stackql_mcp/launcher: gleam run -m stackql_mcp/launcher -- relays stdio
  through the BEAM for smoke-test.py --cmd
- version stamped in gleam.toml; OTP 27+

…dule, Central Portal publishing

- Pins reads the rendered platforms.json classpath resource (no hand table);
  download from baseUrl (proxy) with per-vector User-Agent; Builder.version
  override removed (version-locked)
- gradle.properties version stamped by the renderer; LIBRARY_VERSION follows
- launcher module (application plugin) for smoke-test.py --cmd
- com.vanniktech.maven.publish -> publishToMavenCentral, signed
- costgate demo modules removed (stackql-labs)

…se new files

Also carries the 0.10.601 version stamps for npm/package.json and
pypi/pyproject.toml (rendered by the same renderer for the same release).

…, launcher target

- Pins reads the rendered platforms.json package resource (no hand table);
  BundleFetcher downloads <baseUrl>/<bundle> with per-vector User-Agent,
  version-locked (no version override, no GitHub API calls)
- STACKQL_MCP_BINARY renamed to STACKQL_MCP_BIN (old name still read,
  deprecated); STACKQL_MCP_BUNDLE / Options.bundleOverride added
- stackql-mcp-launch executable target for smoke-test.py --cmd
- Version.swift stamped by the renderer; CloudLens removed (stackql-labs)

make manifests | <vector>-manifest | <vector>-build | <vector>-smoke |
<vector>-publish for cargo/go/dotnet/gleam/kotlin/swift; go and swift
publish by pushing the rendered subtree to their mirror repos and tagging
v<version> (idempotent, immutable).

- .github/workflows/mcp-packaging.yml: sdk job (cargo/go/dotnet/gleam/
  kotlin/swift x runners; PRs smoke against this run's bundle via
  STACKQL_MCP_BUNDLE, dispatch downloads through releases.stackql.io) and
  dispatch-only publish jobs from repo secrets; existing jobs untouched
- docs/stackql release process.md: 7d-7i SDK vectors, immutability rule
- packaging/mcpb/CLAUDE.md, README.md: the nine vectors and ordering rules
- per-vector CLAUDE.md rewritten for the monorepo

…butes for go/kotlin checkouts

…vs preview (gleam, kotlin, swift)

Preview vectors stay in tree on the same contract and are validated by
the sdk CI matrix, but have no publish job and no registry commitment;
their make <vector>-publish targets remain for an out-of-band publish.
Drops the kotlin windows CI slice; last-mile secrets shrink to
CARGO_REGISTRY_TOKEN, NUGET_API_KEY, SDK_MIRROR_TOKEN (go mirror).

…API_KEY secret