Remove mcp-gateway/FORGEJO_SETUP.md
This commit is contained in:
parent
25afe141f2
commit
3c5b473ce4
1 changed files with 0 additions and 245 deletions
|
|
@ -1,245 +0,0 @@
|
||||||
# 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