Remove mcp-gateway/forgejo-mcp/INTEGRATION_GUIDE.md
This commit is contained in:
parent
fa552541a9
commit
73555868a5
1 changed files with 0 additions and 438 deletions
|
|
@ -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 <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