refactor(search_commits): share commit conversion, surface repo, tighten query docs

- Extract newMinimalCommitFromCore to share field mapping between
  convertToMinimalCommit (RepositoryCommit) and the new
  convertCommitResultToMinimalCommit (CommitResult), removing ~50
  lines of duplicated logic from the search_commits handler.
- Add MinimalRepoRef and a Repository field on MinimalCommit so
  cross-repo commit search results identify the repo each commit
  came from (the API returns it; we were trimming it away).
- Rewrite the query description to teach the model the actual
  commit-search qualifier surface (repo:/org:/user: scoping, author/
  committer/date qualifiers, hash/tree/parent, merge:, is:public)
  and reword the sort description to drop redundancy with the enum.
- Extend tests to assert the repository field is surfaced and to
  cover commits with no resolved GitHub user (nil Author/Committer).
- Refresh README and toolsnap.

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

Author: SamMorrowDrums

README.md

@@ -1307,8 +1307,8 @@ The following sets of tools are available:
   - `order`: Sort order (string, optional)
   - `page`: Page number for pagination (min 1) (number, optional)
   - `perPage`: Results per page for pagination (min 1, max 100) (number, optional)
-  - `query`: Commit search query. Examples: 'repo:owner/repo fix bug', 'author:defunkt', 'committer-date:>2024-01-01'. Supports advanced search syntax. (string, required)
-  - `sort`: Sort field ('author-date' or 'committer-date') (string, optional)
+  - `query`: Commit search query (GitHub commit search REST). Searches commit messages on the default branch only. Scope the search with `repo:owner/repo`, `org:`, or `user:` (queries without a scope qualifier match across all of GitHub and are usually not what you want). Other qualifiers: `author:`, `committer:`, `author-name:`, `committer-name:`, `author-email:`, `committer-email:`, `author-date:`, `committer-date:` (supports `>`, `<`, `>=`, `<=`, and `YYYY-MM-DD..YYYY-MM-DD` ranges), `merge:true|false`, `hash:`, `tree:`, `parent:`, `is:public`. Examples: `repo:owner/repo fix panic`; `org:github author:defunkt committer-date:>=2024-01-01`; `"refactor cache" repo:o/r`; `hash:abc1234 repo:o/r`. (string, required)
+  - `sort`: Sort by author or committer date (defaults to best match) (string, optional)
 
 - **search_repositories** - Search repositories
   - **Required OAuth Scopes**: `repo`

pkg/github/__toolsnaps__/search_commits.snap

@@ -3,7 +3,7 @@
     "readOnlyHint": true,
     "title": "Search commits"
   },
-  "description": "Search for commits across GitHub repositories using specialized commit search syntax. Great for finding specific changes, authors, or messages.",
+  "description": "Search for commits across GitHub repositories using GitHub's commit search syntax. Useful for finding specific changes, authors, or messages across one or many repositories. Searches the default branch only.",
   "inputSchema": {
     "properties": {
       "order": {
@@ -26,11 +26,11 @@
         "type": "number"
       },
       "query": {
-        "description": "Commit search query. Examples: 'repo:owner/repo fix bug', 'author:defunkt', 'committer-date:\u003e2024-01-01'. Supports advanced search syntax.",
+        "description": "Commit search query (GitHub commit search REST). Searches commit messages on the default branch only. Scope the search with `repo:owner/repo`, `org:`, or `user:` (queries without a scope qualifier match across all of GitHub and are usually not what you want). Other qualifiers: `author:`, `committer:`, `author-name:`, `committer-name:`, `author-email:`, `committer-email:`, `author-date:`, `committer-date:` (supports `\u003e`, `\u003c`, `\u003e=`, `\u003c=`, and `YYYY-MM-DD..YYYY-MM-DD` ranges), `merge:true|false`, `hash:`, `tree:`, `parent:`, `is:public`. Examples: `repo:owner/repo fix panic`; `org:github author:defunkt committer-date:\u003e=2024-01-01`; `\"refactor cache\" repo:o/r`; `hash:abc1234 repo:o/r`.",
         "type": "string"
       },
       "sort": {
-        "description": "Sort field ('author-date' or 'committer-date')",
+        "description": "Sort by author or committer date (defaults to best match)",
         "enum": [
           "author-date",
           "committer-date"

pkg/github/minimal_types.go

@@ -121,13 +121,23 @@ type MinimalPRFile struct {
 
 // MinimalCommit is the trimmed output type for commit objects.
 type MinimalCommit struct {
-	SHA       string              `json:"sha"`
-	HTMLURL   string              `json:"html_url"`
-	Commit    *MinimalCommitInfo  `json:"commit,omitempty"`
-	Author    *MinimalUser        `json:"author,omitempty"`
-	Committer *MinimalUser        `json:"committer,omitempty"`
-	Stats     *MinimalCommitStats `json:"stats,omitempty"`
-	Files     []MinimalCommitFile `json:"files,omitempty"`
+	SHA        string              `json:"sha"`
+	HTMLURL    string              `json:"html_url"`
+	Commit     *MinimalCommitInfo  `json:"commit,omitempty"`
+	Author     *MinimalUser        `json:"author,omitempty"`
+	Committer  *MinimalUser        `json:"committer,omitempty"`
+	Repository *MinimalRepoRef     `json:"repository,omitempty"`
+	Stats      *MinimalCommitStats `json:"stats,omitempty"`
+	Files      []MinimalCommitFile `json:"files,omitempty"`
+}
+
+// MinimalRepoRef is a lightweight reference to a repository, used when a
+// result needs to identify which repository it belongs to (for example, in
+// cross-repo commit search results).
+type MinimalRepoRef struct {
+	FullName string `json:"full_name"`
+	HTMLURL  string `json:"html_url,omitempty"`
+	Private  bool   `json:"private,omitempty"`
 }
 
 // MinimalRelease is the trimmed output type for release objects.
@@ -700,57 +710,73 @@ func convertToMinimalUser(user *github.User) *MinimalUser {
 	}
 }
 
-// convertToMinimalCommit converts a GitHub API RepositoryCommit to MinimalCommit
-func convertToMinimalCommit(commit *github.RepositoryCommit, includeDiffs bool) MinimalCommit {
+// newMinimalCommitFromCore builds a MinimalCommit from the fields that are
+// shared between *github.RepositoryCommit and *github.CommitResult. Caller
+// is responsible for setting any type-specific extras (stats/files for
+// RepositoryCommit, repository for CommitResult).
+func newMinimalCommitFromCore(sha, htmlURL string, commit *github.Commit, author, committer *github.User) MinimalCommit {
 	minimalCommit := MinimalCommit{
-		SHA:     commit.GetSHA(),
-		HTMLURL: commit.GetHTMLURL(),
+		SHA:     sha,
+		HTMLURL: htmlURL,
 	}
 
-	if commit.Commit != nil {
+	if commit != nil {
 		minimalCommit.Commit = &MinimalCommitInfo{
-			Message: commit.Commit.GetMessage(),
+			Message: commit.GetMessage(),
 		}
 
-		if commit.Commit.Author != nil {
+		if commit.Author != nil {
 			minimalCommit.Commit.Author = &MinimalCommitAuthor{
-				Name:  commit.Commit.Author.GetName(),
-				Email: commit.Commit.Author.GetEmail(),
+				Name:  commit.Author.GetName(),
+				Email: commit.Author.GetEmail(),
 			}
-			if commit.Commit.Author.Date != nil {
-				minimalCommit.Commit.Author.Date = commit.Commit.Author.Date.Format(time.RFC3339)
+			if commit.Author.Date != nil {
+				minimalCommit.Commit.Author.Date = commit.Author.Date.Format(time.RFC3339)
 			}
 		}
 
-		if commit.Commit.Committer != nil {
+		if commit.Committer != nil {
 			minimalCommit.Commit.Committer = &MinimalCommitAuthor{
-				Name:  commit.Commit.Committer.GetName(),
-				Email: commit.Commit.Committer.GetEmail(),
+				Name:  commit.Committer.GetName(),
+				Email: commit.Committer.GetEmail(),
 			}
-			if commit.Commit.Committer.Date != nil {
-				minimalCommit.Commit.Committer.Date = commit.Commit.Committer.Date.Format(time.RFC3339)
+			if commit.Committer.Date != nil {
+				minimalCommit.Commit.Committer.Date = commit.Committer.Date.Format(time.RFC3339)
 			}
 		}
 	}
 
-	if commit.Author != nil {
+	if author != nil {
 		minimalCommit.Author = &MinimalUser{
-			Login:      commit.Author.GetLogin(),
-			ID:         commit.Author.GetID(),
-			ProfileURL: commit.Author.GetHTMLURL(),
-			AvatarURL:  commit.Author.GetAvatarURL(),
+			Login:      author.GetLogin(),
+			ID:         author.GetID(),
+			ProfileURL: author.GetHTMLURL(),
+			AvatarURL:  author.GetAvatarURL(),
 		}
 	}
 
-	if commit.Committer != nil {
+	if committer != nil {
 		minimalCommit.Committer = &MinimalUser{
-			Login:      commit.Committer.GetLogin(),
-			ID:         commit.Committer.GetID(),
-			ProfileURL: commit.Committer.GetHTMLURL(),
-			AvatarURL:  commit.Committer.GetAvatarURL(),
+			Login:      committer.GetLogin(),
+			ID:         committer.GetID(),
+			ProfileURL: committer.GetHTMLURL(),
+			AvatarURL:  committer.GetAvatarURL(),
 		}
 	}
 
+	return minimalCommit
+}
+
+// convertToMinimalCommit converts a GitHub API RepositoryCommit to MinimalCommit
+func convertToMinimalCommit(commit *github.RepositoryCommit, includeDiffs bool) MinimalCommit {
+	minimalCommit := newMinimalCommitFromCore(
+		commit.GetSHA(),
+		commit.GetHTMLURL(),
+		commit.Commit,
+		commit.Author,
+		commit.Committer,
+	)
+
 	// Only include stats and files if includeDiffs is true
 	if includeDiffs {
 		if commit.Stats != nil {
@@ -779,6 +805,29 @@ func convertToMinimalCommit(commit *github.RepositoryCommit, includeDiffs bool)
 	return minimalCommit
 }
 
+// convertCommitResultToMinimalCommit converts a GitHub API commit search
+// result to a MinimalCommit, attaching the containing repository so the
+// caller can tell which repo each result came from.
+func convertCommitResultToMinimalCommit(commit *github.CommitResult) MinimalCommit {
+	minimalCommit := newMinimalCommitFromCore(
+		commit.GetSHA(),
+		commit.GetHTMLURL(),
+		commit.Commit,
+		commit.Author,
+		commit.Committer,
+	)
+
+	if commit.Repository != nil {
+		minimalCommit.Repository = &MinimalRepoRef{
+			FullName: commit.Repository.GetFullName(),
+			HTMLURL:  commit.Repository.GetHTMLURL(),
+			Private:  commit.Repository.GetPrivate(),
+		}
+	}
+
+	return minimalCommit
+}
+
 // MinimalPageInfo contains pagination cursor information.
 type MinimalPageInfo struct {
 	HasNextPage     bool   `json:"hasNextPage"`

pkg/github/search.go

@@ -6,7 +6,6 @@ import (
 	"fmt"
 	"io"
 	"net/http"
-	"time"
 
 	ghErrors "github.com/github/github-mcp-server/pkg/errors"
 	"github.com/github/github-mcp-server/pkg/ifc"
@@ -487,11 +486,11 @@ func SearchCommits(t translations.TranslationHelperFunc) inventory.ServerTool {
 		Properties: map[string]*jsonschema.Schema{
 			"query": {
 				Type:        "string",
-				Description: "Commit search query. Examples: 'repo:owner/repo fix bug', 'author:defunkt', 'committer-date:>2024-01-01'. Supports advanced search syntax.",
+				Description: "Commit search query (GitHub commit search REST). Searches commit messages on the default branch only. Scope the search with `repo:owner/repo`, `org:`, or `user:` (queries without a scope qualifier match across all of GitHub and are usually not what you want). Other qualifiers: `author:`, `committer:`, `author-name:`, `committer-name:`, `author-email:`, `committer-email:`, `author-date:`, `committer-date:` (supports `>`, `<`, `>=`, `<=`, and `YYYY-MM-DD..YYYY-MM-DD` ranges), `merge:true|false`, `hash:`, `tree:`, `parent:`, `is:public`. Examples: `repo:owner/repo fix panic`; `org:github author:defunkt committer-date:>=2024-01-01`; `\"refactor cache\" repo:o/r`; `hash:abc1234 repo:o/r`.",
 			},
 			"sort": {
 				Type:        "string",
-				Description: "Sort field ('author-date' or 'committer-date')",
+				Description: "Sort by author or committer date (defaults to best match)",
 				Enum:        []any{"author-date", "committer-date"},
 			},
 			"order": {
@@ -508,7 +507,7 @@ func SearchCommits(t translations.TranslationHelperFunc) inventory.ServerTool {
 		ToolsetMetadataRepos,
 		mcp.Tool{
 			Name:        "search_commits",
-			Description: t("TOOL_SEARCH_COMMITS_DESCRIPTION", "Search for commits across GitHub repositories using specialized commit search syntax. Great for finding specific changes, authors, or messages."),
+			Description: t("TOOL_SEARCH_COMMITS_DESCRIPTION", "Search for commits across GitHub repositories using GitHub's commit search syntax. Useful for finding specific changes, authors, or messages across one or many repositories. Searches the default branch only."),
 			Annotations: &mcp.ToolAnnotations{
 				Title:        t("TOOL_SEARCH_COMMITS_USER_TITLE", "Search commits"),
 				ReadOnlyHint: true,
@@ -565,59 +564,6 @@ func SearchCommits(t translations.TranslationHelperFunc) inventory.ServerTool {
 				return ghErrors.NewGitHubAPIStatusErrorResponse(ctx, "failed to search commits", resp, body), nil, nil
 			}
 
-			convertCommitResultToMinimalCommit := func(commit *github.CommitResult) MinimalCommit {
-				minimalCommit := MinimalCommit{
-					SHA:     commit.GetSHA(),
-					HTMLURL: commit.GetHTMLURL(),
-				}
-
-				if commit.Commit != nil {
-					minimalCommit.Commit = &MinimalCommitInfo{
-						Message: commit.Commit.GetMessage(),
-					}
-
-					if commit.Commit.Author != nil {
-						minimalCommit.Commit.Author = &MinimalCommitAuthor{
-							Name:  commit.Commit.Author.GetName(),
-							Email: commit.Commit.Author.GetEmail(),
-						}
-						if commit.Commit.Author.Date != nil {
-							minimalCommit.Commit.Author.Date = commit.Commit.Author.Date.Format(time.RFC3339)
-						}
-					}
-
-					if commit.Commit.Committer != nil {
-						minimalCommit.Commit.Committer = &MinimalCommitAuthor{
-							Name:  commit.Commit.Committer.GetName(),
-							Email: commit.Commit.Committer.GetEmail(),
-						}
-						if commit.Commit.Committer.Date != nil {
-							minimalCommit.Commit.Committer.Date = commit.Commit.Committer.Date.Format(time.RFC3339)
-						}
-					}
-				}
-
-				if commit.Author != nil {
-					minimalCommit.Author = &MinimalUser{
-						Login:      commit.Author.GetLogin(),
-						ID:         commit.Author.GetID(),
-						ProfileURL: commit.Author.GetHTMLURL(),
-						AvatarURL:  commit.Author.GetAvatarURL(),
-					}
-				}
-
-				if commit.Committer != nil {
-					minimalCommit.Committer = &MinimalUser{
-						Login:      commit.Committer.GetLogin(),
-						ID:         commit.Committer.GetID(),
-						ProfileURL: commit.Committer.GetHTMLURL(),
-						AvatarURL:  commit.Committer.GetAvatarURL(),
-					}
-				}
-
-				return minimalCommit
-			}
-
 			minimalCommits := make([]MinimalCommit, 0, len(result.Commits))
 			for _, commit := range result.Commits {
 				minimalCommits = append(minimalCommits, convertCommitResultToMinimalCommit(commit))

pkg/github/search_test.go

@@ -875,7 +875,7 @@ func Test_SearchCommits(t *testing.T) {
 
 	now := time.Now().Truncate(time.Second)
 	mockSearchResult := &github.CommitsSearchResult{
-		Total:             github.Ptr(1),
+		Total:             github.Ptr(2),
 		IncompleteResults: github.Ptr(false),
 		Commits: []*github.CommitResult{
 			{
@@ -894,6 +894,23 @@ func Test_SearchCommits(t *testing.T) {
 					ID:      github.Ptr(int64(1)),
 					HTMLURL: github.Ptr("https://github.com/author"),
 				},
+				Repository: &github.Repository{
+					FullName: github.Ptr("owner/repo"),
+					HTMLURL:  github.Ptr("https://github.com/owner/repo"),
+					Private:  github.Ptr(false),
+				},
+			},
+			{
+				// Commit with no resolved GitHub user for author or committer
+				// (common when the commit email isn't linked to an account).
+				SHA:     github.Ptr("def456commit"),
+				HTMLURL: github.Ptr("https://github.com/owner/repo/commit/def456commit"),
+				Commit: &github.Commit{
+					Message: github.Ptr("Unlinked author"),
+				},
+				Repository: &github.Repository{
+					FullName: github.Ptr("owner/repo"),
+				},
 			},
 		},
 	}
@@ -945,7 +962,7 @@ func Test_SearchCommits(t *testing.T) {
 
 	for _, tc := range tests {
 		t.Run(tc.name, func(t *testing.T) {
-			client := github.NewClient(tc.mockedClient)
+			client := mustNewGHClient(t, tc.mockedClient)
 			deps := BaseDeps{
 				Client: client,
 			}
@@ -977,6 +994,23 @@ func Test_SearchCommits(t *testing.T) {
 			assert.Equal(t, *tc.expectedResult.Commits[0].Commit.Author.Name, returnedResult.Items[0].Commit.Author.Name)
 			assert.Equal(t, now.Format(time.RFC3339), returnedResult.Items[0].Commit.Author.Date)
 			assert.Equal(t, *tc.expectedResult.Commits[0].Author.Login, returnedResult.Items[0].Author.Login)
+
+			// Repository info is required so callers can identify which repo
+			// each cross-repo search result belongs to.
+			require.NotNil(t, returnedResult.Items[0].Repository)
+			assert.Equal(t, "owner/repo", returnedResult.Items[0].Repository.FullName)
+			assert.Equal(t, "https://github.com/owner/repo", returnedResult.Items[0].Repository.HTMLURL)
+
+			// Second commit has no resolved GitHub user for author/committer
+			// and no commit-level author block — the handler must not panic
+			// and must omit those fields cleanly.
+			require.Len(t, returnedResult.Items, 2)
+			assert.Equal(t, "def456commit", returnedResult.Items[1].SHA)
+			assert.Nil(t, returnedResult.Items[1].Author)
+			assert.Nil(t, returnedResult.Items[1].Committer)
+			require.NotNil(t, returnedResult.Items[1].Commit)
+			assert.Nil(t, returnedResult.Items[1].Commit.Author)
+			assert.Nil(t, returnedResult.Items[1].Commit.Committer)
 		})
 	}
 }