address feedback

Author: kerobbi

README.md

@@ -620,9 +620,9 @@ Repository tools expose output schemas and typed `structuredContent` when the ne
 
 For `get_file_contents`, directory results (including field projections) are structured arrays. File downloads and metadata-only responses use a `content` array of typed text, embedded-resource, or resource-link blocks, preserving status messages, text, base64 blobs, empty files, and download links. Text-only repository mutations such as starring and deletion also return a structured `message`; fork responses distinguish a repository reference from an in-progress message. Repository deletion still requires its existing confirmation flow before returning a completed result.
 
-Structured repository results use compact DTOs rather than raw REST objects. Release lookups share the compact release shape with release listings; Git references retain the ref, object type, and SHA; annotated tags retain tag/message/tagger/target information; deletion commits retain SHA, message, authors, tree SHA, parent SHAs, and a human-facing `html_url` when available. Directory entries retain file metadata and useful HTML/download links, but omit API and hypermedia routing URLs even when those fields were requested in a projection. Legacy and unknown protocol versions retain the original text byte-for-byte; modern text-only JSON responses serialize the same compact DTO as `structuredContent`. Non-text resource blocks and tool errors retain their existing content behavior. Structured projections use the same sanitized and filtered source as the legacy formatter.
+Structured repository results use compact DTOs rather than raw REST objects. Release lookups share the compact release shape with release listings; Git references retain the ref, object type, and SHA; annotated tags retain tag/message/tagger/target information; deletion commits retain SHA, message, authors, tree SHA, parent SHAs, and a human-facing `html_url` when available. Directory entries retain file metadata and useful HTML/download links; API URLs are omitted by default but retained when explicitly selected. Legacy and unknown protocol versions retain the original text byte-for-byte; modern text-only JSON responses serialize the same compact DTO as `structuredContent`. Non-text resource blocks and tool errors retain their existing content behavior. Structured projections use the same sanitized and filtered source as the legacy formatter.
 
-For `get_repository_tree`, `list_gists`, `get_gist`, `create_gist`, and `update_gist`, gist results retain file names, contents, sizes, language/type information, timestamps, visibility, and compact owner profiles, while omitting API/node and Git transport URLs. Tree entries omit their derivable API URLs. Create/update gist results contain the gist ID and HTML URL. Modern JSON text and structured content serialize the same compact result. Older or unknown protocol versions retain byte-for-byte legacy text without an output schema or structured content.
+For `get_repository_tree`, `list_gists`, `get_gist`, `create_gist`, and `update_gist`, gist results retain file names, contents, sizes, language/type information, timestamps, visibility, compact owner profiles, and `raw_url`/`git_pull_url` recovery handles, while omitting unrelated API/node/push URLs. Tree entries omit their derivable API URLs. Create/update gist results contain the gist ID and HTML URL. Modern JSON text and structured content serialize the same compact result. Older or unknown protocol versions retain byte-for-byte legacy text without an output schema or structured content.
 
 The issue metadata (`list_issue_types`, `list_issue_fields`), comment (`add_issue_comment`, `update_issue_comment`), dependency (`issue_dependency_read`, `issue_dependency_write`), and duplicate-detection (`find_duplicate`) tools provide typed `outputSchema` and `structuredContent` for negotiated supported protocol versions `2026-07-28` or newer. Older or unknown protocol versions retain the same text responses without these fields. Tool errors do not return structured content. Dependency and duplicate-detection tools retain their existing feature gates.
 
@@ -1424,7 +1424,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. If omitted, modern clients receive compact entries without 'url' or 'git_url'; these API URLs require explicit selection. Legacy clients retain all GitHub API fields when omitted. 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)

pkg/github/__toolsnaps__/actions_get.snap

@@ -109,6 +109,11 @@
             "not": {
               "description": "Any value."
             }
+          },
+          "workflow_run": {
+            "not": {
+              "type": "null"
+            }
           }
         },
         "required": [
@@ -151,6 +156,11 @@
       },
       {
         "properties": {
+          "artifact": {
+            "not": {
+              "type": "null"
+            }
+          },
           "logs": {
             "not": {
               "description": "Any value."
@@ -227,6 +237,11 @@
               "description": "Any value."
             }
           },
+          "logs": {
+            "not": {
+              "type": "null"
+            }
+          },
           "method": {
             "enum": [
               "get_workflow_run_logs_url"

pkg/github/__toolsnaps__/actions_list.snap

@@ -170,6 +170,11 @@
               "description": "Any value."
             }
           },
+          "workflow_runs": {
+            "not": {
+              "type": "null"
+            }
+          },
           "workflows": {
             "not": {
               "description": "Any value."
@@ -192,6 +197,11 @@
               "list_workflow_jobs"
             ]
           },
+          "workflow_jobs": {
+            "not": {
+              "type": "null"
+            }
+          },
           "workflow_runs": {
             "not": {
               "description": "Any value."

pkg/github/__toolsnaps__/actions_run_trigger.snap

@@ -95,6 +95,11 @@
               "description": "Any value."
             }
           },
+          "dispatch": {
+            "not": {
+              "type": "null"
+            }
+          },
           "method": {
             "enum": [
               "run_workflow"
@@ -137,6 +142,11 @@
               "rerun_workflow_run"
             ]
           },
+          "rerun": {
+            "not": {
+              "type": "null"
+            }
+          },
           "rerun_failed": {
             "not": {
               "description": "Any value."
@@ -173,6 +183,11 @@
             "not": {
               "description": "Any value."
             }
+          },
+          "rerun_failed": {
+            "not": {
+              "type": "null"
+            }
           }
         },
         "required": [
@@ -181,6 +196,11 @@
       },
       {
         "properties": {
+          "cancel": {
+            "not": {
+              "type": "null"
+            }
+          },
           "delete_logs": {
             "not": {
               "description": "Any value."
@@ -218,6 +238,11 @@
               "description": "Any value."
             }
           },
+          "delete_logs": {
+            "not": {
+              "type": "null"
+            }
+          },
           "dispatch": {
             "not": {
               "description": "Any value."

pkg/github/__toolsnaps__/get_file_contents.snap

@@ -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. If omitted, modern clients receive compact entries without 'url' or 'git_url'; these API URLs require explicit selection. Legacy clients retain all GitHub API fields when omitted. 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",

pkg/github/actions_types.go

@@ -234,7 +234,10 @@ var actionsListOutputSchema = sync.OnceValue(func() *jsonschema.Schema {
 	constrainMethodOutput(schema, map[string]string{
 		actionsMethodListWorkflows: "workflows", actionsMethodListWorkflowRuns: "workflow_runs",
 		actionsMethodListWorkflowJobs: "workflow_jobs", actionsMethodListWorkflowArtifacts: "artifacts",
-	}, "workflows", "artifacts")
+	}, methodOutputConstraints{
+		optionalPayloads:        []string{"workflows", "artifacts"},
+		nonNullRequiredPayloads: true,
+	})
 	return schema
 })
 
@@ -367,7 +370,10 @@ var actionsGetOutputSchema = sync.OnceValue(func() *jsonschema.Schema {
 		actionsMethodGetWorkflow: "workflow", actionsMethodGetWorkflowRun: "workflow_run",
 		actionsMethodGetWorkflowJob: "workflow_job", actionsMethodGetWorkflowRunUsage: "usage",
 		actionsMethodDownloadWorkflowArtifact: "artifact", actionsMethodGetWorkflowRunLogsURL: "logs",
-	}, "workflow", "workflow_job", "usage")
+	}, methodOutputConstraints{
+		optionalPayloads:        []string{"workflow", "workflow_job", "usage"},
+		nonNullRequiredPayloads: true,
+	})
 	return schema
 })
 
@@ -414,7 +420,7 @@ var actionsRunTriggerOutputSchema = sync.OnceValue(func() *jsonschema.Schema {
 		actionsMethodRunWorkflow: "dispatch", actionsMethodRerunWorkflowRun: "rerun",
 		actionsMethodRerunFailedJobs: "rerun_failed", actionsMethodCancelWorkflowRun: "cancel",
 		actionsMethodDeleteWorkflowRunLogs: "delete_logs",
-	})
+	}, methodOutputConstraints{nonNullRequiredPayloads: true})
 	return schema
 })
 

pkg/github/method_output_schema.go

@@ -6,15 +6,23 @@ import (
 	"github.com/google/jsonschema-go/jsonschema"
 )
 
-func constrainMethodOutput(schema *jsonschema.Schema, payloadByMethod map[string]string, optionalPayloads ...string) {
+type methodOutputConstraints struct {
+	optionalPayloads        []string
+	nonNullRequiredPayloads bool
+}
+
+func constrainMethodOutput(schema *jsonschema.Schema, payloadByMethod map[string]string, constraints methodOutputConstraints) {
 	schema.Required = []string{"method"}
 	for _, method := range schema.Properties["method"].Enum {
 		payload := payloadByMethod[method.(string)]
 		variant := &jsonschema.Schema{Properties: map[string]*jsonschema.Schema{
 			"method": {Enum: []any{method}},
 		}}
-		if !slices.Contains(optionalPayloads, payload) {
+		if !slices.Contains(constraints.optionalPayloads, payload) {
 			variant.Required = []string{payload}
+			if constraints.nonNullRequiredPayloads {
+				variant.Properties[payload] = &jsonschema.Schema{Not: &jsonschema.Schema{Type: "null"}}
+			}
 		}
 		for _, other := range payloadByMethod {
 			if other != payload {

pkg/github/repositories.go

@@ -1011,7 +1011,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. If omitted, modern clients receive compact entries without 'url' or 'git_url'; these API URLs require explicit selection. Legacy clients retain all GitHub API fields when omitted. 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,
 	)
 

pkg/github/repositories_test.go

@@ -104,6 +104,9 @@ func Test_GetFileContents(t *testing.T) {
 	assert.Contains(t, schema.Properties, "ref")
 	assert.Contains(t, schema.Properties, "sha")
 	assert.Contains(t, schema.Properties, "fields")
+	assert.Contains(t, schema.Properties["fields"].Description, "modern clients receive compact entries without 'url' or 'git_url'")
+	assert.Contains(t, schema.Properties["fields"].Description, "these API URLs require explicit selection")
+	assert.Contains(t, schema.Properties["fields"].Description, "Legacy clients retain all GitHub API fields when omitted")
 	assert.ElementsMatch(t, schema.Required, []string{"owner", "repo"})
 
 	// Mock response for raw content

pkg/github/security_outputs.go

@@ -5,6 +5,7 @@ import (
 	"encoding/json"
 	"fmt"
 	"math"
+	"slices"
 	"strconv"
 	"time"
 
@@ -448,7 +449,7 @@ func securityAdvisoryOutput(advisory *github.SecurityAdvisory) *SecurityAdvisory
 	output := &SecurityAdvisoryOutput{
 		GHSAID: advisory.GHSAID, CVEID: advisory.CVEID, Summary: advisory.Summary,
 		Description: advisory.Description, Severity: advisory.Severity, State: advisory.State,
-		HTMLURL: advisory.HTMLURL, CWEIDs: advisory.CWEIDs,
+		HTMLURL: advisory.HTMLURL, CWEIDs: slices.Clone(advisory.CWEIDs),
 		PublishedAt: githubTimestampTime(advisory.PublishedAt),
 		UpdatedAt:   githubTimestampTime(advisory.UpdatedAt),
 		WithdrawnAt: githubTimestampTime(advisory.WithdrawnAt),