diff --git a/pkg/inventory/tool_availability.go b/pkg/inventory/tool_availability.go index 3951dcaa6f..fa6121706f 100644 --- a/pkg/inventory/tool_availability.go +++ b/pkg/inventory/tool_availability.go @@ -12,6 +12,46 @@ import ( // multi-round-trip input requests. const ProtocolVersionMultiRoundTrip = "2026-07-28" +// latestLegacyProtocolVersion is the newest protocol version the deprecated +// initialize handshake can negotiate. +const latestLegacyProtocolVersion = "2025-11-25" + +// knownProtocolVersions lists the MCP protocol versions this server understands, +// oldest first. Availability is decided by comparing against these entries +// instead of comparing version strings lexically. +var knownProtocolVersions = []string{ + "2024-11-05", + "2025-03-26", + "2025-06-18", + latestLegacyProtocolVersion, + ProtocolVersionMultiRoundTrip, +} + +// knownProtocolVersionRank returns the position of version in +// knownProtocolVersions, oldest first. +func knownProtocolVersionRank(version string) (int, bool) { + for i, known := range knownProtocolVersions { + if version == known { + return i, true + } + } + return 0, false +} + +// availabilityProtocolVersionRank ranks a client-declared protocol version for +// the >= comparison. Versions the server does not know negotiate down to +// latestLegacyProtocolVersion, and an unset version ranks below every known one. +func availabilityProtocolVersionRank(version string) int { + if version == "" { + return -1 + } + if rank, ok := knownProtocolVersionRank(version); ok { + return rank + } + legacyRank, _ := knownProtocolVersionRank(latestLegacyProtocolVersion) + return legacyRank +} + // ElicitationMode identifies a client-supported elicitation interaction mode. type ElicitationMode string @@ -116,8 +156,9 @@ func toolAvailabilityMiddleware(availabilityByName map[string]toolAvailability) } tools := make([]*mcp.Tool, 0, len(list.Tools)) + protocolVersion := protocolVersionForTools(requestMetaProtocolVersion(req.Params.Meta), req.ProtocolVersion()) for _, tool := range list.Tools { - if toolAvailable(req.ProtocolVersion(), req.ClientCapabilities(), availabilityByName[tool.Name]) { + if toolAvailable(protocolVersion, req.ClientCapabilities(), availabilityByName[tool.Name]) { tools = append(tools, tool) } } @@ -133,7 +174,8 @@ func (st *ServerTool) wrapAvailabilityCheck(next mcp.ToolHandler) mcp.ToolHandle return next } return func(ctx context.Context, req *mcp.CallToolRequest) (*mcp.CallToolResult, error) { - if toolAvailable(req.ProtocolVersion(), req.ClientCapabilities(), availability) { + protocolVersion := protocolVersionForTools(requestMetaProtocolVersion(req.Params.Meta), req.ProtocolVersion()) + if toolAvailable(protocolVersion, req.ClientCapabilities(), availability) { return next(ctx, req) } return toolUnavailableResult(st.Tool.Name, req, availability), nil @@ -146,8 +188,39 @@ func toolAvailable(protocolVersion string, capabilities *mcp.ClientCapabilities, } func protocolVersionAllowed(protocolVersion, minimum string) bool { - // MCP protocol versions use ISO dates, so lexical ordering is chronological. - return minimum == "" || protocolVersion >= minimum + if minimum == "" { + return true + } + minimumRank, ok := knownProtocolVersionRank(minimum) + if !ok { + // Keep comparing lexically when the requirement itself is not a + // version this server knows about. + return protocolVersion >= minimum + } + return availabilityProtocolVersionRank(protocolVersion) >= minimumRank +} + +// protocolVersionForTools resolves the protocol version that gates tool +// availability for a request. The per-request _meta version is authoritative. +// Otherwise the request falls back to the session version established during +// initialize, which the server always negotiates down to +// latestLegacyProtocolVersion. +func protocolVersionForTools(metaVersion, sessionVersion string) string { + if metaVersion != "" { + return metaVersion + } + if sessionVersion == "" { + return "" + } + legacyRank, _ := knownProtocolVersionRank(latestLegacyProtocolVersion) + rank := availabilityProtocolVersionRank(sessionVersion) + if rank > legacyRank { + return latestLegacyProtocolVersion + } + if _, ok := knownProtocolVersionRank(sessionVersion); !ok { + return latestLegacyProtocolVersion + } + return sessionVersion } func elicitationModeSupported(capabilities *mcp.ClientCapabilities, requiredMode ElicitationMode) bool { @@ -170,9 +243,10 @@ func elicitationModeSupported(capabilities *mcp.ClientCapabilities, requiredMode } func toolUnavailableResult(name string, req *mcp.CallToolRequest, availability toolAvailability) *mcp.CallToolResult { + protocolVersion := protocolVersionForTools(requestMetaProtocolVersion(req.Params.Meta), req.ProtocolVersion()) message := fmt.Sprintf("Tool %q is unavailable for this client.", name) switch { - case !protocolVersionAllowed(req.ProtocolVersion(), availability.minimumProtocolVersion): + case !protocolVersionAllowed(protocolVersion, availability.minimumProtocolVersion): message = fmt.Sprintf( "Tool %q requires MCP protocol version %s or later.", name, diff --git a/pkg/inventory/tool_availability_test.go b/pkg/inventory/tool_availability_test.go index a59905b2e4..0d8990f495 100644 --- a/pkg/inventory/tool_availability_test.go +++ b/pkg/inventory/tool_availability_test.go @@ -9,6 +9,7 @@ import ( ghcontext "github.com/github/github-mcp-server/v2/pkg/context" "github.com/google/jsonschema-go/jsonschema" + "github.com/modelcontextprotocol/go-sdk/jsonrpc" "github.com/modelcontextprotocol/go-sdk/mcp" "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" @@ -142,6 +143,262 @@ func TestToolAvailability(t *testing.T) { } } +func TestProtocolVersionAllowed(t *testing.T) { + t.Parallel() + + tests := []struct { + name string + protocolVersion string + minimum string + want bool + }{ + { + name: "unrestricted tool", + protocolVersion: "2024-11-05", + want: true, + }, + { + name: "known older version cannot reach newer minimum", + protocolVersion: "2025-06-18", + minimum: latestLegacyProtocolVersion, + want: false, + }, + { + name: "known minimum reached", + protocolVersion: ProtocolVersionMultiRoundTrip, + minimum: latestLegacyProtocolVersion, + want: true, + }, + { + name: "unknown version is not treated as newer", + protocolVersion: "zzz", + minimum: ProtocolVersionMultiRoundTrip, + want: false, + }, + { + name: "unknown version still reaches legacy minimum", + protocolVersion: "zzz", + minimum: "2025-06-18", + want: true, + }, + { + name: "date-shaped unknown version is not treated as newer", + protocolVersion: "2026-07-28-unknown", + minimum: ProtocolVersionMultiRoundTrip, + want: false, + }, + { + name: "future-looking unknown version is not treated as newer", + protocolVersion: "9999-12-31", + minimum: ProtocolVersionMultiRoundTrip, + want: false, + }, + { + name: "unset version cannot reach a gated minimum", + protocolVersion: "", + minimum: ProtocolVersionMultiRoundTrip, + want: false, + }, + { + name: "unknown minimum keeps lexical comparison", + protocolVersion: "2026-07-28", + minimum: "2026-01-01", + want: true, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + t.Parallel() + assert.Equal(t, tt.want, protocolVersionAllowed(tt.protocolVersion, tt.minimum)) + }) + } +} + +func TestProtocolVersionForTools(t *testing.T) { + t.Parallel() + + tests := []struct { + name string + metaVersion string + sessionVersion string + want string + }{ + { + name: "per-request version wins", + metaVersion: ProtocolVersionMultiRoundTrip, + sessionVersion: latestLegacyProtocolVersion, + want: ProtocolVersionMultiRoundTrip, + }, + { + name: "legacy session cannot negotiate multi-round-trip", + sessionVersion: ProtocolVersionMultiRoundTrip, + want: latestLegacyProtocolVersion, + }, + { + name: "unknown session version negotiates down to legacy", + sessionVersion: "zzz", + want: latestLegacyProtocolVersion, + }, + { + name: "known legacy session version is preserved", + sessionVersion: "2025-06-18", + want: "2025-06-18", + }, + { + name: "unset versions stay unset", + want: "", + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + t.Parallel() + assert.Equal(t, tt.want, protocolVersionForTools(tt.metaVersion, tt.sessionVersion)) + }) + } +} + +// TestToolAvailabilityUsesNegotiatedProtocolVersion emulates a client that +// requests a version the server cannot negotiate during initialize and sends no +// per-request protocolVersion metadata, as a raw JSON-RPC client does. +func TestToolAvailabilityUsesNegotiatedProtocolVersion(t *testing.T) { + t.Parallel() + + tests := []struct { + name string + requested string + }{ + { + name: "multi-round-trip request is capped to the negotiated legacy version", + requested: ProtocolVersionMultiRoundTrip, + }, + { + name: "unknown request version is not treated as newer", + requested: "zzz", + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + t.Parallel() + + var restrictedToolCalls int + tools := []ServerTool{ + availabilityTestTool("always_available", "", "", nil), + availabilityTestTool("restricted", ProtocolVersionMultiRoundTrip, ElicitationModeForm, func() { + restrictedToolCalls++ + }), + } + inv, err := NewBuilder(). + SetTools(tools). + WithToolsets([]string{"all"}). + Build() + require.NoError(t, err) + + server := mcp.NewServer(&mcp.Implementation{Name: "test-server", Version: "v0.0.1"}, nil) + inv.RegisterTools(context.Background(), server, nil) + server.AddReceivingMiddleware(func(next mcp.MethodHandler) mcp.MethodHandler { + return func(ctx context.Context, method string, request mcp.Request) (mcp.Result, error) { + if method == "server/discover" { + return nil, errors.New("legacy server does not support discovery") + } + return next(ctx, method, request) + } + }) + + serverTransport, clientTransport := mcp.NewInMemoryTransports() + serverSession, err := server.Connect(context.Background(), serverTransport, nil) + require.NoError(t, err) + t.Cleanup(func() { _ = serverSession.Close() }) + + client := mcp.NewClient(&mcp.Implementation{Name: "test-client", Version: "v0.0.1"}, &mcp.ClientOptions{ + Capabilities: &mcp.ClientCapabilities{ + Elicitation: &mcp.ElicitationCapabilities{Form: &mcp.FormElicitationCapabilities{}}, + }, + }) + clientSession, err := client.Connect(context.Background(), negotiatedVersionTransport{Transport: clientTransport, requested: tt.requested}, nil) + require.NoError(t, err) + t.Cleanup(func() { _ = clientSession.Close() }) + assert.Equal(t, latestLegacyProtocolVersion, clientSession.InitializeResult().ProtocolVersion) + + listResult, err := clientSession.ListTools(context.Background(), nil) + require.NoError(t, err) + toolNames := make([]string, 0, len(listResult.Tools)) + for _, tool := range listResult.Tools { + toolNames = append(toolNames, tool.Name) + } + assert.Contains(t, toolNames, "always_available") + assert.NotContains(t, toolNames, "restricted") + + callResult, err := clientSession.CallTool(context.Background(), &mcp.CallToolParams{Name: "restricted"}) + require.NoError(t, err) + assert.True(t, callResult.IsError) + assert.Zero(t, restrictedToolCalls) + }) + } +} + +// negotiatedVersionTransport rewrites the initialize request to the requested +// version and strips per-request protocolVersion metadata, matching clients that +// never send _meta. +type negotiatedVersionTransport struct { + mcp.Transport + requested string +} + +func (t negotiatedVersionTransport) Connect(ctx context.Context) (mcp.Connection, error) { + connection, err := t.Transport.Connect(ctx) + if err != nil { + return nil, err + } + return negotiatedVersionConnection{Connection: connection, requested: t.requested}, nil +} + +type negotiatedVersionConnection struct { + mcp.Connection + requested string +} + +func (c negotiatedVersionConnection) Write(ctx context.Context, message jsonrpc.Message) error { + req, ok := message.(*jsonrpc.Request) + if !ok { + return c.Connection.Write(ctx, message) + } + if len(req.Params) == 0 { + return c.Connection.Write(ctx, message) + } + var params map[string]json.RawMessage + if err := json.Unmarshal(req.Params, ¶ms); err != nil { + return err + } + if req.Method == "initialize" { + version, err := json.Marshal(c.requested) + if err != nil { + return err + } + params["protocolVersion"] = version + } else if rawMeta, ok := params["_meta"]; ok { + var meta map[string]json.RawMessage + if err := json.Unmarshal(rawMeta, &meta); err != nil { + return err + } + delete(meta, mcp.MetaKeyProtocolVersion) + encodedMeta, err := json.Marshal(meta) + if err != nil { + return err + } + params["_meta"] = encodedMeta + } + encoded, err := json.Marshal(params) + if err != nil { + return err + } + requestCopy := *req + requestCopy.Params = encoded + return c.Connection.Write(ctx, &requestCopy) +} + func TestToolCallAvailabilitySkipsFeatureChecksOnlyWhenUnavailable(t *testing.T) { tests := []struct { name string