From 73555868a5c992f3af23806e090d4185c3927ac0 Mon Sep 17 00:00:00 2001 From: zgaetano Date: Tue, 31 Mar 2026 15:33:06 -0400 Subject: [PATCH] Remove mcp-gateway/forgejo-mcp/INTEGRATION_GUIDE.md --- mcp-gateway/forgejo-mcp/INTEGRATION_GUIDE.md | 438 ------------------- 1 file changed, 438 deletions(-) delete mode 100644 mcp-gateway/forgejo-mcp/INTEGRATION_GUIDE.md diff --git a/mcp-gateway/forgejo-mcp/INTEGRATION_GUIDE.md b/mcp-gateway/forgejo-mcp/INTEGRATION_GUIDE.md deleted file mode 100644 index edca352..0000000 --- a/mcp-gateway/forgejo-mcp/INTEGRATION_GUIDE.md +++ /dev/null @@ -1,438 +0,0 @@ -# Forgejo-MCP Gateway Integration Guide - -## Architecture Overview - -``` -┌─────────────────────────────────────────────────────────┐ -│ MCP Gateway (Port 4444) │ -│ ┌─────────────────────────────────────────────────┐ │ -│ │ OAuth 2.1 + Tool Registry + Request Router │ │ -│ └────────┬────────────────────────────────────────┘ │ -└───────────┼─────────────────────────────────────────────┘ - │ - │ MCP_BACKEND_FORGEJO=http://mcp-forgejo:8400/mcp - │ -┌───────────▼─────────────────────────────────────────────┐ -│ Forgejo-MCP Service (Port 8400) │ -│ ┌─────────────────────────────────────────────────┐ │ -│ │ 12 Repository/Issue/PR/File Tools │ │ -│ │ Async HTTP Client for Forgejo API │ │ -│ └────────┬────────────────────────────────────────┘ │ -└───────────┼─────────────────────────────────────────────┘ - │ FORGEJO_ACCESS_TOKEN - │ -┌───────────▼─────────────────────────────────────────────┐ -│ Forgejo Instance (http://10.0.0.25:34577) │ -│ ┌─────────────────────────────────────────────────┐ │ -│ │ Repositories, Issues, PRs, Users │ │ -│ └─────────────────────────────────────────────────┘ │ -└─────────────────────────────────────────────────────────┘ -``` - -## Integration Points - -### 1. Docker Network - -The `forgejo-mcp` service joins the `mcpnet` network, allowing internal communication with the gateway: - -```yaml -networks: - mcpnet: - driver: bridge - -services: - forgejo-mcp: - networks: [mcpnet] -``` - -### 2. Gateway Backend Registration - -In `gateway_proxy.py`, backends are discovered via environment variables: - -```python -def load_backends() -> dict[str, str]: - backends = {} - for key, value in os.environ.items(): - if key.startswith("MCP_BACKEND_"): - name = key[len("MCP_BACKEND_"):].lower() - backends[name] = value - return backends -``` - -The `docker-compose.yml` provides: -``` -MCP_BACKEND_FORGEJO=http://mcp-forgejo:8400/mcp -``` - -This automatically registers the Forgejo-MCP service with the gateway. - -### 3. Tool Discovery - -When Claude requests tools, the gateway: - -1. Makes a `GET /tools` request to `http://mcp-forgejo:8400/mcp` -2. Receives the list of 12 available tools -3. Registers them with the tool registry -4. Prefixes tools with the backend name: `forgejo_list_repositories`, etc. - -### 4. Request Routing - -When Claude calls a `forgejo_*` tool: - -1. Gateway receives the request with tool name and arguments -2. Routes to the appropriate backend (Forgejo-MCP) -3. Makes `POST /call_tool` request to Forgejo-MCP -4. Returns results to Claude - -## Configuration Checklist - -Before deploying, verify: - -### Environment Variables -- [ ] `FORGEJO_URL` is set (default: `http://10.0.0.25:34577`) -- [ ] `FORGEJO_ACCESS_TOKEN` is set to your token -- [ ] Token has `repo` scope - -### Docker Compose -- [ ] `docker-compose.yml` includes `forgejo-mcp` service -- [ ] Service port is `8400` -- [ ] Environment variables are passed to container -- [ ] `networks: [mcpnet]` is configured -- [ ] Health check is configured - -### Gateway Configuration -- [ ] `docker-compose.yml` gateway includes `MCP_BACKEND_FORGEJO` environment -- [ ] Gateway depends on `forgejo-mcp` service - -## Health Checks - -### Service Health - -```bash -# Check service is running -docker-compose ps forgejo-mcp - -# Check logs -docker-compose logs forgejo-mcp - -# Manual health check -curl http://localhost:8400/health -``` - -### Network Connectivity - -```bash -# From gateway container, ping forgejo-mcp -docker exec mcp-gateway ping mcp-forgejo - -# From gateway container, check tool endpoint -docker exec mcp-gateway curl http://mcp-forgejo:8400/tools -``` - -### Gateway Integration - -```bash -# Check gateway logs for backend initialization -docker-compose logs gateway | grep -i forgejo - -# Should show: -# Backend configured: forgejo -> http://mcp-forgejo:8400/mcp -``` - -## Deployment Steps - -### 1. Prepare Environment - -```bash -cd /path/to/mcp-gateway - -# Add to .env file -echo "FORGEJO_URL=http://10.0.0.25:34577" >> .env -echo "FORGEJO_ACCESS_TOKEN=df0555d179c7ce6d11c6605b7ddad0921c3c4c83" >> .env -``` - -### 2. Build Service - -```bash -# Build the Forgejo-MCP image -docker-compose build forgejo-mcp - -# Output should show: -# Step 1/6 : FROM python:3.11-slim -# ... -# Successfully built -``` - -### 3. Start Service - -```bash -# Start the Forgejo-MCP service -docker-compose up -d forgejo-mcp - -# Wait for startup (healthcheck) -sleep 5 - -# Verify running -docker-compose ps forgejo-mcp -# Should show "Up" status -``` - -### 4. Restart Gateway - -If the gateway was already running, restart it to pick up the new backend: - -```bash -docker-compose restart gateway - -# Check logs -docker-compose logs -f gateway -``` - -### 5. Verify Tools - -Test tool discovery through the gateway: - -```bash -# List available tools (if gateway provides this endpoint) -curl -H "Authorization: Bearer YOUR_GATEWAY_TOKEN" \ - http://localhost:4444/tools | jq '.[] | select(.name | startswith("forgejo"))' - -# Should list all 12 forgejo_* tools -``` - -## Tool Availability - -Once integrated, these tools will be available: - -**Repository Management** (3 tools) -- `forgejo_list_repositories` -- `forgejo_get_repository` -- `forgejo_create_repository` - -**Issue Management** (3 tools) -- `forgejo_list_issues` -- `forgejo_create_issue` -- `forgejo_update_issue` - -**Pull Requests** (2 tools) -- `forgejo_list_pull_requests` -- `forgejo_create_pull_request` - -**Branches & Files** (2 tools) -- `forgejo_list_branches` -- `forgejo_get_file` - -**Search & Users** (2 tools) -- `forgejo_search_repositories` -- `forgejo_get_user` - -## Testing Integration - -### Test 1: List Repositories - -Request to gateway: -```json -{ - "tool": "forgejo_list_repositories", - "arguments": { - "owner": "your-username" - } -} -``` - -Expected: List of repositories for the user - -### Test 2: Get Repository Details - -Request to gateway: -```json -{ - "tool": "forgejo_get_repository", - "arguments": { - "owner": "your-username", - "repo": "your-repo" - } -} -``` - -Expected: Detailed repository information - -### Test 3: List Issues - -Request to gateway: -```json -{ - "tool": "forgejo_list_issues", - "arguments": { - "owner": "your-username", - "repo": "your-repo", - "state": "open" - } -} -``` - -Expected: Open issues for the repository - -## Troubleshooting Integration - -### Issue: Service doesn't start - -```bash -# Check logs -docker-compose logs forgejo-mcp - -# Common causes: -# - Missing environment variables -# - Port 8400 already in use -# - Invalid base image -``` - -### Issue: Gateway can't connect - -```bash -# Check network -docker network inspect mcpnet - -# Check service IP -docker inspect mcp-forgejo | grep IPAddress - -# Test from gateway container -docker exec mcp-gateway curl -v http://mcp-forgejo:8400/health -``` - -### Issue: Tools not appearing in gateway - -```bash -# Check gateway backend configuration -docker-compose logs gateway | grep -i backend - -# Check gateway can reach service -docker exec mcp-gateway curl http://mcp-forgejo:8400/tools - -# Restart gateway -docker-compose restart gateway -``` - -### Issue: Authentication fails - -```bash -# Test token directly -curl -H "Authorization: token df0555d179c7ce6d11c6605b7ddad0921c3c4c83" \ - http://10.0.0.25:34577/api/v1/user - -# Should return user info, not 401 -``` - -## Performance Considerations - -### Request Latency - -- Gateway to Forgejo-MCP: ~5-10ms (local network) -- Forgejo-MCP to Forgejo: ~10-50ms (HTTP API) -- Total: ~15-60ms per tool call - -### Concurrent Requests - -The Forgejo-MCP server uses async Python with httpx, supporting: -- Multiple concurrent requests -- Connection pooling -- Efficient I/O handling - -### Rate Limiting - -Forgejo local instances typically have no rate limiting. For remote instances, be aware of: -- API rate limits (if enforced) -- Token usage monitoring -- Large result set pagination - -## Security Integration - -### Token Management - -The token is: -- Passed via environment variable (not hardcoded) -- Used in HTTP header: `Authorization: token ` -- Should be rotated periodically - -### Network Security - -- Internal network (`mcpnet`) - secure local communication -- External access only through gateway (port 4444) -- Gateway handles authentication (OAuth 2.1) - -### Data Flow - -``` -Claude Client - ↓ - └─→ Gateway (authenticated) - ├─ Validates request - ├─ Routes to Forgejo-MCP - └─ Returns response - └─→ Forgejo-MCP - ├─ Uses token from env - └─ Calls Forgejo API - └─→ Forgejo Instance -``` - -## Monitoring - -### Log Aggregation - -```bash -# View all service logs -docker-compose logs -f - -# View specific service -docker-compose logs -f forgejo-mcp - -# Follow errors only -docker-compose logs -f 2>&1 | grep ERROR -``` - -### Health Monitoring - -```bash -# Set up monitoring -watch -n 5 'docker-compose ps' - -# Check service health periodically -*/5 * * * * docker-compose exec mcp-forgejo curl -f http://localhost:8400/health -``` - -## Updating the Service - -To update the Forgejo-MCP code: - -```bash -# Edit forgejo_mcp.py - -# Rebuild -docker-compose build --no-cache forgejo-mcp - -# Restart -docker-compose up -d forgejo-mcp - -# Check logs -docker-compose logs -f forgejo-mcp -``` - -## Integration with Claude.ai - -Once deployed: - -1. Connect your MCP gateway to Claude.ai -2. The gateway exposes `forgejo_*` tools -3. Claude can use these tools to: - - List and explore repositories - - Create and manage issues - - Work with pull requests - - Read repository files - - Search repositories - -Example Claude prompt: -> List all open issues in my main project and create a summary - -This would use: -- `forgejo_list_issues` - Get open issues -- Process and summarize results