From 5fb422026daacb5a7ec87c685f584b981e3e867f Mon Sep 17 00:00:00 2001 From: qiansc Date: Wed, 11 Nov 2026 19:38:27 +0800 Subject: [PATCH 1/2] fix(mcp): publish portable nullable schemas and reject null file batches Replace inferred multi-type arrays with single-type anyOf branches for all MCP inputs, including nested read_many ranges. Preserve optional nulls, plugin defaults versus explicit empty lists, and existing validation bounds. Require read_many.files to be a non-null array of 1-10 entries. Previously null passed schema validation and failed in the service; it now returns an MCP input-validation tool error before execution. Error text/code at that boundary changes, but null never represented a successful batch operation. Per-item range validation and partial success remain in the service. Add discovery coverage for all 10 tools, schema validation cases and HTTP MCP calls verifying legacy optional-value behavior. Document the contract. --- docs/interfaces.md | 7 + internal/mcpserver/inputs.go | 30 ++++ internal/mcpserver/schema_portability_test.go | 129 ++++++++++++++++++ 3 files changed, 166 insertions(+) create mode 100644 internal/mcpserver/schema_portability_test.go diff --git a/docs/interfaces.md b/docs/interfaces.md index 5fa5658..dc821d2 100644 --- a/docs/interfaces.md +++ b/docs/interfaces.md @@ -151,3 +151,10 @@ HTTP availability includes bounded historical `job_failures` summaries; see [dia `repository_defaults.git_timeout_minutes` sets the global default (15 minutes initially); valid global values are 15, 30, 45 and 60. Existing settings without this field read as 15. An older settings client that omits the field preserves its saved value. Registration and repository update accept `git_timeout_minutes`: 0 means inherit the current global value, and 15/30/45/60 set an override. Omitted registration values inherit; omitted PATCH values preserve the current setting. Repository details return the stored value. Preview/CAS and registration idempotency include the timeout. Only new tasks use edits; changing a timeout preserves running tasks and published indexes. The setting covers Git fetching and hydration and can be changed from system settings, registration, or repository settings. + + +### Input schema and optional values + +MCP input schemas express nullable fields using `anyOf` with single-type branches. Optional line bounds and array filters accept omission or `null` with their existing defaults. For `read` and `read_many`, omitted or `null` `plugins` uses connection defaults; `plugins: []` disables enhancements. + +`read_many.files` is required and must be an array of 1–10 items; missing, `null` and empty batches fail MCP input validation before execution. Per-file range checks remain in the service, so an invalid range does not suppress other files in the batch. Clients should inspect `isError` rather than depend on the text of schema-validation errors. diff --git a/internal/mcpserver/inputs.go b/internal/mcpserver/inputs.go index ae87dfd..ef4ab1e 100644 --- a/internal/mcpserver/inputs.go +++ b/internal/mcpserver/inputs.go @@ -122,6 +122,7 @@ func inputSchema[In any](name string) *jsonschema.Schema { } if name == "read_many" { files := schema.Properties["files"] + files.Type, files.Types = "array", nil // Required batch; null is not a file list. files.MinItems, files.MaxItems = ptr(1), ptr(10) // Per-item ranges are validated by the shared service so one bad file // does not suppress valid evidence from other items in the batch. @@ -132,6 +133,35 @@ func inputSchema[In any](name string) *jsonschema.Schema { key.MinLength, key.MaxLength = ptr(1), ptr(128) key.Pattern = `^[^\r\n\x00]+$` } + portableInferredSchema(schema) return schema } func ptr[T any](v T) *T { return &v } + +// portableInferredSchema rewrites the nullable types produced by jsonschema.For +// into single-type anyOf branches. Keep constraints inside each branch so clients +// can discover array items and numeric bounds alongside their type. Walk the +// struct, slice and map shapes inferred from our input types (no custom schemas). +func portableInferredSchema(s *jsonschema.Schema) { + if s == nil { + return + } + for _, child := range s.Properties { + portableInferredSchema(child) + } + portableInferredSchema(s.Items) + portableInferredSchema(s.AdditionalProperties) + if len(s.Types) == 0 { + return + } + types := s.Types + s.Types = nil + branches := make([]*jsonschema.Schema, 0, len(types)) + for _, typ := range types { + branch := s.CloneSchemas() + branch.Type = typ + branch.Description = "" + branches = append(branches, branch) + } + *s = jsonschema.Schema{Description: s.Description, AnyOf: branches} +} diff --git a/internal/mcpserver/schema_portability_test.go b/internal/mcpserver/schema_portability_test.go new file mode 100644 index 0000000..6c7c7c4 --- /dev/null +++ b/internal/mcpserver/schema_portability_test.go @@ -0,0 +1,129 @@ +package mcpserver + +import ( + "context" + "encoding/json" + "net/http" + "testing" + + "github.com/google/jsonschema-go/jsonschema" + "github.com/modelcontextprotocol/go-sdk/mcp" +) + +func TestAllToolSchemasPortable(t *testing.T) { + session, ctx := connectTest(t, New(nil)) + list, err := session.ListTools(ctx, nil) + if err != nil { + t.Fatal(err) + } + if len(list.Tools) != 10 { + t.Fatalf("audit new tools: got %d", len(list.Tools)) + } + for _, tool := range list.Tools { + t.Run(tool.Name, func(t *testing.T) { + data, err := json.Marshal(tool.InputSchema) + if err != nil { + t.Fatal(err) + } + var raw any + if err := json.Unmarshal(data, &raw); err != nil { + t.Fatal(err) + } + var walk func(any) + walk = func(v any) { + switch v := v.(type) { + case map[string]any: + if _, ok := v["type"].([]any); ok { + t.Errorf("array type in %s", data) + } + for _, child := range v { + walk(child) + } + case []any: + for _, child := range v { + walk(child) + } + } + } + walk(raw) + var schema jsonschema.Schema + if err := json.Unmarshal(data, &schema); err != nil { + t.Fatal(err) + } + if _, err := schema.Resolve(nil); err != nil { + t.Fatal(err) + } + }) + } +} + +func TestPortableSchemaValidation(t *testing.T) { + for _, tc := range []struct { + name string + schema *jsonschema.Schema + raw string + valid bool + }{ + {"read omitted", inputSchema[readInput]("read"), `{"repo":"org/repo","path":"a"}`, true}, + {"read null", inputSchema[readInput]("read"), `{"repo":"org/repo","path":"a","start_line":null,"end_line":null,"plugins":null}`, true}, + {"read zero", inputSchema[readInput]("read"), `{"repo":"org/repo","path":"a","start_line":0}`, false}, + {"read wrong type", inputSchema[readInput]("read"), `{"repo":"org/repo","path":"a","end_line":"2"}`, false}, + {"plugins empty", inputSchema[readInput]("read"), `{"repo":"org/repo","path":"a","plugins":[]}`, true}, + {"search null", inputSchema[searchInput]("search"), `{"repo":"org/repo","pattern":"x","paths":null,"glob":null}`, true}, + {"search bad items", inputSchema[searchInput]("search"), `{"repo":"org/repo","pattern":"x","paths":[1]}`, false}, + {"diff null", inputSchema[diffInput]("diff"), `{"repo":"org/repo","base":"a","head":"b","first":1,"paths":null}`, true}, + {"diff bound", inputSchema[diffInput]("diff"), `{"repo":"org/repo","base":"a","head":"b","first":101}`, false}, + {"batch missing", inputSchema[readManyInput]("read_many"), `{"repo":"org/repo"}`, false}, + {"batch null", inputSchema[readManyInput]("read_many"), `{"repo":"org/repo","files":null}`, false}, + {"batch empty", inputSchema[readManyInput]("read_many"), `{"repo":"org/repo","files":[]}`, false}, + {"batch nested null", inputSchema[readManyInput]("read_many"), `{"repo":"org/repo","files":[{"path":"a","start_line":null}]}`, true}, + {"batch per item validation", inputSchema[readManyInput]("read_many"), `{"repo":"org/repo","files":[{"path":"a","start_line":0},{"path":"b"}]}`, true}, + } { + t.Run(tc.name, func(t *testing.T) { + resolved, err := tc.schema.Resolve(nil) + if err != nil { + t.Fatal(err) + } + var args any + if err := json.Unmarshal([]byte(tc.raw), &args); err != nil { + t.Fatal(err) + } + err = resolved.Validate(args) + if (err == nil) != tc.valid { + t.Fatalf("valid=%v: %v", tc.valid, err) + } + }) + } +} + +func TestPortableSchemaWireNullAndEmpty(t *testing.T) { + server := mcp.NewServer(&mcp.Implementation{Name: "test", Version: "1"}, nil) + var received []readInput + register(server, "read", "test", func(_ context.Context, in readInput) (any, error) { + received = append(received, in) + return map[string]any{}, nil + }) + batchCalls := 0 + register(server, "read_many", "test", func(_ context.Context, in readManyInput) (any, error) { batchCalls++; return map[string]any{}, nil }) + session, ctx := connectTest(t, mcp.NewStreamableHTTPHandler(func(*http.Request) *mcp.Server { return server }, nil)) + for _, raw := range []string{ + `{"repo":"org/repo","path":"a"}`, + `{"repo":"org/repo","path":"a","plugins":null,"start_line":null}`, + `{"repo":"org/repo","path":"a","plugins":[],"start_line":2}`, + } { + result, err := session.CallTool(ctx, &mcp.CallToolParams{Name: "read", Arguments: json.RawMessage(raw)}) + if err != nil { + t.Fatal(err) + } + if result.IsError { + t.Fatalf("unexpected tool error: %+v", result) + } + } + if len(received) != 3 || received[0].Plugins != nil || received[1].Plugins != nil || received[2].Plugins == nil || received[1].StartLine != nil || *received[2].StartLine != 2 { + t.Fatalf("changed defaults: %+v", received) + } + result, err := session.CallTool(ctx, &mcp.CallToolParams{Name: "read_many", Arguments: json.RawMessage(`{"repo":"org/repo","files":null}`)}) + if err != nil || result == nil || !result.IsError || batchCalls != 0 { + t.Fatalf("null batch reached handler: calls=%d err=%v", batchCalls, err) + } +} From 099c03c9ed70b395f00bc443c03675eb36440d91 Mon Sep 17 00:00:00 2001 From: qiansc Date: Wed, 11 Nov 2026 19:50:55 +0800 Subject: [PATCH 2/2] feat(mcp): portable input schemas Keep null branches type-only and assert this for every advertised tool. Give the input contract its own documentation section. Valid input semantics remain unchanged; null file batches fail before execution. --- docs/interfaces.md | 3 +-- internal/mcpserver/inputs.go | 4 ++++ internal/mcpserver/schema_portability_test.go | 3 +++ 3 files changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/interfaces.md b/docs/interfaces.md index dc821d2..48ca179 100644 --- a/docs/interfaces.md +++ b/docs/interfaces.md @@ -152,8 +152,7 @@ HTTP availability includes bounded historical `job_failures` summaries; see [dia Registration and repository update accept `git_timeout_minutes`: 0 means inherit the current global value, and 15/30/45/60 set an override. Omitted registration values inherit; omitted PATCH values preserve the current setting. Repository details return the stored value. Preview/CAS and registration idempotency include the timeout. Only new tasks use edits; changing a timeout preserves running tasks and published indexes. The setting covers Git fetching and hydration and can be changed from system settings, registration, or repository settings. - -### Input schema and optional values +## Input schema and optional values MCP input schemas express nullable fields using `anyOf` with single-type branches. Optional line bounds and array filters accept omission or `null` with their existing defaults. For `read` and `read_many`, omitted or `null` `plugins` uses connection defaults; `plugins: []` disables enhancements. diff --git a/internal/mcpserver/inputs.go b/internal/mcpserver/inputs.go index ef4ab1e..a623355 100644 --- a/internal/mcpserver/inputs.go +++ b/internal/mcpserver/inputs.go @@ -158,6 +158,10 @@ func portableInferredSchema(s *jsonschema.Schema) { s.Types = nil branches := make([]*jsonschema.Schema, 0, len(types)) for _, typ := range types { + if typ == "null" { + branches = append(branches, &jsonschema.Schema{Type: "null"}) + continue + } branch := s.CloneSchemas() branch.Type = typ branch.Description = "" diff --git a/internal/mcpserver/schema_portability_test.go b/internal/mcpserver/schema_portability_test.go index 6c7c7c4..36a54bc 100644 --- a/internal/mcpserver/schema_portability_test.go +++ b/internal/mcpserver/schema_portability_test.go @@ -33,6 +33,9 @@ func TestAllToolSchemasPortable(t *testing.T) { walk = func(v any) { switch v := v.(type) { case map[string]any: + if typ, ok := v["type"].(string); ok && typ == "null" && len(v) != 1 { + t.Errorf("null branch contains extra keywords: %v", v) + } if _, ok := v["type"].([]any); ok { t.Errorf("array type in %s", data) }