Add forgejo-mcp/README.md
This commit is contained in:
parent
2a40f4cbbc
commit
86d8ed1f20
1 changed files with 305 additions and 0 deletions
305
forgejo-mcp/README.md
Normal file
305
forgejo-mcp/README.md
Normal file
|
|
@ -0,0 +1,305 @@
|
|||
# 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.
|
||||
Loading…
Reference in a new issue