From 4f1013f1133e5f18ccb198304e798b8820c3b01a Mon Sep 17 00:00:00 2001 From: Pranav Tomar Date: Tue, 17 Nov 2026 00:51:15 +0530 Subject: [PATCH] fix(repos): wrap get_file_contents directory listings in an object Directory results were emitted as a top-level array in structuredContent, which clients that require an object-valued structuredContent reject. Return {"entries": [...]} instead and advertise it in the output schema. Legacy-protocol text output is unchanged. Fixes #3864 --- .../__toolsnaps__/get_file_contents.snap | 156 ++++++++++-------- pkg/github/repositories.go | 5 +- pkg/github/repository_tool_types.go | 13 +- pkg/github/typed_compatibility_test.go | 9 +- pkg/github/typed_repository_outputs_test.go | 42 ++++- 5 files changed, 139 insertions(+), 86 deletions(-) diff --git a/pkg/github/__toolsnaps__/get_file_contents.snap b/pkg/github/__toolsnaps__/get_file_contents.snap index fa845c7d50..c8dbd78c0f 100644 --- a/pkg/github/__toolsnaps__/get_file_contents.snap +++ b/pkg/github/__toolsnaps__/get_file_contents.snap @@ -74,84 +74,94 @@ "type": "null" }, { - "items": { - "additionalProperties": false, - "properties": { - "download_url": { - "type": [ - "null", - "string" - ] - }, - "git_url": { - "type": [ - "null", - "string" - ] - }, - "html_url": { - "type": [ - "null", - "string" - ] - }, - "name": { - "type": [ - "null", - "string" - ] - }, - "path": { - "type": [ - "null", - "string" - ] - }, - "sha": { - "type": [ - "null", - "string" - ] - }, - "size": { - "description": "File size in bytes.", - "type": [ - "null", - "integer" - ] - }, - "submodule_git_url": { - "description": "Git remote URL for a submodule.", - "type": [ - "null", - "string" - ] - }, - "target": { - "type": [ - "null", - "string" - ] - }, - "type": { + "additionalProperties": false, + "properties": { + "entries": { + "description": "Entries in the directory.", + "items": { + "additionalProperties": false, + "properties": { + "download_url": { + "type": [ + "null", + "string" + ] + }, + "git_url": { + "type": [ + "null", + "string" + ] + }, + "html_url": { + "type": [ + "null", + "string" + ] + }, + "name": { + "type": [ + "null", + "string" + ] + }, + "path": { + "type": [ + "null", + "string" + ] + }, + "sha": { + "type": [ + "null", + "string" + ] + }, + "size": { + "description": "File size in bytes.", + "type": [ + "null", + "integer" + ] + }, + "submodule_git_url": { + "description": "Git remote URL for a submodule.", + "type": [ + "null", + "string" + ] + }, + "target": { + "type": [ + "null", + "string" + ] + }, + "type": { + "type": [ + "null", + "string" + ] + }, + "url": { + "type": [ + "null", + "string" + ] + } + }, "type": [ "null", - "string" + "object" ] }, - "url": { - "type": [ - "null", - "string" - ] - } - }, - "type": [ - "null", - "object" - ] + "type": "array" + } }, - "type": "array" + "required": [ + "entries" + ], + "type": "object" }, { "additionalProperties": false, diff --git a/pkg/github/repositories.go b/pkg/github/repositories.go index b884f4888d..aad2fe3b9f 100644 --- a/pkg/github/repositories.go +++ b/pkg/github/repositories.go @@ -1210,6 +1210,9 @@ func GetFileContents(t translations.TranslationHelperFunc) inventory.ServerTool if err := json.Unmarshal(r, &output); err != nil { return nil, nil, fmt.Errorf("failed to decode typed directory contents: %w", err) } + if output == nil { + output = []*RepositoryDirectoryEntryOutput{} + } if len(fields) == 0 { for _, entry := range output { if entry != nil { @@ -1217,7 +1220,7 @@ func GetFileContents(t translations.TranslationHelperFunc) inventory.ServerTool } } } - return attachIFC(utils.NewToolResultText(string(r))), &RepositoryContentsOutput{Directory: output}, nil + return attachIFC(utils.NewToolResultText(string(r))), &RepositoryContentsOutput{Directory: &RepositoryDirectoryOutput{Entries: output}}, nil } return utils.NewToolResultError("failed to get file contents"), nil, nil diff --git a/pkg/github/repository_tool_types.go b/pkg/github/repository_tool_types.go index 4f3b584983..e9acb89b6c 100644 --- a/pkg/github/repository_tool_types.go +++ b/pkg/github/repository_tool_types.go @@ -215,10 +215,17 @@ func (out ForkRepositoryOutput) MarshalJSON() ([]byte, error) { // MCP content response. The latter is represented losslessly as typed content // blocks, including the human-readable status and embedded text/blob or link. type RepositoryContentsOutput struct { - Directory []*RepositoryDirectoryEntryOutput + Directory *RepositoryDirectoryOutput Content *RepositoryContentOutput } +// RepositoryDirectoryOutput wraps a directory listing in an object so that +// structured content is always object-valued. Some MCP clients reject a +// top-level array in structuredContent. +type RepositoryDirectoryOutput struct { + Entries []*RepositoryDirectoryEntryOutput `json:"entries" jsonschema:"Entries in the directory."` +} + // Optional pointer fields retain projected zero values without reinstating // omitted fields. API URLs are included only when explicitly projected. type RepositoryDirectoryEntryOutput struct { @@ -536,7 +543,7 @@ func repositoryContentsOutputSchema() *jsonschema.Schema { Required: []string{"content"}, AdditionalProperties: &jsonschema.Schema{Not: &jsonschema.Schema{}}, } - directory := repositoryOutputSchema[[]*RepositoryDirectoryEntryOutput]() - directory.Type, directory.Types = "array", nil + directory := repositoryOutputSchema[RepositoryDirectoryOutput]() + directory.Properties["entries"].Type, directory.Properties["entries"].Types = "array", nil return repositoryUnionSchema(&jsonschema.Schema{Type: "null"}, directory, content) } diff --git a/pkg/github/typed_compatibility_test.go b/pkg/github/typed_compatibility_test.go index d1e68a6b1f..87a77e840b 100644 --- a/pkg/github/typed_compatibility_test.go +++ b/pkg/github/typed_compatibility_test.go @@ -264,7 +264,14 @@ func TestTypedCompatibilityDirectoryProjection(t *testing.T) { }) require.NoError(t, err) require.False(t, result.IsError) - assert.JSONEq(t, `[{"url":"api-content-url","git_url":"api-git-url"}]`, getTextResult(t, result).Text) + entries := `[{"url":"api-content-url","git_url":"api-git-url"}]` + if protocol == inventory.ProtocolVersionMultiRoundTrip { + // Modern text mirrors the object-valued structured content. + assert.JSONEq(t, `{"entries":`+entries+`}`, getTextResult(t, result).Text) + assert.JSONEq(t, `{"entries":`+entries+`}`, mustMarshalJSON(t, result.StructuredContent)) + continue + } + assert.JSONEq(t, entries, getTextResult(t, result).Text) } } diff --git a/pkg/github/typed_repository_outputs_test.go b/pkg/github/typed_repository_outputs_test.go index 672837c711..d6c997cee0 100644 --- a/pkg/github/typed_repository_outputs_test.go +++ b/pkg/github/typed_repository_outputs_test.go @@ -371,22 +371,31 @@ func TestTypedRepositoryOutputs(t *testing.T) { require.NoError(t, json.Unmarshal([]byte(mustMarshalJSON(t, result.StructuredContent)), &output)) require.NoError(t, schemas[call.name].Validate(output)) first := result.Content[0].(*mcp.TextContent).Text + isDirectory := strings.HasSuffix(fmt.Sprint(call.args["path"]), "directory") switch { - case call.name == "get_file_contents" && !strings.HasPrefix(first, "["): + case call.name == "get_file_contents" && !isDirectory: assert.JSONEq(t, `{"content":`+mustMarshalJSON(t, legacy.Content)+`}`, mustMarshalJSON(t, result.StructuredContent)) case call.name == "get_file_contents": - var entries []*RepositoryDirectoryEntryOutput - require.NoError(t, json.Unmarshal([]byte(first), &entries)) - assert.JSONEq(t, mustMarshalJSON(t, entries), mustMarshalJSON(t, result.StructuredContent)) + // Object-only clients decode structuredContent as a JSON object. + var object map[string]json.RawMessage + require.NoError(t, json.Unmarshal([]byte(mustMarshalJSON(t, result.StructuredContent)), &object), + "directory structured content must be an object") + var directory RepositoryDirectoryOutput + require.NoError(t, json.Unmarshal([]byte(first), &directory)) + require.NotNil(t, directory.Entries, "entries is always an array") + assert.JSONEq(t, mustMarshalJSON(t, directory), mustMarshalJSON(t, result.StructuredContent)) if call.args["fields"] == nil { assert.NotContains(t, mustMarshalJSON(t, result.StructuredContent), "api-content-url") } assert.NotContains(t, mustMarshalJSON(t, result.StructuredContent), "api-git-url") if call.args["path"] == "submodule-directory" { - assert.JSONEq(t, `[{"name":"lib","path":"lib","type":"file","sha":"sha","submodule_git_url":"https://github.com/owner/lib.git"}]`, mustMarshalJSON(t, result.StructuredContent)) + assert.JSONEq(t, `{"entries":[{"name":"lib","path":"lib","type":"file","sha":"sha","submodule_git_url":"https://github.com/owner/lib.git"}]}`, mustMarshalJSON(t, result.StructuredContent)) + } + if call.args["path"] == "empty-directory" { + assert.JSONEq(t, `{"entries":[]}`, mustMarshalJSON(t, result.StructuredContent)) } if call.args["path"] == "directory" && call.args["fields"] != nil && len(call.args["fields"].([]any)) == 3 { - assert.JSONEq(t, `[{"size":0,"html_url":"https://github.com/owner/repo/blob/main/file","url":"api-content-url"}]`, mustMarshalJSON(t, result.StructuredContent)) + assert.JSONEq(t, `{"entries":[{"size":0,"html_url":"https://github.com/owner/repo/blob/main/file","url":"api-content-url"}]}`, mustMarshalJSON(t, result.StructuredContent)) } case call.name == "create_branch" || call.name == "push_files": assert.JSONEq(t, `{"ref":"refs/heads/main","object":{"type":"commit","sha":"base"}}`, mustMarshalJSON(t, result.StructuredContent)) @@ -468,6 +477,9 @@ func assertLegacyRepositoryText(t *testing.T, name string, args map[string]any, assert.Equal(t, `{"firstPage":0,"items":[{"login":"octo","id":1,"role_name":"write"}],"lastPage":0,"nextPage":3,"prevPage":0}`, getTextResult(t, result).Text) } case "get_file_contents": + if strings.HasSuffix(fmt.Sprint(args["path"]), "directory") { + assert.True(t, strings.HasPrefix(getTextResult(t, result).Text, "["), "legacy directory text remains a JSON array") + } fields, ok := args["fields"].([]any) if args["path"] == "directory" && ok && len(fields) == 3 { assert.Equal(t, `[{"html_url":"https://github.com/owner/repo/blob/main/file","size":0,"url":"api-content-url"}]`, getTextResult(t, result).Text) @@ -544,11 +556,12 @@ func TestRepositoryOutputUnions(t *testing.T) { }, { "contents", repositoryContentsOutputSchema(), - []string{`null`, `[]`, `[{"name":"file"}]`, `{"content":[]}`, `{"content":[{"type":"text","text":"status"}]}`, + []string{`null`, `{"entries":[]}`, `{"entries":[{"name":"file"}]}`, `{"content":[]}`, `{"content":[{"type":"text","text":"status"}]}`, `{"content":[{"type":"resource","resource":{"uri":"repo://file","mimeType":"text/plain"}}]}`, `{"content":[{"type":"resource","resource":{"uri":"repo://file","blob":"AAEC"}}]}`, `{"content":[{"type":"resource_link","uri":"repo://file","name":"file","size":1048576}]}`}, - []string{`{}`, `{"content":[{"type":"text"}]}`, `{"content":[{"type":"resource","resource":{"uri":"repo://file","text":"x","blob":"AA=="}}]}`, + []string{`{}`, `[]`, `[{"name":"file"}]`, `{"entries":null}`, `{"entries":[],"content":[]}`, + `{"content":[{"type":"text"}]}`, `{"content":[{"type":"resource","resource":{"uri":"repo://file","text":"x","blob":"AA=="}}]}`, `{"content":[{"type":"opaque","data":{}}]}`}, }, } { @@ -569,6 +582,19 @@ func TestRepositoryOutputUnions(t *testing.T) { } } +// Regression test for #3864: clients that require structuredContent to be an +// object must accept every non-null get_file_contents output variant. +func TestRepositoryContentsOutputSchemaIsObjectValued(t *testing.T) { + schema := repositoryContentsOutputSchema() + require.NotEmpty(t, schema.OneOf) + for _, variant := range schema.OneOf { + if variant.Type == "null" { + continue + } + assert.Equal(t, "object", variant.Type, mustMarshalJSON(t, variant)) + } +} + func TestRepositoryPaginationCompatibility(t *testing.T) { for _, raw := range []string{`{}`, `{"page":0,"perPage":0}`, `{"page":"0","perPage":"0"}`} { normalized, err := normalizeRepositoryArguments(json.RawMessage(raw))