From 86d8ed1f208ce6cef5f493225715ed1732d0c8a9 Mon Sep 17 00:00:00 2001 From: zgaetano Date: Tue, 31 Mar 2026 15:33:35 -0400 Subject: [PATCH] Add forgejo-mcp/README.md --- forgejo-mcp/README.md | 305 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 305 insertions(+) create mode 100644 forgejo-mcp/README.md diff --git a/forgejo-mcp/README.md b/forgejo-mcp/README.md new file mode 100644 index 0000000..5781f25 --- /dev/null +++ b/forgejo-mcp/README.md @@ -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.