Skip to content

[FEATURE] Align MCP Go SDK dependencies and complete latest stable specification adoption with Robot regression coverage #919

Open

Description

@jeffreyaven

Summary

Align the MCP Go SDK dependencies across StackQL and its Go launcher, complete adoption of the latest stable MCP specification, and use applicable new features with black-box Robot coverage. Existing tests and client behaviour must remain intact.

This is a follow-up to #729 and #784, not a repeat of the completed SDK upgrade.

Verified baseline

Checked on 14 November 2026 against StackQL main at 5c8c614:

  • The root go.mod already uses github.com/modelcontextprotocol/go-sdk v1.8.0, currently the latest stable upstream release.
  • packaging/mcpb/go/go.mod still uses v1.6.1.
  • The latest stable core specification is 2026-07-28. Version selection, stateless HTTP, legacy negotiation and MRTR approval flows already exist, with Robot tests.
  • HTTP defaults remain stateful for legacy-client compatibility. Stateless HTTP is opt-in or implied by pinning server.protocol_version to 2026-07-28.
  • HTTP authentication currently supports a pre-shared bearer token and an embedding authentication hook. This is not, by itself, full OAuth resource-server support.
  • The Go launcher's integration test assumes InitializeResult() is available. Review that assertion when moving to the newer, handshake-free lifecycle.
  • Server construction does not currently set the SDK's SetCacheable hook.

Recheck stable upstream releases when implementation starts. Record exact selected versions and release dates in the PR. Do not use an unreleased commit or draft specification just to claim "latest".

Implementation scope

Build on the completed protocol work and address the remaining gaps below.

SDK alignment and compatibility

  • Upgrade the separate Go launcher module to the selected stable SDK and update its module checksums. Keep the root module aligned; no artificial root version bump is required while v1.8.0 remains current.
  • Review SDK API and behaviour changes across both modules, including the launcher, internal test client, custom stdio transport and packaging smoke tests.
  • Preserve the existing protocol-version configuration, precedence, automatic negotiation and downgrade behaviour. Do not silently switch legacy HTTP deployments to stateless mode.
  • Verify current-revision discovery, required request metadata, result discriminators and HTTP method/name headers. Use the SDK's protocol implementation rather than duplicating it.
  • Retain legacy handshake and approval behaviour for supported older revisions. Document transport-specific limits, including legacy gated writes on stateless HTTP.
  • Preserve malformed-frame recovery, LF/CRLF handling, input bounds, cancellation and clean shutdown. An SDK upgrade must not remove protections provided by StackQL's custom stdio transport.

Useful stable features

  • Add an explicit cache policy using SetCacheable or the equivalent supported SDK API. Use suitable TTLs and private scope for caller/configuration-sensitive content; only mark content public when safe to share. Keep catalogue ordering deterministic and verify freshness when exposed content changes. This is protocol metadata, not a new query-result cache.
  • Review structured results and JSON Schema support against the stable specification. Adopt capabilities useful to StackQL without changing existing tool names, arguments, DTOs or default Markdown/JSON rendering unnecessarily.
  • Validate existing request-scoped approval, trace propagation and audit behaviour under the current revision, including reconnects and concurrent clients. Do not introduce automatic retries of mutations on connection loss.
  • Preserve per-request authentication, TLS/origin protection, input limits and credential redaction.

Authentication and extensions

  • Add an opt-in remote HTTP integration path for OAuth Client Credentials with an external authorization server: protected-resource metadata/challenges, trusted issuer and audience validation, token validity and scope enforcement on each request. Keep existing bearer-token deployments and local stdio working.
  • Distinguish client token acquisition from resource-server token validation. The SDK's ClientCredentialsHandler is a client helper, not a server authentication implementation. Verify support for the chosen token authentication method; document upstream gaps instead of assuming every method in the extension is implemented.
  • Record an adoption decision for each relevant extension: implement here, already supported, not applicable, or a linked follow-up with rationale.
  • MCP Apps and authentication extensions are Stable but optional. Tasks is Beta, not a core requirement. Keep Beta/Experimental features disabled by default, pin tested revisions, and preserve synchronous tool calls for clients without extension support.
  • Do not make an interactive Apps UI or a durable Tasks service a prerequisite for the SDK alignment. If selected for implementation, give it an explicit contract and Robot coverage. App packaging alone does not establish MCP Apps protocol support.

Robot and regression coverage

Extend test/robot/functional/mcp.robot and the existing Python MCP harness. Test the built StackQL binary against controlled local provider/auth fixtures.

Required coverage:

  • Current 2026-07-28 requests over stdio and stateless HTTP, with and without discovery; missing/invalid metadata, unsupported revisions, header mismatches and result shapes.
  • Explicit 2025-11-25 and 2025-06-18 legacy clients, version pinning, automatic negotiation and stateful downgrade. Keep existing legacy cases.
  • All safety modes; approval accept/decline/cancel, missing capability and tampered/replayed approval state. Assert refused operations never reach the provider. Do not claim distributed replay prevention without shared enforcement.
  • Stable catalogue ordering, cache TTL/scope, sensitive-content isolation and freshness.
  • OAuth success and rejection cases using a mock authorization server: expired/invalid token, wrong issuer/audience, insufficient scope and missing credentials. Retain existing pre-shared-token and unauthenticated-opt-in tests.
  • Existing query results, empty/null values, error classification, credential reload, audit/redaction, TLS, malformed stdio frames, concurrency and timeouts.
  • Go launcher interoperability with the newly built server and a pinned supported legacy server. Exercise both lifecycle models and clean process termination.
  • Every new advertised feature or extension, including capability-disabled/fallback behaviour.

Unit tests supplement Robot tests; they do not replace black-box coverage.

Acceptance criteria

  • Root and launcher SDK versions are reconciled to the selected stable release, with both module test suites passing.
  • A specification/feature checklist identifies what was already implemented, what this PR adds, and any explicitly linked follow-ups.
  • New functionality has Robot assertions for success, failure and compatibility paths.
  • Existing Go, Robot, packaging and required CI checks remain green. Do not delete, skip, loosen or rewrite existing expected results merely to hide regressions.
  • The PR includes before/after test counts and results for the same applicable suites and environments. Pre-existing failures and unavailable checks are reported, not silently accepted as passing.
  • Build and lint pass using the repository's supported Go toolchain. Run tests in the nested launcher module explicitly; root-module tests do not cover it.
  • docs/mcp.md, launcher documentation and release notes describe supported revisions, configuration, new features, extension status and compatibility limits.

Primary references

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

enhancementNew feature or request

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions