Add sort and order parameters to search_repositories tool (#1191)

* add sort and order params

* test adding server instructions for sorting

* improve server instructions

* reorder

Author: kerobbi

README.md

@@ -993,9 +993,11 @@ Possible options:
 
 - **search_repositories** - Search repositories
   - `minimal_output`: Return minimal repository information (default: true). When false, returns full GitHub API repository objects. (boolean, optional)
+  - `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`: Repository search query. Examples: 'machine learning in:name stars:>1000 language:python', 'topic:react', 'user:facebook'. Supports advanced search syntax for precise filtering. (string, required)
+  - `sort`: Sort repositories by field, defaults to best match (string, optional)
 
 </details>
 

pkg/github/__toolsnaps__/search_repositories.snap

@@ -11,6 +11,14 @@
         "description": "Return minimal repository information (default: true). When false, returns full GitHub API repository objects.",
         "type": "boolean"
       },
+      "order": {
+        "description": "Sort order",
+        "enum": [
+          "asc",
+          "desc"
+        ],
+        "type": "string"
+      },
       "page": {
         "description": "Page number for pagination (min 1)",
         "minimum": 1,
@@ -25,6 +33,16 @@
       "query": {
         "description": "Repository search query. Examples: 'machine learning in:name stars:\u003e1000 language:python', 'topic:react', 'user:facebook'. Supports advanced search syntax for precise filtering.",
         "type": "string"
+      },
+      "sort": {
+        "description": "Sort repositories by field, defaults to best match",
+        "enum": [
+          "stars",
+          "forks",
+          "help-wanted-issues",
+          "updated"
+        ],
+        "type": "string"
       }
     },
     "required": [

pkg/github/instructions.go

@@ -36,7 +36,10 @@ Tool selection guidance:
 
 Context management:
 	1. Use pagination whenever possible with batches of 5-10 items.
-	2. Use minimal_output parameter set to true if the full information is not needed to accomplish a task.`
+	2. Use minimal_output parameter set to true if the full information is not needed to accomplish a task.
+
+Tool usage guidance:
+	1. For 'search_*' tools: Use separate 'sort' and 'order' parameters if available for sorting results - do not include 'sort:' syntax in query strings. Query strings should contain only search criteria (e.g., 'org:google language:python'), not sorting instructions.`
 
 	allInstructions := []string{baseInstruction}
 	allInstructions = append(allInstructions, instructions...)

pkg/github/search.go

@@ -26,6 +26,14 @@ func SearchRepositories(getClient GetClientFn, t translations.TranslationHelperF
 				mcp.Required(),
 				mcp.Description("Repository search query. Examples: 'machine learning in:name stars:>1000 language:python', 'topic:react', 'user:facebook'. Supports advanced search syntax for precise filtering."),
 			),
+			mcp.WithString("sort",
+				mcp.Description("Sort repositories by field, defaults to best match"),
+				mcp.Enum("stars", "forks", "help-wanted-issues", "updated"),
+			),
+			mcp.WithString("order",
+				mcp.Description("Sort order"),
+				mcp.Enum("asc", "desc"),
+			),
 			mcp.WithBoolean("minimal_output",
 				mcp.Description("Return minimal repository information (default: true). When false, returns full GitHub API repository objects."),
 				mcp.DefaultBool(true),
@@ -37,6 +45,14 @@ func SearchRepositories(getClient GetClientFn, t translations.TranslationHelperF
 			if err != nil {
 				return mcp.NewToolResultError(err.Error()), nil
 			}
+			sort, err := OptionalParam[string](request, "sort")
+			if err != nil {
+				return mcp.NewToolResultError(err.Error()), nil
+			}
+			order, err := OptionalParam[string](request, "order")
+			if err != nil {
+				return mcp.NewToolResultError(err.Error()), nil
+			}
 			pagination, err := OptionalPaginationParams(request)
 			if err != nil {
 				return mcp.NewToolResultError(err.Error()), nil
@@ -46,6 +62,8 @@ func SearchRepositories(getClient GetClientFn, t translations.TranslationHelperF
 				return mcp.NewToolResultError(err.Error()), nil
 			}
 			opts := &github.SearchOptions{
+				Sort:  sort,
+				Order: order,
 				ListOptions: github.ListOptions{
 					Page:    pagination.Page,
 					PerPage: pagination.PerPage,

pkg/github/search_test.go

@@ -23,6 +23,8 @@ func Test_SearchRepositories(t *testing.T) {
 	assert.Equal(t, "search_repositories", tool.Name)
 	assert.NotEmpty(t, tool.Description)
 	assert.Contains(t, tool.InputSchema.Properties, "query")
+	assert.Contains(t, tool.InputSchema.Properties, "sort")
+	assert.Contains(t, tool.InputSchema.Properties, "order")
 	assert.Contains(t, tool.InputSchema.Properties, "page")
 	assert.Contains(t, tool.InputSchema.Properties, "perPage")
 	assert.ElementsMatch(t, tool.InputSchema.Required, []string{"query"})
@@ -66,6 +68,8 @@ func Test_SearchRepositories(t *testing.T) {
 					mock.GetSearchRepositories,
 					expectQueryParams(t, map[string]string{
 						"q":        "golang test",
+						"sort":     "stars",
+						"order":    "desc",
 						"page":     "2",
 						"per_page": "10",
 					}).andThen(
@@ -75,6 +79,8 @@ func Test_SearchRepositories(t *testing.T) {
 			),
 			requestArgs: map[string]interface{}{
 				"query":   "golang test",
+				"sort":    "stars",
+				"order":   "desc",
 				"page":    float64(2),
 				"perPage": float64(10),
 			},