commit-to-pr-mcp

An MCP (Model Context Protocol) server that enables AI agents to extract PR details from git commit hashes using the GitHub CLI.

Features

• Commit to PR Resolution: Automatically extracts PR numbers from commit hashes, merge commits, and squash commits
• Auto-Detection: Automatically detects GitHub repository from git working directory
• Comprehensive PR Data: Retrieves full PR details including title, description, author, status, labels, and reviews
• Flexible Input: Accepts commit hashes (full or short), branch names, or direct PR numbers
• Type-Safe: Built with TypeScript and Zod for runtime validation

Prerequisites

• Node.js >= 18.0.0
• GitHub CLI installed and authenticated (gh auth login)
• An MCP-compatible client (Cursor, Claude Desktop, VS Code, etc.)

Installation

Getting Started

First, install the commit-to-pr-mcp server with your client.

Standard config works in most tools:

{
  "mcpServers": {
    "commit-to-pr": {
      "command": "npx",
      "args": [
        "commit-to-pr-mcp@latest"
      ]
    }
  }
}

<details> <summary>Claude Code</summary>

Use the Claude Code CLI to add the server:

claude mcp add commit-to-pr npx commit-to-pr-mcp@latest

</details>

<details> <summary>Claude Desktop</summary>

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "commit-to-pr": {
      "command": "npx",
      "args": ["commit-to-pr-mcp@latest"]
    }
  }
}

</details>

<details> <summary>Cursor</summary>

Click the button to install:

Or install manually:

Go to Cursor Settings → MCP → Add new MCP Server. Name to your liking, use command type with the command npx commit-to-pr-mcp@latest. You can also verify config or add command arguments via clicking Edit.

Project-Specific Configuration

Create .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "commit-to-pr": {
      "command": "npx",
      "args": ["commit-to-pr-mcp@latest"]
    }
  }
}

</details>

<details> <summary>VS Code</summary>

Follow the MCP install guide, use the standard config above.

Alternatively, install using the VS Code CLI:

code --add-mcp '{"name":"commit-to-pr","command":"npx","args":["commit-to-pr-mcp@latest"]}'

</details>

<details> <summary>Cline</summary>

Add via the Cline VS Code extension settings or by updating your cline_mcp_settings.json file:

{
  "mcpServers": {
    "commit-to-pr": {
      "command": "npx",
      "args": [
        "commit-to-pr-mcp@latest"
      ]
    }
  }
}

</details>

<details> <summary>Zed</summary>

Follow the MCP Servers documentation. Use the standard config above.

</details>

---

Local Development

For local development and testing:

{
  "mcpServers": {
    "commit-to-pr": {
      "command": "node",
      "args": ["/absolute/path/to/commit-to-pr-mcp/dist/index.js"],
      "env": {
        "LOG_LEVEL": "debug"
      }
    }
  }
}

---

Verify Installation

After installation, verify commit-to-pr-mcp is working:

1. Restart your MCP client completely
2. Check connection status:
   • Cursor: Look for green dot in Settings → Tools & Integrations → MCP Tools
   • Claude Desktop: Check for "commit_to_pr" in available tools
   • VS Code: Verify in GitHub Copilot settings
3. Test with a simple query:

   Get PR details for commit abc123
   

If you see the AI agent use the get_pr tool and return PR information, you're all set! 🎉

Usage

The server provides a single tool: get_pr

Basic Example: Get PR from Commit Hash

{
  "commit": "abc123def456",
  "repo": "owner/repo"  // Optional: auto-detected from git working directory
}

Example: Get PR from Branch Name

{
  "commit": "feature/new-feature",
  "cwd": "/path/to/repo"  // Optional: specify working directory for auto-detection
}

Example: Get PR by Number Directly

{
  "pr_number": 42,
  "repo": "owner/repo"  // Optional: auto-detected from git working directory
}

Example: Auto-Detect Repository

When working in a git repository, you can omit the repo parameter:

{
  "commit": "abc123"
  // Repository is automatically detected from git remote
}

Tool Parameters

get_pr

Get PR details by commit hash or PR number. Extracts PR number from git commits (merge commits, squash commits) and returns full PR details.

Parameters:

• commit (optional): Git commit hash (full or short), branch name, or any git reference. Use this OR pr_number.
• pr_number (optional): PR number to look up directly. Use this OR commit.
• repo (optional): GitHub repository in owner/repo format. If not provided, auto-detects from cwd or current working directory.
• cwd (optional): Working directory path to auto-detect the GitHub repository from git remote.

Note: Either commit or pr_number must be provided.

Response Format

The tool returns a structured response:

{
  "number": 42,
  "title": "Add new feature",
  "body": "This PR adds a new feature...",
  "state": "MERGED",
  "url": "https://github.com/owner/repo/pull/42",
  "author": "username",
  "createdAt": "2025-01-15T10:30:00Z",
  "mergedAt": "2025-01-16T14:20:00Z",
  "baseRef": "main",
  "headRef": "feature/new-feature",
  "labels": ["enhancement", "ready-for-review"],
  "reviews": [
    {
      "author": "reviewer1",
      "state": "APPROVED",
      "submittedAt": "2025-01-16T12:00:00Z"
    },
    {
      "author": "reviewer2",
      "state": "CHANGES_REQUESTED",
      "submittedAt": "2025-01-16T13:00:00Z"
    }
  ]
}

Response Fields

• number: PR number
• title: PR title
• body: PR description/body text
• state: PR state (OPEN, CLOSED, MERGED)
• url: GitHub URL to the PR
• author: PR author username
• createdAt: Creation timestamp (ISO 8601)
• mergedAt: Merge timestamp (ISO 8601), null if not merged
• baseRef: Target branch name
• headRef: Source branch name
• labels: Array of label names
• reviews: Array of review objects with author, state, and submittedAt

How It Works

The server uses the GitHub CLI (gh) to:

1. Extract PR number from commits:

   • Searches PRs containing the commit hash
   • Parses merge commit messages (Merge pull request #123)
   • Parses squash commit messages ((#123))

2. Retrieve PR details:

   • Fetches comprehensive PR information via gh pr view
   • Includes reviews, labels, and metadata

3. Auto-detect repository:

   • Reads git remote get-url origin from the working directory
   • Extracts owner/repo format from the remote URL

Development

Setup

npm install
npm run build

Testing

For local testing:

1. Build the project:

   npm run build
   

2. Configure your MCP client to use the local build (see Local Development section above)

3. Test with an MCP Inspector or client

Development Scripts

• npm run build: Compile TypeScript to JavaScript
• npm run start: Run the compiled server
• npm run dev: Run the server in development mode with tsx

Architecture

src/
└── index.ts              # Main server implementation
    ├── Tool handlers     # get_pr tool logic
    ├── Git utilities     # Repository detection
    └── GitHub CLI        # PR extraction and details

License

ISC

Contributing

Contributions welcome! Please read the contributing guidelines and submit a PR.

Related Projects

• MCP Specification
• MCP TypeScript SDK
• GitHub CLI