# Rohlik MCP Proxy Server

A Docker-based proxy MCP (Model Context Protocol) server for the Rohlik MCP service that forwards requests to `https://mcp.rohlik.cz/mcp` while automatically injecting authentication headers from a base64url token in the URL path (or optional env fallback).

## Features

- **Transparent Proxying**: Forwards MCP protocol messages between clients and the Rohlik MCP server
- **Authentication Injection**: Automatically injects `rhl-email` and `rhl-pass` headers from a base64url path token (env fallback optional)
- **SSE/Streaming Support**: Streams GET responses for real-time MCP sessions
- **Docker-based**: Easy deployment with Docker and Docker Compose
- **Health Monitoring**: Built-in health check endpoint
- **CORS Enabled**: Allows browser-based and desktop MCP clients to connect

## Prerequisites

- Docker and Docker Compose installed
- Rohlik account credentials (email and password)

## Quick Start

### 1. Generate a base64url token

Create a base64url-encoded token for `email:password`:

```bash
python - <<'PY'
import base64
print(base64.urlsafe_b64encode(b"email@gmail.com:password").decode())
PY
```

### 2. Build and Run with Docker Compose

Note: `docker-compose.yml` expects an external network named `cloudflare`. Create it with
`docker network create cloudflare` or remove the `networks` section if you don't need it.

```bash
# Build and start the proxy server
docker-compose up -d

# View logs
docker-compose logs -f rohlik-mcp-proxy

# Stop the server
docker-compose down
```

The proxy server will be available at:
- **MCP Endpoint**: `http://localhost:8000/mcp/<base64url-token>`
- **Health Check**: `http://localhost:8000/health`
- **Info**: `http://localhost:8000/`

### 3. Alternative: Run with Docker

```bash
# Build the image
docker build -t rohlik-mcp-proxy .

# Run the container
docker run -d \
  --name rohlik-mcp-proxy \
  -p 8000:8000 \
  rohlik-mcp-proxy

# View logs
docker logs -f rohlik-mcp-proxy

# Stop the container
docker stop rohlik-mcp-proxy
docker rm rohlik-mcp-proxy
```

## Configuration

### Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `RHL_EMAIL` | No | - | Optional fallback email (used when no path token is provided) |
| `RHL_PASS` | No | - | Optional fallback password (used when no path token is provided) |
| `ROHLIK_MCP_URL` | No | `https://mcp.rohlik.cz/mcp` | Rohlik MCP backend endpoint |

### Base64url Path Token

The proxy expects a URL path like `/mcp/<base64url(email:password)>`. Padding (`=`) is optional.
If you set `RHL_EMAIL` and `RHL_PASS`, you can also use `/mcp` without a token.

### MCP Client Configuration

Configure your MCP client (e.g., Claude Desktop, ChatGPT) to connect to the proxy.
Use the base64url token in the URL path:

```json
{
  "mcpServers": {
    "rohlik": {
      "url": "http://localhost:8000/mcp/<base64url-token>",
      "transport": "streamable-http"
    }
  }
}
```

Or for `fastmcp` client:

Or using MCP Inspector:

```bash
npx @modelcontextprotocol/inspector http://localhost:8000/mcp/<base64url-token>
```

## Development

### Local Development (Without Docker)

```bash
# Install uv package manager
pip install uv

# Install dependencies
uv pip install -e .

# Run the proxy server
python proxy_server.py
```

### Project Structure

```
rohlik-mcp-proxy/
├── proxy_server.py       # Main proxy server implementation
├── pyproject.toml        # Python project configuration
├── Dockerfile            # Docker image definition
├── docker-compose.yml    # Docker Compose configuration
├── .env.example          # Environment variables template
├── .gitignore           # Git ignore rules
└── README.md            # This file
```

## How It Works

1. **Client Connection**: MCP client connects to the proxy at `/mcp/<base64url-token>` (GET for streaming, POST for calls)
2. **Request Forwarding**: Proxy receives MCP requests from the client
3. **Header Injection**: Proxy decodes the path token and adds authentication headers (`rhl-email`, `rhl-pass`)
4. **Backend Communication**: Proxy forwards the authenticated request to Rohlik MCP server
5. **Response Handling**: Proxy streams GET responses and returns POST/other responses
6. **Bidirectional Flow**: Process repeats for all subsequent requests

```
┌─────────────┐         ┌──────────────────┐         ┌─────────────────┐
│             │         │                  │         │                 │
│ MCP Client  │ <-----> │  Rohlik Proxy    │ <-----> │ Rohlik MCP      │
│             │  HTTP   │  (adds headers)  │  HTTPS  │ Backend Server  │
│             │         │                  │         │                 │
└─────────────┘         └──────────────────┘         └─────────────────┘
                        Port 8000                    mcp.rohlik.cz
```

## Health Check

The proxy includes a built-in health check endpoint:

```bash
curl http://localhost:8000/health
# Returns: OK
```

Docker Compose automatically monitors this endpoint and restarts the container if it becomes unhealthy.

## Security Considerations

- **Credentials Storage**: Never commit your `.env` file with real credentials to version control
- **Network Security**: For production use, consider running the proxy behind a reverse proxy with HTTPS
- **Access Control**: No additional authentication is enforced by the proxy; restrict access at the network or reverse proxy level
- **Password Safety**: Credentials are passed via URL path and HTTP headers (ensure HTTPS and avoid logging full URLs in production)

## Troubleshooting

### Container won't start

```bash
# Check logs
docker-compose logs rohlik-mcp-proxy

# Common issues:
# - Port 8000 already in use
# - Invalid or missing base64 token in the URL path
```

### Connection refused

```bash
# Verify the container is running
docker-compose ps

# Check if port is accessible
curl http://localhost:8000/health
```

### Rohlik authentication errors

```bash
# Verify your base64url token decodes to email:password
python - <<'PY'
import base64
print(base64.urlsafe_b64decode(b"<base64url-token>").decode())
PY
```

## License

This project is provided as-is for integration with the Rohlik MCP service.

## Related Documentation

- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/)
- [FastMCP Documentation](https://gofastmcp.com/)
- [Rohlik MCP Service](https://mcp.rohlik.cz/)