fix(inventory): unwrap pointer inputs before schema inference

Match SDK input inference by unwrapping one pointer level before the cached input key and inference. Preserve nullable output pointer schemas. Cover both public constructors with actual modern and legacy discovery and calls, including structured null output.

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

Author: SamMorrowDrums

docs/typed-tool-schemas.md

@@ -6,6 +6,9 @@ does not provide them, validates arguments before the handler runs, and
 validates typed output. Keep business rules that JSON Schema cannot express
 in the handler or a preflight callback.
 
+Input inference unwraps one pointer level, matching the SDK's object input
+contract. Output pointers retain nullable schemas and may return JSON null.
+
 ```go
 tool := github.NewToolWithSchemaOptions[workflowInput, workflowOutput](
     toolset,

pkg/github/dependencies_test.go

@@ -2,7 +2,9 @@ package github_test
 
 import (
 	"context"
+	"encoding/json"
 	"errors"
+	"fmt"
 	"log/slog"
 	"net/http"
 	"net/http/httptest"
@@ -14,9 +16,11 @@ import (
 	ghcontext "github.com/github/github-mcp-server/pkg/context"
 	"github.com/github/github-mcp-server/pkg/github"
 	"github.com/github/github-mcp-server/pkg/http/headers"
+	"github.com/github/github-mcp-server/pkg/inventory"
 	"github.com/github/github-mcp-server/pkg/observability"
 	"github.com/github/github-mcp-server/pkg/observability/metrics"
 	"github.com/github/github-mcp-server/pkg/translations"
+	"github.com/modelcontextprotocol/go-sdk/mcp"
 	"github.com/shurcooL/githubv4"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
@@ -27,6 +31,94 @@ func testExporters() observability.Exporters {
 	return obs
 }
 
+func TestNewToolWithSchemaOptionsPointerInputAndNullableOutput(t *testing.T) {
+	type input struct {
+		Query string `json:"query"`
+	}
+	type output struct {
+		Query string `json:"query"`
+	}
+	for _, legacy := range []bool{false, true} {
+		t.Run(fmt.Sprintf("legacy=%t", legacy), func(t *testing.T) {
+			options := &mcp.ServerOptions{}
+			if legacy {
+				options.SupportedProtocolVersions = []string{"2025-11-25"}
+			}
+			server := mcp.NewServer(&mcp.Implementation{Name: "test", Version: "1"}, options)
+			if legacy {
+				server.AddReceivingMiddleware(func(next mcp.MethodHandler) mcp.MethodHandler {
+					return func(ctx context.Context, method string, req mcp.Request) (mcp.Result, error) {
+						if method == "server/discover" {
+							return nil, errors.New("legacy initialize required")
+						}
+						return next(ctx, method, req)
+					}
+				})
+			}
+			deps := github.NewRequestDeps(newRequestDepsAPIHostResolver(t, "https://api.github.com"),
+				"test", false, nil, translations.NullTranslationHelper, 0, nil, testExporters())
+			server.AddReceivingMiddleware(github.InjectDepsMiddleware(deps))
+			tool := github.NewToolWithSchemaOptions(
+				inventory.ToolsetMetadata{ID: "test"},
+				mcp.Tool{Name: "pointer_tool"},
+				inventory.ScopeAccess{},
+				inventory.TypedSchemaOptions{},
+				func(_ context.Context, gotDeps github.ToolDependencies, _ *mcp.CallToolRequest, args *input) (*mcp.CallToolResult, *output, error) {
+					require.Same(t, deps, gotDeps)
+					require.NotNil(t, args)
+					result := &mcp.CallToolResult{Content: []mcp.Content{&mcp.TextContent{Text: args.Query}}}
+					if args.Query == "null" {
+						return result, nil, nil
+					}
+					return result, &output{Query: args.Query}, nil
+				},
+			)
+			require.NotPanics(t, func() { tool.RegisterFunc(server, deps) })
+			serverTransport, clientTransport := mcp.NewInMemoryTransports()
+			serverSession, err := server.Connect(context.Background(), serverTransport, nil)
+			require.NoError(t, err)
+			defer serverSession.Close()
+			client := mcp.NewClient(&mcp.Implementation{Name: "test-client", Version: "1"}, nil)
+			session, err := client.Connect(context.Background(), clientTransport, nil)
+			require.NoError(t, err)
+			defer session.Close()
+			if legacy {
+				assert.Equal(t, "2025-11-25", session.InitializeResult().ProtocolVersion)
+			}
+			list, err := session.ListTools(context.Background(), nil)
+			require.NoError(t, err)
+			require.Len(t, list.Tools, 1)
+			inputJSON, err := json.Marshal(list.Tools[0].InputSchema)
+			require.NoError(t, err)
+			assert.Contains(t, string(inputJSON), `"type":"object"`)
+			for _, query := range []string{"value", "null"} {
+				result, err := session.CallTool(context.Background(), &mcp.CallToolParams{
+					Name: tool.Tool.Name, Arguments: map[string]any{"query": query},
+				})
+				require.NoError(t, err)
+				require.False(t, result.IsError)
+				if legacy {
+					assert.Nil(t, list.Tools[0].OutputSchema)
+					assert.Nil(t, result.StructuredContent)
+					require.Len(t, result.Content, 1)
+					assert.Equal(t, query, result.Content[0].(*mcp.TextContent).Text)
+				} else {
+					schemaJSON, err := json.Marshal(list.Tools[0].OutputSchema)
+					require.NoError(t, err)
+					assert.Contains(t, string(schemaJSON), `"null"`)
+					valueJSON, err := json.Marshal(result.StructuredContent)
+					require.NoError(t, err)
+					if query == "null" {
+						assert.JSONEq(t, `null`, string(valueJSON))
+					} else {
+						assert.JSONEq(t, `{"query":"value"}`, string(valueJSON))
+					}
+				}
+			}
+		})
+	}
+}
+
 type requestDepsAPIHostResolver struct {
 	endpoint *url.URL
 }

pkg/inventory/typed_output_test.go

@@ -205,6 +205,54 @@ func TestProtocolEraForSupportedVersions(t *testing.T) {
 	}
 }
 
+func TestTypedPointerInputUsesObjectSchemaInBothEras(t *testing.T) {
+	type input struct {
+		Query string `json:"query"`
+	}
+	valueSchema, err := CachedInputSchemaFor[input](nil)
+	require.NoError(t, err)
+	pointerSchema, err := CachedInputSchemaFor[*input](nil)
+	require.NoError(t, err)
+	assert.Same(t, valueSchema, pointerSchema, "SDK inference unwraps one input pointer before caching")
+	assert.Equal(t, "object", pointerSchema.Type)
+	assert.Empty(t, pointerSchema.Types)
+
+	outputSchema, err := CachedSchemaFor[*input](nil)
+	require.NoError(t, err)
+	assert.Contains(t, outputSchema.Types, "null", "output pointers must retain nullability")
+
+	tool := NewServerToolWithContextHandler(
+		mcp.Tool{Name: "pointer_input"},
+		testToolsetMetadata("test"),
+		func(_ context.Context, _ *mcp.CallToolRequest, args *input) (*mcp.CallToolResult, typedTestOutput, error) {
+			require.NotNil(t, args)
+			return &mcp.CallToolResult{Content: []mcp.Content{&mcp.TextContent{Text: args.Query}}},
+				typedTestOutput{Query: args.Query}, nil
+		},
+	)
+	server := mcp.NewServer(&mcp.Implementation{Name: "test", Version: "1"}, nil)
+	require.NotPanics(t, func() { tool.RegisterFunc(server, nil) })
+	for _, version := range []string{"", "2025-11-25"} {
+		session := connectTypedTestClient(t, server, version)
+		list, err := session.ListTools(context.Background(), nil)
+		require.NoError(t, err)
+		require.Len(t, list.Tools, 1)
+		assert.Contains(t, mustMarshalJSON(t, list.Tools[0].InputSchema), `"type":"object"`)
+		result, err := session.CallTool(context.Background(), &mcp.CallToolParams{
+			Name: tool.Tool.Name, Arguments: map[string]any{"query": "pointer input decoded"},
+		})
+		require.NoError(t, err)
+		require.False(t, result.IsError)
+		if version == "" {
+			assert.JSONEq(t, `{"query":"pointer input decoded"}`, mustMarshalJSON(t, result.StructuredContent))
+		} else {
+			assert.Nil(t, result.StructuredContent)
+			require.Len(t, result.Content, 1)
+			assert.Equal(t, "pointer input decoded", result.Content[0].(*mcp.TextContent).Text)
+		}
+	}
+}
+
 func TestCachedSchemaDeepCopiesMutableMetadata(t *testing.T) {
 	constant := any(map[string]any{"nested": []string{"const"}})
 	nullConstant := any(nil)

pkg/inventory/typed_schema.go

@@ -357,6 +357,10 @@ func CachedInputSchemaFor[T any](options *jsonschema.ForOptions, enums ...Schema
 }
 
 func cachedSchemaFor(goType reflect.Type, options *jsonschema.ForOptions, enums []SchemaEnum, inputSchema bool) (*jsonschema.Schema, error) {
+	// Match SDK input inference without removing nullable output semantics.
+	if inputSchema && goType.Kind() == reflect.Pointer {
+		goType = goType.Elem()
+	}
 	optionsKey, err := schemaOptionsKey(options)
 	if err != nil {
 		return nil, err