GeezerVison

Closes #784.

Summary

• Bumps github.com/modelcontextprotocol/go-sdk v1.7.0 to v1.8.0. The build and every existing MCP unit test pass on the new SDK with no code changes.
• Adds a protocol revision ceiling: server.protocol_version in mcp.config, overridden by a new --mcp.protocol.version flag (same pattern as --mcp.log.format).
  • auto (default, or absent): unchanged behaviour, every SDK revision is advertised and negotiated per client.
  • 2026-07-28: only that revision is advertised (ServerOptions.SupportedProtocolVersions) and stateless Streamable HTTP is implied, since the SDK serves that revision over HTTP only without sessions. A legacy initialize is answered with 2025-11-25, the SDK's cue for the client to disconnect.
  • 2025-11-25 (or any older revision): that revision and everything before it. A 2026-07-28 request gets the SDK's -32022 UnsupportedProtocolVersion error listing the advertised revisions so the client can renegotiate; older handshake clients keep their own revision.
  • Any other value fails config validation at startup and names the legal values, so the SDK's NewServer panic is never reached.
• Reviews the v1.8.0 transport limits and deprecations (documented, no new knobs): HTTP request bodies stay at the SDK's 4 MiB default, the custom stdio transport keeps its 8 MiB frame bound (the SDK's own stdio read loop still dies on a decode error, so that transport stays), and stackql uses none of roots, sampling or server logging (SEP-2577).
• Docs: docs/mcp.md gains "Pinning the revision (--mcp.protocol.version)" and "Transport limits and deprecated features (SDK v1.8.0)", and the Streamable HTTP notes now describe the v1.8.0 stateful rejection (JSON-RPC -32022 on a 400 instead of a plain-text 400) and the 405 on GET/DELETE in stateless mode.

Design choices

• The ceiling lives on the existing exported Config/ServerConfig DTO (deserialised from JSON/YAML, so a public field is consistent with its neighbours such as stateless); the mapping to SDK options is behind Config.AdvertisedProtocolVersions() and Config.IsStateless(), so server.go only reads accessors.
• 2026-07-28 stands alone rather than acting as a ceiling over everything, because a ceiling of the newest revision would be identical to auto and the option would have no meaning.
• Size limits are left at SDK defaults on purpose: they sit far above any SQL statement stackql accepts and adding config surface for them was not warranted.
• New robot SQL is inlined in the .robot file; stackql_context.py is untouched.

Test plan

• Unit: TestProtocolVersionConfig (ceiling mapping, implied stateless, validation of unknown values, wire form beside the legacy read_only shim); TestPinnedLegacyRevision_RejectsCurrentRevisionWithDowngradeError, TestPinnedCurrentRevision_ServesCurrentAndAnswersLegacyWithNewestHandshake, TestAutoRevision_ServesBothLifecycles over the raw JSON-RPC connection.
• Robot (Mcp suite): two new servers, 9928 pinned to 2026-07-28 via the flag with no stateless key (safe mode) and 9929 pinned to 2025-11-25 via mcp.config (stateful), plus six new scenarios:
  • sessionless client on 9928: server/discover lists only 2026-07-28, no session id, DELETE is 405, gated write via the input-required round trip
  • legacy initialize on 9928 answered with 2025-11-25, no session issued
  • -32022 downgrade error on 9929 for a current-revision request, while a 2025-06-18 client keeps its revision on a session
  • the same downgrade error over stdio, session survives
  • pinned current revision over stdio serves the gated write unchanged
  • startup refusal of an unknown revision with the legal list
  • The existing MCP HTTP Stateful Server Negotiates Current Client Down scenario now asserts the -32022 payload.
• Harness: mcp_stdio_client.py gains a protocol_version pin, decodes JSON-RPC error bodies on HTTP 400, and probes DELETE.
• Local results: MCP package unit tests clean, golangci-lint (CI-pinned 2.5.0) clean, Mcp robot suite 76/76 in WSL.

Also in this PR: describe_resource retired as an MCP tool

The describe_resource tool wrapped DESCRIBE provider.service.resource, which reports the schema of the one select method resolved without WHERE parameters (GetSelectableObjectSchema), while a SELECT routes by its parameters and can land on a method with a different response shape. describe_method is the exact contract for the method a query routes to (inputs with param_type, output fields), so it is now the single column source and the tool set is list_providers / list_services / list_resources / list_methods / describe_method / run_*. The SQL DESCRIBE statement is unchanged; only MCP tooling is touched.

• Removed the tool registration, Backend.DescribeResource and its implementations, the interrogator SQL builder and the tool description file.
• Rewrote the discovery instructions as a numbered drill-down ending in describe_method, sharpened the describe_method and list_methods descriptions, and repointed the dialect rules, error recovery, prompts and the deploy-stack resource at describe_method output fields.
• Docs: docs/mcp.md (the tool table now lists 15 tools, including the query library pair it was missing), package README, bundle README.
• Tests: TestRegistration_DescribeResourceRetired; the robot list-tools scenario asserts the tool is absent and describe_method present; the describe-resource robot scenario is removed. Unit tests, lint and the Mcp robot suite are green locally; CI covers the combined branch.

Compatibility: clients holding a cached tool list get a tool-not-found error for describe_resource; an enabled_tools allowlist naming it is ignored.

Not in this PR

• Website docs (separate repo) also still list describe_resource as a tool.
• packaging/mcpb/go is a separate client-only module and still pins go-sdk v1.6.1.
• Website docs (separate repo) still need the --mcp.protocol.version rows.

🤖 Generated with Claude Code