# mcp-pagure

[![PyPI version](https://badge.fury.io/py/mcp-pagure.svg)](https://badge.fury.io/py/mcp-pagure)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

MCP server for [Pagure](https://pagure.io) - enables AI assistants to manage issues, pull requests, and projects on Pagure instances (pagure.io and self-hosted).

## Features

- **Read Operations**: List/get projects, issues, pull requests, branches, and user info
- **Write Operations**: Create issues, add comments, update status, assign issues, merge/close PRs
- **Multi-instance Support**: Works with pagure.io and self-hosted Pagure instances
- **Namespace Support**: Full support for namespaced projects (rpms/*, container/*, etc.)

## Installation

### Using uvx (recommended)

```bash
uvx mcp-pagure
```

### Using pip

```bash
pip install mcp-pagure
```

## Configuration

### Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `PAGURE_API_TOKEN` | Yes | - | Your Pagure API token |
| `PAGURE_URL` | No | `https://pagure.io` | Base URL for Pagure instance |

### Getting an API Token

1. Go to your Pagure instance (e.g., https://pagure.io)
2. Navigate to **Settings** → **API Keys**
3. Create a new token with the permissions you need:
   - `issue_create` - Create new issues
   - `issue_update` - Update issues (status, assignee, comments)
   - `pull_request_merge` - Merge pull requests
   - `pull_request_close` - Close pull requests
   - `pull_request_comment` - Comment on pull requests

## Usage with Claude Code

Add to your Claude Code MCP configuration (`~/.claude/claude_code_config.json`):

```json
{
  "mcpServers": {
    "pagure": {
      "command": "uvx",
      "args": ["mcp-pagure"],
      "env": {
        "PAGURE_API_TOKEN": "your-api-token-here",
        "PAGURE_URL": "https://pagure.io"
      }
    }
  }
}
```

### For Fedora's src.fedoraproject.org

```json
{
  "mcpServers": {
    "fedora-dist-git": {
      "command": "uvx",
      "args": ["mcp-pagure"],
      "env": {
        "PAGURE_API_TOKEN": "your-fedora-token",
        "PAGURE_URL": "https://src.fedoraproject.org"
      }
    }
  }
}
```

## Available Tools

### Read Operations

| Tool | Description |
|------|-------------|
| `whoami` | Get information about the authenticated user |
| `list_projects` | Search/list projects with filters (pattern, owner, namespace, fork status) |
| `get_project` | Get detailed project information |
| `list_issues` | List issues with filtering (status, tags, assignee, author, search) |
| `get_issue` | Get issue details including all comments |
| `list_pull_requests` | List PRs with filtering (status, assignee, author) |
| `get_pull_request` | Get PR details including commits and comments |
| `get_user` | Get user profile information |
| `list_branches` | List git branches in a repository |

### Write Operations

| Tool | Description |
|------|-------------|
| `create_issue` | Create a new issue with title, description, tags, assignee |
| `add_issue_comment` | Add a comment to an existing issue |
| `update_issue_status` | Change issue status (Open/Closed) with optional close reason |
| `assign_issue` | Assign or unassign an issue to a user |
| `add_pr_comment` | Add a comment to a pull request (general or inline) |
| `merge_pull_request` | Merge a pull request |
| `close_pull_request` | Close a pull request without merging |

## Examples

### List issues in a project

```
List open issues in the pagure project
```

### Create an issue

```
Create an issue in mcp-pagure titled "Add webhook support" with description "We should add support for Pagure webhooks to enable real-time notifications"
```

### Work with namespaced projects

```
List pull requests in rpms/kernel
```

### Search for projects

```
Find projects matching "container"
```

## Development

### Setup

```bash
git clone https://github.com/fatherlinux/mcp-pagure.git
cd mcp-pagure
uv sync --dev
```

### Run tests

```bash
uv run python -m pytest -v
```

### Run the server locally

```bash
export PAGURE_API_TOKEN="your-token"
uv run mcp-pagure
```

### Test with MCP Inspector

```bash
npx @modelcontextprotocol/inspector uv run mcp-pagure
```

## Supported Pagure Instances

- [pagure.io](https://pagure.io) - Main Pagure instance
- [src.fedoraproject.org](https://src.fedoraproject.org) - Fedora dist-git
- Any self-hosted Pagure instance

## License

MIT License - see [LICENSE](LICENSE) for details.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Related Projects

- [Pagure](https://pagure.io/pagure) - The git-centered forge
- [Model Context Protocol](https://modelcontextprotocol.io/) - The MCP specification