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
2 changes: 1 addition & 1 deletion .github/goreleaser/.goreleaser-for-darwin.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ builds:
ldflags: >-
-s -w
-X github.com/stackql/stackql/internal/stackql/cmd.BuildMajorVersion={{.Major}}
-X github.com/stackql/stackql/internal/stackql/cmd.BuildMinorVersion={{.Minor}}}
-X github.com/stackql/stackql/internal/stackql/cmd.BuildMinorVersion={{.Minor}}
-X github.com/stackql/stackql/internal/stackql/cmd.BuildPatchVersion={{.Patch}}
-X github.com/stackql/stackql/internal/stackql/cmd.BuildCommitSHA={{.FullCommit}}
-X github.com/stackql/stackql/internal/stackql/cmd.BuildShortCommitSHA={{.ShortCommit}}
Expand Down
2 changes: 1 addition & 1 deletion .github/goreleaser/.goreleaser-for-linux.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ builds:
ldflags: >-
-s -w
-X github.com/stackql/stackql/internal/stackql/cmd.BuildMajorVersion={{.Major}}
-X github.com/stackql/stackql/internal/stackql/cmd.BuildMinorVersion={{.Minor}}}
-X github.com/stackql/stackql/internal/stackql/cmd.BuildMinorVersion={{.Minor}}
-X github.com/stackql/stackql/internal/stackql/cmd.BuildPatchVersion={{.Patch}}
-X github.com/stackql/stackql/internal/stackql/cmd.BuildCommitSHA={{.FullCommit}}
-X github.com/stackql/stackql/internal/stackql/cmd.BuildShortCommitSHA={{.ShortCommit}}
Expand Down
2 changes: 1 addition & 1 deletion .github/goreleaser/.goreleaser-for-windows.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ builds:
ldflags: >-
-s -w
-X github.com/stackql/stackql/internal/stackql/cmd.BuildMajorVersion={{.Major}}
-X github.com/stackql/stackql/internal/stackql/cmd.BuildMinorVersion={{.Minor}}}
-X github.com/stackql/stackql/internal/stackql/cmd.BuildMinorVersion={{.Minor}}
-X github.com/stackql/stackql/internal/stackql/cmd.BuildPatchVersion={{.Patch}}
-X github.com/stackql/stackql/internal/stackql/cmd.BuildCommitSHA={{.FullCommit}}
-X github.com/stackql/stackql/internal/stackql/cmd.BuildShortCommitSHA={{.ShortCommit}}
Expand Down
16 changes: 9 additions & 7 deletions .github/workflows/build.yml
Original file line number Diff line number Diff line change
Expand Up @@ -229,6 +229,8 @@ jobs:

$env:BUILDMAJORVERSION = $BuildMajorVersion
$env:BUILDMINORVERSION = $BuildMinorVersion
# ISO-8601 UTC, matching the Linux/macOS jobs (issue #704).
$env:BUILDDATE = (Get-Date).ToUniversalTime().ToString("yyyy-MM-ddTHH:mm:ssZ")

echo "BUILDMAJORVERSION=$env:BUILDMAJORVERSION" >> $GITHUB_ENV
echo "BUILDMINORVERSION=$env:BUILDMINORVERSION" >> $GITHUB_ENV
Expand Down Expand Up @@ -484,7 +486,7 @@ jobs:
fi
BUILDSHORTCOMMITSHA="$(echo "${BUILDCOMMITSHA}" | cut -c 1-7)"
export BUILDSHORTCOMMITSHA
BUILDDATE="$(date)"
BUILDDATE="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
export BUILDDATE
echo "BUILDMAJORVERSION: ${BUILDMAJORVERSION}"
echo "BUILDMINORVERSION: ${BUILDMINORVERSION}"
Expand Down Expand Up @@ -721,7 +723,7 @@ jobs:
fi
BUILDSHORTCOMMITSHA="$(echo "${BUILDCOMMITSHA}" | cut -c 1-7)"
export BUILDSHORTCOMMITSHA
BUILDDATE="$(date)"
BUILDDATE="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
export BUILDDATE
echo "BUILDMAJORVERSION: ${BUILDMAJORVERSION}"
echo "BUILDMINORVERSION: ${BUILDMINORVERSION}"
Expand Down Expand Up @@ -1101,7 +1103,7 @@ jobs:
fi
BUILDSHORTCOMMITSHA="$(echo "${BUILDCOMMITSHA}" | cut -c 1-7)"
export BUILDSHORTCOMMITSHA
BUILDDATE="$(date)"
BUILDDATE="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
export BUILDDATE
echo "BUILDMAJORVERSION: ${BUILDMAJORVERSION}"
echo "BUILDMINORVERSION: ${BUILDMINORVERSION}"
Expand Down Expand Up @@ -1533,7 +1535,7 @@ jobs:
fi
BUILDSHORTCOMMITSHA="$(echo "$BUILDCOMMITSHA" | cut -c 1-7)"
export BUILDSHORTCOMMITSHA
BUILDDATE="$(date)"
BUILDDATE="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
export BUILDDATE
echo "BUILDMAJORVERSION: ${BUILDMAJORVERSION}"
echo "BUILDMINORVERSION: ${BUILDMINORVERSION}"
Expand Down Expand Up @@ -1671,7 +1673,7 @@ jobs:
fi
BUILDSHORTCOMMITSHA="$(echo "$BUILDCOMMITSHA" | cut -c 1-7)"
export BUILDSHORTCOMMITSHA
BUILDDATE="$(date)"
BUILDDATE="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
export BUILDDATE
echo "BUILDMAJORVERSION: ${BUILDMAJORVERSION}"
echo "BUILDMINORVERSION: ${BUILDMINORVERSION}"
Expand Down Expand Up @@ -1803,7 +1805,7 @@ jobs:
BUILDPATCHVERSION="${BUILDPATCHVERSION}"
fi
BUILDSHORTCOMMITSHA="$(echo "${BUILDCOMMITSHA}" | cut -c 1-7)"
BUILDDATE="$(date)"
BUILDDATE="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
export BUILDDATE
echo "BUILDMAJORVERSION: ${BUILDMAJORVERSION}"
echo "BUILDMINORVERSION: ${BUILDMINORVERSION}"
Expand Down Expand Up @@ -2199,7 +2201,7 @@ jobs:
SHORTHAND_DOCKER_TAG="${{ github.ref_name }}"
fi
BUILDSHORTCOMMITSHA="$(echo "${BUILDCOMMITSHA}" | cut -c 1-7)"
BUILDDATE="$(date)"
BUILDDATE="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
export BUILDDATE
echo "BUILDMAJORVERSION: ${BUILDMAJORVERSION}"
echo "BUILDMINORVERSION: ${BUILDMINORVERSION}"
Expand Down
74 changes: 72 additions & 2 deletions docs/mcp.md
Original file line number Diff line number Diff line change
Expand Up @@ -188,13 +188,34 @@ Instructions, prompts and resources are authored as markdown under `pkg/mcp_serv

**Refuse** returns an error immediately.

**Needs approval** uses the MCP elicitation flow:
**Needs approval** uses the MCP elicitation flow, shaped by the negotiated protocol revision (see [Protocol revision support](#protocol-revision-support)):

- If the client advertised elicitation at initialise, the server sends an `elicitation/create` request describing the action (tool name, query class, SQL). Branch on the user response: `accept` -> proceed; `decline` or `cancel` -> return an error.
- If the client advertised elicitation (at initialise, or in the per-request `_meta` client capabilities on 2026-07-28), the server asks the user to approve the action (tool name, query class, SQL). On 2026-07-28 the prompt is returned as an `input_required` result carrying an `elicitation/create` input request under the id `stackql_approval`, and the client retries the call with the answer in `inputResponses`; on earlier revisions the server sends the `elicitation/create` request itself mid-call. Branch on the user response: `accept` -> proceed; `decline` or `cancel` -> return an error.
- If the client did **not** advertise elicitation, the tool is refused with a message that points the operator at `full_access` mode.

The bundled `stackql_mcp_client` does NOT advertise elicitation, so against a `safe` or `delete_safe` server every mutation/lifecycle call is refused with the no-elicitation message. This is by design - the bundled client exists for scripting and regression tests, not interactive use. Elicitation-capable MCP clients (eg Claude Desktop, Cursor) prompt the user normally.

## Protocol revision support

The server speaks every revision the [Go MCP SDK](https://github.com/modelcontextprotocol/go-sdk) supports and negotiates per client, so a fleet of mixed clients works against one server:

| Revision | Lifecycle | Approval prompt (`safe` / `delete_safe`) |
|---|---|---|
| `2026-07-28` (advertised) | No handshake: `server/discover`, then every request carries `io.modelcontextprotocol/protocolVersion` and `io.modelcontextprotocol/clientCapabilities` in `_meta` (plus the `Mcp-Protocol-Version` header on HTTP) | `input_required` result + retry with `inputResponses` (SEP-2322) |
| `2025-11-25`, `2025-06-18` | `initialize` / `notifications/initialized` | Server-initiated `elicitation/create` request |
| `2025-03-26`, `2024-11-05` | as above | as above |

Transport behaviour:

- **stdio** serves every revision on one process; a new-revision client's first request is served without a handshake and a legacy client's `initialize` still works.
- **Streamable HTTP** defaults to the stateful, session-per-client model (`Mcp-Session-Id`), which the SDK serves for revisions up to `2025-11-25`; a `2026-07-28` client learns that from `server/discover` and negotiates down, so existing HTTP hosts keep their sessions and elicitation unchanged. Set `"stateless": true` in `server` to serve `2026-07-28` natively: no `Mcp-Session-Id` is issued or read, `tools/list` / `prompts/list` / `resources/list` are connection-invariant, and gated writes use the input-required round trip. A sessionless server still accepts a legacy `initialize` and serves reads to that client, but cannot retain the elicitation capability a legacy client declared at initialise (the SDK gives each request an ephemeral session), so legacy HTTP clients cannot approve gated writes on it. Pick stateless for current-revision hosts, stateful for a mixed legacy fleet.

```bash
./build/stackql mcp --mcp.server.type=http --mcp.config '{"server": {"transport": "http", "address": "127.0.0.1:9992", "stateless": true} }'
```

The server holds no cross-call state: mode, audit and provider auth are process-level configuration, so nothing needed to move behind explicit handles (SEP-2567). The robot suite drives stdio and both HTTP models with a 2025-06-18 handshake client and a 2026-07-28 stateless client, including the gated write on each revision.

### Breaking change vs PR1

PR1 had a single `read_only: true/false` flag with a default of "no enforcement; mutations proceed." PR2 replaces that flag with `mode: safe` as the default, which means **mutations now require user approval out of the box.** Operators running an elicitation-capable client see one approval prompt per mutation. Operators running automation or the bundled client must explicitly opt into `full_access`.
Expand Down Expand Up @@ -253,6 +274,55 @@ When the sink returns an error, the response behaviour depends on `failure_mode`

The audit write happens AFTER the tool executes (or is skipped because it was gated out) but BEFORE the response returns to the client. In strict mode an audit-write failure on a successful DELETE means the row is gone but the client sees an error - by design.

### Log format (`--mcp.log.format`)

The audit stream has two encodings, written to the same file sink:

```bash
./build/stackql mcp --mcp.server.type=stdio --mcp.log.format=jsonl # default, unchanged
./build/stackql mcp --mcp.server.type=stdio --mcp.log.format=otel # OTLP/JSON log records
```

The flag overrides `server.audit.format` in `mcp.config` (`"audit": {"format": "otel"}`). `jsonl` is byte-compatible with the records described above. `otel` wraps the same sink with the generic OTLP/JSON decorator from [`pkg/sink`](/pkg/sink) (usable by any subsystem that writes records; the MCP-specific part is only the attribute mapping in `pkg/mcp_server/audit`) and writes one OTLP/JSON `LogsData` object per line, the shape the OpenTelemetry Collector's `otlp_json_file` receiver ingests as-is (verified against otelcol-contrib 0.160.0), so the stream reaches any OTLP pipeline with no transform processor:

```yaml
receivers:
otlp_json_file:
include: [/var/log/stackql-mcp.log]
exporters:
debug: {}
service:
pipelines:
logs:
receivers: [otlp_json_file]
exporters: [debug]
```

Each tool call produces one log record; a call that went through the approval gate produces a second record for the elicitation decision. Records of one call share `gen_ai.tool.call.id` and a trace id; a W3C `traceparent` supplied by the caller in `params._meta` is honoured, otherwise one trace id is generated per MCP session so an agent session's records correlate.

The emitted attribute set is a versioned interface: the instrumentation scope is `github.com/stackql/stackql/pkg/mcp_server/audit` at version `1.0.0`, and `schemaUrl` pins the stable conventions to `https://opentelemetry.io/schemas/1.44.0`. The `gen_ai.*` and `mcp.*` attributes follow the [GenAI](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/docs/gen-ai/gen-ai-spans.md#execute-tool-span) and [MCP](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/docs/gen-ai/mcp.md) semantic conventions, which are Development status; a unit test asserts the exact set below and the scope version is bumped when it changes.

| Attribute | Record | Value |
|---|---|---|
| `service.name`, `service.version` | resource | `stackql`, the stackql version |
| `gen_ai.operation.name` | tool call | `execute_tool` |
| `mcp.method.name` | both | `tools/call` on the tool call record, `elicitation/create` on the decision record |
| `gen_ai.tool.name` | both | tool name |
| `gen_ai.tool.call.id` | both | generated per call, shared by both records |
| `mcp.protocol.version` | both | negotiated revision |
| `mcp.session.id` | both | session id (absent for stateless HTTP requests) |
| `stackql.mode` | both | server mode |
| `stackql.decision` | both | the `decision` value from the JSONL table |
| `stackql.query` | tool call | verbatim SQL, for query tools |
| `stackql.query_class` | tool call | the `query_class` value |
| `stackql.provider` | tool call | provider, for metadata tools |
| `stackql.query.source` | tool call | query library entry id, when supplied |
| `stackql.duration_ms` | tool call | wall-clock duration |
| `stackql.rows_returned` | tool call | row count, for row-returning tools |
| `error.type`, `error.message` | tool call | on failure: the refusing decision, or `tool_error` past the gate |

Body is `execute_tool <tool>` / `elicitation <tool>`; severity is `INFO`, or `ERROR` when the call failed or was refused. The redaction contract is identical in both formats: result values are never serialised, only the statement that produced them.

### Breaking change vs PR1

PR1 had no audit subsystem; PR2 enables audit by default. To preserve PR1 behaviour, pass `"audit": {"disabled": true}` in `mcp.config`.
Expand Down
9 changes: 6 additions & 3 deletions go.mod
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ require (
github.com/jackc/pgx/v5 v5.0.4
github.com/lib/pq v1.10.4
github.com/magiconair/properties v1.8.6
github.com/modelcontextprotocol/go-sdk v1.0.0
github.com/modelcontextprotocol/go-sdk v1.7.0
github.com/olekukonko/tablewriter v0.0.0-20180130162743-b8a9be070da4
github.com/sirupsen/logrus v1.9.3
github.com/snowflakedb/gosnowflake v1.15.0
Expand Down Expand Up @@ -86,13 +86,13 @@ require (
github.com/goccy/go-json v0.10.4 // indirect
github.com/godbus/dbus v0.0.0-20190726142602-4481cbc300e2 // indirect
github.com/gofrs/flock v0.10.0 // indirect
github.com/golang-jwt/jwt/v5 v5.2.2 // indirect
github.com/golang-jwt/jwt/v5 v5.3.1 // indirect
github.com/golang/glog v1.2.5 // indirect
github.com/golang/groupcache v0.0.0-20210331224755-41bb18bfe9da // indirect
github.com/golang/protobuf v1.5.4 // indirect
github.com/google/flatbuffers v24.12.23+incompatible // indirect
github.com/google/go-cmp v0.7.0 // indirect
github.com/google/jsonschema-go v0.3.0 // indirect
github.com/google/jsonschema-go v0.4.3 // indirect
github.com/google/uuid v1.6.0 // indirect
github.com/gorilla/mux v1.8.0 // indirect
github.com/gsterjov/go-libsecret v0.0.0-20161001094733-a6f4afe4910c // indirect
Expand Down Expand Up @@ -123,6 +123,8 @@ require (
github.com/pmezard/go-difflib v1.0.0 // indirect
github.com/rivo/uniseg v0.2.0 // indirect
github.com/santhosh-tekuri/jsonschema/v5 v5.3.1 // indirect
github.com/segmentio/asm v1.1.3 // indirect
github.com/segmentio/encoding v0.5.4 // indirect
github.com/sony/gobreaker/v2 v2.4.0 // indirect
github.com/spf13/afero v1.15.0 // indirect
github.com/spf13/cast v1.4.1 // indirect
Expand All @@ -148,6 +150,7 @@ require (
golang.org/x/telemetry v0.0.0-20260409153401-be6f6cb8b1fa // indirect
golang.org/x/term v0.43.0 // indirect
golang.org/x/text v0.37.0 // indirect
golang.org/x/time v0.15.0 // indirect
golang.org/x/tools v0.44.0 // indirect
golang.org/x/xerrors v0.0.0-20240903120638-7835f813f4da // indirect
google.golang.org/genproto/googleapis/rpc v0.0.0-20260526163538-3dc84a4a5aaa // indirect
Expand Down
Loading
Loading