Add FORGEJO_SETUP.md
This commit is contained in:
parent
a6bc138817
commit
95bf59824e
1 changed files with 245 additions and 0 deletions
245
FORGEJO_SETUP.md
Normal file
245
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