mcp-servers/FORGEJO_SETUP.md

# Forgejo MCP Setup Guide

This guide walks you through adding Forgejo-MCP to your MCP gateway.

## Quick Start

### 1. Prerequisites

- Docker and Docker Compose installed
- Forgejo instance running at `http://10.0.0.25:34577`
- Forgejo API access token (you have this: `df0555d179c7ce6d11c6605b7ddad0921c3c4c83`)

### 2. Update Environment Variables

Add the following to your `.env` file in the `mcp-gateway` directory:

```env
# Forgejo Configuration
FORGEJO_URL=http://10.0.0.25:34577
FORGEJO_ACCESS_TOKEN=df0555d179c7ce6d11c6605b7ddad0921c3c4c83
```

### 3. Build and Deploy

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

# Build the Forgejo-MCP service
docker-compose build forgejo-mcp

# Start the service
docker-compose up -d forgejo-mcp

# Verify it's running
docker-compose logs -f forgejo-mcp
```

### 4. Verify Integration

The gateway should automatically discover the Forgejo-MCP service. Check the gateway logs:

```bash
docker-compose logs -f gateway
```

You should see a message like:
```
Backend configured: forgejo -> http://mcp-forgejo:8400/mcp
```

### 5. Test the Tools

Using curl to test the gateway:

```bash
# List repositories (example)
curl -X POST http://localhost:4444/call_tool \
  -H "Authorization: Bearer YOUR_GATEWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "forgejo_list_repositories",
    "arguments": {
      "owner": "your-username"
    }
  }'
```

## Configuration Details

### Forgejo API Token

Your token has been provided: `df0555d179c7ce6d11c6605b7ddad0921c3c4c83`

This token provides access to:
- Repository operations
- Issue management
- Pull request management
- User information
- File reading

**To create new tokens in Forgejo:**

1. Log in to your Forgejo instance
2. Go to Settings → Applications → Personal Access Tokens
3. Click "New Token"
4. Name: `MCP Gateway`
5. Scopes:
   - ✓ `repo` - Full repository access
   - ✓ `read:user` - Read user information
6. Click "Generate Token"
7. Copy the token and add to `.env`

### Port Configuration

- **Forgejo-MCP Service**: Port `8400` (internal to Docker)
- **MCP Gateway**: Port `4444` (exposed to host)
- **Forgejo**: `http://10.0.0.25:34577` (local network)

### Health Checks

The Forgejo-MCP service includes health checks:

```bash
# Check service health
docker-compose ps forgejo-mcp

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

## Available Tools

After setup, the following tools will be available through the gateway:

### Repository Management
- `forgejo_list_repositories` - List user/org repositories
- `forgejo_get_repository` - Get repository details
- `forgejo_create_repository` - Create a new repository

### Issue Management
- `forgejo_list_issues` - List repository issues
- `forgejo_create_issue` - Create a new issue
- `forgejo_update_issue` - Update an issue

### Pull Requests
- `forgejo_list_pull_requests` - List pull requests
- `forgejo_create_pull_request` - Create a pull request

### Files & Branches
- `forgejo_list_branches` - List repository branches
- `forgejo_get_file` - Read file contents

### Search & Users
- `forgejo_search_repositories` - Search repositories
- `forgejo_get_user` - Get user profile information

## Troubleshooting

### Service won't start

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

Common issues:
- **Port 8400 already in use**: Change `PORT` in docker-compose.yml
- **Missing environment variables**: Verify `.env` file has `FORGEJO_ACCESS_TOKEN`
- **Network issues**: Verify `10.0.0.25:34577` is reachable

### Gateway can't connect to Forgejo-MCP

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

# Check network connectivity
docker exec mcp-gateway ping mcp-forgejo

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

### Authentication errors

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

Should return your user information.

### Tool returns empty results

- Verify you have repositories in Forgejo
- Check you're using correct owner name (username or org name)
- Try with `limit: 50` to increase result count

## Performance Considerations

- **Pagination**: Tools support pagination with `limit` and `page` parameters
- **Default limits**: Default limit is 20 items per request
- **Large result sets**: Use pagination to retrieve more results
- **API rate limiting**: Forgejo's rate limiting is not typically a concern for local instances

## Security Best Practices

1. **Token Management**
   - Store token in `.env` (Git-ignored)
   - Don't hardcode tokens in source files
   - Periodically rotate tokens
   - Use minimal scope tokens

2. **Network Security**
   - Use HTTPS for production Forgejo instances
   - Restrict gateway access with authentication
   - Use firewall rules to limit access to Forgejo

3. **Monitoring**
   - Monitor token usage logs
   - Review gateway logs for errors
   - Alert on authentication failures

## Next Steps

1. **Test the integration**: Use the gateway API to list repositories
2. **Configure access**: Set up OAuth users if needed
3. **Monitor**: Check logs for any issues
4. **Extend**: Create additional workflows using Forgejo tools

## Stopping the Service

```bash
# Stop just Forgejo-MCP
docker-compose stop forgejo-mcp

# Stop all services
docker-compose down

# Stop and remove volumes
docker-compose down -v
```

## Updating the Service

After making changes to the code:

```bash
# Rebuild
docker-compose build forgejo-mcp

# Restart
docker-compose up -d forgejo-mcp

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

## Additional Resources

- [Forgejo API Documentation](https://forgejo.org/docs/latest/api/)
- [MCP Specification](https://modelcontextprotocol.io/)
- [Gateway Configuration](./DEPLOYMENT_GUIDE.md)