GitHub Issue MCP

GitHub Issue MCP Assistant

一个使用 Model Context Protocol（MCP）、Google Gemini、TypeScript 和 GitHub REST API 构建的 AI 驱动的 GitHub 问题管理系统。

GitHub Issue MCP 可以将简短的自然语言错误报告转化为结构化的 GitHub 问题，并在创建前智能检查是否存在重复问题。

该项目展示了一种受控的 Agent 工作流：Gemini 可以进行推理并使用 MCP 工具，而持久化的 GitHub 写入操作则由应用程序和用户明确控制。

此 MCP 服务也以可复用的 npm 包形式发布，可嵌入其他 Node.js 应用程序，或直接作为 MCP stdio 服务启动。

---

✨ 功能

• 🤖 使用 Google Gemini AI 驱动的问题生成
• 🔍 重复问题检测
• 🧠 语义重复分析，而非仅依赖关键词匹配
• 📝 交互式收集补充的问题详情
• 🏷️ 检索并验证仓库标签
• 👤 创建问题前由人工审批
• 🔐 防止自主 AI Agent 直接创建 GitHub 问题
• 🔄 自动重试临时的 Gemini API 故障
• 🚦 检测 Gemini 每日配额耗尽，避免不必要的重试
• ⚙️ 可配置 Gemini 模型和重试行为
• 🧪 全面的单元测试、工作流测试和集成测试
• 📦 可复用的 MCP 服务架构
• 🔌 已发布的 npm 包
• 🚀 可执行的 github-issue-mcp MCP CLI
• 🌐 已发布到官方 MCP Registry
• 🛡️ 受阶段限制的 AI 工具访问
• 🔗 分离 AI 推理与外部 GitHub 操作

---

📦 安装

从 npm 安装

npm install github-issue-mcp

The package is available on npm as:

github-issue-mcp

Current release:

v1.1.2
🚀 Quick Start
Run as an MCP server

The package exposes an executable MCP server CLI.

npx -y github-issue-mcp

The server communicates using MCP over stdio.

This is the recommended approach when configuring the server in an MCP-compatible client.

🔌 MCP Client Configuration

GitHub Issue MCP can be used with any MCP-compatible client that supports stdio servers.

Using npx

The simplest configuration uses the published npm package:

{
  "mcpServers": {
    "github-issue-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "github-issue-mcp"
      ],
      "env": {
        "GITHUB_TOKEN": "YOUR_GITHUB_TOKEN",
        "GITHUB_OWNER": "YOUR_GITHUB_OWNER",
        "GITHUB_REPO": "YOUR_GITHUB_REPO",
        "GEMINI_API_KEY": "YOUR_GEMINI_API_KEY"
      }
    }
  }
}

The MCP client starts:

npx -y github-issue-mcp

and communicates with the server over stdio.

⚙️ Configuration

Create a .env file when running the project locally.

GITHUB_TOKEN=your_github_token
GITHUB_OWNER=your_github_username
GITHUB_REPO=your_repository


GEMINI_API_KEY=your_gemini_api_key


GEMINI_MODEL=gemini-3.6-flash
GEMINI_MAX_RETRIES=3
GEMINI_RETRY_BASE_DELAY=1000


DEBUG=false
Environment variables
Variable	Required	Description	Default
GITHUB_TOKEN	Yes	GitHub API authentication token	Required
GITHUB_OWNER	Yes	GitHub repository owner or organization	Required
GITHUB_REPO	Yes	GitHub repository name	Required
GEMINI_API_KEY	Yes	Google Gemini API key	Required
GEMINI_MODEL	No	Gemini model used by the AI client	gemini-3.6-flash
GEMINI_MAX_RETRIES	No	Maximum number of Gemini retries	3
GEMINI_RETRY_BASE_DELAY	No	Base retry delay in milliseconds	1000
DEBUG	No	Enables debug behavior/logging	false

Never commit .env, GitHub tokens, or Gemini API keys to Git.

🧩 MCP Tools

The MCP server exposes the following tools:

Tool	Purpose
generate_issue	Generate a structured GitHub issue
create_github_issue	Create an issue on GitHub
list_github_issues	Retrieve open repository issues
list_github_labels	Retrieve repository labels
check_duplicate_issue	Find likely duplicate issue candidates
generate_issue

Generates a structured issue from supplied information.

Inputs
description
reproductionSteps
expectedBehavior
actualBehavior
environment
additionalContext
Example output
{
  "title": "Bug: Login button does not work",
  "body": "## Description\n\nLogin button does not work...",
  "labels": ["bug"]
}
check_duplicate_issue

Retrieves likely duplicate candidates from the repository.

The tool performs inexpensive lexical candidate ranking against existing open issues.

The similarity score is not treated as proof of duplication.

Gemini performs the final semantic analysis.

This keeps the expensive AI reasoning focused on a small candidate set rather than every issue in the repository.

list_github_issues

Retrieves open GitHub issues while filtering out pull requests.

list_github_labels

Retrieves labels available in the repository.

create_github_issue

Creates the final GitHub issue.

This tool is intentionally not exposed to the autonomous Gemini agent.

It is invoked directly by the client only after explicit human approval.

🏗️ Architecture
                         ┌──────────────────┐
                         │      User        │
                         └────────┬─────────┘
                                  │
                                  ▼
                         ┌──────────────────┐
                         │    CLI Client    │
                         └────────┬─────────┘
                                  │
                                  ▼
                    ┌──────────────────────────┐
                    │       MCP Client         │
                    └────────────┬─────────────┘
                                 │
                                 ▼
                    ┌──────────────────────────┐
                    │       MCP Server         │
                    └────────────┬─────────────┘
                                 │
              ┌──────────────────┼──────────────────┐
              │                  │                  │
              ▼                  ▼                  ▼
       Duplicate Check     Issue Generation    GitHub Tools
              │                  │                  │
              ▼                  ▼                  ▼
       Candidate Issues    Proposed Issue      GitHub REST API
              │                  │
              ▼                  ▼
       Gemini Semantic      Human Approval
          Analysis              │
              │                  │
         ┌────┴────┐        ┌────┴────┐
         │         │        │         │
        Yes        No       No       Yes
         │         │        │         │
         ▼         ▼        ▼         ▼
        Stop    Continue   Stop   Create Issue
🔑 Core Design Principle

The most important architectural decision is:

Gemini does not have autonomous access to the GitHub write operation.

The workflow is intentionally divided into controlled phases.

Phase 1
Duplicate Detection
        │
        ▼
Semantic Analysis
        │
        ▼
Phase 2
Collect Details
        │
        ▼
Phase 3
Issue Generation
        │
        ▼
Phase 4
Human Approval
        │
        ▼
Phase 5
GitHub Creation

This provides a clear human-in-the-loop safety boundary around persistent external side effects.

🔄 Workflow

The complete workflow is:

1. User describes an issue
              │
              ▼
2. Retrieve duplicate candidates
              │
              ▼
3. Gemini performs semantic analysis
              │
       ┌──────┴──────┐
       │             │
    Duplicate      No duplicate
       │             │
       ▼             ▼
      Stop    4. Collect additional details
                     │
                     ▼
             5. Gemini generates
                structured issue
                     │
                     ▼
             6. Display proposed issue
                     │
                     ▼
             7. Ask user for approval
                     │
              ┌──────┴──────┐
              │             │
             No            Yes
              │             │
              ▼             ▼
             Stop    8. Client creates
                       GitHub issue
🔍 Duplicate Detection

Duplicate detection is deliberately split into two stages.

Stage 1 — Candidate Retrieval

The MCP tool performs inexpensive lexical similarity/ranking against existing open issues.

For example:

User:


"The search results page crashes when I apply multiple filters."


                    │
                    ▼


          check_duplicate_issue


                    │
                    ▼


Candidate #8


"The search results page crashes
when I apply multiple filters."


Similarity: 0.21

The similarity score is only used to identify potentially relevant candidates.

It is not considered proof of duplication.

Stage 2 — Semantic Analysis

Gemini receives the candidate issues and determines whether any candidate describes the same underlying problem.

Example:

{
  "isDuplicate": true,
  "duplicateIssue": {
    "number": 8,
    "title": "Bug: The search results page crashes when I apply multiple filters.",
    "url": "https://github.com/example/repository/issues/8"
  },
  "reason": "The candidate describes the exact same underlying problem."
}

This prevents unrelated issues from being incorrectly classified as duplicates merely because they share common words such as:

login
page
button
crash
issue
🤖 Agent Workflow

The Gemini agent supports controlled multi-step tool execution.

Available MCP tools are restricted according to the current workflow phase.

Phase 1 — Duplicate Detection

Gemini receives:

check_duplicate_issue

The agent can use this tool to retrieve candidate issues.

It cannot use:

generate_issue
create_github_issue

during this phase.

Phase 3 — Issue Generation

Gemini receives:

list_github_labels
generate_issue

This allows the agent to inspect repository labels and generate the proposed issue.

It still cannot create the GitHub issue.

Phase 5 — Issue Creation

The autonomous Gemini agent does not receive:

create_github_issue

Instead, the application directly invokes the tool after explicit human approval.

🔐 Security Model

The project uses multiple layers to prevent unintended GitHub writes.

1. Phase-Based Tool Exposure

Available tools are restricted depending on the current workflow phase.

Duplicate Phase
      │
      └── check_duplicate_issue
Generate Phase
      │
      ├── list_github_labels
      └── generate_issue
Creation Phase
      │
      └── create_github_issue
             (client-controlled)
2. Autonomous Write Protection

The Gemini agent cannot directly invoke:

create_github_issue

Even if the model attempts to request the tool, the agent workflow rejects the operation.

3. Human Approval

The proposed issue is displayed to the user before creation.

Example:

================================
PROPOSED GITHUB ISSUE
================================


Title:
Bug: Login button does not work with valid credentials.


Labels:
bug


Body:


## Description


Login button does not work with valid credentials.


## Steps to Reproduce


Open login page → enter valid credentials → click Login.


## Expected Behavior


User should be redirected to the dashboard.


## Actual Behavior


Nothing happens after clicking Login.


Create this issue on GitHub? [y/N]:

Only explicit approval proceeds to the GitHub write operation.

👤 Human-in-the-Loop Creation

Issue creation is intentionally controlled by the application.

Gemini
   │
   ▼
Generate Proposed Issue
   │
   ▼
CLI Displays Issue
   │
   ▼
User Approval
   │
   ├── No ──► Stop
   │
   └── Yes
         │
         ▼
Client invokes create_github_issue
         │
         ▼
GitHub

Creating a GitHub issue is a persistent external side effect.

Therefore, the AI proposes the action while the user controls the final write operation.

🔄 Gemini Error Handling

The Gemini client includes retry handling for temporary API failures.

HTTP 429

The system distinguishes between temporary rate-limit errors and exhausted daily quotas.

Temporary 429 errors are retried according to the configured retry policy.

Daily quota exhaustion is detected separately and is not repeatedly retried because additional requests cannot succeed until the quota resets or a different Gemini project/model is used.

HTTP 5xx

Temporary Gemini server-side failures are retried automatically.

Examples include:

500
502
503
504
Retry Configuration

Retry behavior can be configured through environment variables:

GEMINI_MAX_RETRIES=3
GEMINI_RETRY_BASE_DELAY=1000

The retry delay increases between attempts.

Invalid JSON

If an MCP tool expected to return JSON produces malformed output, the agent reports a clear error.

Examples:

generate_issue returned invalid JSON.

or:

check_duplicate_issue returned invalid JSON.

This keeps failures localized and easier to diagnose.

📚 Use as a Library

GitHub Issue MCP is designed to be embedded into another Node.js application.

Create an MCP server
import {
  createGitHubIssueMcpServer
} from "github-issue-mcp/server";


const server = createGitHubIssueMcpServer({
  name: "my-github-issue-server",
  version: "1.0.0"
});

The server factory has no dependency on a specific transport, allowing the MCP server to be reused by different hosts and transports.

Start a stdio server
import {
  startStdioServer
} from "github-issue-mcp/server/stdio";


await startStdioServer();
Start the executable CLI
npx -y github-issue-mcp

The executable starts the reusable MCP server using the stdio transport.

📦 Package Exports

The npm package exposes the following public entry points:

github-issue-mcp
github-issue-mcp/server
github-issue-mcp/server/stdio
Server factory
import {
  createGitHubIssueMcpServer
} from "github-issue-mcp/server";
Stdio server
import {
  startStdioServer
} from "github-issue-mcp/server/stdio";
CLI
npx -y github-issue-mcp
🌐 MCP Registry

GitHub Issue MCP is published to the official MCP Registry.

Registry identifier:

io.github.sarim-aliii/github-issue-mcp

npm package:

github-issue-mcp

Current release:

v1.1.2

The Registry publication allows MCP-compatible ecosystems to discover the server using its official registry identity.

🧪 Testing

The project uses Vitest for automated testing.

The current test suite contains:

12 test files
47 tests
47 passing

Tests cover multiple layers of the application.

GitHub API Tests
tests/github/issues.test.ts

Validates:

GitHub issue retrieval
Pull-request filtering
Label retrieval
Label validation
Empty label handling
GitHub issue creation
GitHub API error handling
MCP Tool Tests
tests/tools/mcp-tools.test.ts

Validates:

MCP tool registration
MCP tool invocation
Tool argument handling
MCP error responses
Issue Generation Tests
tests/tools/generate-issue.test.ts

Validates:

Bug issue generation
Optional field handling
Fallback placeholders
Structured issue output
Duplicate Detection Tests
tests/tools/check-duplicate.test.ts

Validates:

Candidate retrieval
Similarity ranking
Candidate limiting
Duplicate detection behavior
Gemini Agent Tests
tests/client/agent.test.ts

Validates:

Gemini request handling
Temporary 429 retry behavior
Temporary 5xx retry behavior
Daily quota handling
Maximum retry behavior
Non-retryable errors
Agent Workflow Tests
tests/client/agent-workflow.test.ts

Validates:

Duplicate-check phase restrictions
Issue-generation phase restrictions
Label lookup
Structured issue generation
Autonomous creation protection
Malformed MCP responses
Workflow Tests
tests/client/workflow.test.ts

Validates:

Duplicate workflow termination
Successful issue generation and creation
Approval rejection
Missing generated issue handling
Configuration Tests
tests/client/config.test.ts

Validates:

Default Gemini configuration
Environment-variable configuration
MCP Integration Tests
tests/integration/mcp-server.test.ts

Validates:

MCP server startup
MCP connection behavior
MCP tool availability
Package API Integration Tests
tests/integration/package-api.test.ts

Validates the public npm package API and ensures the published package exposes the expected reusable server interfaces.

Issue Creation Safety Tests

The integration suite also validates that the issue creation boundary remains client-controlled and that the autonomous agent cannot bypass the intended approval flow.

▶️ Run Tests

Run the complete test suite:

npm test

Run TypeScript validation:

npm run typecheck

Build the project:

npm run build

Expected current result:

Test Files  12 passed (12)
Tests       47 passed (47)
📊 Test Coverage

The current suite validates:

✓ GitHub API interactions
✓ Issue listing
✓ Pull-request filtering
✓ Label retrieval
✓ Label validation
✓ Issue creation
✓ GitHub API error handling
✓ MCP tool registration
✓ MCP tool invocation
✓ Issue generation
✓ Duplicate candidate retrieval
✓ Lexical candidate ranking
✓ Semantic duplicate workflow
✓ Gemini retries
✓ Gemini 429 handling
✓ Gemini 5xx handling
✓ Gemini quota handling
✓ Malformed JSON handling
✓ Agent phase restrictions
✓ Human-controlled write boundary
✓ Workflow orchestration
✓ Approval handling
✓ MCP integration
✓ Package API
✓ Configuration defaults
✓ Environment-based configuration
🧪 Consumer Integration Testing

The project also validates installation from the built npm package in a clean consumer project.

The tested flow is:

Build package
      │
      ▼
npm pack
      │
      ▼
Install package in clean project
      │
      ▼
Import public API
      │
      ▼
Create MCP server
      │
      ▼
Start stdio server
      │
      ▼
Connect with MCP Client
      │
      ▼
Discover tools

The published package has been tested using:

npm install github-issue-mcp

and the executable:

npx github-issue-mcp

The consumer integration verifies that the expected MCP tools are available.

🛠️ Tech Stack
Language
TypeScript
Node.js
AI
Google Gemini
@google/genai
MCP
@modelcontextprotocol/sdk
Validation
Zod
CLI
Inquirer
Testing
Vitest
GitHub
GitHub REST API
📁 Project Structure
github-issue-mcp/
│   │   ├── agent.ts
│   │   ├── ai-client.ts
│   │   ├── approval.ts
│   │   ├── cli.ts
│   │   ├── config.ts
│   │   ├── index.ts
│   │   ├── issue-details.ts
│   │   ├── logger.ts
│   │   ├── tool-adapter.ts
│   │   └── workflow.ts
│   │
│   ├── github/
│   │   ├── client.ts
│   │   └── issues.ts
│   │
│   ├── server/
│   │   ├── cli.ts
│   │   ├── create-server.ts
│   │   ├── index.ts
│   │   └── stdio.ts
│   │
│   ├── tools/
│   │   ├── check-duplicate.ts
│   │   ├── create-issue.ts
│   │   ├── generate-issue.ts
│   │   ├── list-issues.ts
│   │   └── list-labels.ts
│   │
│   ├── types/
│   │   └── issue.ts
│   │
│   └── index.ts
│
├── examples/
│   ├── basic-server/
│   │   └── index.mjs
│   │
│   ├── stdio-client/
│   │   └── index.mjs
│   │
│   └── README.md
│
├── tests/
│   ├── client/
│   │   ├── agent.test.ts
│   │   ├── agent-workflow.test.ts
│   │   ├── config.test.ts
│   │   └── workflow.test.ts
│   │
│   ├── github/
│   │   └── issues.test.ts
│   │
│   ├── integration/
│   │   ├── issue-creation-safety.test.ts
│   │   ├── mcp-server.test.ts
│   │   └── package-api.test.ts
│   │
│   ├── server/
│   │   └── create-server.test.ts
│   │
│   └── tools/
│       ├── check-duplicate.test.ts
│       ├── generate-issue.test.ts
│       └── mcp-tools.test.ts
│
├── .env.example
├── .gitignore
├── package.json
├── server.json
├── tsconfig.json
└── README.md
⚙️ Local Development Setup
1. Clone the repository
git clone https://github.com/sarim-aliii/github-issue-mcp.git
cd github-issue-mcp
2. Install dependencies
npm install
3. Configure environment variables

Create a .env file:

GITHUB_TOKEN=your_github_token
GITHUB_OWNER=your_github_username
GITHUB_REPO=your_repository


GEMINI_API_KEY=your_gemini_api_key


GEMINI_MODEL=gemini-3.6-flash
GEMINI_MAX_RETRIES=3
GEMINI_RETRY_BASE_DELAY=1000


DEBUG=false

Never commit .env to Git.

▶️ Running the Assistant

The original interactive client can be started with:

npx tsx src/client/index.ts

The assistant will ask for a short issue description.

Example:

✔ Describe your issue:
The export button on the reports page does nothing when clicked.

The assistant will then:

1. Connect to the MCP server
2. Discover available MCP tools
3. Search for possible duplicates
4. Analyze candidates semantically
5. Stop if a duplicate exists
6. Ask for additional details
7. Generate a structured issue
8. Display the proposed issue
9. Ask for human confirmation
10. Create the issue if approved
💡 Example
Input
The export button on the reports page does nothing when clicked.
Additional Information
Reproduction
Open the reports page, select a report, and click Export.
Expected
The selected report should be downloaded as a CSV file.
Actual
Nothing happens after clicking Export.
Environment
Chrome 126, Windows 11, App v2.4.1.
Additional context
The issue occurs consistently.
Generated Issue
## Description


The export button on the reports page does nothing when clicked.


## Steps to Reproduce


Open the reports page, select a report, and click Export.


## Expected Behavior


The selected report should be downloaded as a CSV file.


## Actual Behavior


Nothing happens after clicking the Export button.


## Environment


Chrome 126, Windows 11, App v2.4.1.


## Additional Context


The issue occurs consistently.

The user then sees:

Create this issue on GitHub? [y/N]:

Only an explicit approval creates the issue.

🧠 Design Decisions
Why MCP?

MCP provides a standardized interface between the AI agent and external capabilities.

Instead of embedding GitHub API logic directly into the Gemini workflow, GitHub operations are exposed as MCP tools.

                 Gemini
                    │
                    │ MCP
                    ▼
              GitHub Tools
                    │
                    ▼
             GitHub REST API

This keeps the AI layer separated from external-service logic and makes the tools reusable.

Why separate duplicate retrieval and semantic analysis?

The candidate retrieval process is inexpensive and deterministic enough to narrow the search space.

Gemini then performs the more expensive semantic reasoning only on relevant candidates.

All Open Issues
      │
      ▼
Lexical Candidate Ranking
      │
      ▼
Small Candidate Set
      │
      ▼
Gemini Semantic Analysis
      │
      ▼
Duplicate / Not Duplicate

This is more efficient than asking an LLM to reason over every issue in a repository.

Why require human approval?

Creating a GitHub issue is a persistent external side effect.

The system therefore separates:

AI Reasoning

from:

External Write Operation

The AI proposes the issue while the user controls the final action.

Why restrict tools by phase?

Different workflow stages require different capabilities.

Giving the model access to every tool at every stage increases the possibility of unintended behavior.

Instead:

Duplicate Phase
       │
       ▼
check_duplicate_issue
Generate Phase
       │
       ├── list_github_labels
       └── generate_issue
Creation Phase
       │
       ▼
create_github_issue
(client controlled)

This makes the agent's permissions explicit and easier to reason about.

🛡️ Reliability

The project includes explicit handling for temporary Gemini failures.

Temporary 429
     │
     ▼
Retry according to policy
Temporary 5xx
     │
     ▼
Retry according to policy
Daily quota exhausted
     │
     ▼
Stop immediately

This avoids wasting retry attempts when a daily quota cannot be recovered through another request.

🚧 Future Improvements

Potential future improvements include:

More sophisticated duplicate-ranking algorithms
GitHub issue comments
Issue updates
Issue assignment
Milestone support
GitHub Projects integration
Pull-request creation
Automatic issue categorization
Repository-specific issue templates
Support for multiple GitHub repositories
Persistent conversation context
Streaming Gemini responses
More comprehensive end-to-end integration tests
Structured logging and observability
Metrics for agent/tool execution
Repository-specific issue policies
Additional MCP transports
🎯 Project Goals

This project demonstrates how to combine:

LLM Reasoning
      +
MCP Tool Calling
      +
External APIs
      +
Structured Validation
      +
Semantic Duplicate Detection
      +
Human Approval
      +
Automated Testing

The main goal is not simply to generate GitHub issues with AI.

The goal is to demonstrate a controlled agentic workflow where:

The model can reason
The model can use tools
Tool access is restricted by workflow phase
GitHub operations are isolated behind MCP
Duplicate detection combines deterministic retrieval with AI reasoning
Persistent writes require explicit human approval
Temporary AI failures are handled automatically
The MCP server can be reused independently of the interactive client
The package can be consumed by other Node.js applications
The package can be launched directly as an MCP stdio server
The workflow is covered by automated tests
📌 Current Status
Project
Functional
Package
github-issue-mcp
v1.1.2
MCP Registry
io.github.sarim-aliii/github-issue-mcp
TypeScript
✓ Typecheck passing
✓ Build passing
Tests
✓ 12 test files
✓ 47 tests
✓ 47 passing
Core Workflow
✓ MCP server
✓ MCP client
✓ Gemini integration
✓ Duplicate candidate retrieval
✓ Semantic duplicate analysis
✓ Issue generation
✓ Label retrieval
✓ Human approval
✓ GitHub issue creation
Reusable Package
✓ npm package
✓ Public server factory
✓ Public stdio server API
✓ Executable MCP CLI
✓ Consumer integration test
✓ Package API integration test
Safety
✓ Phase-restricted Gemini tools
✓ Autonomous write protection
✓ Client-controlled GitHub creation
✓ Human approval boundary
Reliability
✓ Gemini 429 retry handling
✓ Gemini 5xx retry handling
✓ Daily quota detection
✓ Configurable retry policy
✓ Invalid JSON handling
📄 License

This project is intended as a demonstration and reusable implementation of an AI-powered, MCP-based GitHub issue management workflow.

See the repository license for licensing terms.

🔗 Links

Repository:

https://github.com/sarim-aliii/github-issue-mcp

npm:

https://www.npmjs.com/package/github-issue-mcp

MCP Registry:

https://registry.modelcontextprotocol.io/