# GitHub Issue Intelligence MCP

An MCP (Model Context Protocol) server that connects AI clients such as Cursor with GitHub repositories and exposes purpose-built tools for issue management, issue analysis, prioritization, repository reporting, and release-note generation.

The project is built with **TypeScript + Node.js + Express**, uses the **Model Context Protocol SDK** for tool exposure, and uses **Octokit** to communicate with the GitHub REST API.

---

## Table of Contents

- [Overview](#overview)
- [Why MCP](#why-mcp)
- [Architecture](#architecture)
- [Project Structure](#project-structure)
- [MCP Tools](#mcp-tools)
- [Tool Workflow](#tool-workflow)
- [Issue Intelligence Workflow](#issue-intelligence-workflow)
- [Technology Stack](#technology-stack)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Environment Configuration](#environment-configuration)
- [Running Locally](#running-locally)
- [Connecting Cursor](#connecting-cursor)
- [Example Prompts](#example-prompts)
- [HTTP Endpoints](#http-endpoints)
- [Docker](#docker)
- [Development](#development)
- [Security](#security)
- [Future Improvements](#future-improvements)
- [License](#license)

---

# Overview

GitHub provides a powerful REST API, but an AI agent should not need to understand every GitHub API endpoint to perform common issue-management tasks.

This project adds an **MCP layer** between the AI client and GitHub.

Instead of asking an AI agent to manually construct GitHub API requests, the MCP server exposes higher-level tools such as:

- `list_issues`
- `triage_issue`
- `issue_health_check`
- `prioritize_issues`
- `add_comment`
- `weekly_digest`
- `release_notes`

This allows an MCP-compatible client such as Cursor to interact with GitHub through a small, controlled set of workflows.

---

# Why MCP?

Without MCP, an AI agent would need a direct GitHub integration and would have to understand how to perform individual GitHub API operations.

With this project:

```text
User
  |
  v
Cursor / MCP Client
  |
  | MCP
  v
GitHub Issue Intelligence MCP
  |
  | Octokit / GitHub REST API
  v
GitHub Repository
```

The MCP server acts as an **application layer** that converts GitHub API capabilities into workflows that are easier for an AI agent to use.

For example:

```text
"Check whether issue #1 is ready for development."

             ↓

       issue_health_check

             ↓

       GitHub REST API

             ↓

     Analyze issue fields

             ↓

     Health score + report
```

The value of the project is therefore not simply "calling GitHub APIs"; it is exposing **useful issue-management intelligence as MCP tools**.

---

# Architecture

## High-Level Architecture

```text
┌──────────────────────────────────────┐
│              User                    │
│                                      │
│ "Prioritize all open issues"         │
└──────────────────┬───────────────────┘
                   │
                   v
┌──────────────────────────────────────┐
│          Cursor / MCP Client          │
│                                      │
│  Discovers and invokes MCP tools     │
└──────────────────┬───────────────────┘
                   │
                   │ Streamable HTTP
                   v
┌──────────────────────────────────────┐
│       GitHub Issue Intelligence      │
│              MCP Server              │
│                                      │
│  Express                           │
│    │                                 │
│    └── /mcp                          │
│          │                            │
│          v                            │
│      McpServer                       │
│          │                            │
│          ├── list_issues              │
│          ├── triage_issue             │
│          ├── issue_health_check       │
│          ├── prioritize_issues        │
│          ├── add_comment              │
│          ├── weekly_digest            │
│          └── release_notes            │
│                                      │
└──────────────────┬───────────────────┘
                   │
                   │ Octokit
                   v
┌──────────────────────────────────────┐
│              GitHub API               │
│                                      │
│  Issues        Pull Requests         │
│  Labels        Comments              │
└──────────────────────────────────────┘
```

---

# Request Flow

A typical tool request follows this path:

```text
1. User gives instruction
          |
          v
2. Cursor selects an MCP tool
          |
          v
3. Cursor sends MCP request to /mcp
          |
          v
4. Express receives HTTP request
          |
          v
5. MCP SDK routes request to tool
          |
          v
6. Tool calls GitHub through Octokit
          |
          v
7. GitHub returns repository data
          |
          v
8. Tool processes the result
          |
          v
9. MCP response is returned to Cursor
          |
          v
10. Cursor presents result to user
```

---

# Project Structure

The repository is organized into application source code, MCP configuration, deployment files, and development configuration.

```text
github-issue-tracker/
│
├── .cursor/
│   ├── mcp.json
│   └── rules/
│
├── .vscode/
│
├── node_modules/
│
├── scripts/
│
├── src/
│   ├── index.ts
│   └── tools.ts
│
├── tests/
│
├── .dockerignore
├── .gitignore
├── CLAUDE.md
├── Dockerfile
├── mcpize.yaml
├── package.json
├── package-lock.json
├── README.md
└── tsconfig.json
```

## Directory and File Responsibilities

### `.cursor/`

Contains Cursor-specific configuration.

```text
.cursor/
├── mcp.json
└── rules/
```

### `.cursor/mcp.json`

Configures the MCP server so Cursor can connect to it.

Example:

```json
{
  "mcpServers": {
    "github-issue-tracker": {
      "url": "http://127.0.0.1:8080/mcp"
    }
  }
}
```

### `.cursor/rules/`

Contains project-specific Cursor rules and instructions.

These can be used to guide how Cursor works with the project.

---

## `.vscode/`

Contains Visual Studio Code / Cursor editor-specific configuration.

---

## `scripts/`

Contains project scripts and supporting development automation.

---

## `src/`

This is the main application source directory.

```text
src/
├── index.ts
└── tools.ts
```

### `src/index.ts`

The main MCP server entry point.

Responsibilities include:

- Creating the MCP server
- Registering MCP tools
- Creating the Express application
- Configuring the `/health` endpoint
- Configuring the `/mcp` endpoint
- Creating the Streamable HTTP transport
- Connecting the MCP server to the transport
- Starting the HTTP server
- Handling graceful shutdown

The MCP tools are registered through the server created by `createMcpServer()`.

### `src/tools.ts`

Contains supporting tool/helper functionality used by the project.

Keeping reusable functionality separate from the main server setup makes the project easier to extend as the number of tools grows.

---

## `tests/`

Contains automated tests for the project.

As the project grows, this directory can contain tests for:

- Tool input validation
- Issue classification
- Priority scoring
- Health-check logic
- GitHub API behavior
- MCP endpoint behavior

---

## `Dockerfile`

Defines how the application can be packaged into a Docker container.

This makes the MCP server suitable for container-based deployment.

---

## `mcpize.yaml`

Contains MCPize-related project/deployment configuration.

---

## `package.json`

Defines:

- Project metadata
- Dependencies
- Development dependencies
- npm scripts

---

## `tsconfig.json`

Contains TypeScript compiler configuration.

---

## `.gitignore`

Prevents files such as the following from being committed:

```text
node_modules/
dist/
.env
logs
editor-specific files
```

Keeping `.env` out of Git is especially important because it contains the GitHub token.

---

# MCP Tools

The server currently exposes seven main tools.

| Tool | Type | Purpose |
|---|---|---|
| `list_issues` | Read | List repository issues |
| `triage_issue` | Write | Classify and label an issue |
| `weekly_digest` | Read | Summarize recent issue activity |
| `release_notes` | Read/Generate | Generate notes from merged PRs |
| `add_comment` | Write | Add a GitHub comment |
| `issue_health_check` | Read/Analyze | Check issue quality and readiness |
| `prioritize_issues` | Read/Analyze | Rank open issues by priority |

---

# 1. `list_issues`

Fetches issues from a GitHub repository.

### Inputs

```text
owner
repo
state
```

`state` supports:

```text
open
closed
all
```

Pull requests are filtered out so the result focuses on actual issues.

### Example

```text
List all open issues in codecrafters-alt/mcp-test-lab.
```

---

# 2. `triage_issue`

Automatically classifies an issue and applies a GitHub label.

Current classification:

```text
Bug-related issue       → bug
Feature/enhancement     → enhancement
```

The classification logic uses issue text and can detect bug-related signals such as:

```text
bug
crash
error
broken
fails
```

### Example

```text
Triage issue #1 in codecrafters-alt/mcp-test-lab.
```

---

# 3. `issue_health_check`

Determines whether a GitHub issue contains enough information for development.

The tool checks:

- Clear title
- Detailed description
- Reproduction steps
- Expected behavior
- Actual behavior
- Labels

It then calculates a health score out of 10.

### Why reproduction steps matter

Reproduction steps tell a developer:

> If I follow these steps, I should be able to make the bug happen again.

For example:

```text
Steps to reproduce:

1. Send POST /login
2. Set username to an empty string
3. Provide a valid password
4. Send the request
```

### Example result

```text
Health Score: 7/10
Status: Needs More Information

Missing Information:
- Reproduction steps
- Expected behavior

Recommendation:
Add the missing information before starting development.
```

---

# 4. `prioritize_issues`

Analyzes open issues and ranks them according to a priority score.

The current scoring logic considers signals such as:

- Critical keywords
- Bugs
- Enhancements/features
- Urgency
- Security-related terms

The resulting priority levels are:

```text
Critical
High
Medium
Low
```

### Example

```text
Prioritize all open issues in codecrafters-alt/mcp-test-lab.
```

Example output:

```text
Issue Priority Ranking

1. #1 - Login API returns 500 when username is empty
   Priority: High
   Score: 8
   Reasons: Bug, Urgent

2. #3 - Issue tracker shows duplicate issues
   Priority: Medium
   Score: 3
   Reasons: Bug

3. #2 - Add pagination to issue listing API
   Priority: Low
   Score: 1
   Reasons: Feature/enhancement
```

---

# 5. `add_comment`

Adds a comment to a GitHub issue or pull request.

### Inputs

```text
owner
repo
issue_number
body
```

### Example

```text
Add a comment to issue #1:

"This issue has been automatically reviewed by the MCP server."
```

---

# 6. `weekly_digest`

Summarizes repository activity from the previous seven days.

It can be used to quickly understand recent issue activity without manually browsing GitHub.

### Example

```text
Give me the weekly digest for codecrafters-alt/mcp-test-lab.
```

---

# 7. `release_notes`

Generates Markdown release notes from recently merged pull requests.

The tool:

1. Fetches recently closed pull requests.
2. Filters for merged pull requests.
3. Extracts PR titles and authors.
4. Produces Markdown release notes.

### Example

```text
Generate release notes for codecrafters-alt/mcp-test-lab.
```

---

# Issue Intelligence Workflow

The strongest part of the project is the combination of the health-check, triage, comment, and prioritization tools.

```text
                 GitHub Issues
                       |
                       v
             ┌──────────────────┐
             │ Issue Health Check│
             └────────┬─────────┘
                      |
             Is the issue complete?
                 /            \
               No              Yes
               |                |
               v                v
         Missing info       Triage Issue
               |                |
               v                v
         Add Comment        Add Label
                                |
                                v
                       Prioritize Issues
                                |
                                v
                       Development Queue
```

This workflow moves beyond simple GitHub CRUD operations and demonstrates how MCP can provide higher-level issue-management workflows.

---

# Example End-to-End Workflow

A user can ask Cursor:

```text
Using the GitHub Issue Tracker MCP:

1. Analyze all open issues.
2. Triage each issue.
3. Check the health of each issue.
4. Identify issues missing important information.
5. Add a health report comment where appropriate.
6. Prioritize the open issues.
7. Show me the final priority ranking.
```

The MCP server can then coordinate the individual tools to complete the workflow.

---

# Technology Stack

## Runtime

- Node.js
- TypeScript

## MCP

- Model Context Protocol
- `@modelcontextprotocol/sdk`
- Streamable HTTP transport

## Web Server

- Express

## GitHub Integration

- Octokit
- GitHub REST API

## Validation

- Zod

## Configuration

- dotenv

## Development / Deployment

- npm
- TypeScript
- Docker
- MCPize configuration

---

# Prerequisites

Install the following before running the project:

- Node.js
- npm
- Git
- Cursor or another MCP-compatible client
- A GitHub account
- A GitHub Personal Access Token

---

# Installation

Clone the repository:

```bash
git clone <your-repository-url>
cd github-issue-tracker
```

Install dependencies:

```bash
npm install
```

---

# Environment Configuration

Create a `.env` file in the project root:

```env
GITHUB_TOKEN=your_github_token
PORT=8080
```

The GitHub token is used by Octokit to authenticate requests to GitHub.

Never commit the `.env` file.

The repository's `.gitignore` should contain:

```text
.env
.env.*
!.env.example
```

An optional `.env.example` can be created:

```env
GITHUB_TOKEN=
PORT=8080
```

---

# Running Locally

Start the development server:

```bash
npm run dev
```

The server should start on:

```text
http://localhost:8080
```

You should see:

```text
MCP Server running on http://localhost:8080

Health: http://localhost:8080/health
MCP:    http://localhost:8080/mcp
```

---

# Health Check

The server exposes:

```text
GET /health
```

Example:

```bash
curl http://localhost:8080/health
```

Expected response:

```json
{
  "status": "healthy"
}
```

---

# MCP Endpoint

The MCP server is exposed through:

```text
POST /mcp
```

The endpoint uses the MCP SDK's **Streamable HTTP transport**.

Cursor connects to this endpoint through the MCP configuration.

---

# Connecting to Cursor

Create or update:

```text
.cursor/mcp.json
```

Example:

```json
{
  "mcpServers": {
    "github-issue-tracker": {
      "url": "http://127.0.0.1:8080/mcp"
    }
  }
}
```

Start the server first:

```bash
npm run dev
```

Then refresh the MCP connection in Cursor.

The server should appear as:

```text
github-issue-tracker
```

and Cursor should discover the available tools automatically.

---

# Example Cursor Prompts

## List Issues

```text
Using the GitHub Issue Tracker MCP, list all open issues in
codecrafters-alt/mcp-test-lab.
```

## Triage an Issue

```text
Using the GitHub Issue Tracker MCP, triage issue #1 in
codecrafters-alt/mcp-test-lab and apply the appropriate label.
```

## Health Check

```text
Using the GitHub Issue Tracker MCP, run issue_health_check on
issue #1 in codecrafters-alt/mcp-test-lab.

Tell me:
1. The health score
2. Which checks passed
3. Which information is missing
4. Whether the issue is ready for development
```

## Health Check + Comment

```text
Using the GitHub Issue Tracker MCP:

1. Run issue_health_check on issue #1 in
   codecrafters-alt/mcp-test-lab.
2. Add the health-check report as a comment to issue #1.
3. Include the health score, status, passed checks,
   missing information, and recommendation.
4. Do not modify labels.
```

## Prioritize Issues

```text
Using the GitHub Issue Tracker MCP, analyze all open issues in
codecrafters-alt/mcp-test-lab and rank them by priority.

Show:
- Issue number
- Title
- Priority
- Score
- Reason
```

## Triage + Prioritize

```text
Using the GitHub Issue Tracker MCP:

1. Triage all open issues in codecrafters-alt/mcp-test-lab.
2. Apply the appropriate bug or enhancement label.
3. Run prioritize_issues.
4. Show the final priority ranking.
5. Do not add comments.
```

---

# Docker

The repository includes a `Dockerfile`, allowing the application to be containerized.

Build the image:

```bash
docker build -t github-issue-tracker .
```

Run the container:

```bash
docker run --rm -p 8080:8080 \
  -e GITHUB_TOKEN=your_github_token \
  -e PORT=8080 \
  github-issue-tracker
```

The application can then be accessed at:

```text
http://localhost:8080
```

Health check:

```text
http://localhost:8080/health
```

MCP endpoint:

```text
http://localhost:8080/mcp
```

For production deployments, use a secure secret-management mechanism rather than placing secrets directly in commands or configuration files.

---

# Development

## TypeScript

The application source is written in TypeScript.

Main entry point:

```text
src/index.ts
```

Supporting tools/helpers:

```text
src/tools.ts
```

## Add a New MCP Tool

New tools should be registered with the MCP server inside the server creation flow.

Conceptually:

```text
createMcpServer()
      |
      ├── registerTool(...)
      ├── registerTool(...)
      ├── registerTool(...)
      └── registerTool(...)
```

This keeps the MCP server's tool registry together and ensures that the server instance used by the HTTP endpoint exposes the tools.

---

# Design Principles

## 1. Purpose-built tools

Tools represent meaningful workflows rather than exposing every GitHub API endpoint directly.

## 2. Clear input schemas

Zod is used to validate tool inputs.

## 3. Separation of responsibilities

The application separates:

```text
HTTP transport
      |
MCP server
      |
MCP tools
      |
GitHub API
```

## 4. AI-friendly outputs

Tool responses are formatted so an AI client can easily understand and present the result.

## 5. Controlled GitHub access

The MCP server provides a defined set of GitHub operations rather than giving an AI agent unrestricted API access.

---

# Security

The GitHub token is sensitive.

Never:

- Commit `.env`
- Put the token directly in source code
- Print the token in logs
- Share the token publicly
- Add the token to the README

If a token is accidentally exposed, revoke it immediately and create a new one.

For production deployments, use environment variables or a managed secret store.

---

# Current Project Scope

The project currently focuses on GitHub issue intelligence and repository workflows.

The core capabilities are:

```text
                    GitHub Issue Intelligence
                              |
       ┌──────────────────────┼──────────────────────┐
       |                      |                      |
       v                      v                      v
   Management             Intelligence            Reporting
       |                      |                      |
       |                      |                      |
 list_issues            health_check           weekly_digest
 triage_issue            prioritize             release_notes
 add_comment
```

---

# Future Improvements

Potential next steps include:

### Smarter Issue Classification

Replace simple keyword-based classification with a more robust classification system.

### Duplicate Issue Detection

Detect potentially duplicate issues by comparing titles and descriptions.

### Better Priority Analysis

Use additional signals such as:

- Issue age
- Number of comments
- Repository labels
- Assignees
- User impact
- Severity
- Dependencies

### Automated Issue Improvement

Allow the MCP server to identify missing issue information and generate a suggested issue template.

### AI-Based Health Analysis

Use an LLM to understand the semantic meaning of an issue rather than relying only on keyword checks.

### Multi-Repository Support

Allow the same MCP server to manage multiple repositories.

### Production Authentication

Add authentication and authorization for the MCP HTTP endpoint.

### Observability

Add structured logging, request tracing, metrics, and error monitoring.

### Cloud Deployment

Deploy the containerized MCP server to a cloud platform such as Google Cloud Run.

---

# Project Vision

The long-term goal is to evolve this from a basic GitHub MCP integration into an **AI-powered GitHub Issue Intelligence platform**.

The intended progression is:

```text
GitHub API Access
       ↓
MCP Tools
       ↓
Issue Intelligence
       ↓
Automated Workflows
       ↓
AI-Assisted Issue Management
```

The MCP layer makes GitHub functionality available to AI agents in a structured and reusable way.

---

# License

Add the project's chosen license here.

For example:

```text
MIT License
```

if the project is intended to be released under the MIT License.