gitea-mcp-remote/README.md

# Gitea MCP Remote

An HTTP transport server that exposes Gitea operations via the MCP Streamable HTTP protocol for AI assistants like Claude Desktop. This server imports tools from the marketplace `gitea-mcp-server` package and serves them over HTTP with authentication and tool filtering.

## Architecture

This is NOT a standalone MCP server. It imports tool definitions from the marketplace package and serves them:
1. Imports tools from `gitea-mcp-server` marketplace package
2. Serves via MCP Streamable HTTP protocol (`/mcp` endpoint)
3. Adds Bearer token authentication (optional)
4. Provides tool filtering (whitelist/blacklist)
5. Health check endpoints for monitoring

```
Claude Desktop (HTTP) ──▶ gitea-mcp-remote ──imports──▶ gitea-mcp-server ──API──▶ Gitea
                               │
                               ├── Authentication (Bearer token)
                               ├── Tool Filtering
                               └── MCP Streamable HTTP protocol
```

## 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 with Caddy reverse proxy:

```bash
# 1. Clone the repository
git clone https://gitea.hotserv.cloud/personal-projects/gitea-mcp-remote.git
cd gitea-mcp-remote

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

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

# 4. Start the services (app + Caddy)
docker-compose -f docker/docker-compose.yml up -d

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

The server will be available at `http://localhost` (Caddy) or `http://localhost:8080` (direct).

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

# Optional
GITEA_REPO=your_repo_name  # Can be omitted, specified per-request

# HTTP Server (defaults)
HTTP_HOST=0.0.0.0
HTTP_PORT=8080
```

### 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
cd docker
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
# Or use the startup script
./scripts/start.sh
```

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

### HTTP Endpoints

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

Response: {"status": "ok"}
```

#### 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:8080/mcp",
      "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 tests/ -v

# Run with coverage
pytest tests/ --cov=gitea_mcp_remote

# Run specific test file
pytest tests/test_mcp_endpoints.py -v
```

### Project Structure

```
gitea-mcp-remote/
├── src/gitea_mcp_remote/          # Main package
│   ├── __init__.py
│   ├── server_http.py             # MCP HTTP server
│   ├── config/                    # Configuration module
│   │   ├── __init__.py
│   │   └── settings.py
│   ├── middleware/                # HTTP middleware
│   │   ├── __init__.py
│   │   └── auth.py
│   └── filtering/                 # Tool filtering
│       ├── __init__.py
│       └── filter.py
├── tests/                         # Test suite (at repo root)
│   ├── conftest.py
│   ├── test_config.py
│   ├── test_filtering.py
│   ├── test_middleware.py
│   └── test_mcp_endpoints.py
├── docker/                        # Docker infrastructure
│   ├── Dockerfile
│   ├── docker-compose.yml
│   ├── Caddyfile
│   └── .env.example
├── scripts/                       # Utility scripts
│   ├── start.sh
│   └── healthcheck.sh
├── pyproject.toml                 # Project config
├── requirements.txt               # Dependencies
├── README.md                      # This file
├── CLAUDE.md                      # Claude Code guidance
└── 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: 2.0.0

## Author

Leo Miranda

## Links

- Repository: https://gitea.hotserv.cloud/personal-projects/gitea-mcp-remote
- Issues: https://gitea.hotserv.cloud/personal-projects/gitea-mcp-remote/issues
- Marketplace Package: https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/mcp-servers/gitea
- MCP Documentation: https://modelcontextprotocol.io