finn-mcp/DEPLOY.md

# Deployment Guide - finn-eiendom MCP Server

This guide covers deploying the FINN Eiendom MCP server using Docker.

## Quick Start

### Prerequisites
- Docker and Docker Compose installed
- Remote server with port 8010 available
- (Optional) Reverse proxy (nginx/caddy) for HTTPS and load balancing

### Build the Image

```bash
cd /root/projects/finn-mcp
docker build -t finn-mcp:latest .
```

### Run Locally (Development)

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

Verify the server is running:
```bash
curl http://localhost:8010
```

### Deploy to Remote Server

1. **Build and tag the image:**
   ```bash
   docker build -t your-registry/finn-mcp:latest .
   docker push your-registry/finn-mcp:latest
   ```

2. **On the remote server, create docker-compose.yml:**
   ```bash
   mkdir -p /opt/finn-mcp
   cd /opt/finn-mcp
   # Copy the docker-compose.yml and docker-compose.prod.yml files
   ```

3. **Start the service:**
   ```bash
   docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d
   ```

4. **Verify the service:**
   ```bash
   docker ps | grep finn-mcp
   docker logs finn-mcp-server
   ```

## Configuration

### Environment Variables

Set these via `docker-compose.yml`:

```yaml
environment:
  MCP_TRANSPORT: http        # Transport protocol (http or stdio)
  MCP_HOST: 0.0.0.0          # Bind address
  MCP_PORT: 8010             # Port number
  PYTHONUNBUFFERED: 1        # Immediate output logging
```

### Port Configuration

**Development (localhost only):**
```yaml
ports:
  - "127.0.0.1:8010:8010"
```

**Production (all interfaces):**
```yaml
ports:
  - "8010:8010"
```

**With reverse proxy (recommended):**
```yaml
ports:
  - "127.0.0.1:8010:8010"  # Only accessible via reverse proxy
```

## Networking & Security

### Option 1: Direct HTTP (Development Only)
```bash
# Not recommended for production
curl http://your-server:8010
```

### Option 2: Reverse Proxy (Recommended)

**Nginx example:**
```nginx
server {
    listen 443 ssl http2;
    server_name your-domain.com;
    
    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
    
    location / {
        proxy_pass http://localhost:8010;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 86400;
    }
}
```

**Caddy example:**
```caddyfile
your-domain.com {
    reverse_proxy localhost:8010 {
        header_up X-Forwarded-Proto {scheme}
        header_up X-Forwarded-Host {host}
    }
}
```

## Monitoring

### Check Container Health

```bash
# View logs
docker logs -f finn-mcp-server

# Check resource usage
docker stats finn-mcp-server

# View health status
docker inspect --format='{{.State.Health}}' finn-mcp-server
```

### Log Aggregation

Logs are written to:
- `json-file` driver with 100MB max size, 10 file rotation
- Structured JSON output for easy parsing

Forward to ELK/Splunk/Datadog if needed:
```yaml
logging:
  driver: "splunk"
  options:
    splunk-token: "your-token"
    splunk-url: "https://your-instance.splunk.com"
```

## Updates & Maintenance

### Update the Image

```bash
# Pull latest code
git pull origin main

# Rebuild image
docker build -t finn-mcp:latest .

# Restart containers
docker-compose up -d
```

### Database Backup

Cache database location: `/app/cache.sqlite` (inside container)

```bash
# Backup from host
docker exec finn-mcp-server cp /app/cache.sqlite /tmp/cache.sqlite.bak
docker cp finn-mcp-server:/tmp/cache.sqlite.bak ./cache.sqlite.bak
```

## Troubleshooting

### Server won't start
```bash
# Check logs
docker logs finn-mcp-server

# Verify port is available
lsof -i :8010
```

### Health check failing
```bash
# Test connection
docker exec finn-mcp-server python -c "import socket; socket.create_connection(('localhost', 8010), timeout=5).close()"
```

### High memory usage
```bash
# Check limits in docker-compose.yml
# Adjust memory limit if needed
deploy:
  resources:
    limits:
      memory: 2G
```

## Production Checklist

- [ ] Docker image built and tested locally
- [ ] Reverse proxy configured (nginx/caddy)
- [ ] SSL certificates installed
- [ ] Environment variables reviewed
- [ ] Resource limits appropriate for server
- [ ] Health checks enabled
- [ ] Logging configured (syslog/ELK/Datadog)
- [ ] Backups scheduled
- [ ] Monitoring alerts configured
- [ ] Failover/HA plan in place (if needed)

## Integration with Copilot

Once the MCP server is running on your remote server, configure Copilot to connect:

**On the machine running Copilot Desktop:**

1. Open Claude Desktop settings (or config file at `~/.config/claude-desktop/config.json`)
2. Add HTTP transport configuration:

```json
{
  "mcpServers": {
    "finn-eiendom": {
      "type": "http",
      "url": "http://your-server:8010"
    }
  }
}
```

Or with a reverse proxy:

```json
{
  "mcpServers": {
    "finn-eiendom": {
      "type": "http",
      "url": "https://your-domain.com"
    }
  }
}
```

## Support & Debugging

### Test MCP Server Directly

```bash
# Test with stdio transport
cat > test_mcp.json << 'EOF'
{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test", "version": "1.0"}}}
EOF

docker run -i finn-mcp:latest python -m finn_eiendom.mcp_server < test_mcp.json
```

### List Available Tools

```bash
curl http://your-server:8010 -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}'
```

## References

- [MCP Protocol](https://spec.modelcontextprotocol.io/)
- [FastMCP Documentation](https://github.com/jlopp/fastmcp)
- [Docker Compose Docs](https://docs.docker.com/compose/)