fix(server): Implement MCP protocol negotiation. (#341)

According to [the MCP spec](https://modelcontextprotocol.io/specification/2025-03-26/basic/lifecycle#version-negotiation):

> If the server supports the requested protocol version, it MUST respond with
> the same version. Otherwise, the server MUST respond with another protocol
> version it supports.

This adds `mcp.ValidProtocolVersions`, a slice with all currently specified MCP
versions.

In the `server` package we check if the client provided a known MCP version
and, if so, return that version. Otherwise `LATEST_PROTOCOL_VERSION` is
returned as previously.

Author: octo

mcp/types.go

@@ -98,6 +98,12 @@ type JSONRPCMessage any
 // LATEST_PROTOCOL_VERSION is the most recent version of the MCP protocol.
 const LATEST_PROTOCOL_VERSION = "2025-03-26"
 
+// ValidProtocolVersions lists all known valid MCP protocol versions.
+var ValidProtocolVersions = []string{
+	"2024-11-05",
+	LATEST_PROTOCOL_VERSION,
+}
+
 // JSONRPC_VERSION is the version of JSON-RPC used by MCP.
 const JSONRPC_VERSION = "2.0"
 

server/server.go

@@ -6,6 +6,7 @@ import (
 	"encoding/base64"
 	"encoding/json"
 	"fmt"
+	"slices"
 	"sort"
 	"sync"
 
@@ -550,7 +551,7 @@ func (s *MCPServer) handleInitialize(
 	}
 
 	result := mcp.InitializeResult{
-		ProtocolVersion: mcp.LATEST_PROTOCOL_VERSION,
+		ProtocolVersion: s.protocolVersion(request.Params.ProtocolVersion),
 		ServerInfo: mcp.Implementation{
 			Name:    s.name,
 			Version: s.version,
@@ -570,6 +571,14 @@ func (s *MCPServer) handleInitialize(
 	return &result, nil
 }
 
+func (s *MCPServer) protocolVersion(clientVersion string) string {
+	if slices.Contains(mcp.ValidProtocolVersions, clientVersion) {
+		return clientVersion
+	}
+
+	return mcp.LATEST_PROTOCOL_VERSION
+}
+
 func (s *MCPServer) handlePing(
 	_ context.Context,
 	_ any,

server/server_test.go

@@ -1946,3 +1946,79 @@ func TestMCPServer_ToolCapabilitiesBehavior(t *testing.T) {
 		})
 	}
 }
+
+func TestMCPServer_ProtocolNegotiation(t *testing.T) {
+	tests := []struct {
+		name            string
+		clientVersion   string
+		expectedVersion string
+	}{
+		{
+			name:            "Server supports client version - should respond with same version",
+			clientVersion:   "2024-11-05",
+			expectedVersion: "2024-11-05", // Server must respond with client's version if supported
+		},
+		{
+			name:            "Client requests current latest - should respond with same version",
+			clientVersion:   mcp.LATEST_PROTOCOL_VERSION, // "2025-03-26"
+			expectedVersion: mcp.LATEST_PROTOCOL_VERSION,
+		},
+		{
+			name:            "Client requests unsupported future version - should respond with server's latest",
+			clientVersion:   "2026-01-01",                // Future unsupported version
+			expectedVersion: mcp.LATEST_PROTOCOL_VERSION, // Server responds with its latest supported
+		},
+		{
+			name:            "Client requests unsupported old version - should respond with server's latest",
+			clientVersion:   "2023-01-01",                // Very old unsupported version
+			expectedVersion: mcp.LATEST_PROTOCOL_VERSION, // Server responds with its latest supported
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			server := NewMCPServer("test-server", "1.0.0")
+
+			params := struct {
+				ProtocolVersion string                 `json:"protocolVersion"`
+				ClientInfo      mcp.Implementation     `json:"clientInfo"`
+				Capabilities    mcp.ClientCapabilities `json:"capabilities"`
+			}{
+				ProtocolVersion: tt.clientVersion,
+				ClientInfo: mcp.Implementation{
+					Name:    "test-client",
+					Version: "1.0.0",
+				},
+			}
+
+			// Create initialize request with specific protocol version
+			initRequest := mcp.JSONRPCRequest{
+				JSONRPC: "2.0",
+				ID:      mcp.NewRequestId(int64(1)),
+				Request: mcp.Request{
+					Method: "initialize",
+				},
+				Params: params,
+			}
+
+			messageBytes, err := json.Marshal(initRequest)
+			assert.NoError(t, err)
+
+			response := server.HandleMessage(context.Background(), messageBytes)
+			assert.NotNil(t, response)
+
+			resp, ok := response.(mcp.JSONRPCResponse)
+			assert.True(t, ok)
+
+			initResult, ok := resp.Result.(mcp.InitializeResult)
+			assert.True(t, ok)
+
+			assert.Equal(
+				t,
+				tt.expectedVersion,
+				initResult.ProtocolVersion,
+				"Protocol version should follow MCP spec negotiation rules",
+			)
+		})
+	}
+}