Issue Management
Relevant source files
The following files were used as context for generating this wiki page:
The Issue Management system in the GitHub MCP server provides a comprehensive suite of tools for interacting with GitHub issues. It enables Model Context Protocol (MCP) clients to create, retrieve, list, update, and search for issues, as well as manage comments and sub-issues. The system acts as a bridge between agentic workflows and the GitHub API, supporting both REST and GraphQL interfaces for complex operations.
Sources: pkg/github/issues.go:1-30, cmd/github-mcp-server/generate_docs.go:210-230
Architecture and API Integration
The system utilizes a dual-API approach, leveraging the GitHub REST API for standard resource manipulation and the GraphQL API (v4) for complex queries and specific mutations like closing issues as duplicates or managing suggested actors.
Core Components
- REST Client: Used for standard operations such as creating comments and initial issue creation.
- GraphQL Client: Used for high-performance listing with specific filters and advanced mutations.
- Tool Handlers: Functions that map MCP
CallToolRequestobjects to specific GitHub API calls.
Data Flow for Issue Retrieval
When a request is made to list issues, the system determines the appropriate GraphQL query structure based on the provided filters (e.g., labels or "since" timestamps).
Primary Issue Operations
The system exposes several tools to manage the lifecycle of an issue.
Issue Lifecycle Tools
| Tool Name | Description | Key Parameters |
|---|---|---|
create_issue | Opens a new issue in a repository. | owner, repo, title, body, assignees, labels |
get_issue | Retrieves full details for a specific issue. | owner, repo, issue_number |
update_issue | Modifies an existing issue, including state changes. | owner, repo, issue_number, state, state_reason |
search_issues | Finds issues using GitHub search syntax. | query, owner, repo, sort, order |
Sources: pkg/github/issues.go:580-600, pkg/github/issues.go:940-960, pkg/github/issues_test.go:420-450
Advanced State Management
The update_issue tool handles state transitions using the GraphQL API to support advanced reasons like marking an issue as a duplicate. This requires a two-step process to fetch the internal Node IDs for both the target issue and the "duplicate of" issue.
Sub-Issue Management
A specialized set of tools supports the management of sub-issues, allowing for hierarchical task organization.
add_sub_issue: Associates a child issue with a parent.list_sub_issues: Retrieves the hierarchy of tasks.reprioritize_sub_issue: Reorders sub-issues usingafter_idorbefore_idmarkers.remove_sub_issue: Detaches a sub-issue. Note: This currently uses direct HTTP DELETE due to library limitations.
Sources: pkg/github/issues.go:450-480, pkg/github/issues.go:530-550, pkg/github/issues_test.go:1180-1200
Automation and Agent Workflows
The system includes built-in workflows to facilitate autonomous agent actions.
Copilot Integration
The assign_copilot_to_issue tool allows for the "Copilot GitHub Coding Agent" to be assigned to a specific task. The system automatically searches through suggestedActors to find the correct bot ID (copilot-swe-agent) before performing the assignment.
Guided Prompts
The server provides structured prompts like IssueToFixWorkflow which guide an LLM through a multi-step process:
- Creating an issue with a clear description.
- Assigning the issue to the Copilot coding agent.
- Monitoring for the resulting Pull Request.
Sources: pkg/github/workflow_prompts.go:14-40
Data Structures
Issue Fragment
The system uses an IssueFragment to standardize data retrieved from GraphQL, ensuring consistency across different list operations.
| Field | Type | Description |
|---|---|---|
Number | githubv4.Int | The public issue number. |
Title | githubv4.String | The headline of the issue. |
Author | struct | Contains the Login of the creator. |
Labels | Nodes | List of applied labels (retrieves first 100). |
Comments | TotalCount | Count of total comments on the issue. |
Sources: pkg/github/issues.go:85-108
Conclusion
Issue Management within the GitHub MCP server is designed for both high-level automation and granular control. By abstracting the complexities of GitHub's REST and GraphQL APIs into standardized MCP tools, it enables agents to perform complex repository management tasks, from simple bug tracking to coordinated autonomous coding workflows.