diff --git a/mcp-gateway/forgejo-mcp/README.md b/mcp-gateway/forgejo-mcp/README.md deleted file mode 100644 index 5781f25..0000000 --- a/mcp-gateway/forgejo-mcp/README.md +++ /dev/null @@ -1,305 +0,0 @@ -# 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.