gitea-mcp-remote/README.md

# Gitea HTTP MCP Wrapper

An HTTP transport wrapper around the official Gitea MCP server that enables AI assistants like Claude Desktop to interact with Gitea repositories via HTTP. This wrapper provides authentication, tool filtering, and HTTP transport while delegating Gitea operations to the official `gitea-mcp-server`.

## Architecture

This is NOT a standalone MCP server. It's an HTTP wrapper that:
1. Wraps the official `gitea-mcp-server` (stdio transport)
2. Provides HTTP transport for Claude Desktop compatibility
3. Adds Bearer token authentication
4. Filters tools for Claude Desktop compatibility
5. Proxies requests between HTTP and stdio transport

```
Claude Desktop (HTTP) → HTTP Wrapper → Gitea MCP Server (stdio) → Gitea API
```

## Features

- **HTTP Transport**: Exposes MCP server via HTTP for Claude Desktop
- **Authentication**: Optional Bearer token authentication
- **Tool Filtering**: Enable/disable specific tools for compatibility
- **Docker Deployment**: Production-ready containerization
- **Health Checks**: Monitoring endpoints (`/health`, `/healthz`, `/ping`)
- **Async Architecture**: Built on Starlette and uvicorn

## Requirements

- Python >= 3.10
- Official `gitea-mcp-server` package (auto-installed as dependency)
- Gitea instance with API access
- Gitea API token with appropriate permissions

## Quick Start with Docker

The easiest way to deploy is using Docker Compose:

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

# 2. Create .env file from template
cp .env.docker.example .env

# 3. Edit .env with your Gitea credentials
nano .env

# 4. Start the server
docker-compose up -d

# 5. Check health
curl http://localhost:8000/health
```

The server will be available at `http://localhost:8000`.

See [DEPLOYMENT.md](DEPLOYMENT.md) for detailed deployment instructions.

## Installation

### Option 1: Docker (Recommended)

See [Quick Start](#quick-start-with-docker) above or [DEPLOYMENT.md](DEPLOYMENT.md).

### Option 2: From Source

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

# Install the wrapper and its dependencies (including gitea-mcp-server)
pip install -e .

# Or use requirements.txt
pip install -r requirements.txt
```

### For Development

Install with development dependencies:

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

## Configuration

The wrapper uses environment variables or a `.env` file for configuration.

### Required Configuration

```bash
# Gitea Instance
GITEA_URL=https://gitea.example.com
GITEA_TOKEN=your_gitea_api_token_here
GITEA_OWNER=your_username_or_org
GITEA_REPO=your_repo_name

# HTTP Server
HTTP_HOST=127.0.0.1  # Use 0.0.0.0 in Docker
HTTP_PORT=8000
```

### Optional Configuration

```bash
# Bearer Authentication (optional but recommended)
AUTH_TOKEN=your_secret_bearer_token

# Tool Filtering (optional)
ENABLED_TOOLS=list_issues,create_issue,update_issue  # Whitelist mode
# OR
DISABLED_TOOLS=delete_issue,close_milestone  # Blacklist mode
```

### 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 Wrapper")
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

### Running the Server

#### With Docker

```bash
docker-compose up -d
```

#### From Source

```bash
# Create .env file from template
cp .env.example .env
# Edit .env with your configuration
nano .env

# Run the server
gitea-mcp-remote
```

The server will start on the configured host/port (default: `http://127.0.0.1:8000`).

### HTTP Endpoints

#### Health Check
```bash
GET /health
GET /healthz
GET /ping

Response: {"status": "healthy"}
```

#### MCP Protocol Endpoint

The server implements the MCP Streamable HTTP protocol:

```bash
# Check protocol version
HEAD /mcp

# Send MCP JSON-RPC requests
POST /mcp
Content-Type: application/json
Accept: application/json, text/event-stream
Authorization: Bearer YOUR_TOKEN  # If auth enabled

# Example: Initialize
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "my-client",
      "version": "1.0.0"
    }
  }
}

# Example: List tools
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}

# Example: Call tool
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "list_issues",
    "arguments": {
      "owner": "myorg",
      "repo": "myrepo",
      "state": "open"
    }
  }
}
```

### With Claude Desktop

Configure Claude Desktop to use the HTTP wrapper:

**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": {
      "url": "http://localhost:8000",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}
```

## Available Tools

The wrapper exposes all tools from the official `gitea-mcp-server`. See the [official Gitea MCP documentation](https://github.com/modelcontextprotocol/servers/tree/main/src/gitea) for the complete list of available tools:

- **Issues**: List, get, create, update issues
- **Labels**: List, create labels
- **Milestones**: List, create milestones

Tool availability can be controlled via the `ENABLED_TOOLS` or `DISABLED_TOOLS` configuration.

## Development

### Setup Development Environment

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

### Running Tests

```bash
# Run all tests
pytest

# Run with coverage
pytest --cov=gitea_mcp_remote

# Run specific test file
pytest src/gitea_mcp_remote/tests/test_config.py
```

### Project Structure

```
gitea-mcp-remote/
├── src/
│   └── gitea_mcp_remote/
│       ├── __init__.py
│       ├── server.py              # Main HTTP server
│       ├── config/
│       │   ├── __init__.py
│       │   └── settings.py        # Configuration loader
│       ├── middleware/
│       │   ├── __init__.py
│       │   └── auth.py            # HTTP authentication
│       ├── filtering/
│       │   ├── __init__.py
│       │   └── filter.py          # Tool filtering
│       └── tests/                 # Test suite
│           ├── conftest.py
│           ├── test_config.py
│           ├── test_filtering.py
│           └── test_middleware.py
├── Dockerfile                     # Docker image
├── docker-compose.yml             # Docker orchestration
├── pyproject.toml                 # Project config
├── requirements.txt               # Dependencies
├── .env.example                   # Config template
├── .env.docker.example            # Docker config template
├── README.md                      # This file
└── DEPLOYMENT.md                  # Deployment guide
```

## Deployment

For production deployment instructions, see [DEPLOYMENT.md](DEPLOYMENT.md), which covers:

- Docker deployment
- Docker Compose orchestration
- Security best practices
- Monitoring and health checks
- Scaling considerations
- Cloud deployment (AWS, GCP, Azure)
- Kubernetes deployment

## Troubleshooting

### Authentication Errors

If you receive authentication errors:

1. Verify your `GITEA_TOKEN` is correct
2. Check that the token has appropriate permissions
3. Ensure your `GITEA_URL` does NOT include `/api/v1` (wrapper adds it)
4. Verify the Gitea instance is accessible from the wrapper's network

### HTTP 401/403 Errors

If Claude Desktop receives 401 or 403 errors:

1. Check that `AUTH_TOKEN` is configured (if authentication is enabled)
2. Verify Claude Desktop config includes the correct `Authorization` header
3. Check server logs for authentication failures

### Connection Errors

If the wrapper cannot connect to Gitea:

1. Check that `GITEA_URL` is correct and accessible
2. Verify network connectivity to the Gitea instance
3. Check for firewalls or proxies blocking the connection
4. In Docker: Ensure the container can reach the Gitea host

### gitea-mcp-server Not Found

If the wrapper fails to start with "gitea-mcp-server not found":

1. Verify `gitea-mcp-server` is installed: `pip list | grep gitea-mcp`
2. Install it manually: `pip install gitea-mcp-server`
3. In Docker: Rebuild the image

### Tool Filtering Not Working

If tool filtering is not applied:

1. Check `.env` file syntax (no spaces around `=`)
2. Verify comma-separated list format
3. Check server logs for filter configuration
4. Send `tools/list` MCP request to see filtered tools

## Security Considerations

- **Always use HTTPS** in production (configure reverse proxy)
- **Set AUTH_TOKEN** to secure the HTTP endpoint
- **Rotate tokens regularly** (both Gitea token and auth token)
- **Use secrets management** (not .env files) in production
- **Limit network exposure** (firewall, VPN, or private network)
- **Monitor access logs** for suspicious activity

## 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
- Official Gitea MCP Server: https://github.com/modelcontextprotocol/servers/tree/main/src/gitea
- MCP Documentation: https://modelcontextprotocol.io