Add mcp-gateway/forgejo-mcp/INTEGRATION_GUIDE.md
This commit is contained in:
parent
5892891c91
commit
68167804ad
1 changed files with 438 additions and 0 deletions
438
mcp-gateway/forgejo-mcp/INTEGRATION_GUIDE.md
Normal file
438
mcp-gateway/forgejo-mcp/INTEGRATION_GUIDE.md
Normal file
|
|
@ -0,0 +1,438 @@
|
|||
# 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 <image_id>
|
||||
```
|
||||
|
||||
### 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 <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
|
||||
Loading…
Reference in a new issue