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

• Why MCP

• Architecture

• Project Structure

• MCP Tools

• Tool Workflow

• Issue Intelligence Workflow

• Technology Stack

• Prerequisites

• Installation

• Environment Configuration

• Running Locally

• Connecting Cursor

• Example Prompts

• HTTP Endpoints

• Docker

• Development

• Security

• Future Improvements

• 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:

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:

"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

Related MCP server: Narad GitHub Agent

High-Level Architecture

┌──────────────────────────────────────┐
│              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:

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.

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.

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

.cursor/mcp.json

Configures the MCP server so Cursor can connect to it.

Example:

{
  "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.

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:

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.

1. list_issues

Fetches issues from a GitHub repository.

Inputs

owner
repo
state

state supports:

open
closed
all

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

Example

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

2. triage_issue

Automatically classifies an issue and applies a GitHub label.

Current classification:

Bug-related issue       → bug
Feature/enhancement     → enhancement

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

bug
crash
error
broken
fails

Example

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:

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

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:

Critical
High
Medium
Low

Example

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

Example output:

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

owner
repo
issue_number
body

Example

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

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

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.

                 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:

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:

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

Install dependencies:

npm install

Environment Configuration

Create a .env file in the project root:

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:

.env
.env.*
!.env.example

An optional .env.example can be created:

GITHUB_TOKEN=
PORT=8080

Running Locally

Start the development server:

npm run dev

The server should start on:

http://localhost:8080

You should see:

MCP Server running on http://localhost:8080

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

Health Check

The server exposes:

GET /health

Example:

curl http://localhost:8080/health

Expected response:

{
  "status": "healthy"
}

MCP Endpoint

The MCP server is exposed through:

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:

.cursor/mcp.json

Example:

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

Start the server first:

npm run dev

Then refresh the MCP connection in Cursor.

The server should appear as:

github-issue-tracker

and Cursor should discover the available tools automatically.

Example Cursor Prompts

List Issues

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

Triage an Issue

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

Health Check

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

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

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

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:

docker build -t github-issue-tracker .

Run the container:

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:

http://localhost:8080

Health check:

http://localhost:8080/health

MCP endpoint:

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:

src/index.ts

Supporting tools/helpers:

src/tools.ts

Add a New MCP Tool

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

Conceptually:

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:

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:

                    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:

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:

MIT License

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