René's URL Explorer Experiment

Title: mcp: server modes, elicitation gating, audit subsystem (PR2) by jeffreyaven · Pull Request #652 · stackql/stackql · GitHub

Open Graph Title: mcp: server modes, elicitation gating, audit subsystem (PR2) by jeffreyaven · Pull Request #652 · stackql/stackql

X Title: mcp: server modes, elicitation gating, audit subsystem (PR2) by jeffreyaven · Pull Request #652 · stackql/stackql

Description: Summary PR2 of the two-PR MCP server series. PR1 trimmed the tool surface to 11 + 1 prompt and shipped a single read_only: true/false flag. PR2 replaces that flag with a four-mode safety contract, wires MCP elicitation for approval-required modes, and adds an audit subsystem. Four server modes replacing IsReadOnly: read_only, safe (new default), delete_safe, full_access. Verb-classified gate (SELECT / INSERT|UPDATE|REPLACE|MERGE|UPSERT / DELETE / EXEC) decides allow / refuse / needs-approval per mode. Elicitation flow for needs-approval modes: server sends elicitation/create if the client advertised the capability; otherwise refuses with a message pointing at full_access. Audit subsystem writing JSONL via a Sink interface; file sink ships with lumberjack rotation. Audit is on by default. Three failure_mode options: strict (default), strict_mutations, best_effort. Gate middleware is the single chokepoint: classify → decide → (refuse / elicit / allow) → handler → audit. Replaces PR1's per-handler isReadOnlyConfig checks. server_info exposes mode (new) and is_read_only (back-compat: true iff mode == "read_only"). Legacy back-compat: read_only: true JSON/YAML key still parses and maps to mode: read_only. When both are set, mode wins. Breaking changes Default behaviour shift. PR1 default = "no enforcement; mutations proceed." PR2 default = mode: safe = "mutations require user approval." Operators running the bundled client (which does not advertise elicitation) or any non-elicitation automation must explicitly opt into mode: full_access. Audit on by default. PR1 logged nothing. PR2 writes JSONL to ./stackql_mcp_server_.log by default. To preserve PR1 behaviour set "audit": {"disabled": true} in mcp.config. Config.Server.IsReadOnly *bool removed in favour of Config.Server.Mode string. Legacy wire form preserved. Backend constructors (NewStackqlMCPBackendService, NewStackqlMCPReverseProxyService) no longer take isReadOnly bool - the value is derived from the mode string carried by serverBuildInfo. Architectural invariant pkg/mcp_server/... still imports zero symbols from internal/... or any-sdk. Verified by grep. The new policy and audit packages are pure: primitive types only, no SDK or internal dependencies. The serverBuildInfo data carrier in internal/stackql/mcpbackend remains an unexported interface backed by an unexported struct with constructor-only mutation, per the AGENTS.md data-carrier rule. What landed New packages pkg/mcp_server/policy/ - QueryClass, ClassifyQuery, Decision, GateDecision, mode string constants. Pure functions. pkg/mcp_server/audit/ - Event (flat, primitive-typed DTO), Sink interface, NopSink, NewFileSink (lumberjack-backed, fsync per record, 0600 file perms). New / changed files pkg/mcp_server/gate.go - new middleware that wraps every tool registration with classify / decide / elicit / audit. pkg/mcp_server/server.go - all 11 tools wrapped via addToolWithGate; init audit sink at server start; close it at shutdown. pkg/mcp_server/config.go - Mode + AuditConfig fields; legacy read_only shim via custom UnmarshalJSON/UnmarshalYAML; Validate() rejects unknown modes + failure_modes. pkg/mcp_server/dto/dto.go - Mode added to ServerInfoOutput and ServerInfoDTO; ReadOnly retained for back-compat. internal/stackql/mcpbackend/mcp_service_stackql.go, .../mcp_reverse_proxy_backend_service.go - constructors take a mode string via serverBuildInfo; ServerInfo() returns Mode and derives ReadOnly. internal/stackql/cmd/mcp.go - reads mode from config (cfg.GetMode()), threads through NewServerBuildInfo. docs/mcp.md - new Server modes section, new Audit log section, updated examples and breaking-change notes. pkg/mcp_server/README.md - mirrors the docs/mcp.md update with package-developer framing. test/robot/functional/mcp.robot - four new MCP servers (9920 read_only, 9921 delete_safe, 9922 full_access, 9923 audit-enabled); five new mode-contract scenarios; two audit scenarios; existing servers pinned to mode: full_access + audit.disabled: true so PR1 scenarios keep passing. Go module Added gopkg.in/natefinch/lumberjack.v2 for log rotation. Test plan go build ./... clean. go vet ./... clean. golangci-lint run ./pkg/mcp_server/... ./internal/stackql/mcpbackend/... ./internal/stackql/cmd/... → 0 issues. go test --tags sqlite_stackql -count=1 ./... → all packages pass. New unit tests pkg/mcp_server/policy/policy_test.go - 6 tests covering classification of every verb and gate decision for every (mode, class) combination including empty / unknown. pkg/mcp_server/audit/file_test.go - JSONL round-trip, default-path generation in cwd, fail-fast on unwritable dir, nop sink. pkg/mcp_server/tools_test.go extensions: TestMode_ReadOnly_RefusesAllMutationsAndLifecycle TestMode_Safe_RefusesMutationsWithoutElicitation TestMode_DeleteSafe_AllowsCreateRefusesDeleteAndLifecycle TestMode_FullAccess_AllowsEverything TestMode_Safe_ElicitationAcceptProceeds (uses ClientOptions.ElicitationHandler) TestMode_Safe_ElicitationDeclineRefuses TestMode_Safe_ElicitationCancelRefuses TestMode_DeleteSafe_ElicitationAcceptAllowsDelete TestServerInfo_SurfacesMode TestAudit_RecordsAllToolCalls (end-to-end: in-process server → temp audit file → JSONL parse) pkg/mcp_server/config_legacy_test.go - 8 tests covering legacy shim mapping, mode-wins-over-legacy, read_only: false doesn't force a mode, unknown-mode rejected, audit.disabled parsing, failure_mode validation, empty-mode defaults to safe. Robot scenarios added MCP HTTP Mode Read Only Refuses Mutations And Lifecycle (9920) MCP HTTP Mode Safe Refuses Mutations Without Elicitation (asserts the no-elicitation fallback) MCP HTTP Mode Delete Safe Allows Create Refuses Delete And Lifecycle (9921) MCP HTTP Mode Full Access Allows Everything (9922) MCP HTTP Audit Basic Records Tool Calls (9923 with known path) MCP HTTP Audit Disabled Writes No File Existing MCP HTTP Server Info Includes Version extended to assert the mode key. Existing MCP HTTPS Run Mutation Refused In Read Only updated to assert read_only (underscore) - exercises the legacy shim on the 9916 server which still uses the read_only: true wire form. Robot suite run locally / in CI Out of scope (deferred) An elicitation-capable MCP test client. Robot scenarios cover the no-elicitation fallback path only; the elicitation-positive path is covered by Go unit tests via ClientOptions.ElicitationHandler and verified manually with elicitation-capable clients (Claude Desktop, Cursor, etc). Sinks other than file (Kafka, RDBMS, KV). The Sink interface admits them as future additions. Per-tool mode overrides. Mode is global per server. 🤖 Generated with Claude Code

Open Graph Description: Summary PR2 of the two-PR MCP server series. PR1 trimmed the tool surface to 11 + 1 prompt and shipped a single read_only: true/false flag. PR2 replaces that flag with a four-mode safety contract...

X Description: Summary PR2 of the two-PR MCP server series. PR1 trimmed the tool surface to 11 + 1 prompt and shipped a single read_only: true/false flag. PR2 replaces that flag with a four-mode safety contract...

Opengraph URL: https://github.com/stackql/stackql/pull/652

X: @github

direct link

Domain: github.com

Links:

Viewport: width=device-width