# Systemd Service Setup

This directory contains files for running the Gogs MCP Server as a systemd service on Linux.

## Files

- **gogs-mcp-server.service**: Systemd service configuration
- **install-service.sh**: Installation script
- **uninstall-service.sh**: Uninstallation script

## Configuration

The service is configured to run on **port 3100** (instead of the default 3000) with HTTP transport.

## Installation

### 1. Configure the Service

Before installing, edit `gogs-mcp-server.service` to set your Gogs server details:

```bash
nano gogs-mcp-server.service
```

Update these environment variables:
- `GOGS_SERVER_URL`: Your Gogs server URL (e.g., https://gogs.example.com)
- `GOGS_ACCESS_TOKEN`: Your Gogs access token

### 2. Run the Installation Script

```bash
sudo ./install-service.sh
```

This will:
- Copy the service file to `/etc/systemd/system/`
- Reload systemd daemon
- Enable the service to start on boot

### 3. Start the Service

```bash
sudo systemctl start gogs-mcp-server
```

### 4. Check Status

```bash
sudo systemctl status gogs-mcp-server
```

## Usage

### Service Commands

```bash
# Start the service
sudo systemctl start gogs-mcp-server

# Stop the service
sudo systemctl stop gogs-mcp-server

# Restart the service
sudo systemctl restart gogs-mcp-server

# Check status
sudo systemctl status gogs-mcp-server

# Enable on boot
sudo systemctl enable gogs-mcp-server

# Disable on boot
sudo systemctl disable gogs-mcp-server
```

### View Logs

```bash
# Follow live logs
sudo journalctl -u gogs-mcp-server -f

# View recent logs
sudo journalctl -u gogs-mcp-server -n 50

# View logs since last boot
sudo journalctl -u gogs-mcp-server -b
```

## Testing the Server

Once the service is running, test it:

```bash
# Health check
curl http://localhost:3100/health

# Expected response:
# {"status":"ok","service":"gogs-mcp-server","transport":"http"}

# Test SSE endpoint
curl -N http://localhost:3100/sse
```

## Claude Code Integration

From inside your Claude Code Docker container, add the MCP server:

```bash
# Docker Desktop (Mac/Windows)
claude mcp add --transport sse gogs http://host.docker.internal:3100/sse

# Linux Docker (using docker0 bridge)
claude mcp add --transport sse gogs http://172.17.0.1:3100/sse

# Or use host machine IP
claude mcp add --transport sse gogs http://<host-ip>:3100/sse
```

Verify it was added:

```bash
claude mcp list
```

## Updating Configuration

If you need to change environment variables after installation:

```bash
# Edit the service file
sudo nano /etc/systemd/system/gogs-mcp-server.service

# Reload systemd configuration
sudo systemctl daemon-reload

# Restart the service
sudo systemctl restart gogs-mcp-server
```

## Uninstallation

To remove the service:

```bash
sudo ./uninstall-service.sh
```

This will:
- Stop the service
- Disable it from starting on boot
- Remove the service file
- Reload systemd daemon

## Troubleshooting

### Service won't start

Check the logs for errors:
```bash
sudo journalctl -u gogs-mcp-server -n 50
```

Common issues:
- Incorrect GOGS_SERVER_URL or GOGS_ACCESS_TOKEN
- Port 3100 already in use
- Node.js not installed or wrong path
- Project not built (run `npm run build` first)

### Port already in use

Check what's using port 3100:
```bash
sudo lsof -i :3100
```

Change the port in the service file if needed:
```bash
sudo nano /etc/systemd/system/gogs-mcp-server.service
# Change HTTP_PORT=3100 to another port
sudo systemctl daemon-reload
sudo systemctl restart gogs-mcp-server
```

### Can't connect from Docker container

1. Verify service is running:
   ```bash
   sudo systemctl status gogs-mcp-server
   curl http://localhost:3100/health
   ```

2. Check firewall settings:
   ```bash
   sudo ufw status
   sudo ufw allow 3100/tcp
   ```

3. Verify Docker can reach host:
   ```bash
   # From inside container
   curl http://172.17.0.1:3100/health
   ```

## Security Notes

The service includes these security settings:
- `NoNewPrivileges=true`: Prevents privilege escalation
- `PrivateTmp=true`: Uses private /tmp directory

For production deployments, consider:
- Using environment file instead of inline environment variables
- Setting up SSL/TLS reverse proxy (nginx, caddy)
- Restricting network access with firewall rules
- Running on a non-standard port or behind authentication

## Environment File Alternative

Instead of inline environment variables, you can use an environment file:

1. Create `/etc/gogs-mcp-server.env`:
   ```bash
   GOGS_SERVER_URL=https://gogs.example.com
   GOGS_ACCESS_TOKEN=your-token-here
   TRANSPORT_MODE=http
   HTTP_PORT=3100
   HTTP_HOST=0.0.0.0
   NODE_ENV=production
   ```

2. Update service file:
   ```ini
   [Service]
   EnvironmentFile=/etc/gogs-mcp-server.env
   ```

3. Secure the file:
   ```bash
   sudo chmod 600 /etc/gogs-mcp-server.env
   sudo chown root:root /etc/gogs-mcp-server.env
   ```