zgaetano/mcp-servers
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
mcp-servers/mcp-gateway/forgejo-mcp/INTEGRATION_GUIDE.md

11 KiB
Raw Blame History

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:

networks:
  mcpnet:
    driver: bridge

services:
  forgejo-mcp:
    networks: [mcpnet]

2. Gateway Backend Registration

In gateway_proxy.py, backends are discovered via environment variables:

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

# 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

# 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

# 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

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

# Build the Forgejo-MCP image
docker-compose build forgejo-mcp

# Output should show:
# Step 1/6 : FROM python:3.11-slim
# ...
# Successfully built <image_id>

3. Start Service

# 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:

docker-compose restart gateway

# Check logs
docker-compose logs -f gateway

5. Verify Tools

Test tool discovery through the gateway:

# 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:

{
  "tool": "forgejo_list_repositories",
  "arguments": {
    "owner": "your-username"
  }
}

Expected: List of repositories for the user

Test 2: Get Repository Details

Request to gateway:

{
  "tool": "forgejo_get_repository",
  "arguments": {
    "owner": "your-username",
    "repo": "your-repo"
  }
}

Expected: Detailed repository information

Test 3: List Issues

Request to gateway:

{
  "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

# 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

# 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

# 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

# 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 <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

# 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

# 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:

# 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