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

5.7 KiB
Raw Blame History

Forgejo MCP Setup Guide

This guide walks you through adding Forgejo-MCP to your MCP gateway.

Quick Start

1. Prerequisites

  • Docker and Docker Compose installed
  • Forgejo instance running at http://10.0.0.25:34577
  • Forgejo API access token (you have this: df0555d179c7ce6d11c6605b7ddad0921c3c4c83)

2. Update Environment Variables

Add the following to your .env file in the mcp-gateway directory:

# Forgejo Configuration
FORGEJO_URL=http://10.0.0.25:34577
FORGEJO_ACCESS_TOKEN=df0555d179c7ce6d11c6605b7ddad0921c3c4c83

3. Build and Deploy

cd /path/to/mcp-gateway

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

# Start the service
docker-compose up -d forgejo-mcp

# Verify it's running
docker-compose logs -f forgejo-mcp

4. Verify Integration

The gateway should automatically discover the Forgejo-MCP service. Check the gateway logs:

docker-compose logs -f gateway

You should see a message like:

Backend configured: forgejo -> http://mcp-forgejo:8400/mcp

5. Test the Tools

Using curl to test the gateway:

# List repositories (example)
curl -X POST http://localhost:4444/call_tool \
  -H "Authorization: Bearer YOUR_GATEWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "forgejo_list_repositories",
    "arguments": {
      "owner": "your-username"
    }
  }'

Configuration Details

Forgejo API Token

Your token has been provided: df0555d179c7ce6d11c6605b7ddad0921c3c4c83

This token provides access to:

  • Repository operations
  • Issue management
  • Pull request management
  • User information
  • File reading

To create new tokens in Forgejo:

  1. Log in to your Forgejo instance
  2. Go to Settings → Applications → Personal Access Tokens
  3. Click "New Token"
  4. Name: MCP Gateway
  5. Scopes:
    • ✓ repo - Full repository access
    • ✓ read:user - Read user information
  6. Click "Generate Token"
  7. Copy the token and add to .env

Port Configuration

  • Forgejo-MCP Service: Port 8400 (internal to Docker)
  • MCP Gateway: Port 4444 (exposed to host)
  • Forgejo: http://10.0.0.25:34577 (local network)

Health Checks

The Forgejo-MCP service includes health checks:

# Check service health
docker-compose ps forgejo-mcp

# Manual health check
curl http://localhost:8400/health

Available Tools

After setup, the following tools will be available through the gateway:

Repository Management

  • forgejo_list_repositories - List user/org repositories
  • forgejo_get_repository - Get repository details
  • forgejo_create_repository - Create a new repository

Issue Management

  • forgejo_list_issues - List repository issues
  • forgejo_create_issue - Create a new issue
  • forgejo_update_issue - Update an issue

Pull Requests

  • forgejo_list_pull_requests - List pull requests
  • forgejo_create_pull_request - Create a pull request

Files & Branches

  • forgejo_list_branches - List repository branches
  • forgejo_get_file - Read file contents

Search & Users

  • forgejo_search_repositories - Search repositories
  • forgejo_get_user - Get user profile information

Troubleshooting

Service won't start

Check logs:

docker-compose logs forgejo-mcp

Common issues:

  • Port 8400 already in use: Change PORT in docker-compose.yml
  • Missing environment variables: Verify .env file has FORGEJO_ACCESS_TOKEN
  • Network issues: Verify 10.0.0.25:34577 is reachable

Gateway can't connect to Forgejo-MCP

# Check service is running
docker-compose ps forgejo-mcp

# Check network connectivity
docker exec mcp-gateway ping mcp-forgejo

# Check gateway logs
docker-compose logs gateway

Authentication errors

Verify your token:

# Test Forgejo API directly
curl -H "Authorization: token df0555d179c7ce6d11c6605b7ddad0921c3c4c83" \
  http://10.0.0.25:34577/api/v1/user

Should return your user information.

Tool returns empty results

  • Verify you have repositories in Forgejo
  • Check you're using correct owner name (username or org name)
  • Try with limit: 50 to increase result count

Performance Considerations

  • Pagination: Tools support pagination with limit and page parameters
  • Default limits: Default limit is 20 items per request
  • Large result sets: Use pagination to retrieve more results
  • API rate limiting: Forgejo's rate limiting is not typically a concern for local instances

Security Best Practices

  1. Token Management

    • Store token in .env (Git-ignored)
    • Don't hardcode tokens in source files
    • Periodically rotate tokens
    • Use minimal scope tokens

  2. Network Security

    • Use HTTPS for production Forgejo instances
    • Restrict gateway access with authentication
    • Use firewall rules to limit access to Forgejo

  3. Monitoring

    • Monitor token usage logs
    • Review gateway logs for errors
    • Alert on authentication failures

Next Steps

  1. Test the integration: Use the gateway API to list repositories
  2. Configure access: Set up OAuth users if needed
  3. Monitor: Check logs for any issues
  4. Extend: Create additional workflows using Forgejo tools

Stopping the Service

# Stop just Forgejo-MCP
docker-compose stop forgejo-mcp

# Stop all services
docker-compose down

# Stop and remove volumes
docker-compose down -v

Updating the Service

After making changes to the code:

# Rebuild
docker-compose build forgejo-mcp

# Restart
docker-compose up -d forgejo-mcp

# Check logs
docker-compose logs -f forgejo-mcp

Additional Resources