Add mcp-gateway/FORGEJO_SETUP.md
This commit is contained in:
parent
537ecb7722
commit
fa7a182e78
1 changed files with 245 additions and 0 deletions
245
mcp-gateway/FORGEJO_SETUP.md
Normal file
245
mcp-gateway/FORGEJO_SETUP.md
Normal file
|
|
@ -0,0 +1,245 @@
|
||||||
|
# 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:
|
||||||
|
|
||||||
|
```env
|
||||||
|
# Forgejo Configuration
|
||||||
|
FORGEJO_URL=http://10.0.0.25:34577
|
||||||
|
FORGEJO_ACCESS_TOKEN=df0555d179c7ce6d11c6605b7ddad0921c3c4c83
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Build and Deploy
|
||||||
|
|
||||||
|
```bash
|
||||||
|
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:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
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:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 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:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 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:
|
||||||
|
```bash
|
||||||
|
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
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 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:
|
||||||
|
```bash
|
||||||
|
# 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
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 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:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Rebuild
|
||||||
|
docker-compose build forgejo-mcp
|
||||||
|
|
||||||
|
# Restart
|
||||||
|
docker-compose up -d forgejo-mcp
|
||||||
|
|
||||||
|
# Check logs
|
||||||
|
docker-compose logs -f forgejo-mcp
|
||||||
|
```
|
||||||
|
|
||||||
|
## Additional Resources
|
||||||
|
|
||||||
|
- [Forgejo API Documentation](https://forgejo.org/docs/latest/api/)
|
||||||
|
- [MCP Specification](https://modelcontextprotocol.io/)
|
||||||
|
- [Gateway Configuration](./DEPLOYMENT_GUIDE.md)
|
||||||
Loading…
Reference in a new issue