fix(inventory): harden typed schema registration contracts

Cache immutable schema variants and enum overrides, preserve runtime input compatibility and request-era output behavior, and normalize dynamic scope challenges before dispatch.

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

Author: SamMorrowDrums

CONTRIBUTING.md

@@ -60,6 +60,7 @@ For UI dependency upgrades, compare all four views (`get-me`, `issue-write`, `pr
     - Update readme documentation: `script/generate-docs`
     - If renaming a tool, add a deprecation alias (see [Tool Renaming Guide](docs/tool-renaming.md))
     - For toolset and icon configuration, see [Toolsets and Icons Guide](docs/toolsets-and-icons.md)
+    - For typed tool registration and compatibility schemas, see [Typed Tool Schemas](docs/typed-tool-schemas.md)
 6. Push to your fork and [submit a pull request][pr] targeting the `main` branch
 7. Pat yourself on the back and wait for your pull request to be reviewed and merged.
 

docs/typed-tool-schemas.md

@@ -0,0 +1,54 @@
+# Typed tool schemas
+
+Typed tool registrations use concrete Go input and output types with the MCP
+Go SDK's `mcp.AddTool` path. The SDK infers schemas when the tool definition
+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.
+
+```go
+tool := github.NewToolWithSchemaOptions[workflowInput, workflowOutput](
+    toolset,
+    mcp.Tool{Name: "list_workflow_runs"},
+    scopeAccess,
+    inventory.TypedSchemaOptions{
+        InputEnums: []inventory.SchemaEnum{
+            {Path: "status", Values: github.WorkflowStatusValues()},
+        },
+    },
+    listWorkflowRuns,
+)
+```
+
+`SchemaEnum.Path` addresses inferred properties with dot-separated names and
+uses `items` to descend into array elements. `EnumSchema` creates a standalone
+string enum schema, while `WithEnum` returns a cloned explicit schema with an
+enum applied at a path. Inferred and explicit schema helpers cache immutable
+schemas; do not mutate the returned pointers.
+
+When compatibility requires a broader runtime input contract than the one
+advertised to clients, provide `ValidationInputSchema`. The tool's declared
+`InputSchema` remains visible while the SDK validates calls against the
+runtime-only schema. Use `Preflight` for checks that need raw arguments or
+request dependencies before typed decoding; it may return a derived context
+for the handler. Input normalizers are only for compatibility transformations,
+not a replacement for schema validation.
+
+The SDK applies defaults from the runtime input schema before decoding. If an
+omitted field must remain omitted, build the runtime schema with
+`inventory.CloneSchemaWithoutDefaults` before applying validation-only
+changes. The advertised schema can retain its defaults; the constructor caches
+the runtime schema without mutating either caller-owned schema.
+
+The output schema and `structuredContent` are exposed only for the exact
+protocol version `2026-07-28`. Older, absent, and unrecognized versions retain
+the legacy text result. Normal `Inventory.RegisterTools` and
+`ServerTool.RegisterFunc` registrations select behavior per request. Use
+`RegisterToolsForProtocolEra` or `RegisterFuncForProtocolEra` only when the
+protocol era is already known before server construction, such as a stateless
+request-scoped server.
+
+If a handler intentionally returns non-JSON text or content blocks, set
+`PreserveHandlerContent` in `TypedSchemaOptions`, or call
+`inventory.PreserveToolHandlerContent(ctx)` from the handler middleware for
+request-dependent output such as CSV.

pkg/context/mcp_info.go

@@ -24,6 +24,12 @@ type MCPMethodInfo struct {
 	ItemName string
 	// RawArguments contains the unmaterialized tool arguments for tools/call requests.
 	RawArguments json.RawMessage
+	// NormalizedArguments contains canonical arguments prepared by HTTP scope
+	// middleware so tool adapters do not rerun non-idempotent normalizers.
+	NormalizedArguments json.RawMessage
+	// ArgumentsNormalized distinguishes an intentionally empty normalized value
+	// from a request that has not been normalized.
+	ArgumentsNormalized bool
 	// ProtocolVersion and ClientCapabilities describe the requesting MCP client
 	// when stateless HTTP parsing makes them available before registration.
 	ProtocolVersion    string

pkg/github/csv_output.go

@@ -77,6 +77,7 @@ func csvOutputMiddleware(deps any) inventory.ToolHandlerMiddleware {
 			if csvDeps == nil || !csvDeps.IsFeatureEnabled(ctx, FeatureFlagCSVOutput) {
 				return result, err
 			}
+			inventory.PreserveToolHandlerContent(ctx)
 			return convertJSONTextResultToCSV(result), nil
 		}
 	}

pkg/github/dependencies.go

@@ -233,10 +233,31 @@ func NewTool[In, Out any](
 	handler func(ctx context.Context, deps ToolDependencies, req *mcp.CallToolRequest, args In) (*mcp.CallToolResult, Out, error),
 	inputNormalizers ...inventory.InputNormalizer,
 ) inventory.ServerTool {
-	st := inventory.NewServerToolWithContextHandler(tool, toolset, func(ctx context.Context, req *mcp.CallToolRequest, args In) (*mcp.CallToolResult, Out, error) {
+	return NewToolWithSchemaOptions(
+		toolset,
+		tool,
+		scopeAccess,
+		inventory.TypedSchemaOptions{},
+		handler,
+		inputNormalizers...,
+	)
+}
+
+// NewToolWithSchemaOptions is like NewTool, with options for schema inference,
+// runtime-only input validation schemas, and pre-decode compatibility checks.
+// The original tool schema remains the schema advertised to clients.
+func NewToolWithSchemaOptions[In, Out any](
+	toolset inventory.ToolsetMetadata,
+	tool mcp.Tool,
+	scopeAccess inventory.ScopeAccess,
+	schemaOptions inventory.TypedSchemaOptions,
+	handler func(ctx context.Context, deps ToolDependencies, req *mcp.CallToolRequest, args In) (*mcp.CallToolResult, Out, error),
+	inputNormalizers ...inventory.InputNormalizer,
+) inventory.ServerTool {
+	st := inventory.NewServerToolWithContextHandlerAndSchemaOptions(tool, toolset, func(ctx context.Context, req *mcp.CallToolRequest, args In) (*mcp.CallToolResult, Out, error) {
 		deps := MustDepsFromContext(ctx)
 		return handler(ctx, deps, req, args)
-	}, inputNormalizers...)
+	}, schemaOptions, inputNormalizers...)
 	st.ScopeAccess = scopeAccess
 	return st
 }

pkg/github/server.go

@@ -110,20 +110,23 @@ func NewMCPServer(ctx context.Context, cfg *MCPServerConfig, deps ToolDependenci
 
 	ghServer := NewServer(cfg.Version, cfg.Translator("SERVER_NAME", "github-mcp-server"), cfg.Translator("SERVER_TITLE", "GitHub MCP Server"), serverOpts)
 
-	// Add middlewares. Order matters - for example, the error context middleware should be applied last so that it runs FIRST (closest to the handler) to ensure all errors are captured,
-	// and any middleware that needs to read or modify the context should be before it.
-	ghServer.AddReceivingMiddleware(middleware...)
-	ghServer.AddReceivingMiddleware(injectFeatureStateMiddleware(inv))
-	ghServer.AddReceivingMiddleware(InjectDepsMiddleware(deps))
-	ghServer.AddReceivingMiddleware(addGitHubAPIErrorToContext)
-
 	if unrecognized := inv.UnrecognizedToolsets(); len(unrecognized) > 0 {
 		cfg.Logger.Warn("Warning: unrecognized toolsets ignored", "toolsets", strings.Join(unrecognized, ", "))
 	}
 
 	// Register GitHub tools/resources/prompts from the inventory.
 	inv.RegisterAll(ctx, ghServer, deps, cfg.ToolHandlerMiddleware...)
 
+	// Add request middleware after registering tools so it wraps the protocol
+	// adapter. Preflight and legacy typed calls then receive the same request
+	// context as modern typed calls.
+	// Middleware order matters: the error context wrapper is applied last so it
+	// runs first and can observe errors from every inner middleware.
+	ghServer.AddReceivingMiddleware(middleware...)
+	ghServer.AddReceivingMiddleware(injectFeatureStateMiddleware(inv))
+	ghServer.AddReceivingMiddleware(InjectDepsMiddleware(deps))
+	ghServer.AddReceivingMiddleware(addGitHubAPIErrorToContext)
+
 	// Register MCP App UI resources whenever the embedded UI assets are
 	// available. The resources are static HTML referenced by tools' _meta.ui
 	// block (the inventory strips that block for clients that do not support

pkg/github/server_test.go

@@ -194,6 +194,69 @@ func TestNewMCPServer_CreatesSuccessfully(t *testing.T) {
 	// is already tested in pkg/github/*_test.go.
 }
 
+func TestNewMCPServerTypedLegacyPreflightAndHandlerReceiveDependencies(t *testing.T) {
+	type output struct {
+		OK bool `json:"ok"`
+	}
+	deps := stubDeps{obsv: stubExporters()}
+	tool := NewToolWithSchemaOptions[struct{}, output](
+		inventory.ToolsetMetadata{ID: inventory.ToolsetID("test"), Description: "Test"},
+		mcp.Tool{Name: "typed_dependency_tool"},
+		inventory.ScopeAccess{},
+		inventory.TypedSchemaOptions{
+			Preflight: func(ctx context.Context, _ *mcp.CallToolRequest) (context.Context, *mcp.CallToolResult, error) {
+				if _, ok := DepsFromContext(ctx); !ok {
+					return ctx, nil, errors.New("dependencies missing in preflight")
+				}
+				return ctx, nil, nil
+			},
+		},
+		func(ctx context.Context, handlerDeps ToolDependencies, _ *mcp.CallToolRequest, _ struct{}) (*mcp.CallToolResult, output, error) {
+			if _, ok := DepsFromContext(ctx); !ok || handlerDeps == nil {
+				return nil, output{}, errors.New("dependencies missing in handler")
+			}
+			return &mcp.CallToolResult{
+				Content: []mcp.Content{&mcp.TextContent{Text: "legacy text"}},
+			}, output{OK: true}, nil
+		},
+	)
+	inv, err := inventory.NewBuilder().
+		SetTools([]inventory.ServerTool{tool}).
+		WithToolsets([]string{"all"}).
+		Build()
+	require.NoError(t, err)
+	cfg := MCPServerConfig{
+		Version:    "test",
+		Translator: translations.NullTranslationHelper,
+		Logger:     slog.New(slog.DiscardHandler),
+	}
+	server, err := NewMCPServer(context.Background(), &cfg, deps, inv)
+	require.NoError(t, err)
+
+	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: "legacy-test", Version: "1"}, nil)
+	clientSession, err := client.Connect(context.Background(), clientTransport, &mcp.ClientSessionOptions{
+		ProtocolVersion: "2025-11-25",
+	})
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = clientSession.Close() })
+
+	list, err := clientSession.ListTools(context.Background(), nil)
+	require.NoError(t, err)
+	require.Len(t, list.Tools, 1)
+	assert.Nil(t, list.Tools[0].OutputSchema)
+
+	result, err := clientSession.CallTool(context.Background(), &mcp.CallToolParams{Name: "typed_dependency_tool"})
+	require.NoError(t, err)
+	require.False(t, result.IsError)
+	assert.Nil(t, result.StructuredContent)
+	require.Len(t, result.Content, 1)
+	assert.Equal(t, "legacy text", result.Content[0].(*mcp.TextContent).Text)
+}
+
 func TestFeatureStateMiddlewareCachesHandlerChecks(t *testing.T) {
 	var calls int
 	checker := func(_ context.Context, flag string) (bool, error) {

pkg/github/workflow_enums.go

@@ -0,0 +1,50 @@
+package github
+
+import "slices"
+
+// WorkflowStatus is a GitHub Actions workflow-run status.
+type WorkflowStatus string
+
+var workflowStatusValues = []string{
+	"queued",
+	"in_progress",
+	"completed",
+	"requested",
+	"waiting",
+	"pending",
+}
+
+// Values returns the supported workflow statuses.
+func (WorkflowStatus) Values() []string {
+	return slices.Clone(workflowStatusValues)
+}
+
+// WorkflowStatusValues returns the supported workflow statuses.
+func WorkflowStatusValues() []string {
+	return (WorkflowStatus("")).Values()
+}
+
+// WorkflowConclusion is a GitHub Actions workflow-run conclusion.
+type WorkflowConclusion string
+
+var workflowConclusionValues = []string{
+	"success",
+	"failure",
+	"neutral",
+	"cancelled",
+	"skipped",
+	"timed_out",
+	"action_required",
+	"stale",
+	"startup_failure",
+}
+
+// Values returns the supported workflow conclusions.
+func (WorkflowConclusion) Values() []string {
+	return slices.Clone(workflowConclusionValues)
+}
+
+// WorkflowConclusionValues returns the supported workflow conclusions.
+func WorkflowConclusionValues() []string {
+	return (WorkflowConclusion("")).Values()
+}

pkg/http/handler_test.go

@@ -1265,21 +1265,22 @@ func TestHTTPStatelessTypedOutputProtocolHeaders(t *testing.T) {
 	)
 
 	for _, tc := range []struct {
-		name            string
-		protocolVersion string
-		wantModern      bool
+		name          string
+		headerVersion string
+		metaVersion   string
+		wantModern    bool
 	}{
-		{name: "modern header", protocolVersion: inventory.ProtocolVersionMultiRoundTrip, wantModern: true},
-		{name: "legacy header", protocolVersion: "2025-11-25"},
-		{name: "absent header"},
+		{name: "modern header and metadata", headerVersion: inventory.ProtocolVersionMultiRoundTrip, metaVersion: inventory.ProtocolVersionMultiRoundTrip, wantModern: true},
+		{name: "legacy header and metadata", headerVersion: "2025-11-25", metaVersion: "2025-11-25"},
+		{name: "absent protocol version"},
 	} {
 		t.Run(tc.name, func(t *testing.T) {
 			post := func(method string, id int) map[string]json.RawMessage {
 				t.Helper()
 				params := map[string]any{"name": "typed_http_tool", "arguments": map[string]any{}}
-				if tc.protocolVersion != "" {
+				if tc.metaVersion != "" {
 					params["_meta"] = map[string]any{
-						mcp.MetaKeyProtocolVersion:    tc.protocolVersion,
+						mcp.MetaKeyProtocolVersion:    tc.metaVersion,
 						mcp.MetaKeyClientInfo:         map[string]any{"name": "test", "version": "1.0.0"},
 						mcp.MetaKeyClientCapabilities: map[string]any{},
 					}
@@ -1298,8 +1299,8 @@ func TestHTTPStatelessTypedOutputProtocolHeaders(t *testing.T) {
 				if method == "tools/call" {
 					req.Header.Set(headers.MCPNameHeader, "typed_http_tool")
 				}
-				if tc.protocolVersion != "" {
-					req.Header.Set("MCP-Protocol-Version", tc.protocolVersion)
+				if tc.headerVersion != "" {
+					req.Header.Set(headers.MCPProtocolVersionHeader, tc.headerVersion)
 				}
 
 				recorder := httptest.NewRecorder()
@@ -1352,10 +1353,11 @@ func TestHTTPStatelessTypedOutputProtocolHeaders(t *testing.T) {
 			require.NoError(t, json.Unmarshal(callResultJSON, &called))
 			require.Len(t, called.Content, 1, "SDK fallback serialization must not duplicate the existing text")
 			assert.Equal(t, "text", called.Content[0].Type)
-			assert.Equal(t, "legacy text", called.Content[0].Text)
 			if tc.wantModern {
 				assert.JSONEq(t, `{"values":["one","two"]}`, string(called.StructuredContent))
+				assert.Equal(t, `{"values":["one","two"]}`, called.Content[0].Text)
 			} else {
+				assert.Equal(t, "legacy text", called.Content[0].Text)
 				assert.Empty(t, called.StructuredContent, "legacy and unknown protocol versions must not expose structured content")
 			}
 		})

pkg/http/headers/headers.go

@@ -39,6 +39,8 @@ const (
 
 	// MCP-specific headers.
 
+	// MCPProtocolVersionHeader carries the protocol version for HTTP MCP requests.
+	MCPProtocolVersionHeader = "MCP-Protocol-Version"
 	// MCPMethodHeader mirrors the JSON-RPC method for request routing.
 	MCPMethodHeader = "Mcp-Method"
 	// MCPNameHeader identifies the requested MCP primitive.