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
7 changes: 7 additions & 0 deletions .github/workflows/build.yml
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,8 @@ on:
- 'CLAUDE.md'
- 'glama.json'
- 'get-app/**'
- 'cicd/python/attach_build_artifacts.py'
- 'cicd/python/test_attach_build_artifacts.py'
- 'test-get-app.ps1'
- 'test-get-app.sh'
- 'packaging/**'
Expand All @@ -47,6 +49,8 @@ on:
- 'CLAUDE.md'
- 'glama.json'
- 'get-app/**'
- 'cicd/python/attach_build_artifacts.py'
- 'cicd/python/test_attach_build_artifacts.py'
- 'test-get-app.ps1'
- 'test-get-app.sh'
- 'packaging/**'
Expand Down Expand Up @@ -2251,6 +2255,9 @@ jobs:
runs-on: ubuntu-latest
strategy:
fail-fast: false
# One manifest push at a time: the two variants in parallel have hit
# Docker Hub 429s on the manifest reads (2026-11-05, twice).
max-parallel: 1
matrix:
variant: [standard, python]
needs:
Expand Down
9 changes: 5 additions & 4 deletions docs/stackql_release_process.md
Original file line number Diff line number Diff line change
Expand Up @@ -175,7 +175,7 @@ git commit -m "vX.Y.Z"
git push origin main
```

`publish-prep.ps1` downloads both MSIs from `https://releases.stackql.io/stackql/X.Y.Z/`, checks their `ProductVersion` (nothing is installed) and rewrites `chocolatey\tools\chocolateyinstall.ps1` (URLs and SHA256 checksums) and `chocolatey\stackql.nuspec` (version, release notes). The push to `main` runs that repo's `chocolatey-publish` workflow, which packs, test-installs and pushes the package to chocolatey.org with the `CHOCOLATEY_API_KEY` secret; a push without a version bump is a no-op. Verify with `choco info stackql` or that repo's `chocolatey-smoke` workflow.
`publish-prep.ps1` downloads both MSIs from `https://releases.stackql.io/stackql/X.Y.Z/`, checks their `ProductVersion` (nothing is installed) and rewrites `chocolatey\tools\chocolateyinstall.ps1` (URLs and SHA256 checksums) and `chocolatey\stackql.nuspec` (version, release notes). The push to `main` runs that repo's `chocolatey-publish` workflow, which packs, test-installs and pushes the package to chocolatey.org with the `CHOCOLATEY_API_KEY` secret; a push without a version bump is a no-op. Verify with `choco info stackql` or that repo's `chocolatey-smoke` workflow. `stackql` is a trusted Chocolatey package: moderation emails "Submitted for Moderation Review" on the push, the automated checks typically finish within 1 to 2 hours, and the version is listed without human moderation once they pass.

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

Expand Down Expand Up @@ -270,7 +270,7 @@ What the render changes, all of which is committed:

Both plugins read the plugin from git, so their `platforms.json` is committed, unlike the wrappers'. The validators fail when any vendored file or version disagrees with `packaging/mcpb/npm`. Open a PR (`chore/pins-X.Y.Z`); the `stdio-plugins` workflow repeats validation and the smoke tests on four platforms, re-renders both plugins from the published checksums and fails if the committed payload differs, runs `claude plugin validate --strict`, and builds the ChatGPT directory ZIP as a run artifact. Merge it. The Codex repo marketplace (`codex plugin marketplace add stackql/stackql --sparse .agents/plugins --sparse packaging/openai-plugin`) serves the new pin as soon as the merge lands; nothing else to do for it.

Branch from `main`, not from a fix branch used during the release. Because the PR changes `packaging/**`, the full `Build` matrix and the `mcp-packaging` validation run as well as `stdio-plugins` (about an hour); that is expected.
Branch from `main`, not from a fix branch used during the release. `packaging/**` is in the Build workflow's `paths-ignore`, so the PR runs `stdio-plugins`, the `mcp-packaging` validation, Lint and CodeQL only (about 25 minutes); the full Build matrix does not run.

This step does not change the MCPB, PyPI, OCI or MCP Registry artefacts.

Expand All @@ -280,7 +280,8 @@ Manual, from the merged pin PR. The listing is a Skills-only upload of the plugi

One-time setup (tracked in stackql#893 and stackql.io#305):

- The submitting organization is allowlisted for local MCP submissions by the OpenAI representative (send the platform organization ID). Business verification completed; submitters other than owners hold **Apps Management Write**.
- The submitting organization is allowlisted for local MCP submissions by the OpenAI representative: send them the platform organization ID (platform.openai.com > Settings > Organization > General, the `org-` value; sent 2026-11-05). Business verification is completed by an owner on the same page (Verify organization); submitters other than owners hold **Apps Management Write** (Settings > Organization > Members).
- Upload the first ZIP as soon as the allowlist lands, before the recording exists, to read the validator: `mcp_configuration_excluded` on the MCPs tab means the organization is not allowlisted yet (wait, do not strip the MCP configuration); the demo recording warning is expected until it is set.
- `https://stackql.io/terms` and `https://stackql.io/support` are live alongside `/privacy` and `/docs`; the manifest points at all four.
- `review.demo_recording_url` in `packaging/openai-plugin/plugins/stackql/plugin.json` points at a reviewer-accessible recording of the eight test cases (`validate.py` warns while it is unset); the five positive and three negative cases are already in the manifest.
- If the portal asks for domain verification, host the exact token at `https://stackql.io/.well-known/openai-apps-challenge` as plain text.
Expand All @@ -305,7 +306,7 @@ cd packaging/mcpb
make claude-plugin-mirror VERSION=X.Y.Z # validates, then pushes packaging/claude-plugin to the mirror's main and tags vX.Y.Z
```

The push is idempotent and immutable: an existing `vX.Y.Z` tag with a different tree fails (cut the next release instead). The directory picks up the commit through the GitHub push webhook (or its scheduled check), validates and scans it, and the version goes live per the plugin's auto-publish setting; if a reviewer publishes each version, select **Publish** on the plugin's page at https://claude.ai/directory/manage. A version held for a reviewer is not a rejection; the expected hold (credentials read from the user's machine) is documented in the submission checklist.
The push is idempotent and immutable: an existing `vX.Y.Z` tag with a different tree fails (cut the next release instead). The directory picks up the commit through the GitHub push webhook (or its scheduled check), validates and scans it, and the version goes live per the plugin's auto-publish setting; if a reviewer publishes each version, select **Publish** on the plugin's page at https://claude.ai/directory/manage. A version held for a reviewer is not a rejection; the expected holds (the node launcher the validator cannot follow, and credentials read from the user's machine) and the warnings that are by design are documented in the submission checklist, together with the answers given on 2026-11-05 (listed on Claude Code and Cowork only, data handling, compliance contact). Auto-publish is on and the push webhook is configured on the mirror, so after the first version is published by us or the reviewer, each `make claude-plugin-mirror` push is scanned within minutes and goes live on its own (the directory also polls `main` about every 6 hours).

### 13. Assurance

Expand Down
4 changes: 2 additions & 2 deletions packaging/claude-plugin/.claude-plugin/plugin.json
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
"email": "info@stackql.io",
"url": "https://stackql.io"
},
"homepage": "https://stackql.io/docs",
"homepage": "https://stackql.io/getting-started",
"repository": "https://github.com/stackql/stackql",
"license": "MIT",
"keywords": [
Expand All @@ -21,7 +21,7 @@
"devops"
],
"icon": "./icon.png",
"documentationUrl": "https://stackql.io/docs",
"documentationUrl": "https://stackql.io/getting-started",
"supportUrl": "https://stackql.io/support",
"privacyPolicyUrl": "https://stackql.io/privacy",
"termsOfServiceUrl": "https://stackql.io/terms",
Expand Down
2 changes: 1 addition & 1 deletion packaging/claude-plugin/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ apply its own permission rules on top.

## Links

- Documentation: https://stackql.io/docs
- Documentation: https://stackql.io/getting-started
- Source: https://github.com/stackql/stackql
- Privacy policy: https://stackql.io/privacy
- Support: https://stackql.io/support
2 changes: 1 addition & 1 deletion packaging/claude-plugin/skills/stackql-setup/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ AWS_SECRET_ACCESS_KEY=...
To find the variable names another provider expects, call
`reload_credentials` after pulling the provider: the report lists every
installed provider with the variables it looks for. The provider pages at
https://stackql.io/docs document every option.
https://stackql.io/providers document every option.

After the user edits the file, call `reload_credentials` (optionally with the
provider name). It re-sources the file and reports, per provider, a status of
Expand Down
92 changes: 63 additions & 29 deletions packaging/mcpb/docs/anthropic-submission.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,7 @@ All enforced by `python packaging/mcpb/scripts/validate-claude-plugin.py` and
A hold is not a rejection; an Anthropic reviewer reads the version before it
goes live, and the same hold can recur on later versions:

- "Scripts the validator couldn't follow": the node launcher, see above.
- "Uses a credential from the user's machine": the server reads
`~/.stackql/.env` and sends provider credentials to the provider APIs. The
README states it; the reviewer confirms the behaviour matches.
Expand All @@ -74,40 +75,73 @@ goes live, and the same hold can recur on later versions:
from the StackQL registry, queries go to the providers the user queries,
nothing goes to StackQL Studios.

## What the validator reports, and what to leave alone

The 2026-11-05 validation of `stackql/stackql-claude-plugin` at `main` passed its
seven checks with five warnings and one policy hold. None of them is a defect:

- Policy hold, "Scripts the validator couldn't follow" on
`server/bin/stackql-mcp.js`: inherent to a node launcher. The validator follows
only plain shell scripts, and a file a shell wrapper runs in turn is not
followed either, so a wrapper would not remove it. The portal says leaving
the script and waiting for the review is fine. Expect it on every version.
- "Unrecognized field in plugin.json" for `documentationUrl`, `supportUrl`,
`privacyPolicyUrl` and `termsOfServiceUrl`, and "Field from another tool's
manifest" for `icon`: these are the directory listing fields. Claude Code
ignores them at load time and the directory reads them for the listing; the
portal marks each "No action needed". Removing them would drop the links
and the icon from the listing.
- "Local MCP server: not on claude.ai" and "Images and fonts passed without a
code check" (`icon.png`): informational.
- "Local MCP servers accepted only from Verified organizations": not refused
today, but the directory intends to accept servers that run on the user's
computer only from Verified organizations, and StackQL Studios is not one.
The docs describe no application ("Anthropic decides during review");
directory@anthropic.com was asked on 2026-11-05 how to become one.
- `classification` is filled in by the directory after submission. The portal
mentions a `classification` block in `plugin.json` but the manifest reference
does not document one, so it is left to the automatic fill.

## Outside the repository

One-time:

- [ ] The June 2026 Desktop Extension listing: look for it at
claude.ai/directory/manage and at platform.claude.com/plugins/submissions.
If it shows **Withdraw**, withdraw it. If it is there without that
button, or not there at all, email directory@anthropic.com asking what
happens to the MCPB listing and to attach the plugin submission to the
same organization. Until it is withdrawn or moved the portal can refuse
**Submit for review** with "Already submitted by another organization".
- [ ] Submit from the organization that should own the listing long term, on
a paid plan (Pro, Max, Ultra: your own account; Team or Enterprise: an
Owner, or a member granted the **Directory** permission), with the
GitHub account connected on claude.ai that has push access to
`stackql/stackql-claude-plugin`. The repository must be public before
the listing goes live.
- [ ] stackql.io `/terms` and `/support` live (stackql/stackql.io#305); the
manifest already points at them. `/privacy` and `/docs` are live.
- [ ] Create the mirror and push the first render:
`gh repo create stackql/stackql-claude-plugin --public --description "StackQL plugin for Claude (mirror of packaging/claude-plugin in stackql/stackql)"`
then `make claude-plugin-mirror VERSION=X.Y.Z` from `packaging/mcpb`.
- [ ] Portal: **Submit new** > **Plugin bundle**; repository
- [x] The June 2026 Desktop Extension listing was made through the submission
Google Form and appears in neither claude.ai/directory/manage nor
platform.claude.com/plugins/submissions, so there is nothing to withdraw.
Email directory@anthropic.com only if **Submit for review** is refused
with "Already submitted by another organization" (it was not).
- [x] Submitted 2026-11-05 from the StackQL Studios owner's claude.ai account
(paid plan, GitHub account with push access to the mirror connected).
Keep submitting from that account; the listing belongs to it.
- [x] stackql.io `/terms`, `/support`, `/privacy` live (2026-11-05). `/docs`
redirects to the homepage, so the manifest links point at `/getting-started`.
- [x] Mirror created 2026-11-05 (`gh repo create stackql/stackql-claude-plugin --public`)
and `make claude-plugin-mirror VERSION=1.0.888` pushed the root plugin to
`main` with tag `v1.0.888`.
- [x] Portal submission 2026-11-05: **Submit new** > **Plugin bundle**, repository
`stackql/stackql-claude-plugin`, plugin path empty, branch `main`;
**Validate**, fix anything marked Blocking, re-validate; check the
listing details (read from `plugin.json` and the README); data handling
answers (the plugin stores no personal data; data goes to the cloud
providers the user queries and to GitHub releases for the binary
download; no retention; not intended for people under 18); the four
compliance acknowledgements and a monitored contact email; choose
**GitHub push webhook** and set it up (needs repository admin); submit.
- [ ] After the first version passes, select **Publish**; a reviewer
publishes it. Then turn on **Publish new versions automatically** on the
plugin's Settings tab if offered.
**Validate** (see the section above). Listing details are read from
`plugin.json` and the README; **Listed on** was set to Claude Code and
Cowork only, because the local server does not run in the Claude apps and
the setup skill alone would mislead there. Data handling answers: personal
data **Reads only** (queries return whatever the user's own tenancy holds,
such as IAM or directory users; nothing is stored beyond the local session),
skills send data elsewhere **No** (the binary and provider downloads are the
server's and are declared in the README), retention **Not retained**
(StackQL Studios runs no service that receives data from Claude), under 18
**No**. Compliance: four acknowledgements, contact javen@stackql.io.
**Auto-publish passing versions** on. New versions: **GitHub push webhook**.
- [x] Webhook configured 2026-11-05 on the mirror (Settings > Webhooks: the
payload URL and secret the portal issued after submission, content type
`application/json`, SSL verification on, push event only; the ping
delivery returned 200). It is a repository webhook, not an Actions
secret. The directory also polls `main` about every 6 hours.
- [ ] Reviewer decision on the launcher hold: shows on the plugin's page at
claude.ai/directory/manage. The first version is published by us or the
reviewer; later versions go live automatically (auto-publish is on).
- [ ] Verified organization: reply from directory@anthropic.com (asked
2026-11-05) and whatever it requires, before local servers are gated on it.

Per release: docs/stackql_release_process.md step 12. In short, after the
pin PR for `X.Y.Z` merges, `make claude-plugin-mirror VERSION=X.Y.Z`; the
Expand Down
2 changes: 1 addition & 1 deletion packaging/mcpb/docs/install.md
Original file line number Diff line number Diff line change
Expand Up @@ -83,7 +83,7 @@ The server picks up provider credentials through stackql's normal `--auth` flag.
}
```

See https://stackql.io/docs for the full provider auth catalogue.
See https://stackql.io/providers for the full provider auth catalogue.

## 4. npx (any stdio MCP client, no install)

Expand Down
4 changes: 2 additions & 2 deletions packaging/mcpb/manifest/BUNDLE_README.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ mode:

Credentials are read locally (from environment variables or files you nominate)
and used only to sign requests to the relevant provider's API. They are never
transmitted anywhere else. See https://stackql.io/docs for the full provider
transmitted anywhere else. See https://stackql.io/getting-started for the full provider
auth catalogue.

## Data and configuration root
Expand Down Expand Up @@ -68,7 +68,7 @@ handled.

## Links

- Documentation: https://stackql.io/docs
- Documentation: https://stackql.io/getting-started
- Source: https://github.com/stackql/stackql
- Official MCP Registry: `io.github.stackql/stackql-mcp`
- License: MIT (see LICENSE in this bundle)
2 changes: 1 addition & 1 deletion packaging/mcpb/manifest/manifest.combined.template.json
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
"url": "https://stackql.io"
},
"homepage": "https://stackql.io",
"documentation": "https://stackql.io/docs",
"documentation": "https://stackql.io/getting-started",
"license": "MIT",
"privacy_policies": ["https://stackql.io/privacy"],
"icon": "icon.png",
Expand Down
2 changes: 1 addition & 1 deletion packaging/mcpb/manifest/manifest.template.json
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
"url": "https://stackql.io"
},
"homepage": "https://stackql.io",
"documentation": "https://stackql.io/docs",
"documentation": "https://stackql.io/getting-started",
"license": "MIT",
"privacy_policies": ["https://stackql.io/privacy"],
"icon": "icon.png",
Expand Down
2 changes: 1 addition & 1 deletion packaging/mcpb/manifest/manifest.test.json
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
"url": "https://stackql.io"
},
"homepage": "https://stackql.io",
"documentation": "https://stackql.io/docs",
"documentation": "https://stackql.io/getting-started",
"license": "MIT",
"server": {
"type": "binary",
Expand Down
2 changes: 1 addition & 1 deletion packaging/mcpb/manifest/manifest.test.windows.json
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
"url": "https://stackql.io"
},
"homepage": "https://stackql.io",
"documentation": "https://stackql.io/docs",
"documentation": "https://stackql.io/getting-started",
"license": "MIT",
"server": {
"type": "binary",
Expand Down
2 changes: 1 addition & 1 deletion packaging/mcpb/npm/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,6 @@ override (later flags win).

## Links

- Docs: https://stackql.io/docs
- Docs: https://stackql.io/getting-started
- MCP Registry: `io.github.stackql/stackql-mcp`
- Source: https://github.com/stackql/stackql
4 changes: 2 additions & 2 deletions packaging/mcpb/npm/package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion packaging/mcpb/pypi/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,6 @@ to override (later flags win).

## Links

- Docs: https://stackql.io/docs
- Docs: https://stackql.io/getting-started
- MCP Registry: `io.github.stackql/stackql-mcp`
- Source: https://github.com/stackql/stackql
2 changes: 1 addition & 1 deletion packaging/mcpb/pypi/pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ classifiers = [

[project.urls]
Homepage = "https://stackql.io"
Documentation = "https://stackql.io/docs"
Documentation = "https://stackql.io/getting-started"
Source = "https://github.com/stackql/stackql"

[project.scripts]
Expand Down
2 changes: 1 addition & 1 deletion packaging/mcpb/registry/server.template.json
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@
"io.modelcontextprotocol.registry/publisher-provided": {
"tool": "stackql-mcpb-packaging",
"homepage": "https://stackql.io",
"documentation": "https://stackql.io/docs"
"documentation": "https://stackql.io/getting-started"
}
}
}
Loading
Loading