305 lines
8.2 KiB
Markdown
305 lines
8.2 KiB
Markdown
# 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.
|