# Forgejo-MCP Gateway Integration Guide

## Architecture Overview

```
┌─────────────────────────────────────────────────────────┐
│                   MCP Gateway (Port 4444)               │
│  ┌─────────────────────────────────────────────────┐   │
│  │  OAuth 2.1 + Tool Registry + Request Router     │   │
│  └────────┬────────────────────────────────────────┘   │
└───────────┼─────────────────────────────────────────────┘
            │
            │ MCP_BACKEND_FORGEJO=http://mcp-forgejo:8400/mcp
            │
┌───────────▼─────────────────────────────────────────────┐
│            Forgejo-MCP Service (Port 8400)              │
│  ┌─────────────────────────────────────────────────┐   │
│  │  12 Repository/Issue/PR/File Tools              │   │
│  │  Async HTTP Client for Forgejo API             │   │
│  └────────┬────────────────────────────────────────┘   │
└───────────┼─────────────────────────────────────────────┘
            │ FORGEJO_ACCESS_TOKEN
            │
┌───────────▼─────────────────────────────────────────────┐
│   Forgejo Instance (http://10.0.0.25:34577)            │
│  ┌─────────────────────────────────────────────────┐   │
│  │  Repositories, Issues, PRs, Users               │   │
│  └─────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘
```

## Integration Points

### 1. Docker Network

The `forgejo-mcp` service joins the `mcpnet` network, allowing internal communication with the gateway:

```yaml
networks:
  mcpnet:
    driver: bridge

services:
  forgejo-mcp:
    networks: [mcpnet]
```

### 2. Gateway Backend Registration

In `gateway_proxy.py`, backends are discovered via environment variables:

```python
def load_backends() -> dict[str, str]:
    backends = {}
    for key, value in os.environ.items():
        if key.startswith("MCP_BACKEND_"):
            name = key[len("MCP_BACKEND_"):].lower()
            backends[name] = value
    return backends
```

The `docker-compose.yml` provides:
```
MCP_BACKEND_FORGEJO=http://mcp-forgejo:8400/mcp
```

This automatically registers the Forgejo-MCP service with the gateway.

### 3. Tool Discovery

When Claude requests tools, the gateway:

1. Makes a `GET /tools` request to `http://mcp-forgejo:8400/mcp`
2. Receives the list of 12 available tools
3. Registers them with the tool registry
4. Prefixes tools with the backend name: `forgejo_list_repositories`, etc.

### 4. Request Routing

When Claude calls a `forgejo_*` tool:

1. Gateway receives the request with tool name and arguments
2. Routes to the appropriate backend (Forgejo-MCP)
3. Makes `POST /call_tool` request to Forgejo-MCP
4. Returns results to Claude

## Configuration Checklist

Before deploying, verify:

### Environment Variables
- [ ] `FORGEJO_URL` is set (default: `http://10.0.0.25:34577`)
- [ ] `FORGEJO_ACCESS_TOKEN` is set to your token
- [ ] Token has `repo` scope

### Docker Compose
- [ ] `docker-compose.yml` includes `forgejo-mcp` service
- [ ] Service port is `8400`
- [ ] Environment variables are passed to container
- [ ] `networks: [mcpnet]` is configured
- [ ] Health check is configured

### Gateway Configuration
- [ ] `docker-compose.yml` gateway includes `MCP_BACKEND_FORGEJO` environment
- [ ] Gateway depends on `forgejo-mcp` service

## Health Checks

### Service Health

```bash
# Check service is running
docker-compose ps forgejo-mcp

# Check logs
docker-compose logs forgejo-mcp

# Manual health check
curl http://localhost:8400/health
```

### Network Connectivity

```bash
# From gateway container, ping forgejo-mcp
docker exec mcp-gateway ping mcp-forgejo

# From gateway container, check tool endpoint
docker exec mcp-gateway curl http://mcp-forgejo:8400/tools
```

### Gateway Integration

```bash
# Check gateway logs for backend initialization
docker-compose logs gateway | grep -i forgejo

# Should show:
# Backend configured: forgejo -> http://mcp-forgejo:8400/mcp
```

## Deployment Steps

### 1. Prepare Environment

```bash
cd /path/to/mcp-gateway

# Add to .env file
echo "FORGEJO_URL=http://10.0.0.25:34577" >> .env
echo "FORGEJO_ACCESS_TOKEN=df0555d179c7ce6d11c6605b7ddad0921c3c4c83" >> .env
```

### 2. Build Service

```bash
# Build the Forgejo-MCP image
docker-compose build forgejo-mcp

# Output should show:
# Step 1/6 : FROM python:3.11-slim
# ...
# Successfully built <image_id>
```

### 3. Start Service

```bash
# Start the Forgejo-MCP service
docker-compose up -d forgejo-mcp

# Wait for startup (healthcheck)
sleep 5

# Verify running
docker-compose ps forgejo-mcp
# Should show "Up" status
```

### 4. Restart Gateway

If the gateway was already running, restart it to pick up the new backend:

```bash
docker-compose restart gateway

# Check logs
docker-compose logs -f gateway
```

### 5. Verify Tools

Test tool discovery through the gateway:

```bash
# List available tools (if gateway provides this endpoint)
curl -H "Authorization: Bearer YOUR_GATEWAY_TOKEN" \
  http://localhost:4444/tools | jq '.[] | select(.name | startswith("forgejo"))'

# Should list all 12 forgejo_* tools
```

## Tool Availability

Once integrated, these tools will be available:

**Repository Management** (3 tools)
- `forgejo_list_repositories`
- `forgejo_get_repository`
- `forgejo_create_repository`

**Issue Management** (3 tools)
- `forgejo_list_issues`
- `forgejo_create_issue`
- `forgejo_update_issue`

**Pull Requests** (2 tools)
- `forgejo_list_pull_requests`
- `forgejo_create_pull_request`

**Branches & Files** (2 tools)
- `forgejo_list_branches`
- `forgejo_get_file`

**Search & Users** (2 tools)
- `forgejo_search_repositories`
- `forgejo_get_user`

## Testing Integration

### Test 1: List Repositories

Request to gateway:
```json
{
  "tool": "forgejo_list_repositories",
  "arguments": {
    "owner": "your-username"
  }
}
```

Expected: List of repositories for the user

### Test 2: Get Repository Details

Request to gateway:
```json
{
  "tool": "forgejo_get_repository",
  "arguments": {
    "owner": "your-username",
    "repo": "your-repo"
  }
}
```

Expected: Detailed repository information

### Test 3: List Issues

Request to gateway:
```json
{
  "tool": "forgejo_list_issues",
  "arguments": {
    "owner": "your-username",
    "repo": "your-repo",
    "state": "open"
  }
}
```

Expected: Open issues for the repository

## Troubleshooting Integration

### Issue: Service doesn't start

```bash
# Check logs
docker-compose logs forgejo-mcp

# Common causes:
# - Missing environment variables
# - Port 8400 already in use
# - Invalid base image
```

### Issue: Gateway can't connect

```bash
# Check network
docker network inspect mcpnet

# Check service IP
docker inspect mcp-forgejo | grep IPAddress

# Test from gateway container
docker exec mcp-gateway curl -v http://mcp-forgejo:8400/health
```

### Issue: Tools not appearing in gateway

```bash
# Check gateway backend configuration
docker-compose logs gateway | grep -i backend

# Check gateway can reach service
docker exec mcp-gateway curl http://mcp-forgejo:8400/tools

# Restart gateway
docker-compose restart gateway
```

### Issue: Authentication fails

```bash
# Test token directly
curl -H "Authorization: token df0555d179c7ce6d11c6605b7ddad0921c3c4c83" \
  http://10.0.0.25:34577/api/v1/user

# Should return user info, not 401
```

## Performance Considerations

### Request Latency

- Gateway to Forgejo-MCP: ~5-10ms (local network)
- Forgejo-MCP to Forgejo: ~10-50ms (HTTP API)
- Total: ~15-60ms per tool call

### Concurrent Requests

The Forgejo-MCP server uses async Python with httpx, supporting:
- Multiple concurrent requests
- Connection pooling
- Efficient I/O handling

### Rate Limiting

Forgejo local instances typically have no rate limiting. For remote instances, be aware of:
- API rate limits (if enforced)
- Token usage monitoring
- Large result set pagination

## Security Integration

### Token Management

The token is:
- Passed via environment variable (not hardcoded)
- Used in HTTP header: `Authorization: token <token>`
- Should be rotated periodically

### Network Security

- Internal network (`mcpnet`) - secure local communication
- External access only through gateway (port 4444)
- Gateway handles authentication (OAuth 2.1)

### Data Flow

```
Claude Client
    ↓
    └─→ Gateway (authenticated)
        ├─ Validates request
        ├─ Routes to Forgejo-MCP
        └─ Returns response
            └─→ Forgejo-MCP
                ├─ Uses token from env
                └─ Calls Forgejo API
                    └─→ Forgejo Instance
```

## Monitoring

### Log Aggregation

```bash
# View all service logs
docker-compose logs -f

# View specific service
docker-compose logs -f forgejo-mcp

# Follow errors only
docker-compose logs -f 2>&1 | grep ERROR
```

### Health Monitoring

```bash
# Set up monitoring
watch -n 5 'docker-compose ps'

# Check service health periodically
*/5 * * * * docker-compose exec mcp-forgejo curl -f http://localhost:8400/health
```

## Updating the Service

To update the Forgejo-MCP code:

```bash
# Edit forgejo_mcp.py

# Rebuild
docker-compose build --no-cache forgejo-mcp

# Restart
docker-compose up -d forgejo-mcp

# Check logs
docker-compose logs -f forgejo-mcp
```

## Integration with Claude.ai

Once deployed:

1. Connect your MCP gateway to Claude.ai
2. The gateway exposes `forgejo_*` tools
3. Claude can use these tools to:
   - List and explore repositories
   - Create and manage issues
   - Work with pull requests
   - Read repository files
   - Search repositories

Example Claude prompt:
> List all open issues in my main project and create a summary

This would use:
- `forgejo_list_issues` - Get open issues
- Process and summarize results