feat: Implement list_milestones and search_milestones commands

google-labs-jules[bot] · google-labs-jules[bot] · commit d76a8d547301 · 2025-09-02T06:49:45.000Z
This commit introduces two new commands for interacting with GitHub milestones:
- `list_milestones`: Lists milestones for a repository with options for filtering by state, sorting, and pagination.
- `search_milestones`: Searches for milestones in a repository by a query string, filtering by title and description.

The changes include:
- Implementation of `ListMilestones` and `SearchMilestones` functions in `pkg/github/issues.go`.
- Addition of the new tools to the `issues` toolset in `pkg/github/tools.go`.
- Unit tests for the new functions in `pkg/github/issues_test.go`.
- Updated tool snapshots and generated documentation.
diff --git a/README.md b/README.md
@@ -544,6 +544,11 @@ The following sets of tools are available (all are on by default):
   - `state`: Milestone state (string, required)
   - `title`: Milestone title (string, required)
 
+- **delete_milestone** - Delete milestone
+  - `milestone_number`: The number of the milestone to delete (number, required)
+  - `owner`: Repository owner (string, required)
+  - `repo`: Repository name (string, required)
+
 - **edit_milestone** - Edit milestone
   - `description`: New milestone description (string, optional)
   - `due_on`: New milestone due date in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ) (string, optional)
@@ -553,11 +558,6 @@ The following sets of tools are available (all are on by default):
   - `state`: New milestone state (string, optional)
   - `title`: New milestone title (string, optional)
 
-- **delete_milestone** - Delete milestone
-  - `milestone_number`: The number of the milestone to delete (number, required)
-  - `owner`: Repository owner (string, required)
-  - `repo`: Repository name (string, required)
-
 - **get_issue** - Get issue details
   - `issue_number`: The number of the issue (number, required)
   - `owner`: The owner of the repository (string, required)
@@ -584,6 +584,15 @@ The following sets of tools are available (all are on by default):
   - `since`: Filter by date (ISO 8601 timestamp) (string, optional)
   - `state`: Filter by state, by default both open and closed issues are returned when not provided (string, optional)
 
+- **list_milestones** - List milestones
+  - `direction`: Sort direction (string, optional)
+  - `owner`: Repository owner (string, required)
+  - `page`: Page number for pagination (min 1) (number, optional)
+  - `perPage`: Results per page for pagination (min 1, max 100) (number, optional)
+  - `repo`: Repository name (string, required)
+  - `sort`: Sort field (string, optional)
+  - `state`: Filter by state (string, optional)
+
 - **list_sub_issues** - List sub-issues
   - `issue_number`: Issue number (number, required)
   - `owner`: Repository owner (string, required)
@@ -614,6 +623,12 @@ The following sets of tools are available (all are on by default):
   - `repo`: Optional repository name. If provided with owner, only issues for this repository are listed. (string, optional)
   - `sort`: Sort field by number of matches of categories, defaults to best match (string, optional)
 
+- **search_milestones** - Search milestones
+  - `owner`: Repository owner (string, required)
+  - `query`: Search query to filter milestones by title or description (string, required)
+  - `repo`: Repository name (string, required)
+  - `state`: Filter by state (string, optional)
+
 - **update_issue** - Edit issue
   - `assignees`: New assignees (string[], optional)
   - `body`: New description (string, optional)
diff --git a/pkg/github/__toolsnaps__/list_milestones.snap b/pkg/github/__toolsnaps__/list_milestones.snap
@@ -0,0 +1,61 @@
+{
+  "annotations": {
+    "title": "List milestones",
+    "readOnlyHint": true
+  },
+  "description": "List milestones for a repository.",
+  "inputSchema": {
+    "properties": {
+      "direction": {
+        "description": "Sort direction",
+        "enum": [
+          "asc",
+          "desc"
+        ],
+        "type": "string"
+      },
+      "owner": {
+        "description": "Repository owner",
+        "type": "string"
+      },
+      "page": {
+        "description": "Page number for pagination (min 1)",
+        "minimum": 1,
+        "type": "number"
+      },
+      "perPage": {
+        "description": "Results per page for pagination (min 1, max 100)",
+        "maximum": 100,
+        "minimum": 1,
+        "type": "number"
+      },
+      "repo": {
+        "description": "Repository name",
+        "type": "string"
+      },
+      "sort": {
+        "description": "Sort field",
+        "enum": [
+          "due_on",
+          "completeness"
+        ],
+        "type": "string"
+      },
+      "state": {
+        "description": "Filter by state",
+        "enum": [
+          "open",
+          "closed",
+          "all"
+        ],
+        "type": "string"
+      }
+    },
+    "required": [
+      "owner",
+      "repo"
+    ],
+    "type": "object"
+  },
+  "name": "list_milestones"
+}
diff --git a/pkg/github/__toolsnaps__/search_milestones.snap b/pkg/github/__toolsnaps__/search_milestones.snap
@@ -0,0 +1,39 @@
+{
+  "annotations": {
+    "title": "Search milestones",
+    "readOnlyHint": true
+  },
+  "description": "Search for milestones in a repository.",
+  "inputSchema": {
+    "properties": {
+      "owner": {
+        "description": "Repository owner",
+        "type": "string"
+      },
+      "query": {
+        "description": "Search query to filter milestones by title or description",
+        "type": "string"
+      },
+      "repo": {
+        "description": "Repository name",
+        "type": "string"
+      },
+      "state": {
+        "description": "Filter by state",
+        "enum": [
+          "open",
+          "closed",
+          "all"
+        ],
+        "type": "string"
+      }
+    },
+    "required": [
+      "owner",
+      "repo",
+      "query"
+    ],
+    "type": "object"
+  },
+  "name": "search_milestones"
+}
diff --git a/pkg/github/issues.go b/pkg/github/issues.go
@@ -206,6 +206,84 @@ func GetIssue(getClient GetClientFn, t translations.TranslationHelperFunc) (tool
 		}
 }
 
+// SearchMilestones creates a tool to search for milestones in a repository.
+func SearchMilestones(getClient GetClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) {
+	return mcp.NewTool("search_milestones",
+			mcp.WithDescription(t("TOOL_SEARCH_MILESTONES_DESCRIPTION", "Search for milestones in a repository.")),
+			mcp.WithToolAnnotation(mcp.ToolAnnotation{
+				Title:        t("TOOL_SEARCH_MILESTONES_USER_TITLE", "Search milestones"),
+				ReadOnlyHint: ToBoolPtr(true),
+			}),
+			mcp.WithString("owner",
+				mcp.Required(),
+				mcp.Description("Repository owner"),
+			),
+			mcp.WithString("repo",
+				mcp.Required(),
+				mcp.Description("Repository name"),
+			),
+			mcp.WithString("query",
+				mcp.Required(),
+				mcp.Description("Search query to filter milestones by title or description"),
+			),
+			mcp.WithString("state",
+				mcp.Description("Filter by state"),
+				mcp.Enum("open", "closed", "all"),
+			),
+		),
+		func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+			owner, err := RequiredParam[string](request, "owner")
+			if err != nil {
+				return mcp.NewToolResultError(err.Error()), nil
+			}
+			repo, err := RequiredParam[string](request, "repo")
+			if err != nil {
+				return mcp.NewToolResultError(err.Error()), nil
+			}
+			query, err := RequiredParam[string](request, "query")
+			if err != nil {
+				return mcp.NewToolResultError(err.Error()), nil
+			}
+			state, err := OptionalParam[string](request, "state")
+			if err != nil {
+				return mcp.NewToolResultError(err.Error()), nil
+			}
+
+			if state == "" {
+				state = "open"
+			}
+
+			opts := &github.MilestoneListOptions{
+				State: state,
+			}
+
+			client, err := getClient(ctx)
+			if err != nil {
+				return nil, fmt.Errorf("failed to get GitHub client: %w", err)
+			}
+
+			allMilestones, _, err := client.Issues.ListMilestones(ctx, owner, repo, opts)
+			if err != nil {
+				return nil, fmt.Errorf("failed to list milestones: %w", err)
+			}
+
+			var filteredMilestones []*github.Milestone
+			for _, milestone := range allMilestones {
+				if (milestone.Title != nil && strings.Contains(strings.ToLower(*milestone.Title), strings.ToLower(query))) ||
+					(milestone.Description != nil && strings.Contains(strings.ToLower(*milestone.Description), strings.ToLower(query))) {
+					filteredMilestones = append(filteredMilestones, milestone)
+				}
+			}
+
+			r, err := json.Marshal(filteredMilestones)
+			if err != nil {
+				return nil, fmt.Errorf("failed to marshal response: %w", err)
+			}
+
+			return mcp.NewToolResultText(string(r)), nil
+		}
+}
+
 // EditMilestone creates a tool to edit an existing milestone in a GitHub repository.
 func EditMilestone(getClient GetClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) {
 	return mcp.NewTool("edit_milestone",
@@ -474,6 +552,100 @@ func DeleteMilestone(getClient GetClientFn, t translations.TranslationHelperFunc
 		}
 }
 
+// ListMilestones creates a tool to list milestones for a repository.
+func ListMilestones(getClient GetClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) {
+	return mcp.NewTool("list_milestones",
+			mcp.WithDescription(t("TOOL_LIST_MILESTONES_DESCRIPTION", "List milestones for a repository.")),
+			mcp.WithToolAnnotation(mcp.ToolAnnotation{
+				Title:        t("TOOL_LIST_MILESTONES_USER_TITLE", "List milestones"),
+				ReadOnlyHint: ToBoolPtr(true),
+			}),
+			mcp.WithString("owner",
+				mcp.Required(),
+				mcp.Description("Repository owner"),
+			),
+			mcp.WithString("repo",
+				mcp.Required(),
+				mcp.Description("Repository name"),
+			),
+			mcp.WithString("state",
+				mcp.Description("Filter by state"),
+				mcp.Enum("open", "closed", "all"),
+			),
+			mcp.WithString("sort",
+				mcp.Description("Sort field"),
+				mcp.Enum("due_on", "completeness"),
+			),
+			mcp.WithString("direction",
+				mcp.Description("Sort direction"),
+				mcp.Enum("asc", "desc"),
+			),
+			WithPagination(),
+		),
+		func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+			owner, err := RequiredParam[string](request, "owner")
+			if err != nil {
+				return mcp.NewToolResultError(err.Error()), nil
+			}
+			repo, err := RequiredParam[string](request, "repo")
+			if err != nil {
+				return mcp.NewToolResultError(err.Error()), nil
+			}
+			state, err := OptionalParam[string](request, "state")
+			if err != nil {
+				return mcp.NewToolResultError(err.Error()), nil
+			}
+			sort, err := OptionalParam[string](request, "sort")
+			if err != nil {
+				return mcp.NewToolResultError(err.Error()), nil
+			}
+			direction, err := OptionalParam[string](request, "direction")
+			if err != nil {
+				return mcp.NewToolResultError(err.Error()), nil
+			}
+			pagination, err := OptionalPaginationParams(request)
+			if err != nil {
+				return mcp.NewToolResultError(err.Error()), nil
+			}
+
+			opts := &github.MilestoneListOptions{
+				State:     state,
+				Sort:      sort,
+				Direction: direction,
+				ListOptions: github.ListOptions{
+					Page:    pagination.Page,
+					PerPage: pagination.PerPage,
+				},
+			}
+
+			client, err := getClient(ctx)
+			if err != nil {
+				return nil, fmt.Errorf("failed to get GitHub client: %w", err)
+			}
+
+			milestones, resp, err := client.Issues.ListMilestones(ctx, owner, repo, opts)
+			if err != nil {
+				return nil, fmt.Errorf("failed to list milestones: %w", err)
+			}
+			defer func() { _ = resp.Body.Close() }()
+
+			if resp.StatusCode != http.StatusOK {
+				body, err := io.ReadAll(resp.Body)
+				if err != nil {
+					return nil, fmt.Errorf("failed to read response body: %w", err)
+				}
+				return mcp.NewToolResultError(fmt.Sprintf("failed to list milestones: %s", string(body))), nil
+			}
+
+			r, err := json.Marshal(milestones)
+			if err != nil {
+				return nil, fmt.Errorf("failed to marshal response: %w", err)
+			}
+
+			return mcp.NewToolResultText(string(r)), nil
+		}
+}
+
 // ListIssueTypes creates a tool to list defined issue types for an organization. This can be used to understand supported issue type values for creating or updating issues.
 func ListIssueTypes(getClient GetClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) {
 
diff --git a/pkg/github/issues_test.go b/pkg/github/issues_test.go
diff --git a/pkg/github/tools.go b/pkg/github/tools.go
