mcp-servers/mcp-gateway/forgejo-mcp/README.md

# Forgejo MCP Server

A comprehensive Model Context Protocol (MCP) server for interacting with a self-hosted Forgejo Git service.

## Features

The Forgejo MCP server provides tools for:

- **Repository Management**: List, create, and inspect repositories
- **Issue Tracking**: Create, update, list, and manage issues
- **Pull Requests**: Create and manage pull requests
- **Branch Management**: List branches and retrieve branch information
- **File Operations**: Read file contents from repositories
- **Search**: Search for repositories across the instance
- **User Profiles**: Get user information and statistics

## Configuration

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `FORGEJO_URL` | `http://10.0.0.25:34577` | Forgejo instance URL |
| `FORGEJO_ACCESS_TOKEN` | (required) | Forgejo API access token |
| `PORT` | `8400` | Server port |
| `TRANSPORT` | `http` | Transport protocol (http recommended) |

### Obtaining an Access Token

1. Log in to your Forgejo instance
2. Go to Settings → Applications → Personal Access Tokens
3. Create a new token with the following scopes:
   - `repo` - Full repository access
   - `admin:org_hook` (optional) - For webhook management
   - `user` (optional) - For user profile access

## Docker Deployment

The server is containerized and integrated with the MCP gateway docker-compose setup.

### Environment File (.env)

Add these variables to your `.env` file:

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

### Docker Compose Integration

The `docker-compose.yml` includes the Forgejo-MCP service with:

- Container name: `mcp-forgejo`
- Port: `8400`
- Network: `mcpnet` (internal gateway network)
- Health checks enabled

To start the service:

```bash
docker-compose up -d forgejo-mcp
```

## Available Tools

### Repository Tools

#### `forgejo_list_repositories`
List repositories for a user or organization.

**Parameters:**
- `owner` (string, required): Username or organization name
- `limit` (integer, optional): Max repositories to return (default: 20)
- `page` (integer, optional): Page number for pagination (default: 1)

#### `forgejo_get_repository`
Get details about a specific repository.

**Parameters:**
- `owner` (string, required): Repository owner
- `repo` (string, required): Repository name

#### `forgejo_create_repository`
Create a new repository.

**Parameters:**
- `name` (string, required): Repository name (lowercase, no spaces)
- `description` (string, optional): Repository description
- `private` (boolean, optional): Whether repository is private (default: false)
- `auto_init` (boolean, optional): Initialize with README (default: true)

### Issue Tools

#### `forgejo_list_issues`
List issues in a repository.

**Parameters:**
- `owner` (string, required): Repository owner
- `repo` (string, required): Repository name
- `state` (string, optional): Filter by state (open, closed, all) (default: open)
- `limit` (integer, optional): Max issues to return (default: 20)
- `page` (integer, optional): Page number (default: 1)

#### `forgejo_create_issue`
Create a new issue.

**Parameters:**
- `owner` (string, required): Repository owner
- `repo` (string, required): Repository name
- `title` (string, required): Issue title
- `body` (string, optional): Issue description (markdown)
- `labels` (array, optional): Label names

#### `forgejo_update_issue`
Update an existing issue.

**Parameters:**
- `owner` (string, required): Repository owner
- `repo` (string, required): Repository name
- `issue_number` (integer, required): Issue number
- `state` (string, optional): New state (open, closed)
- `title` (string, optional): New issue title
- `body` (string, optional): New issue description

### Pull Request Tools

#### `forgejo_list_pull_requests`
List pull requests in a repository.

**Parameters:**
- `owner` (string, required): Repository owner
- `repo` (string, required): Repository name
- `state` (string, optional): Filter by state (open, closed, all) (default: open)
- `limit` (integer, optional): Max PRs to return (default: 20)
- `page` (integer, optional): Page number (default: 1)

#### `forgejo_create_pull_request`
Create a new pull request.

**Parameters:**
- `owner` (string, required): Repository owner
- `repo` (string, required): Repository name
- `title` (string, required): PR title
- `body` (string, optional): PR description
- `head` (string, required): Head branch (source)
- `base` (string, required): Base branch (target)

### Branch Tools

#### `forgejo_list_branches`
List branches in a repository.

**Parameters:**
- `owner` (string, required): Repository owner
- `repo` (string, required): Repository name
- `limit` (integer, optional): Max branches to return (default: 20)
- `page` (integer, optional): Page number (default: 1)

### File Tools

#### `forgejo_get_file`
Get file contents from a repository.

**Parameters:**
- `owner` (string, required): Repository owner
- `repo` (string, required): Repository name
- `path` (string, required): File path in repository
- `ref` (string, optional): Branch, tag, or commit SHA (default: main)

### Search Tools

#### `forgejo_search_repositories`
Search for repositories across the Forgejo instance.

**Parameters:**
- `q` (string, required): Search query
- `limit` (integer, optional): Max results to return (default: 20)
- `page` (integer, optional): Page number (default: 1)

### User Tools

#### `forgejo_get_user`
Get user profile information.

**Parameters:**
- `username` (string, required): Username

## Usage Examples

### List all repositories for a user

```
Tool: forgejo_list_repositories
Parameters:
  owner: "myusername"
  limit: 10
```

### Create a new issue

```
Tool: forgejo_create_issue
Parameters:
  owner: "myorg"
  repo: "myproject"
  title: "Bug: Login form not responsive"
  body: "The login form breaks on mobile devices"
  labels: ["bug", "high-priority"]
```

### Get repository details

```
Tool: forgejo_get_repository
Parameters:
  owner: "myorg"
  repo: "myproject"
```

### Read a configuration file

```
Tool: forgejo_get_file
Parameters:
  owner: "myorg"
  repo: "infrastructure"
  path: "config/production.yml"
  ref: "main"
```

## Error Handling

The server provides detailed error messages:

- **Authentication Errors**: Check your access token is valid and has required scopes
- **Repository Not Found**: Verify owner and repository names
- **Invalid Parameters**: Check parameter types and required fields
- **Network Errors**: Verify Forgejo URL is accessible

## Integration with MCP Gateway

The Forgejo-MCP server is automatically registered with the MCP gateway via the `MCP_BACKEND_FORGEJO` environment variable. The gateway will:

1. Discover all available tools
2. Register them in the tool registry
3. Route requests to the Forgejo-MCP service
4. Handle authentication and error responses

## Development

### Building Locally

```bash
pip install -r requirements.txt
python3 -m mcp.server.stdio_sse_server forgejo_mcp:server --port 8400
```

### Testing

Use the MCP Inspector to test the server:

```bash
npx @modelcontextprotocol/inspector python3 -m mcp.server.stdio_sse_server forgejo_mcp:server
```

## API Documentation

For more information about the Forgejo API, visit:
https://forgejo.org/docs/latest/api/

## Troubleshooting

### "Invalid token" errors
- Verify the token is correct and hasn't expired
- Check token has required scopes (at minimum: `repo`)
- Try creating a new token with full permissions

### "Repository not found"
- Verify the owner and repository names are correct
- Check the user/org has the repository
- Ensure you have access permissions

### Connection timeout
- Verify Forgejo URL is correct and accessible
- Check network connectivity to the Forgejo instance
- Verify firewall rules allow the connection

### 403 Forbidden
- Check token has appropriate scopes
- Verify repository access permissions
- Ensure token hasn't been revoked

## Security Considerations

- **Token Storage**: Store the access token in environment variables or secure configuration
- **Network**: Use HTTPS in production
- **Permissions**: Use tokens with minimal required scopes
- **Monitoring**: Monitor token usage and revoke unused tokens
- **Rotation**: Periodically rotate access tokens

## License

Part of the MCP gateway ecosystem.