# 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](https://cli.github.com/)** 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:
```json
{
"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:
```bash
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):
```json
{
"mcpServers": {
"commit-to-pr": {
"command": "npx",
"args": ["commit-to-pr-mcp@latest"]
}
}
}
```
</details>
<details>
<summary>Cursor</summary>
#### Click the button to install:
[](https://cursor.com/en-US/install-mcp?name=commit-to-pr&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyJjb21taXQtdG8tcHItbWNwQGxhdGVzdCJdfQ==)
#### 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:
```json
{
"mcpServers": {
"commit-to-pr": {
"command": "npx",
"args": ["commit-to-pr-mcp@latest"]
}
}
}
```
</details>
<details>
<summary>VS Code</summary>
Follow the [MCP install guide](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server), use the standard config above.
Alternatively, install using the VS Code CLI:
```bash
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:
```json
{
"mcpServers": {
"commit-to-pr": {
"command": "npx",
"args": [
"commit-to-pr-mcp@latest"
]
}
}
}
```
</details>
<details>
<summary>Zed</summary>
Follow the [MCP Servers documentation](https://zed.dev/docs/assistant/model-context-protocol). Use the standard config above.
</details>
---
### Local Development
For local development and testing:
```json
{
"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
```typescript
{
"commit": "abc123def456",
"repo": "owner/repo" // Optional: auto-detected from git working directory
}
```
### Example: Get PR from Branch Name
```typescript
{
"commit": "feature/new-feature",
"cwd": "/path/to/repo" // Optional: specify working directory for auto-detection
}
```
### Example: Get PR by Number Directly
```typescript
{
"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:
```typescript
{
"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:
```json
{
"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
```bash
npm install
npm run build
```
### Testing
For local testing:
1. Build the project:
```bash
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](https://modelcontextprotocol.io)
- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
- [GitHub CLI](https://cli.github.com/)
