gitea-mcp-remote/README.md

# Gitea MCP Server

A Model Context Protocol (MCP) server that enables AI assistants like Claude to interact with Gitea repositories through its API. This server provides tools for managing issues, labels, and milestones in your Gitea instance.

## Features

- **Issue Operations**: List, get, create, and update issues with full support for labels, milestones, and assignees
- **Label Management**: List and create labels with custom colors and descriptions
- **Milestone Management**: List and create milestones with due dates and descriptions
- **Async API**: Built on modern async Python for efficient operations
- **Type Safety**: Full type hints for better IDE support and code quality

## Requirements

- Python >= 3.10
- Gitea instance with API access
- Gitea API token with appropriate permissions

## Installation

### From Source

```bash
# Clone the repository
git clone https://github.com/lmiranda/gitea-mcp-remote.git
cd gitea-mcp-remote

# Install the package
pip install -e .
```

### For Development

Install with development dependencies:

```bash
pip install -e ".[dev]"
```

## Configuration

The server requires two environment variables to connect to your Gitea instance:

- `GITEA_API_URL`: Base URL of your Gitea instance (e.g., `https://gitea.example.com/api/v1`)
- `GITEA_API_TOKEN`: Personal access token for authentication

### Creating a .env File

Create a `.env` file in your project directory:

```bash
GITEA_API_URL=https://gitea.example.com/api/v1
GITEA_API_TOKEN=your_gitea_token_here
```

### Getting a Gitea API Token

1. Log into your Gitea instance
2. Navigate to Settings > Applications
3. Under "Generate New Token", enter a name (e.g., "MCP Server")
4. Select appropriate permissions (minimum: read/write for repositories)
5. Click "Generate Token" and copy the token
6. Add the token to your `.env` file

## Usage with Claude Desktop

Add this configuration to your Claude Desktop config file:

**Location:**
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`

**Configuration:**

```json
{
  "mcpServers": {
    "gitea": {
      "command": "python",
      "args": ["-m", "gitea_mcp.server"],
      "env": {
        "GITEA_API_URL": "https://gitea.example.com/api/v1",
        "GITEA_API_TOKEN": "your_gitea_token_here"
      }
    }
  }
}
```

Or, if you prefer using a .env file:

```json
{
  "mcpServers": {
    "gitea": {
      "command": "python",
      "args": ["-m", "gitea_mcp.server"],
      "cwd": "/path/to/gitea-mcp-remote"
    }
  }
}
```

## Usage with Claude Code

Add to your MCP settings file:

**Location:** `~/.config/claude-code/mcp.json` (or your configured MCP settings path)

**Configuration:**

```json
{
  "mcpServers": {
    "gitea": {
      "command": "python",
      "args": ["-m", "gitea_mcp.server"],
      "env": {
        "GITEA_API_URL": "https://gitea.example.com/api/v1",
        "GITEA_API_TOKEN": "your_gitea_token_here"
      }
    }
  }
}
```

## Available Tools

### Issue Tools

#### gitea_list_issues

List issues in a repository with optional filters.

**Parameters:**
- `owner` (required): Repository owner (username or organization)
- `repo` (required): Repository name
- `state` (optional): Filter by state - `open`, `closed`, or `all` (default: `open`)
- `labels` (optional): Comma-separated list of label names to filter by
- `milestone` (optional): Milestone name to filter by
- `page` (optional): Page number for pagination (default: 1)
- `limit` (optional): Number of issues per page (default: 30)

**Example:**
```
List all open issues in myorg/myrepo
```

#### gitea_get_issue

Get details of a specific issue by number.

**Parameters:**
- `owner` (required): Repository owner
- `repo` (required): Repository name
- `index` (required): Issue number

**Example:**
```
Get details of issue #42 in myorg/myrepo
```

#### gitea_create_issue

Create a new issue in a repository.

**Parameters:**
- `owner` (required): Repository owner
- `repo` (required): Repository name
- `title` (required): Issue title
- `body` (optional): Issue description/body
- `labels` (optional): Array of label IDs to assign
- `milestone` (optional): Milestone ID to assign
- `assignees` (optional): Array of usernames to assign

**Example:**
```
Create an issue in myorg/myrepo with title "Bug: Login fails" and body "Users cannot log in with special characters in password"
```

#### gitea_update_issue

Update an existing issue.

**Parameters:**
- `owner` (required): Repository owner
- `repo` (required): Repository name
- `index` (required): Issue number
- `title` (optional): New issue title
- `body` (optional): New issue body
- `state` (optional): Issue state - `open` or `closed`
- `labels` (optional): Array of label IDs (replaces existing)
- `milestone` (optional): Milestone ID to assign
- `assignees` (optional): Array of usernames (replaces existing)

**Example:**
```
Close issue #42 in myorg/myrepo
```

### Label Tools

#### gitea_list_labels

List all labels in a repository.

**Parameters:**
- `owner` (required): Repository owner
- `repo` (required): Repository name

**Example:**
```
List all labels in myorg/myrepo
```

#### gitea_create_label

Create a new label in a repository.

**Parameters:**
- `owner` (required): Repository owner
- `repo` (required): Repository name
- `name` (required): Label name
- `color` (required): Label color (hex without #, e.g., `ff0000` for red)
- `description` (optional): Label description

**Example:**
```
Create a label "bug" with red color (ff0000) in myorg/myrepo
```

### Milestone Tools

#### gitea_list_milestones

List milestones in a repository.

**Parameters:**
- `owner` (required): Repository owner
- `repo` (required): Repository name
- `state` (optional): Filter by state - `open`, `closed`, or `all` (default: `open`)

**Example:**
```
List all milestones in myorg/myrepo
```

#### gitea_create_milestone

Create a new milestone in a repository.

**Parameters:**
- `owner` (required): Repository owner
- `repo` (required): Repository name
- `title` (required): Milestone title
- `description` (optional): Milestone description
- `due_on` (optional): Due date in ISO 8601 format (e.g., `2024-12-31T23:59:59Z`)

**Example:**
```
Create a milestone "v1.0 Release" with due date 2024-12-31 in myorg/myrepo
```

## API Reference

### Core Components

#### GiteaClient

HTTP client for Gitea API interactions.

**Methods:**
- `get(endpoint, params)`: GET request
- `post(endpoint, json)`: POST request
- `patch(endpoint, json)`: PATCH request

#### AuthConfig

Configuration manager for API authentication.

**Environment Variables:**
- `GITEA_API_URL`: Gitea API base URL
- `GITEA_API_TOKEN`: Authentication token

**Methods:**
- `get_auth_headers()`: Returns authentication headers

### Tool Modules

- `gitea_mcp.tools.issues`: Issue operation tools and handlers
- `gitea_mcp.tools.labels`: Label operation tools and handlers
- `gitea_mcp.tools.milestones`: Milestone operation tools and handlers

## Development

### Setup Development Environment

```bash
# Install with development dependencies
pip install -e ".[dev]"
```

### Running Tests

```bash
pytest
```

### Project Structure

```
gitea-mcp-remote/
├── src/
│   └── gitea_mcp/
│       ├── __init__.py
│       ├── server.py          # MCP server implementation
│       ├── auth.py            # Authentication config
│       ├── client.py          # Gitea API client
│       └── tools/             # Tool implementations
│           ├── __init__.py
│           ├── issues.py      # Issue tools
│           ├── labels.py      # Label tools
│           └── milestones.py  # Milestone tools
├── tests/                     # Test suite
├── pyproject.toml             # Project configuration
└── README.md                  # This file
```

### Code Quality

This project uses:
- Type hints throughout the codebase
- Async/await for all I/O operations
- Comprehensive error handling
- Structured logging

## Troubleshooting

### Authentication Errors

If you receive authentication errors:

1. Verify your `GITEA_API_TOKEN` is correct
2. Check that the token has appropriate permissions
3. Ensure your `GITEA_API_URL` includes `/api/v1` at the end
4. Verify the Gitea instance is accessible from your network

### Connection Errors

If you cannot connect to Gitea:

1. Check that `GITEA_API_URL` is correct and accessible
2. Verify network connectivity to the Gitea instance
3. Check for firewalls or proxies blocking the connection

### Tool Not Found

If Claude cannot find the tools:

1. Restart Claude Desktop/Code after updating the configuration
2. Verify the configuration file syntax is valid JSON
3. Check that Python is in your PATH
4. Ensure the package is properly installed (`pip list | grep gitea-mcp`)

## Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

## License

MIT License - see LICENSE file for details

## Version

Current version: 0.1.0

## Author

Leo Miranda

## Links

- Repository: https://github.com/lmiranda/gitea-mcp-remote
- Issues: https://github.com/lmiranda/gitea-mcp-remote/issues
- MCP Documentation: https://modelcontextprotocol.io