Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
57 commits
Select commit Hold shift + click to select a range
5fc6e24
initial commit
jeffreyaven Jun 4, 2026
e9eb28a
updates
jeffreyaven Jun 5, 2026
a259b44
v0.10.500
jeffreyaven Jun 12, 2026
c85b0aa
Set executable bit on shell scripts for Linux/macOS runners
jeffreyaven Jun 12, 2026
c442bd1
Invoke scripts via bash so a lost exec bit cannot break the build
jeffreyaven Jun 12, 2026
6c9400f
Merge pull request #1 from stackql/feature/mcpb-publish
jeffreyaven Jun 12, 2026
e408838
Add make sign target and optional envelope signing in publish workflow
jeffreyaven Jun 12, 2026
a59fa1d
Merge pull request #2 from stackql/feature/envelope-signing
jeffreyaven Jun 12, 2026
8252b56
Add append-signature.py for externally-produced CMS signatures
jeffreyaven Jun 12, 2026
88f553f
Add workflow_dispatch re-publish path to publish.yml
jeffreyaven Jun 12, 2026
fe6cd47
Merge pull request #3 from stackql/feature/publish-dispatch
jeffreyaven Jun 12, 2026
c4b16de
Add StackQL icon to bundle manifest
jeffreyaven Jun 12, 2026
bdf8064
Merge pull request #4 from stackql/feature/extension-icon
jeffreyaven Jun 12, 2026
0f6c3d8
Fix server.json template for registry validation rules
jeffreyaven Jun 12, 2026
202fbd8
Merge pull request #5 from stackql/feature/registry-template-fixes
jeffreyaven Jun 12, 2026
ab74007
Record current Anthropic directory submission form URLs
jeffreyaven Jun 12, 2026
e08eff4
Merge pull request #6 from stackql/docs/submission-form-urls
jeffreyaven Jun 12, 2026
940eeec
Fix server death under Claude Desktop: cwd-independent approot and audit
jeffreyaven Jun 12, 2026
94feb10
Merge pull request #7 from stackql/fix/desktop-cwd-readonly
jeffreyaven Jun 12, 2026
c8fb791
Document registry SHA-pin recovery after in-place republish
jeffreyaven Jun 12, 2026
ebcd12d
Merge pull request #8 from stackql/docs/registry-republish-note
jeffreyaven Jun 12, 2026
7885d65
Update listings tracker: registry live, Anthropic/Glama/mcp.so submit…
jeffreyaven Jun 12, 2026
ab1e321
Merge pull request #9 from stackql/docs/listings-tracker-20260613
jeffreyaven Jun 12, 2026
8da83cf
Restructure listings tracker with status/date/follow-up columns; add …
jeffreyaven Jun 12, 2026
0af03ad
Merge pull request #10 from stackql/docs/listings-restructure
jeffreyaven Jun 12, 2026
67fc8fc
Feature/install vectors (#11)
jeffreyaven Jun 15, 2026
8d55bfe
Post-rollout cleanup: extract action to its own repo, land registry/d…
jeffreyaven Jun 15, 2026
20d7f89
Merge pull request #12 from stackql/chore/post-rollout-cleanup
jeffreyaven Jun 15, 2026
ee84379
Update listings tracker for Monday rollout
jeffreyaven Jun 15, 2026
b18ade7
Merge pull request #13 from stackql/docs/listings-monday-rollout
jeffreyaven Jun 15, 2026
3ea7a02
listings: Smithery N/A (25MB bundle cap), Docker Catalog pending upst…
jeffreyaven Jun 15, 2026
4106385
Merge pull request #14 from stackql/docs/listings-smithery-docker
jeffreyaven Jun 15, 2026
90434ec
listings: correct GitHub MCP Registry guidance (curated, auto-ingest …
jeffreyaven Jun 15, 2026
28d8f16
Merge pull request #15 from stackql/docs/github-mcp-registry-guidance
jeffreyaven Jun 15, 2026
4f5088b
Add LICENSE, README, and privacy_policies to bundles (Anthropic review)
jeffreyaven Jun 20, 2026
3ae9082
Merge pull request #16 from stackql/feat/bundle-license-readme-privacy
jeffreyaven Jun 20, 2026
e0e6eff
LICENSE: copyright year range 2022-2026 (#17)
jeffreyaven Jun 20, 2026
3738746
Release: package stackql v0.10.542 (+ #18 proxy/UA changes) (#19)
jeffreyaven Jul 3, 2026
5398e49
render scripts: proxy path is /stackql/<version> without v prefix (#20)
jeffreyaven Jul 3, 2026
ccf3b91
feat: mcp credential (re)sourcing via server.env_file + reload_creden…
jeffreyaven Jul 17, 2026
588ea9e
fix: odata pushdown $select unions WHERE and ORDER BY columns (#682)
jeffreyaven Jul 17, 2026
8aeff64
fix: function projections no longer inherit argument column schema ty…
jeffreyaven Jul 17, 2026
e2d743e
ci: disable star-check workflow
jeffreyaven Jul 17, 2026
e750756
feat: constant-fold WHERE function expressions for provider parameter…
jeffreyaven Jul 17, 2026
bc7d2b9
test: robot coverage for page_number REST and pluggable GraphQL pagin…
jeffreyaven Jul 17, 2026
8ce217a
feat: batch mutation fan-out for IN-list parameters in the planner (#…
jeffreyaven Jul 17, 2026
49c5895
chore: remove repo-level FUNDING.yml (moved to org level)
jeffreyaven Jul 17, 2026
1a25ce2
test: strengthen batch mutation fan-out coverage (#683)
jeffreyaven Jul 17, 2026
5848916
Add 'packaging/mcpb/' from commit '5398e499f2706cbb306ac12f8263676a64…
jeffreyaven Jul 18, 2026
cb64459
packaging: adapt imported mcpb tooling to in-repo workflows (manual p…
jeffreyaven Jul 18, 2026
3aff354
packaging: multiplatform combined bundle for single-artefact venues
jeffreyaven Jul 18, 2026
9886d82
ci: exempt mcp-packaging workflow edits from the full build matrix
jeffreyaven Jul 18, 2026
784124f
ci: teach actionlint the ubuntu-24.04-arm hosted runner label
jeffreyaven Jul 18, 2026
2e7e1a4
refactor: promote env_file to a root --env.file flag for every entryp…
jeffreyaven Jul 18, 2026
0912041
docs: halve comment volume across PR-touched code
jeffreyaven Jul 18, 2026
a885d57
packaging: wire credentials env file into MCPB user_config
jeffreyaven Jul 18, 2026
da2fe11
Revert "packaging: wire credentials env file into MCPB user_config"
jeffreyaven Jul 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
2 changes: 0 additions & 2 deletions .github/FUNDING.yml

This file was deleted.

3 changes: 2 additions & 1 deletion .github/actionlint.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -8,4 +8,5 @@ self-hosted-runner:
- macos-14 # should not be necessary
- macos-15 # should not be necessary
- macos-15-intel # should not be necessary
- windows-11-arm # GitHub-hosted arm64 Windows runner, newer than actionlint's built-in label list
- windows-11-arm # GitHub-hosted arm64 Windows runner, newer than actionlint's built-in label list
- ubuntu-24.04-arm # GitHub-hosted arm64 Linux runner, newer than actionlint's built-in label list
4 changes: 4 additions & 0 deletions .github/workflows/build.yml
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,8 @@ on:
- 'get-app/**'
- 'test-get-app.ps1'
- 'test-get-app.sh'
- 'packaging/**'
- '.github/workflows/mcp-packaging.yml'
pull_request:
branches:
- main
Expand All @@ -45,6 +47,8 @@ on:
- 'get-app/**'
- 'test-get-app.ps1'
- 'test-get-app.sh'
- 'packaging/**'
- '.github/workflows/mcp-packaging.yml'
env:
GOTESTCMD: "go test -timeout 1200s --tags \"sqlite_stackql\" -v ./..."
TESTSCRIPT: "test/deprecated/python/main.py"
Expand Down
272 changes: 272 additions & 0 deletions .github/workflows/mcp-packaging.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,272 @@
# MCP bundle packaging: builds + smoke-tests the .mcpb bundles, OCI image and
# npm/pypi wrapper artifacts from packaging/mcpb. Validation runs on
# packaging/** PRs; publishing is MANUAL (workflow_dispatch) because the
# consumed release assets (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.

name: mcp-packaging

on:
pull_request:
paths: ['packaging/**']
workflow_dispatch:
inputs:
version:
description: stackql release version without the leading v (e.g. 0.10.550); the release's signed assets must already be attached
required: true
type: string

permissions:
contents: read

defaults:
run:
working-directory: packaging/mcpb

jobs:
version:
name: resolve version
runs-on: ubuntu-latest
outputs:
version: ${{ steps.resolve.outputs.version }}
is_publish: ${{ steps.resolve.outputs.is_publish }}
steps:
- name: Resolve target release version
id: resolve
working-directory: .
env:
GH_TOKEN: ${{ github.token }}
run: |
if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
tag="v${{ inputs.version }}"
echo "is_publish=true" >> "$GITHUB_OUTPUT"
else
tag="$(gh release view -R "$GITHUB_REPOSITORY" --json tagName -q .tagName)"
echo "is_publish=false" >> "$GITHUB_OUTPUT"
fi
echo "resolved: $tag"
echo "version=${tag#v}" >> "$GITHUB_OUTPUT"

bundle:
needs: version
strategy:
fail-fast: false
matrix:
include:
- target: linux-x64
runner: ubuntu-latest
- target: linux-arm64
runner: ubuntu-24.04-arm
- target: darwin-universal
runner: macos-latest
name: ${{ matrix.target }}
runs-on: ${{ matrix.runner }}
steps:
- uses: actions/checkout@v6
- name: Build bundle
run: make one TARGET=${{ matrix.target }} VERSION=${{ needs.version.outputs.version }}
- name: Smoke test (deterministic MCP handshake)
run: python3 scripts/smoke-test.py dist/stackql-mcp-${{ matrix.target }}.mcpb
- name: Upload bundle artifact
uses: actions/upload-artifact@v7
with:
name: stackql-mcp-${{ matrix.target }}
path: |
packaging/mcpb/dist/stackql-mcp-${{ matrix.target }}.mcpb
packaging/mcpb/dist/stackql-mcp-${{ matrix.target }}.mcpb.sha256
if-no-files-found: error

bundle-windows:
name: windows-x64 (build)
needs: version
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- name: Build bundle
run: make one TARGET=windows-x64 VERSION=${{ needs.version.outputs.version }}
- name: Upload bundle artifact
uses: actions/upload-artifact@v7
with:
name: stackql-mcp-windows-x64
path: |
packaging/mcpb/dist/stackql-mcp-windows-x64.mcpb
packaging/mcpb/dist/stackql-mcp-windows-x64.mcpb.sha256
if-no-files-found: error

smoke-windows:
name: windows-x64 (smoke)
needs: bundle-windows
runs-on: windows-latest
steps:
- uses: actions/checkout@v6
- name: Download bundle artifact
uses: actions/download-artifact@v8
with:
name: stackql-mcp-windows-x64
path: packaging/mcpb/dist
- name: Smoke test (deterministic MCP handshake)
run: python scripts/smoke-test.py dist/stackql-mcp-windows-x64.mcpb

oci:
name: oci (build + smoke)
needs: version
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- name: Build image
run: make oci VERSION=${{ needs.version.outputs.version }}
- name: Smoke test (deterministic MCP handshake)
run: python3 scripts/smoke-test.py --docker stackql/stackql-mcp:${{ needs.version.outputs.version }}

# Multiplatform bundle for single-artefact venues, built from the four
# per-platform bundle artifacts (byte-identical binaries); verify-combined.py
# asserts every binary's machine type.
combined:
name: multiplatform (combined build + byte verification)
needs: [version, bundle, bundle-windows]
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- name: Gather per-platform bundle artifacts
uses: actions/download-artifact@v8
with:
pattern: stackql-mcp-*
path: packaging/mcpb/dist
merge-multiple: true
- name: Build combined bundle (hard-fails unless all four bundles present)
run: make combined VERSION=${{ needs.version.outputs.version }}
- name: Upload combined bundle artifact
uses: actions/upload-artifact@v7
with:
name: stackql-mcp-multiplatform
path: |
packaging/mcpb/dist/stackql-mcp-multiplatform.mcpb
packaging/mcpb/dist/stackql-mcp-multiplatform.mcpb.sha256
if-no-files-found: error

# Install-and-handshake the combined bundle on every host OS (arm64 linux
# leg covers the arch shim): each host must select its own binary via
# platform_overrides and complete the MCP handshake.
combined-smoke:
name: multiplatform smoke (${{ matrix.runner }})
needs: combined
strategy:
fail-fast: false
matrix:
include:
- runner: ubuntu-latest
py: python3
- runner: ubuntu-24.04-arm
py: python3
- runner: macos-latest
py: python3
- runner: windows-latest
py: python
runs-on: ${{ matrix.runner }}
steps:
- uses: actions/checkout@v6
- name: Download combined bundle
uses: actions/download-artifact@v8
with:
name: stackql-mcp-multiplatform
path: packaging/mcpb/dist
- name: Smoke test (platform_overrides selection + MCP handshake)
run: ${{ matrix.py }} scripts/smoke-test.py dist/stackql-mcp-multiplatform.mcpb

publish:
name: upload bundles to release
if: needs.version.outputs.is_publish == 'true'
needs: [version, bundle, bundle-windows, smoke-windows, oci, combined, combined-smoke]
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- uses: actions/checkout@v6
- name: Gather bundle artifacts
uses: actions/download-artifact@v8
with:
pattern: stackql-mcp-*
path: packaging/mcpb/dist
merge-multiple: true
- name: Envelope-sign bundles (when signing material configured)
env:
MCPB_SIGNING_CERT: ${{ secrets.MCPB_SIGNING_CERT }}
MCPB_SIGNING_KEY: ${{ secrets.MCPB_SIGNING_KEY }}
MCPB_SIGNING_INTERMEDIATES: ${{ secrets.MCPB_SIGNING_INTERMEDIATES }}
run: |
if [ -n "$MCPB_SIGNING_CERT" ] && [ -n "$MCPB_SIGNING_KEY" ]; then
make sign
else
echo "signing material not configured; publishing unsigned bundles"
fi
- name: Upload to release (same repo - GITHUB_TOKEN suffices)
env:
GH_TOKEN: ${{ github.token }}
run: make publish VERSION=${{ needs.version.outputs.version }}

oci-publish:
name: push OCI image
if: needs.version.outputs.is_publish == 'true'
needs: [version, oci]
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- name: Push multi-arch image
env:
DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }}
run: |
echo "$DOCKERHUB_TOKEN" | docker login -u "$DOCKERHUB_USERNAME" --password-stdin
docker buildx create --use
make oci-push VERSION=${{ needs.version.outputs.version }}

# npm / pypi manifests render from the published .sha256 files as run
# artifacts; publishing to npmjs / PyPI stays manual (2FA).
npm-tarball:
name: npm tarball (manual publish artifact)
if: needs.version.outputs.is_publish == 'true'
needs: [version, publish]
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- name: Render manifest + pack
run: make npm-pack VERSION=${{ needs.version.outputs.version }}
- uses: actions/upload-artifact@v7
with:
name: npm-package
path: packaging/mcpb/npm/*.tgz

pypi-dist:
name: pypi dist (manual publish artifact)
if: needs.version.outputs.is_publish == 'true'
needs: [version, publish]
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- name: Render manifest + build
run: make pypi-build VERSION=${{ needs.version.outputs.version }}
- uses: actions/upload-artifact@v7
with:
name: pypi-dist
path: packaging/mcpb/pypi/dist/*

server-json:
name: render registry server.json
if: needs.version.outputs.is_publish == 'true'
needs: [version, publish]
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- name: Gather bundle artifacts (for sha pins)
uses: actions/download-artifact@v8
with:
pattern: stackql-mcp-*
path: packaging/mcpb/dist
merge-multiple: true
- name: Render server.json
run: make server-json VERSION=${{ needs.version.outputs.version }}
- uses: actions/upload-artifact@v7
with:
name: server-json
path: packaging/mcpb/registry/server.json
26 changes: 25 additions & 1 deletion docs/mcp.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,27 @@ Audit is on by default. To opt out:

```

### Credential (re)sourcing (`--env.file` + `reload_credentials`)

`--env.file` is a root flag: it nominates a dotenv-style file that every stackql entrypoint (`exec`, `shell`, `srv`, `mcp`) sources into the process environment at startup. For the MCP server it additionally acts as a mutable credential store: a process env block is fixed at spawn, so a stdio server launched without credential vars (eg by Claude Desktop) can only pick them up from such a file, re-sourced on each `reload_credentials` tool call.

```bash

./build/stackql mcp --mcp.server.type=stdio --env.file /path/to/stackql-credentials.env

```

Semantics:

- Sourced at startup (if the file exists) and again on every `reload_credentials` call; only keys with non-empty values are set, nothing is ever unset.
- The file may be created, updated or rotated at any time while the server runs.
- `reload_credentials` reports variable names and per-provider status (`ok`, `unresolved`, `not_checked`) only; secret values are never returned, logged or audited. Without `--env.file` it degrades to a pure status probe.
- Credential resolution failures carry a hint directing the agent to call `reload_credentials` and retry.

File format: one `KEY=VALUE` per line; `#` comments, blank lines, `export ` prefixes, surrounding quotes and CRLF are tolerated.

Note for Claude Desktop on Windows: `setx` writes the registry, not running processes, and Claude Desktop passes its own (stale) environment to MCP subprocesses; `--env.file` avoids restarts entirely.


## Using the MCP Client

Expand Down Expand Up @@ -121,7 +142,7 @@ Then, assuming you have a `stackql` MCP server serving streamable HTTP on port `

## Canonical agent tools

The server publishes 11 tools. Each returns both rendered text (for the LLM) and a typed structured payload (for programmatic clients). Rendering is fixed per tool: a markdown table for uniform multi-row results, a markdown KV block for sparse / single-record / mixed-shape results.
The server publishes 14 tools. Each returns both rendered text (for the LLM) and a typed structured payload (for programmatic clients). Rendering is fixed per tool: a markdown table for uniform multi-row results, a markdown KV block for sparse / single-record / mixed-shape results.

| Tool | Renderer | Description |
|---|---|---|
Expand All @@ -136,6 +157,9 @@ The server publishes 11 tools. Each returns both rendered text (for the LLM) an
| `run_select_query` | Table | Execute a SELECT. Returns `{rows}`. Reads only. |
| `run_mutation_query` | KV | Execute INSERT/UPDATE/REPLACE/DELETE. **Real side effects.** Returns `{messages, timestamp}`. Gated by the server [mode](#server-modes). |
| `run_lifecycle_operation` | KV | Execute a stackql `EXEC` lifecycle operation. Returns `{messages, timestamp}`. Gated by the server [mode](#server-modes). |
| `list_registry` | Table | Providers (and their versions) available in the configured registry. Optional `provider` lists versions for that provider. |
| `pull_provider` | KV | Install a provider from the registry into the local approot cache. Requires `provider`; `version` optional. Local cache write only. |
| `reload_credentials` | Table | Re-source credentials from the [`--env.file`](#credential-resourcing---envfile--reload_credentials) dotenv file into the process environment and report per-provider resolution status. Never returns secret values. Optional `provider` scopes the report. Allowed in every mode. |

## Canonical agent prompts

Expand Down
Loading
Loading