Skip to content
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -1466,7 +1466,7 @@ For negotiated supported protocol versions `2026-07-28` or newer, the consolidat

- **get_file_contents** - Get file or directory contents
- **OAuth Challenge Scopes**: `repo`
- `fields`: Subset of fields to return for each entry when the path is a directory. If omitted, all fields are returned. Ignored when the path is a single file. Use this to reduce response size when listing directories and you only need specific fields, e.g. just 'name' and 'type'. (string[], optional)
- `fields`: Subset of fields to return for each entry when the path is a directory. 'download_url' is omitted by default; request it explicitly in 'fields' when needed. Ignored when the path is a single file. Use this to reduce response size when listing directories and you only need specific fields, e.g. just 'name' and 'type'. (string[], optional)
- `owner`: Repository owner (username or organization) (string, required)
- `path`: Path to file/directory (string, optional)
- `ref`: Accepts optional git refs such as `refs/tags/{tag}`, `refs/heads/{branch}` or `refs/pull/{pr_number}/head` (string, optional)
Expand Down
2 changes: 1 addition & 1 deletion pkg/github/__toolsnaps__/get_file_contents.snap
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@
"inputSchema": {
"properties": {
"fields": {
"description": "Subset of fields to return for each entry when the path is a directory. If omitted, all fields are returned. Ignored when the path is a single file. Use this to reduce response size when listing directories and you only need specific fields, e.g. just 'name' and 'type'.",
"description": "Subset of fields to return for each entry when the path is a directory. 'download_url' is omitted by default; request it explicitly in 'fields' when needed. Ignored when the path is a single file. Use this to reduce response size when listing directories and you only need specific fields, e.g. just 'name' and 'type'.",
"items": {
"enum": [
"type",
Expand Down
21 changes: 19 additions & 2 deletions pkg/github/repositories.go
Original file line number Diff line number Diff line change
Expand Up @@ -1007,7 +1007,7 @@ func GetFileContents(t translations.TranslationHelperFunc) inventory.ServerTool
Required: []string{"owner", "repo"},
}
schema.Properties["fields"] = fieldsSchemaProperty(
"Subset of fields to return for each entry when the path is a directory. If omitted, all fields are returned. Ignored when the path is a single file. Use this to reduce response size when listing directories and you only need specific fields, e.g. just 'name' and 'type'.",
"Subset of fields to return for each entry when the path is a directory. 'download_url' is omitted by default; request it explicitly in 'fields' when needed. Ignored when the path is a single file. Use this to reduce response size when listing directories and you only need specific fields, e.g. just 'name' and 'type'.",
fileContentFieldEnum,
)

Expand Down Expand Up @@ -1192,14 +1192,16 @@ func GetFileContents(t translations.TranslationHelperFunc) inventory.ServerTool
} else if dirContent != nil {
// file content or file SHA is nil which means it's a directory
filtered := false
var payload any = dirContent
var payload any
if len(fields) > 0 {
filteredEntries, err := filterEachField(dirContent, fields)
if err != nil {
return utils.NewToolResultErrorFromErr("failed to filter directory contents", err), nil, nil
}
payload = filteredEntries
filtered = true
} else {
payload = cloneDirectoryEntriesWithoutDownloadURLs(dirContent)
Comment on lines +1203 to +1204
}
r, err := json.Marshal(payload)
if err != nil {
Expand All @@ -1226,6 +1228,21 @@ func GetFileContents(t translations.TranslationHelperFunc) inventory.ServerTool
)
}

// cloneDirectoryEntriesWithoutDownloadURLs returns directory entries without
// download URLs while leaving the API response untouched.
func cloneDirectoryEntriesWithoutDownloadURLs(entries []*github.RepositoryContent) []*github.RepositoryContent {
cloned := make([]*github.RepositoryContent, len(entries))
for i, entry := range entries {
if entry == nil {
continue
}
entryCopy := *entry
entryCopy.DownloadURL = nil
cloned[i] = &entryCopy
}
return cloned
}

// recordDirContentsFieldsUsage emits fields telemetry for a get_file_contents
// directory listing. sentBytes is the size of the payload actually returned.
func recordDirContentsFieldsUsage(ctx context.Context, deps ToolDependencies, full []*github.RepositoryContent, filtered bool, sentBytes int) {
Expand Down
47 changes: 47 additions & 0 deletions pkg/github/repositories_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -925,6 +925,53 @@ func Test_GetFileContents_DirectoryFieldFiltering(t *testing.T) {
assert.NotContains(t, textContent.Text, "download_url")
}

// Test_GetFileContents_DirectoryOmitsDownloadURLByDefault verifies that directory
// listings omit bearer-token URLs from the model-visible text by default.
func Test_GetFileContents_DirectoryOmitsDownloadURLByDefault(t *testing.T) {
const tokenizedURL = "https://raw.githubusercontent.com/owner/private-repo/main/.env.example?token=GHSAT0AAAAA_SECRET_TOKEN" //nolint:gosec // G101: Synthetic tokenized download URL fixture verifies default omission; it cannot authenticate.
result, requests := runRepositoryReadFixture(t, repositoryReadFixture{
contents: []*github.RepositoryContent{{
Type: new("file"),
Name: new(".env.example"),
Path: new(".env.example"),
SHA: new("abc123"),
Size: new(42),
HTMLURL: new("https://github.com/owner/private-repo/blob/main/.env.example"),
DownloadURL: new(tokenizedURL),
}},
}, map[string]any{
"owner": "owner",
"repo": "private-repo",
"path": "src/",
"sha": strings.Repeat("a", 40),
})

require.False(t, result.IsError)
assert.Equal(t, 1, requests)
textContent := getTextResult(t, result)
assert.NotContains(t, textContent.Text, "download_url")
assert.NotContains(t, textContent.Text, "GHSAT0AAAAA_SECRET_TOKEN")
assert.Contains(t, textContent.Text, ".env.example")
assert.Contains(t, textContent.Text, "html_url")
}

func TestCloneDirectoryEntriesWithoutDownloadURLs(t *testing.T) {
const tokenizedURL = "https://raw.githubusercontent.com/owner/private-repo/main/.env.example?token=GHSAT0AAAAA_SECRET_TOKEN" //nolint:gosec // G101: Synthetic tokenized download URL fixture verifies default omission; it cannot authenticate.
entry := &github.RepositoryContent{Name: new(".env.example"), DownloadURL: new(tokenizedURL)}
original := []*github.RepositoryContent{entry, nil}

cloned := cloneDirectoryEntriesWithoutDownloadURLs(original)

require.Len(t, cloned, 2)
require.NotNil(t, cloned[0])
assert.NotSame(t, entry, cloned[0])
assert.Nil(t, cloned[0].DownloadURL)
assert.Equal(t, ".env.example", cloned[0].GetName())
assert.Nil(t, cloned[1])
require.NotNil(t, entry.DownloadURL)
assert.Equal(t, tokenizedURL, *entry.DownloadURL)
}

func Test_GetFileContents_DirectoryFieldsTelemetry(t *testing.T) {
mockDirContent := []*github.RepositoryContent{
{
Expand Down
36 changes: 36 additions & 0 deletions pkg/github/typed_compatibility_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -268,6 +268,42 @@ func TestTypedCompatibilityDirectoryProjection(t *testing.T) {
}
}

// TestTypedCompatibilityDirectoryDownloadURL verifies that download URLs are
// omitted from default directory listings across protocols and remain opt-in.
func TestTypedCompatibilityDirectoryDownloadURL(t *testing.T) {
tool := GetFileContents(translations.NullTranslationHelper)
for _, protocol := range []string{"2025-11-25", inventory.ProtocolVersionMultiRoundTrip} {
t.Run(protocol+"/default", func(t *testing.T) {
session := connectTypedSearchClient(t, tool, typedRepositoryDeps(t), protocol)
result, err := session.CallTool(context.Background(), &mcp.CallToolParams{
Name: tool.Tool.Name, Arguments: map[string]any{"owner": "owner", "repo": "repo", "path": "directory"},
})
require.NoError(t, err)
require.False(t, result.IsError)
assert.NotContains(t, getTextResult(t, result).Text, "download_url")
if protocol == inventory.ProtocolVersionMultiRoundTrip {
require.NotNil(t, result.StructuredContent)
assert.NotContains(t, mustMarshalJSON(t, result.StructuredContent), "download_url")
}
})
t.Run(protocol+"/explicit opt-in", func(t *testing.T) {
session := connectTypedSearchClient(t, tool, typedRepositoryDeps(t), protocol)
result, err := session.CallTool(context.Background(), &mcp.CallToolParams{
Name: tool.Tool.Name, Arguments: map[string]any{
"owner": "owner", "repo": "repo", "path": "directory", "fields": []string{"download_url"},
},
})
require.NoError(t, err)
require.False(t, result.IsError)
assert.JSONEq(t, `[{"download_url":"https://raw.githubusercontent.com/owner/repo/main/file"}]`, getTextResult(t, result).Text)
if protocol == inventory.ProtocolVersionMultiRoundTrip {
require.NotNil(t, result.StructuredContent)
assert.Contains(t, mustMarshalJSON(t, result.StructuredContent), "download_url")
}
})
}
}

func TestTypedCompatibilityBlameIFC(t *testing.T) {
for _, private := range []bool{false, true} {
for _, protocol := range []string{"2025-11-25", inventory.ProtocolVersionMultiRoundTrip} {
Expand Down