Merge branch 'main' into xodene/feat-gists-tools-start

Author: mattdholloway

README.md

@@ -467,7 +467,7 @@ The following sets of tools are available (all are on by default):
   - `orderBy`: Order discussions by field. If provided, the 'direction' also needs to be provided. (string, optional)
   - `owner`: Repository owner (string, required)
   - `perPage`: Results per page for pagination (min 1, max 100) (number, optional)
-  - `repo`: Repository name (string, required)
+  - `repo`: Repository name. If not provided, discussions will be queried at the organisation level. (string, optional)
 
 </details>
 
@@ -636,7 +636,7 @@ The following sets of tools are available (all are on by default):
   - `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`: Search query using GitHub organizations search syntax scoped to type:org (string, required)
+  - `query`: Organization search query. Examples: 'microsoft', 'location:california', 'created:>=2025-01-01'. Search is automatically scoped to type:org. (string, required)
   - `sort`: Sort field by category (string, optional)
 
 </details>
@@ -761,6 +761,7 @@ The following sets of tools are available (all are on by default):
 - **update_pull_request** - Edit pull request
   - `base`: New base branch name (string, optional)
   - `body`: New description (string, optional)
+  - `draft`: Mark pull request as draft (true) or ready for review (false) (boolean, optional)
   - `maintainer_can_modify`: Allow maintainer edits (boolean, optional)
   - `owner`: Repository owner (string, required)
   - `pullNumber`: Pull request number to update (number, required)
@@ -860,16 +861,16 @@ The following sets of tools are available (all are on by default):
   - `repo`: Repository name (string, required)
 
 - **search_code** - Search code
-  - `order`: Sort order (string, optional)
+  - `order`: Sort order for results (string, optional)
   - `page`: Page number for pagination (min 1) (number, optional)
   - `perPage`: Results per page for pagination (min 1, max 100) (number, optional)
-  - `query`: Search query using GitHub code search syntax (string, required)
+  - `query`: Search query using GitHub's powerful code search syntax. Examples: 'content:Skill language:Java org:github', 'NOT is:archived language:Python OR language:go', 'repo:github/github-mcp-server'. Supports exact matching, language filters, path filters, and more. (string, required)
   - `sort`: Sort field ('indexed' only) (string, optional)
 
 - **search_repositories** - Search repositories
   - `page`: Page number for pagination (min 1) (number, optional)
   - `perPage`: Results per page for pagination (min 1, max 100) (number, optional)
-  - `query`: Search query (string, required)
+  - `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)
 
 </details>
 
@@ -899,8 +900,8 @@ The following sets of tools are available (all are on by default):
   - `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`: Search query using GitHub users search syntax scoped to type:user (string, required)
-  - `sort`: Sort field by category (string, optional)
+  - `query`: User search query. Examples: 'john smith', 'location:seattle', 'followers:>100'. Search is automatically scoped to type:user. (string, required)
+  - `sort`: Sort users by number of followers or repositories, or when the person joined GitHub. (string, optional)
 
 </details>
 <!-- END AUTOMATED TOOLS -->

pkg/github/__toolsnaps__/search_code.snap

@@ -3,11 +3,11 @@
     "title": "Search code",
     "readOnlyHint": true
   },
-  "description": "Search for code across GitHub repositories",
+  "description": "Fast and precise code search across ALL GitHub repositories using GitHub's native search engine. Best for finding exact symbols, functions, classes, or specific code patterns.",
   "inputSchema": {
     "properties": {
       "order": {
-        "description": "Sort order",
+        "description": "Sort order for results",
         "enum": [
           "asc",
           "desc"
@@ -26,7 +26,7 @@
         "type": "number"
       },
       "query": {
-        "description": "Search query using GitHub code search syntax",
+        "description": "Search query using GitHub's powerful code search syntax. Examples: 'content:Skill language:Java org:github', 'NOT is:archived language:Python OR language:go', 'repo:github/github-mcp-server'. Supports exact matching, language filters, path filters, and more.",
         "type": "string"
       },
       "sort": {

pkg/github/__toolsnaps__/search_repositories.snap

@@ -3,7 +3,7 @@
     "title": "Search repositories",
     "readOnlyHint": true
   },
-  "description": "Search for GitHub repositories",
+  "description": "Find GitHub repositories by name, description, readme, topics, or other metadata. Perfect for discovering projects, finding examples, or locating specific repositories across GitHub.",
   "inputSchema": {
     "properties": {
       "page": {
@@ -18,7 +18,7 @@
         "type": "number"
       },
       "query": {
-        "description": "Search 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"
       }
     },

pkg/github/__toolsnaps__/search_users.snap

@@ -3,7 +3,7 @@
     "title": "Search users",
     "readOnlyHint": true
   },
-  "description": "Search for GitHub users exclusively",
+  "description": "Find GitHub users by username, real name, or other profile information. Useful for locating developers, contributors, or team members.",
   "inputSchema": {
     "properties": {
       "order": {
@@ -26,11 +26,11 @@
         "type": "number"
       },
       "query": {
-        "description": "Search query using GitHub users search syntax scoped to type:user",
+        "description": "User search query. Examples: 'john smith', 'location:seattle', 'followers:\u003e100'. Search is automatically scoped to type:user.",
         "type": "string"
       },
       "sort": {
-        "description": "Sort field by category",
+        "description": "Sort users by number of followers or repositories, or when the person joined GitHub.",
         "enum": [
           "followers",
           "repositories",

pkg/github/__toolsnaps__/update_pull_request.snap

@@ -14,6 +14,10 @@
         "description": "New description",
         "type": "string"
       },
+      "draft": {
+        "description": "Mark pull request as draft (true) or ready for review (false)",
+        "type": "boolean"
+      },
       "maintainer_can_modify": {
         "description": "Allow maintainer edits",
         "type": "boolean"

pkg/github/discussions.go

@@ -119,7 +119,7 @@ func getQueryType(useOrdering bool, categoryID *githubv4.ID) any {
 
 func ListDiscussions(getGQLClient GetGQLClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) {
 	return mcp.NewTool("list_discussions",
-			mcp.WithDescription(t("TOOL_LIST_DISCUSSIONS_DESCRIPTION", "List discussions for a repository")),
+			mcp.WithDescription(t("TOOL_LIST_DISCUSSIONS_DESCRIPTION", "List discussions for a repository or organisation.")),
 			mcp.WithToolAnnotation(mcp.ToolAnnotation{
 				Title:        t("TOOL_LIST_DISCUSSIONS_USER_TITLE", "List discussions"),
 				ReadOnlyHint: ToBoolPtr(true),
@@ -129,8 +129,7 @@ func ListDiscussions(getGQLClient GetGQLClientFn, t translations.TranslationHelp
 				mcp.Description("Repository owner"),
 			),
 			mcp.WithString("repo",
-				mcp.Required(),
-				mcp.Description("Repository name"),
+				mcp.Description("Repository name. If not provided, discussions will be queried at the organisation level."),
 			),
 			mcp.WithString("category",
 				mcp.Description("Optional filter by discussion category ID. If provided, only discussions with this category are listed."),
@@ -150,10 +149,15 @@ func ListDiscussions(getGQLClient GetGQLClientFn, t translations.TranslationHelp
 			if err != nil {
 				return mcp.NewToolResultError(err.Error()), nil
 			}
-			repo, err := RequiredParam[string](request, "repo")
+			repo, err := OptionalParam[string](request, "repo")
 			if err != nil {
 				return mcp.NewToolResultError(err.Error()), nil
 			}
+			// when not provided, default to the .github repository
+			// this will query discussions at the organisation level
+			if repo == "" {
+				repo = ".github"
+			}
 
 			category, err := OptionalParam[string](request, "category")
 			if err != nil {

pkg/github/discussions_test.go

@@ -50,6 +50,46 @@ var (
 		},
 	}
 
+	discussionsOrgLevel = []map[string]any{
+		{
+			"number":    1,
+			"title":     "Org Discussion 1 - Community Guidelines",
+			"createdAt": "2023-01-15T00:00:00Z",
+			"updatedAt": "2023-01-15T00:00:00Z",
+			"author":    map[string]any{"login": "org-admin"},
+			"url":       "https://github.com/owner/.github/discussions/1",
+			"category":  map[string]any{"name": "Announcements"},
+		},
+		{
+			"number":    2,
+			"title":     "Org Discussion 2 - Roadmap 2023",
+			"createdAt": "2023-02-20T00:00:00Z",
+			"updatedAt": "2023-02-20T00:00:00Z",
+			"author":    map[string]any{"login": "org-admin"},
+			"url":       "https://github.com/owner/.github/discussions/2",
+			"category":  map[string]any{"name": "General"},
+		},
+		{
+			"number":    3,
+			"title":     "Org Discussion 3 - Roadmap 2024",
+			"createdAt": "2023-02-20T00:00:00Z",
+			"updatedAt": "2023-02-20T00:00:00Z",
+			"author":    map[string]any{"login": "org-admin"},
+			"url":       "https://github.com/owner/.github/discussions/3",
+			"category":  map[string]any{"name": "General"},
+		},
+		{
+			"number":    4,
+			"title":     "Org Discussion 4 - Roadmap 2025",
+			"createdAt": "2023-02-20T00:00:00Z",
+			"updatedAt": "2023-02-20T00:00:00Z",
+			"author":    map[string]any{"login": "org-admin"},
+			"url":       "https://github.com/owner/.github/discussions/4",
+			"category":  map[string]any{"name": "General"},
+		},
+
+	}
+
 	// Ordered mock responses
 	discussionsOrderedCreatedAsc = []map[string]any{
 		discussionsAll[0], // Discussion 1 (created 2023-01-01)
@@ -139,6 +179,22 @@ var (
 			},
 		},
 	})
+
+	mockResponseOrgLevel = githubv4mock.DataResponse(map[string]any{
+		"repository": map[string]any{
+			"discussions": map[string]any{
+				"nodes": discussionsOrgLevel,
+				"pageInfo": map[string]any{
+					"hasNextPage":     false,
+					"hasPreviousPage": false,
+					"startCursor":     "",
+					"endCursor":       "",
+				},
+				"totalCount": 4, 
+			},
+		},
+	})
+
 	mockErrorRepoNotFound = githubv4mock.ErrorResponse("repository not found")
 )
 
@@ -151,7 +207,7 @@ func Test_ListDiscussions(t *testing.T) {
 	assert.Contains(t, toolDef.InputSchema.Properties, "repo")
 	assert.Contains(t, toolDef.InputSchema.Properties, "orderBy")
 	assert.Contains(t, toolDef.InputSchema.Properties, "direction")
-	assert.ElementsMatch(t, toolDef.InputSchema.Required, []string{"owner", "repo"})
+	assert.ElementsMatch(t, toolDef.InputSchema.Required, []string{"owner"})
 
 	// Variables matching what GraphQL receives after JSON marshaling/unmarshaling
 	varsListAll := map[string]interface{}{
@@ -204,6 +260,13 @@ func Test_ListDiscussions(t *testing.T) {
 		"after":            (*string)(nil),
 	}
 
+	varsOrgLevel := map[string]interface{}{
+		"owner": "owner",
+		"repo":  ".github", // This is what gets set when repo is not provided
+		"first": float64(30),
+		"after": (*string)(nil),
+	}
+
 	tests := []struct {
 		name          string
 		reqParams     map[string]interface{}
@@ -314,6 +377,15 @@ func Test_ListDiscussions(t *testing.T) {
 			expectError: true,
 			errContains: "repository not found",
 		},
+		{
+			name: "list org-level discussions (no repo provided)",
+			reqParams: map[string]interface{}{
+				"owner": "owner",
+				// repo is not provided, it will default to ".github"
+			},
+			expectError:   false,
+			expectedCount: 4,
+		},
 	}
 
 	// Define the actual query strings that match the implementation
@@ -351,6 +423,9 @@ func Test_ListDiscussions(t *testing.T) {
 			case "repository not found error":
 				matcher := githubv4mock.NewQueryMatcher(qBasicNoOrder, varsRepoNotFound, mockErrorRepoNotFound)
 				httpClient = githubv4mock.NewMockedHTTPClient(matcher)
+			case "list org-level discussions (no repo provided)":
+				matcher := githubv4mock.NewQueryMatcher(qBasicNoOrder, varsOrgLevel, mockResponseOrgLevel)
+				httpClient = githubv4mock.NewMockedHTTPClient(matcher)
 			}
 
 			gqlClient := githubv4.NewClient(httpClient)