fix(context): preserve advertised input schema compatibility

Keep legacy-visible schemas byte-compatible while applying unknown-field acceptance only to the cached runtime validation schema. Verify modern DTO text parity and preserve legacy formatted text.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: SamMorrowDrums

pkg/github/__toolsnaps__/get_me.snap

@@ -15,7 +15,6 @@
   },
   "description": "Get details of the authenticated GitHub user. Use this when a request is about the user's own profile for GitHub. Or when information is missing to build other tool calls.",
   "inputSchema": {
-    "additionalProperties": true,
     "properties": {},
     "type": "object"
   },

pkg/github/__toolsnaps__/get_team_members.snap

@@ -6,7 +6,6 @@
   },
   "description": "Get member usernames of a specific team in an organization. Limited to organizations accessible with current credentials",
   "inputSchema": {
-    "additionalProperties": true,
     "properties": {
       "org": {
         "description": "Organization login (owner) that contains the team.",

pkg/github/__toolsnaps__/get_teams.snap

@@ -6,7 +6,6 @@
   },
   "description": "Get details of the teams the user is a member of. Limited to organizations accessible with current credentials",
   "inputSchema": {
-    "additionalProperties": true,
     "properties": {
       "user": {
         "description": "Username to get teams for. If not provided, uses the authenticated user.",

pkg/github/context_tools.go

@@ -38,13 +38,19 @@ func contextToolInputSchema[In any](descriptions map[string]string) *jsonschema.
 	if schema.Properties == nil {
 		schema.Properties = make(map[string]*jsonschema.Schema)
 	}
-	schema.AdditionalProperties = &jsonschema.Schema{}
+	schema.AdditionalProperties = nil
 	for name, description := range descriptions {
 		schema.Properties[name].Description = description
 	}
 	return schema
 }
 
+func contextToolValidationSchema(schema *jsonschema.Schema) *jsonschema.Schema {
+	validationSchema := schema.CloneSchemas()
+	validationSchema.AdditionalProperties = &jsonschema.Schema{}
+	return validationSchema
+}
+
 // UserDetails contains additional fields about a GitHub user not already
 // present in MinimalUser. Used by get_me context tool but omitted from search_users.
 type UserDetails struct {
@@ -69,7 +75,8 @@ type UserDetails struct {
 
 // GetMe creates a tool to get details of the authenticated user.
 func GetMe(t translations.TranslationHelperFunc) inventory.ServerTool {
-	return NewTool[GetMeInput, MinimalUser](
+	inputSchema := contextToolInputSchema[GetMeInput](nil)
+	return NewToolWithSchemaOptions[GetMeInput, MinimalUser](
 		ToolsetMetadataContext,
 		mcp.Tool{
 			Name:        "get_me",
@@ -78,7 +85,7 @@ func GetMe(t translations.TranslationHelperFunc) inventory.ServerTool {
 				Title:        t("TOOL_GET_ME_USER_TITLE", "Get my user profile"),
 				ReadOnlyHint: true,
 			},
-			InputSchema: contextToolInputSchema[GetMeInput](nil),
+			InputSchema: inputSchema,
 			Meta: mcp.Meta{
 				"ui": map[string]any{
 					"resourceUri": GetMeUIResourceURI,
@@ -87,6 +94,9 @@ func GetMe(t translations.TranslationHelperFunc) inventory.ServerTool {
 			},
 		},
 		scopes.NoScopes(),
+		inventory.TypedSchemaOptions{
+			ValidationInputSchema: contextToolValidationSchema(inputSchema),
+		},
 		func(ctx context.Context, deps ToolDependencies, _ *mcp.CallToolRequest, _ GetMeInput) (*mcp.CallToolResult, MinimalUser, error) {
 			client, err := deps.GetClient(ctx)
 			if err != nil {
@@ -148,7 +158,10 @@ type OrganizationTeams struct {
 }
 
 func GetTeams(t translations.TranslationHelperFunc) inventory.ServerTool {
-	return NewTool[GetTeamsInput, []OrganizationTeams](
+	inputSchema := contextToolInputSchema[GetTeamsInput](map[string]string{
+		"user": t("TOOL_GET_TEAMS_USER_DESCRIPTION", "Username to get teams for. If not provided, uses the authenticated user."),
+	})
+	return NewToolWithSchemaOptions[GetTeamsInput, []OrganizationTeams](
 		ToolsetMetadataContext,
 		mcp.Tool{
 			Name:        "get_teams",
@@ -157,11 +170,12 @@ func GetTeams(t translations.TranslationHelperFunc) inventory.ServerTool {
 				Title:        t("TOOL_GET_TEAMS_TITLE", "Get teams"),
 				ReadOnlyHint: true,
 			},
-			InputSchema: contextToolInputSchema[GetTeamsInput](map[string]string{
-				"user": t("TOOL_GET_TEAMS_USER_DESCRIPTION", "Username to get teams for. If not provided, uses the authenticated user."),
-			}),
+			InputSchema: inputSchema,
 		},
 		scopes.RequireAll(scopes.ReadOrg),
+		inventory.TypedSchemaOptions{
+			ValidationInputSchema: contextToolValidationSchema(inputSchema),
+		},
 		func(ctx context.Context, deps ToolDependencies, _ *mcp.CallToolRequest, args GetTeamsInput) (*mcp.CallToolResult, []OrganizationTeams, error) {
 			var username string
 			if args.User != "" {
@@ -248,7 +262,7 @@ func GetTeamMembers(t translations.TranslationHelperFunc) inventory.ServerTool {
 		"team_slug": t("TOOL_GET_TEAM_MEMBERS_TEAM_SLUG_DESCRIPTION", "Team slug"),
 	})
 
-	return NewTool[GetTeamMembersInput, []string](
+	return NewToolWithSchemaOptions[GetTeamMembersInput, []string](
 		ToolsetMetadataContext,
 		mcp.Tool{
 			Name:        "get_team_members",
@@ -260,6 +274,9 @@ func GetTeamMembers(t translations.TranslationHelperFunc) inventory.ServerTool {
 			InputSchema: inputSchema,
 		},
 		scopes.RequireAll(scopes.ReadOrg),
+		inventory.TypedSchemaOptions{
+			ValidationInputSchema: contextToolValidationSchema(inputSchema),
+		},
 		func(ctx context.Context, deps ToolDependencies, _ *mcp.CallToolRequest, args GetTeamMembersInput) (*mcp.CallToolResult, []string, error) {
 			if args.Org == "" {
 				return utils.NewToolResultError("missing required parameter: org"), nil, nil

pkg/github/context_tools_test.go

@@ -9,6 +9,7 @@ import (
 
 	"github.com/github/github-mcp-server/internal/githubv4mock"
 	"github.com/github/github-mcp-server/internal/toolsnaps"
+	"github.com/github/github-mcp-server/pkg/inventory"
 	"github.com/github/github-mcp-server/pkg/translations"
 	"github.com/google/go-github/v92/github"
 	"github.com/google/jsonschema-go/jsonschema"
@@ -255,23 +256,30 @@ func TestContextToolsTypedRegistration(t *testing.T) {
 	server := mcp.NewServer(&mcp.Implementation{Name: "test-server", Version: "v0.0.1"}, nil)
 	server.AddReceivingMiddleware(InjectDepsMiddleware(deps))
 	getMeTool := GetMe(translations.NullTranslationHelper)
-	getMeTool.RegisterFunc(server, nil)
 	getTeamsTool := GetTeams(translations.NullTranslationHelper)
-	getTeamsTool.RegisterFunc(server, nil)
 	teamMembersTool := GetTeamMembers(translations.NullTranslationHelper)
-	teamMembersTool.RegisterFunc(server, nil)
+	inv, err := inventory.NewBuilder().
+		SetTools([]inventory.ServerTool{getMeTool, getTeamsTool, teamMembersTool}).
+		WithToolsets([]string{"all"}).
+		Build()
+	require.NoError(t, err)
+	inv.RegisterTools(context.Background(), server, deps)
 
 	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"}, nil)
-	clientSession, err := client.Connect(context.Background(), clientTransport, nil)
+	clientSession, err := client.Connect(context.Background(), clientTransport, &mcp.ClientSessionOptions{
+		ProtocolVersion: inventory.ProtocolVersionMultiRoundTrip,
+	})
 	require.NoError(t, err)
+	require.Equal(t, inventory.ProtocolVersionMultiRoundTrip, clientSession.InitializeResult().ProtocolVersion)
 	t.Cleanup(func() { _ = clientSession.Close() })
 
-	list, err := clientSession.ListTools(context.Background(), nil)
+	protocolMeta := mcp.Meta{mcp.MetaKeyProtocolVersion: inventory.ProtocolVersionMultiRoundTrip}
+	list, err := clientSession.ListTools(context.Background(), &mcp.ListToolsParams{Meta: protocolMeta})
 	require.NoError(t, err)
 	require.Len(t, list.Tools, 3)
 	outputSchemas := make(map[string]*jsonschema.Resolved)
@@ -299,9 +307,7 @@ func TestContextToolsTypedRegistration(t *testing.T) {
 			AdditionalProperties *bool `json:"additionalProperties"`
 		}
 		require.NoError(t, json.Unmarshal(schemaJSON, &schemaMetadata))
-		if schemaMetadata.AdditionalProperties != nil {
-			assert.True(t, *schemaMetadata.AdditionalProperties, "explicit true must retain the legacy default")
-		}
+		assert.Nil(t, schemaMetadata.AdditionalProperties, "advertised input schema must match the legacy snapshot bytes")
 		for propertyName, property := range schema.Properties {
 			var propertySchema jsonschema.Schema
 			require.NoError(t, json.Unmarshal(property, &propertySchema))
@@ -340,6 +346,7 @@ func TestContextToolsTypedRegistration(t *testing.T) {
 	result, err := clientSession.CallTool(context.Background(), &mcp.CallToolParams{
 		Name:      "get_me",
 		Arguments: map[string]any{"legacy_ignored_argument": true},
+		Meta:      protocolMeta,
 	})
 	require.NoError(t, err)
 	require.False(t, result.IsError)
@@ -362,52 +369,56 @@ func TestContextToolsTypedRegistration(t *testing.T) {
 	result, err = clientSession.CallTool(context.Background(), &mcp.CallToolParams{
 		Name:      "get_teams",
 		Arguments: map[string]any{"user": "specificuser", "legacy_ignored_argument": true},
+		Meta:      protocolMeta,
 	})
 	require.NoError(t, err)
 	require.False(t, result.IsError)
 	structuredJSON, err = json.Marshal(result.StructuredContent)
 	require.NoError(t, err)
 	assert.JSONEq(t, `[{"org":"testorg","teams":[{"name":"team1","slug":"team1","description":"Team 1"}]}]`, string(structuredJSON))
-	assert.Equal(t, string(structuredJSON), getTextResult(t, result).Text)
+	assert.JSONEq(t, string(structuredJSON), getTextResult(t, result).Text)
 	request = createMCPRequest(map[string]any{"user": "specificuser"})
 	legacyResult, err = getTeamsTool.Handler(deps)(ContextWithDeps(context.Background(), deps), &request)
 	require.NoError(t, err)
 	assert.Equal(t, `[{"org":"testorg","teams":[{"name":"team1","slug":"team1","description":"Team 1"}]}]`, getTextResult(t, legacyResult).Text)
 	require.NoError(t, outputSchemas["get_teams"].Validate(result.StructuredContent))
-	assert.Equal(t, 1, graphQLCalls)
+	assert.Equal(t, 2, graphQLCalls)
 
 	result, err = clientSession.CallTool(context.Background(), &mcp.CallToolParams{
 		Name:      "get_team_members",
 		Arguments: map[string]any{"org": "testorg", "team_slug": "testteam", "legacy_ignored_argument": true},
+		Meta:      protocolMeta,
 	})
 	require.NoError(t, err)
 	require.False(t, result.IsError)
 	structuredJSON, err = json.Marshal(result.StructuredContent)
 	require.NoError(t, err)
 	assert.JSONEq(t, `["user1","user2"]`, string(structuredJSON))
-	assert.Equal(t, string(structuredJSON), getTextResult(t, result).Text)
+	assert.JSONEq(t, string(structuredJSON), getTextResult(t, result).Text)
 	request = createMCPRequest(map[string]any{"org": "testorg", "team_slug": "testteam"})
 	legacyResult, err = teamMembersTool.Handler(deps)(ContextWithDeps(context.Background(), deps), &request)
 	require.NoError(t, err)
 	assert.Equal(t, `["user1","user2"]`, getTextResult(t, legacyResult).Text)
 	require.NoError(t, outputSchemas["get_team_members"].Validate(result.StructuredContent))
-	assert.Equal(t, 2, graphQLCalls)
+	assert.Equal(t, 4, graphQLCalls)
 
 	result, err = clientSession.CallTool(context.Background(), &mcp.CallToolParams{
 		Name:      "get_team_members",
 		Arguments: map[string]any{},
+		Meta:      protocolMeta,
 	})
 	require.NoError(t, err)
 	assert.True(t, result.IsError, "missing required arguments should be rejected by the inferred input schema")
-	assert.Equal(t, 2, graphQLCalls, "schema validation must happen before invoking the handler")
+	assert.Equal(t, 4, graphQLCalls, "schema validation must happen before invoking the handler")
 
 	result, err = clientSession.CallTool(context.Background(), &mcp.CallToolParams{
 		Name:      "get_team_members",
 		Arguments: map[string]any{"org": "", "team_slug": "testteam"},
+		Meta:      protocolMeta,
 	})
 	require.NoError(t, err)
 	assert.True(t, result.IsError, "empty required strings should remain invalid")
-	assert.Equal(t, 2, graphQLCalls, "handler validation must reject empty identifiers before acquiring GraphQL")
+	assert.Equal(t, 4, graphQLCalls, "handler validation must reject empty identifiers before acquiring GraphQL")
 
 	for _, tc := range []struct {
 		name       string
@@ -430,20 +441,20 @@ func TestContextToolsTypedRegistration(t *testing.T) {
 		require.NoError(t, err)
 		require.False(t, legacyResult.IsError)
 		assert.Equal(t, tc.text, getTextResult(t, legacyResult).Text)
-		result, err := clientSession.CallTool(context.Background(), &mcp.CallToolParams{Name: tc.name, Arguments: tc.args})
+		result, err := clientSession.CallTool(context.Background(), &mcp.CallToolParams{Name: tc.name, Arguments: tc.args, Meta: protocolMeta})
 		require.NoError(t, err)
 		require.False(t, result.IsError)
 		require.NotNil(t, result.StructuredContent, "empty successful collections must have structured content on the wire")
 		require.Len(t, result.Content, 1, "SDK fallback must not duplicate the legacy text")
 		structuredJSON, err := json.Marshal(result.StructuredContent)
 		require.NoError(t, err)
 		assert.JSONEq(t, tc.structured, string(structuredJSON))
-		assert.Equal(t, string(structuredJSON), getTextResult(t, result).Text)
+		assert.JSONEq(t, string(structuredJSON), getTextResult(t, result).Text)
 		require.NoError(t, outputSchemas[tc.name].Validate(result.StructuredContent))
 	}
 
 	failGetMe = true
-	result, err = clientSession.CallTool(context.Background(), &mcp.CallToolParams{Name: "get_me"})
+	result, err = clientSession.CallTool(context.Background(), &mcp.CallToolParams{Name: "get_me", Meta: protocolMeta})
 	require.NoError(t, err)
 	assert.True(t, result.IsError)
 	assert.Nil(t, result.StructuredContent, "handler errors must not expose a successful typed output")