Create Github Issue

Tool: mcp_github_get_me or mcp_github2_get_me

Call this first to confirm the authenticated user's identity and permissions. This ensures you have write access to create issues.

Action:

Call get_me with no parameters.

Expected output: A JSON object with the authenticated user's login, name, and scopes. If this fails, stop — the user likely needs to authenticate or configure the MCP server.

Step 2: Check for Issue Types (Organizations Only)

Tool: mcp_github_list_issue_types or mcp_github2_list_issue_types

If the repository is owned by an organization (not a personal account), check whether the organization has configured custom issue types.

Action:

Call list_issue_types with:
  owner: "<organization-name>"

Decision logic:

• If the tool returns issue types (e.g., Bug, Feature, Task), you must use the appropriate type field when creating the issue in Step 5.
• If the tool returns an empty list or an error, omit the type field entirely in Step 5.
• If the repository is owned by a personal account (not an org), skip this step.

Step 3: Search for Duplicate Issues

Tool: mcp_github_search_issues or activate activate_issue_and_commit_tools / activate_issue_and_commit_tools to access search_issues

Before creating a new issue, always search for existing issues that may already cover the same topic to avoid duplicates.

Action:

Call search_issues with:
  query: "<keywords from the issue title or description> repo:<owner>/<repo> is:issue"
  perPage: 10

Decision logic:

• If a matching open issue exists, do not create a duplicate. Instead, inform the user and link to the existing issue. Optionally suggest adding a comment to the existing issue.
• If a matching closed issue exists, inform the user and ask if they want to reopen it or create a new one.
• If no matches are found, proceed to Step 4.

Step 4: Compose the Issue Content

Before calling the creation tool, assemble all issue fields. Each field has specific formatting guidelines.

4a. Title

• Required. One clear, concise sentence.
• Start with a category prefix when applicable: [Bug], [Feature], [Chore], [Docs], [Refactor].
• Be specific: ❌ "Fix bug" → ✅ "[Bug] Login form crashes when email contains special characters"
• Maximum ~80 characters.

4b. Body

• Required. Use Markdown. Structure the body using the appropriate template below based on issue type.

Bug Report Template:

## Description
<1–3 sentences describing the problem.>

## Steps to Reproduce
1. <Step one>
2. <Step two>
3. <Step three>

## Expected Behavior
<What should happen.>

## Actual Behavior
<What actually happens. Include error messages, stack traces, or screenshots if available.>

## Environment
- **OS:** <e.g., Windows 11, macOS 14>
- **Browser/Runtime:** <e.g., Chrome 120, Node.js 20>
- **Version/Commit:** <e.g., v2.3.1 or commit SHA>

## Additional Context
<Any other relevant information, logs, or links.>

Feature Request Template:

## Summary
<1–2 sentences describing the desired feature.>

## Motivation
<Why is this feature needed? What problem does it solve?>

## Proposed Solution
<Describe the implementation approach or desired behavior.>

## Alternatives Considered
<What other approaches were evaluated and why they were not chosen?>

## Acceptance Criteria
- [ ] <Criterion 1>
- [ ] <Criterion 2>
- [ ] <Criterion 3>

## Additional Context
<Mockups, links, or related issues.>

Task / Chore Template:

## Summary
<1–2 sentences describing the task.>

## Details
<Detailed description of what needs to be done.>

## Checklist
- [ ] <Subtask 1>
- [ ] <Subtask 2>
- [ ] <Subtask 3>

## Related Issues
<Links to related issues or PRs, if any.>

If the user has provided free-form text, restructure it into the most appropriate template above. Do not discard any information the user provided.

4c. Labels

• Optional but recommended. Use labels that already exist in the repository.
• Common convention: bug, enhancement, documentation, good first issue, help wanted, priority:high, priority:low.
• If unsure which labels exist, call get_label with the suspected label name to verify, or use search_issues output to observe labels on similar issues.
• Do not invent labels that do not exist — the API will reject them.

4d. Assignees

• Optional. Array of GitHub usernames to assign.
• Only assign users who are collaborators of the repository. If unsure, omit this field.
• If the user asks to self-assign, use the login returned from Step 1.

4e. Milestone

• Optional. Integer milestone number (not the milestone title).
• Only include if the user specifies a milestone or one can be inferred from context.

4f. Issue Type (Organizations with Issue Types)

• Conditional. Only include if Step 2 returned valid issue types.
• Set to the exact string value returned by list_issue_types (e.g., "Bug", "Feature").

Step 5: Create the Issue

Tool: mcp_github_issue_write

Action:

Call issue_write with:
  method: "create"
  owner: "<owner>"
  repo: "<repo>"
  title: "<composed title from Step 4a>"
  body: "<composed body from Step 4b>"
  labels: [<labels from Step 4c>]          # omit if none
  assignees: [<assignees from Step 4d>]    # omit if none
  milestone: <milestone from Step 4e>      # omit if none
  type: "<type from Step 4f>"             # omit if not applicable

Expected output: A JSON object containing the created issue's number, html_url, title, and state.

Error handling:

• 422 Validation Error: Usually means a label does not exist, an assignee is not a collaborator, or a required field is missing. Read the error message, correct the field, and retry once.
• 403 Forbidden: The authenticated user lacks write access. Inform the user.
• 404 Not Found: The owner/repo combination is incorrect. Verify and retry.

Step 6: Confirm and Report

After successful creation, report back to the user with:

1. Issue number and URL (from the API response).
2. Title as created.
3. Summary of labels, assignees, and milestone if any were applied.

Format:

Created issue #<number>: <title>
URL: <html_url>
Labels: <labels or "none">
Assignees: <assignees or "none">

Rules and Constraints

• Never create an issue without first searching for duplicates (Step 3). This is mandatory.
• Never invent labels that do not exist in the repository — the API will return a 422 error.
• Never assign users who are not collaborators of the repository.
• Always use the method: "create" parameter when calling issue_write for new issues. Use method: "update" only for modifying existing issues.
• Always structure the body using one of the templates in Step 4b. Raw unformatted text is not acceptable.
• Always check for issue types in organization-owned repositories before creating issues.
• If the user's request is ambiguous, infer the most reasonable issue type (bug vs. feature vs. task) from context. If genuinely unclear, ask the user one clarifying question before proceeding.
• Omit optional fields rather than setting them to empty values or guessing.

Quick Reference: Tool Parameter Summary