From 730caa2daaf7ec70dd40651f7dcaea0439dc699d Mon Sep 17 00:00:00 2001 From: Jeffrey Aven Date: Mon, 15 Jun 2026 15:56:42 +1000 Subject: [PATCH 1/4] add-security-policy Add SECURITY.md at repo root exposing a private vulnerability reporting channel (GitHub private advisories, with info@stackql.io as fallback), supported-versions table, response expectations, and coordinated disclosure policy. Satisfies the Security Contact requirement for the Docker MCP Catalog submission of stackql-mcp. Co-Authored-By: Claude Opus 4.8 (1M context) --- SECURITY.md | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 SECURITY.md diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 00000000..a2d7da8d --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,40 @@ +# Security Policy + +The StackQL team takes the security of `stackql` seriously. We appreciate everyone who reports vulnerabilities responsibly, and we will do our best to acknowledge and address valid reports promptly. + +## Reporting a Vulnerability + +Please do not open a public GitHub issue for security reports. A public issue discloses the problem before a fix is available and puts users at risk. + +Instead, report privately using GitHub private vulnerability reporting: + +1. Open the [new advisory form](https://github.com/stackql/stackql/security/advisories/new) (Security tab -> Advisories -> "Report a vulnerability"). +2. Provide as much detail as you can: affected version(s), reproduction steps, impact, and any suggested remediation. +3. Submit. This opens a private advisory thread visible only to you and the maintainers. + +If you cannot use GitHub private vulnerability reporting, email us at [info@stackql.io](mailto:info@stackql.io). Please put "SECURITY" in the subject line and treat the contents as confidential. + +## Supported Versions + +Security fixes are applied to the latest released minor line. Older lines are supported on a best-effort basis only; we recommend upgrading to the latest release. See the [releases page](https://github.com/stackql/stackql/releases) for the current version. + +| Version | Supported | +| ------- | ------------ | +| 0.10.x | Yes | +| < 0.10 | Best-effort | + +## Response Expectations + +These are targets, not contractual guarantees: + +- We aim to acknowledge a report within a few business days. +- We will keep you updated as we investigate and work on a fix. +- We will coordinate disclosure timing with you once a fix or mitigation is ready. + +## Disclosure Policy + +We follow coordinated (responsible) disclosure. Please give us a reasonable opportunity to release a fix before any public disclosure. We are happy to credit reporters in the advisory and release notes, unless you prefer to remain anonymous. + +## Scope + +This policy covers the `stackql` engine in this repository and its official distributions and images (for example, the binaries on the releases page and the `stackql/stackql` Docker images). Provider definitions are maintained separately in the [stackql-provider-registry](https://github.com/stackql/stackql-provider-registry), and the request-execution library in [any-sdk](https://github.com/stackql/any-sdk); please report issues specific to those in their respective repositories. From d5d606e1a97e746cb9085a30aca573d2250b4309 Mon Sep 17 00:00:00 2001 From: Jeffrey Aven Date: Mon, 15 Jun 2026 16:25:55 +1000 Subject: [PATCH 2/4] registry prep --- README.md | 30 +++++++++++++++++------------- glama.json | 6 ++++++ 2 files changed, 23 insertions(+), 13 deletions(-) create mode 100644 glama.json diff --git a/README.md b/README.md index 88200627..decf1f5a 100644 --- a/README.md +++ b/README.md @@ -17,10 +17,12 @@ [setupaction]: https://github.com/marketplace/actions/stackql-studios-setup-stackql [execaction]: https://github.com/marketplace/actions/stackql-studios-stackql-exec -[badge1]: https://img.shields.io/badge/platform-windows%20macos%20linux-brightgreen "Platforms" -[badge2]: https://github.com/stackql/stackql/workflows/Go/badge.svg "Go" -[badge3]: https://img.shields.io/github/license/stackql/stackql "License" -[badge4]: https://img.shields.io/tokei/lines/github/stackql/stackql "Lines" +[platforms]: https://img.shields.io/badge/platform-windows%20macos%20linux-brightgreen?style=flat-square "Platforms" +[license]: https://img.shields.io/badge/license-MIT-blue?style=flat-square "License" +[build]: https://github.com/stackql/stackql/actions/workflows/build.yml/badge.svg "Build" +[stars]: https://img.shields.io/github/stars/stackql/stackql?style=flat-square "GitHub Stars" +[forks]: https://img.shields.io/github/forks/stackql/stackql?style=flat-square "GitHub Forks" +[contributors]: https://img.shields.io/github/contributors/stackql/stackql?style=flat-square "Contributors" [issues]: https://github.com/stackql/stackql/issues/new?assignees=&labels=bug&template=bug_report.md&title=%5BBUG%5D [features]: https://github.com/stackql/stackql/issues/new?assignees=&labels=enhancement&template=feature_request.md&title=%5BFEATURE%5D @@ -39,24 +41,26 @@
[![logo]][homepage] -![badge1] -![badge2] -![badge3] -![badge4] +![platforms] +![license] +![build] +![stars] +![forks] +![contributors]
-![homebrew downloads](https://img.shields.io/homebrew/installs/dy/stackql?label=homebrew%20downloads) -![homebrew version](https://img.shields.io/homebrew/v/stackql?label=homebrew%20version) -![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/stackql/stackql/total?label=github%20release%20downloads) + ![GitHub Release](https://img.shields.io/github/v/release/stackql/stackql?label=github%20release) -![Docker Pulls](https://img.shields.io/docker/pulls/stackql/stackql) +![GitHub Downloads](https://img.shields.io/github/downloads/stackql/stackql/total?label=github%20downloads) ![Docker Image Version](https://img.shields.io/docker/v/stackql/stackql?label=docker%20version) +![Docker Pulls](https://img.shields.io/docker/pulls/stackql/stackql) ![Chocolatey Downloads](https://img.shields.io/chocolatey/dt/stackql?label=chocolatey%20downloads) ![Chocolatey Version](https://img.shields.io/chocolatey/v/stackql) -![PyPI - Downloads](https://img.shields.io/pypi/dm/stackql-deploy?label=pypi%20downloads) +![homebrew version](https://img.shields.io/homebrew/v/stackql?label=homebrew%20version) +
diff --git a/glama.json b/glama.json new file mode 100644 index 00000000..43565a22 --- /dev/null +++ b/glama.json @@ -0,0 +1,6 @@ +{ + "$schema": "https://glama.ai/mcp/schemas/server.json", + "maintainers": [ + "stackql" + ] +} \ No newline at end of file From a88ada30a527706145149ddd8afad2bd9dce0768 Mon Sep 17 00:00:00 2001 From: Jeffrey Aven Date: Mon, 15 Jun 2026 18:19:51 +1000 Subject: [PATCH 3/4] build ignore-paths --- .github/workflows/build.yml | 32 ++++++++++++++++++++------------ 1 file changed, 20 insertions(+), 12 deletions(-) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 8054a9bc..a29e41b5 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -9,24 +9,32 @@ on: tags: - build* paths-ignore: - - "**/*.md" - - "docs/**" - - "licenses/**" - - "test/python/markdown_testing/**" - - ".github/workflows/scenario.yaml" + - '**/*.md' + - 'docs/**' + - '.github/ISSUE_TEMPLATE/**' + - '.github/PULL_REQUEST_TEMPLATE.md' + - 'LICENSE' + - 'CODE_OF_CONDUCT.md' + - 'CONTRIBUTING.md' + - 'SECURITY.md' + - 'AGENTS.md' + - 'CLAUDE.md' pull_request: branches: - main - develop - version* paths-ignore: - - "**/*.md" - - "docs/**" - - "examples/**" - - "licenses/**" - - "test/python/markdown_testing/**" - - ".github/workflows/scenario.yaml" - + - '**/*.md' + - 'docs/**' + - '.github/ISSUE_TEMPLATE/**' + - '.github/PULL_REQUEST_TEMPLATE.md' + - 'LICENSE' + - 'CODE_OF_CONDUCT.md' + - 'CONTRIBUTING.md' + - 'SECURITY.md' + - 'AGENTS.md' + - 'CLAUDE.md' env: GOTESTCMD: "go test -timeout 1200s --tags \"sqlite_stackql\" -v ./..." TESTSCRIPT: "test/deprecated/python/main.py" From 39bef88a2c870b13390ff9fd4c3d1e7b1e383c53 Mon Sep 17 00:00:00 2001 From: Jeffrey Aven Date: Tue, 16 Jun 2026 07:19:04 +1000 Subject: [PATCH 4/4] mcp registry discovery --- .github/workflows/build.yml | 2 + README.md | 92 +++++++++++++++++++++++++++++++++++++ server.json | 68 +++++++++++++++++++++++++++ 3 files changed, 162 insertions(+) create mode 100644 server.json diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index a29e41b5..a24fa625 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -19,6 +19,7 @@ on: - 'SECURITY.md' - 'AGENTS.md' - 'CLAUDE.md' + - 'server.json' pull_request: branches: - main @@ -35,6 +36,7 @@ on: - 'SECURITY.md' - 'AGENTS.md' - 'CLAUDE.md' + - 'server.json' env: GOTESTCMD: "go test -timeout 1200s --tags \"sqlite_stackql\" -v ./..." TESTSCRIPT: "test/deprecated/python/main.py" diff --git a/README.md b/README.md index decf1f5a..31e9ee2c 100644 --- a/README.md +++ b/README.md @@ -23,6 +23,7 @@ [stars]: https://img.shields.io/github/stars/stackql/stackql?style=flat-square "GitHub Stars" [forks]: https://img.shields.io/github/forks/stackql/stackql?style=flat-square "GitHub Forks" [contributors]: https://img.shields.io/github/contributors/stackql/stackql?style=flat-square "Contributors" +[mcpregistrybadge]: https://img.shields.io/badge/MCP%20Registry-io.github.stackql%2Fstackql--mcp-blue?style=flat-square "MCP Registry" [issues]: https://github.com/stackql/stackql/issues/new?assignees=&labels=bug&template=bug_report.md&title=%5BBUG%5D [features]: https://github.com/stackql/stackql/issues/new?assignees=&labels=enhancement&template=feature_request.md&title=%5BFEATURE%5D @@ -36,6 +37,8 @@ [lightmodeterm]: /docs/images/stackql-dark-term.gif#gh-light-mode-only [twitter]: https://twitter.com/stackql +[mcpregistry]: https://registry.modelcontextprotocol.io/?search=stackql +[mcpdocs]: https://stackql.io/docs
@@ -44,6 +47,7 @@ ![platforms] ![license] ![build] +[![MCP Registry][mcpregistrybadge]][mcpregistry] ![stars] ![forks] ![contributors] @@ -83,6 +87,7 @@ Contents
  1. About The Project
    2. +
  2. MCP Server
  3. Installation
  4. Usage
    5. @@ -139,6 +144,93 @@ More detailed design documentation can be found in the [here][designdocs]. +## MCP Server + +StackQL is an [MCP](https://modelcontextprotocol.io) server - SQL over 40+ cloud and SaaS providers for AI agents. Point any MCP-capable client (Claude, VS Code, Cursor, etc.) at StackQL and it can query and provision cloud resources using SQL. + +Run it over stdio: + +```sh +stackql mcp --mcp.server.type=stdio +``` + +StackQL MCP is published to the [Official MCP Registry][mcpregistry] as `io.github.stackql/stackql-mcp` and distributed via npm, PyPI, Docker, a GitHub Action and `.mcpb` bundles. Pick an install vector and add the matching block to your MCP client config: + +
    +npm (npx) + +```json +{ + "mcpServers": { + "stackql": { + "command": "npx", + "args": ["-y", "@stackql/mcp-server"] + } + } +} +``` + +
    + +
    +PyPI (uvx) + +```json +{ + "mcpServers": { + "stackql": { + "command": "uvx", + "args": ["stackql-mcp-server"] + } + } +} +``` + +
    + +
    +Docker + +```json +{ + "mcpServers": { + "stackql": { + "command": "docker", + "args": ["run", "-i", "--rm", "stackql/stackql-mcp"] + } + } +} +``` + +
    + +
    +.mcpb bundle + +> Download the bundle for your platform from the [latest release](https://github.com/stackql/stackql/releases/latest) and install it in your MCP client (one-click in clients that support `.mcpb`). + +- `stackql-mcp-linux-x64.mcpb` +- `stackql-mcp-linux-arm64.mcpb` +- `stackql-mcp-windows-x64.mcpb` +- `stackql-mcp-darwin-universal.mcpb` + +
    + +
    +GitHub Actions + +> Wire StackQL MCP into agentic CI workflows. Defaults to `read_only` mode, the safe default for CI. + +```yaml +- uses: stackql/setup-stackql-mcp@v1 + with: + mode: read_only +``` + +
    + +For client-specific setup, authentication and server modes, see the [full MCP install and usage docs][mcpdocs]. + ## Installation StackQL is available for Windows, MacOS, Linux, Docker, GitHub Actions and more. See the installation instructions below for your platform. diff --git a/server.json b/server.json new file mode 100644 index 00000000..487e65c6 --- /dev/null +++ b/server.json @@ -0,0 +1,68 @@ +{ + "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", + "name": "io.github.stackql/stackql-mcp", + "title": "StackQL MCP Server", + "description": "SQL-native query and provisioning engine for cloud infrastructure, served over MCP.", + "websiteUrl": "https://stackql.io", + "repository": { + "url": "https://github.com/stackql/stackql", + "source": "github" + }, + "version": "0.10.500.2", + "packages": [ + { + "registryType": "mcpb", + "identifier": "https://github.com/stackql/stackql/releases/download/v0.10.500/stackql-mcp-linux-x64.mcpb", + "version": "0.10.500", + "fileSha256": "6615737747156b1a8413a976afb23af2e7eec29ebc98a6f0a0f65d1b153c44be", + "transport": { "type": "stdio" } + }, + { + "registryType": "mcpb", + "identifier": "https://github.com/stackql/stackql/releases/download/v0.10.500/stackql-mcp-linux-arm64.mcpb", + "version": "0.10.500", + "fileSha256": "594bedbabc3096dc3563c907724e845ce0b61a67de4b3fed4158b40c0363786c", + "transport": { "type": "stdio" } + }, + { + "registryType": "mcpb", + "identifier": "https://github.com/stackql/stackql/releases/download/v0.10.500/stackql-mcp-windows-x64.mcpb", + "version": "0.10.500", + "fileSha256": "d2ce895e88f9c6b557df07073158629808f56d75598f3a701164d65506b791b0", + "transport": { "type": "stdio" } + }, + { + "registryType": "mcpb", + "identifier": "https://github.com/stackql/stackql/releases/download/v0.10.500/stackql-mcp-darwin-universal.mcpb", + "version": "0.10.500", + "fileSha256": "4eed70af5cfa67295ae0b42fa3a6dca71ac9acabd0d67914fd96ad1247a9b4cc", + "transport": { "type": "stdio" } + }, + { + "registryType": "oci", + "identifier": "docker.io/stackql/stackql-mcp:0.10.500", + "transport": { "type": "stdio" } + }, + { + "registryType": "npm", + "registryBaseUrl": "https://registry.npmjs.org", + "identifier": "@stackql/mcp-server", + "version": "0.10.500", + "transport": { "type": "stdio" } + }, + { + "registryType": "pypi", + "registryBaseUrl": "https://pypi.org", + "identifier": "stackql-mcp-server", + "version": "0.10.500", + "transport": { "type": "stdio" } + } + ], + "_meta": { + "io.modelcontextprotocol.registry/publisher-provided": { + "tool": "stackql-mcpb-packaging", + "homepage": "https://stackql.io", + "documentation": "https://stackql.io/docs" + } + } +}