Add forgejo-mcp/INTEGRATION_GUIDE.md
This commit is contained in:
parent
7c8861e048
commit
fc489a2673
1 changed files with 438 additions and 0 deletions
438
forgejo-mcp/INTEGRATION_GUIDE.md
Normal file
438
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