docs: rewrite README with structured overview and quick start guide
Replaces the minimal project description with a comprehensive README including a component overview table, quick start instructions, common Ansible operations, and links to detailed documentation. Aligns with Red Panda Approval™ standards.
This commit is contained in:
344
docs/github_mcp.md
Normal file
344
docs/github_mcp.md
Normal file
@@ -0,0 +1,344 @@
|
||||
# GitHub MCP Server
|
||||
|
||||
## Overview
|
||||
|
||||
The GitHub MCP server provides read-only access to GitHub repositories through the Model Context Protocol (MCP). It enables AI assistants and other MCP clients to explore repository contents, search code, read issues, and analyze pull requests without requiring local clones.
|
||||
|
||||
**Deployment Host:** miranda.incus (10.10.0.156)
|
||||
**Port:** 25533 (HTTP MCP endpoint)
|
||||
**MCPO Proxy:** http://miranda.incus:25530/github
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ MCP CLIENTS │
|
||||
│ VS Code/Cline │ OpenWebUI │ Custom Applications │
|
||||
└─────────────────────────┬───────────────────────────────────┘
|
||||
│
|
||||
┌───────────┴──────────────┐
|
||||
│ │
|
||||
▼ ▼
|
||||
Direct MCP (port 25533) MCPO Proxy (port 25530)
|
||||
streamable-http OpenAI-compatible API
|
||||
│ │
|
||||
└──────────┬───────────────┘
|
||||
▼
|
||||
┌──────────────────────┐
|
||||
│ GitHub MCP Server │
|
||||
│ Docker Container │
|
||||
│ miranda.incus │
|
||||
└──────────┬───────────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────────────┐
|
||||
│ GitHub API │
|
||||
│ (Read-Only PAT) │
|
||||
└──────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## GitHub Personal Access Token
|
||||
|
||||
### Required Scopes
|
||||
|
||||
The GitHub MCP server requires a **read-only Personal Access Token (PAT)** with the following scopes:
|
||||
|
||||
| Scope | Purpose |
|
||||
|-------|---------|
|
||||
| `public_repo` | Read access to public repositories |
|
||||
| `repo` | Read access to private repositories (if needed) |
|
||||
| `read:org` | Read organization membership and teams |
|
||||
| `read:user` | Read user profile information |
|
||||
|
||||
### Creating a PAT
|
||||
|
||||
1. Navigate to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
|
||||
2. Click "Generate new token (classic)"
|
||||
3. Set name: `Agathos GitHub MCP - Read Only`
|
||||
4. Set expiration: Custom or 90 days (recommended)
|
||||
5. Select scopes: `public_repo`, `read:org`, `read:user`
|
||||
6. Click "Generate token"
|
||||
7. Copy the token immediately (it won't be shown again)
|
||||
8. Store in Ansible vault: `ansible-vault edit ansible/inventory/group_vars/all/vault.yml`
|
||||
- Add: `vault_github_personal_access_token: "ghp_xxxxxxxxxxxxx"`
|
||||
|
||||
---
|
||||
|
||||
## Available Tools
|
||||
|
||||
The GitHub MCP server provides the following tools:
|
||||
|
||||
### Repository Operations
|
||||
- `get_file_contents` - Read file contents from repository
|
||||
- `search_repositories` - Search for repositories on GitHub
|
||||
- `list_commits` - List commits in a repository
|
||||
- `create_branch` - Create a new branch (requires write access)
|
||||
- `push_files` - Push files to repository (requires write access)
|
||||
|
||||
### Issue Management
|
||||
- `create_issue` - Create a new issue (requires write access)
|
||||
- `list_issues` - List issues in a repository
|
||||
- `get_issue` - Get details of a specific issue
|
||||
- `update_issue` - Update an issue (requires write access)
|
||||
|
||||
### Pull Request Management
|
||||
- `create_pull_request` - Create a new PR (requires write access)
|
||||
- `list_pull_requests` - List pull requests in a repository
|
||||
- `get_pull_request` - Get details of a specific PR
|
||||
|
||||
### Search Operations
|
||||
- `search_code` - Search code across repositories
|
||||
- `search_users` - Search for GitHub users
|
||||
|
||||
**Note:** With a read-only PAT, write operations (`create_*`, `update_*`, `push_*`) will fail. The primary use case is repository exploration and code reading.
|
||||
|
||||
---
|
||||
|
||||
## Client Configuration
|
||||
|
||||
### MCP Native Clients (Cline, Claude Desktop)
|
||||
|
||||
Add the following to your MCP settings (e.g., `~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`):
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"github": {
|
||||
"type": "streamable-http",
|
||||
"url": "http://miranda.incus:25533/mcp"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### OpenWebUI Configuration
|
||||
|
||||
1. Navigate to **Settings → Tools → OpenAPI Servers**
|
||||
2. Click **Add OpenAPI Server**
|
||||
3. Configure:
|
||||
- **Name:** GitHub MCP
|
||||
- **URL:** `http://miranda.incus:25530/github`
|
||||
- **Authentication:** None (MCPO handles upstream auth)
|
||||
4. Save and enable desired GitHub tools
|
||||
|
||||
### Custom Applications
|
||||
|
||||
**Direct MCP Connection:**
|
||||
```python
|
||||
import mcp
|
||||
|
||||
client = mcp.Client("http://miranda.incus:25533/mcp")
|
||||
tools = await client.list_tools()
|
||||
```
|
||||
|
||||
**Via MCPO (OpenAI-compatible):**
|
||||
```python
|
||||
import openai
|
||||
|
||||
client = openai.OpenAI(
|
||||
base_url="http://miranda.incus:25530/github",
|
||||
api_key="not-required" # MCPO doesn't require auth for GitHub MCP
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Deployment
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Miranda container running with Docker installed
|
||||
- Ansible vault containing `vault_github_personal_access_token`
|
||||
- Network connectivity from clients to miranda.incus
|
||||
|
||||
### Deploy GitHub MCP Server
|
||||
|
||||
```bash
|
||||
cd /home/robert/dv/agathos/ansible
|
||||
ansible-playbook github_mcp/deploy.yml
|
||||
```
|
||||
|
||||
This playbook:
|
||||
1. Creates `github_mcp` user and group
|
||||
2. Creates `/srv/github_mcp` directory
|
||||
3. Templates docker-compose.yml with PAT from vault
|
||||
4. Starts github-mcp-server container on port 25533
|
||||
|
||||
### Update MCPO Configuration
|
||||
|
||||
```bash
|
||||
ansible-playbook mcpo/deploy.yml
|
||||
```
|
||||
|
||||
This restarts MCPO with the updated config including GitHub MCP server.
|
||||
|
||||
### Update Alloy Logging
|
||||
|
||||
```bash
|
||||
ansible-playbook alloy/deploy.yml --limit miranda.incus
|
||||
```
|
||||
|
||||
This reconfigures Alloy to collect GitHub MCP server logs.
|
||||
|
||||
---
|
||||
|
||||
## Verification
|
||||
|
||||
### Test Direct MCP Endpoint
|
||||
|
||||
```bash
|
||||
# Check container is running
|
||||
ssh miranda.incus docker ps | grep github-mcp-server
|
||||
|
||||
# Test MCP endpoint responds
|
||||
curl http://miranda.incus:25533/mcp
|
||||
|
||||
# List available tools (expect JSON response)
|
||||
curl -X POST http://miranda.incus:25533/mcp \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'
|
||||
```
|
||||
|
||||
### Test MCPO Proxy
|
||||
|
||||
```bash
|
||||
# List GitHub tools via MCPO
|
||||
curl http://miranda.incus:25530/github/tools
|
||||
|
||||
# Test repository file reading
|
||||
curl -X POST http://miranda.incus:25530/github/tools/get_file_contents \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"owner": "github",
|
||||
"repo": "docs",
|
||||
"path": "README.md"
|
||||
}'
|
||||
```
|
||||
|
||||
### View Logs
|
||||
|
||||
```bash
|
||||
# Container logs
|
||||
ssh miranda.incus docker logs github-mcp-server
|
||||
|
||||
# Loki logs (via Grafana on prospero.incus)
|
||||
# Navigate to Explore → Loki
|
||||
# Query: {job="github-mcp-server"}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Container Won't Start
|
||||
|
||||
**Check Docker Compose:**
|
||||
```bash
|
||||
ssh miranda.incus
|
||||
sudo -u github_mcp docker compose -f /srv/github_mcp/docker-compose.yml logs
|
||||
```
|
||||
|
||||
**Common Issues:**
|
||||
- Missing or invalid GitHub PAT in vault
|
||||
- Port 25533 already in use
|
||||
- Docker image pull failure
|
||||
|
||||
### MCP Endpoint Returns Errors
|
||||
|
||||
**Check GitHub PAT validity:**
|
||||
```bash
|
||||
curl -H "Authorization: token YOUR_PAT" https://api.github.com/user
|
||||
```
|
||||
|
||||
**Verify PAT scopes:**
|
||||
```bash
|
||||
curl -i -H "Authorization: token YOUR_PAT" https://api.github.com/user \
|
||||
| grep X-OAuth-Scopes
|
||||
```
|
||||
|
||||
### MCPO Not Exposing GitHub Tools
|
||||
|
||||
**Verify MCPO config:**
|
||||
```bash
|
||||
ssh miranda.incus cat /srv/mcpo/config.json | jq '.mcpServers.github'
|
||||
```
|
||||
|
||||
**Restart MCPO:**
|
||||
```bash
|
||||
ssh miranda.incus sudo systemctl restart mcpo
|
||||
ssh miranda.incus sudo systemctl status mcpo
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Monitoring
|
||||
|
||||
### Prometheus Metrics
|
||||
|
||||
GitHub MCP server exposes Prometheus metrics (if supported by the container). Add to Prometheus scrape config:
|
||||
|
||||
```yaml
|
||||
scrape_configs:
|
||||
- job_name: 'github-mcp'
|
||||
static_configs:
|
||||
- targets: ['miranda.incus:25533']
|
||||
```
|
||||
|
||||
### Grafana Dashboard
|
||||
|
||||
Import or create a dashboard on prospero.incus to visualize:
|
||||
- Request rate and latency
|
||||
- GitHub API rate limits
|
||||
- Tool invocation counts
|
||||
- Error rates
|
||||
|
||||
### Log Queries
|
||||
|
||||
Useful Loki queries in Grafana:
|
||||
|
||||
```logql
|
||||
# All GitHub MCP logs
|
||||
{job="github-mcp-server"}
|
||||
|
||||
# Errors only
|
||||
{job="github-mcp-server"} |= "error" or |= "ERROR"
|
||||
|
||||
# GitHub API rate limit warnings
|
||||
{job="github-mcp-server"} |= "rate limit"
|
||||
|
||||
# Tool invocations
|
||||
{job="github-mcp-server"} |= "tool"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Security Considerations
|
||||
|
||||
✔ **Read-Only PAT** - Server uses minimal scopes, cannot modify repositories
|
||||
✔ **Network Isolation** - Only accessible within Agathos network (miranda.incus)
|
||||
✔ **Vault Storage** - PAT stored encrypted in Ansible Vault
|
||||
✔ **No Public Exposure** - MCP endpoint not exposed to internet
|
||||
⚠️ **PAT Rotation** - Consider rotating PAT every 90 days
|
||||
⚠️ **Access Control** - MCPO currently doesn't require authentication
|
||||
|
||||
### Recommended Enhancements
|
||||
|
||||
1. Add authentication to MCPO endpoints
|
||||
2. Implement request rate limiting
|
||||
3. Monitor GitHub API quota usage
|
||||
4. Set up PAT expiration alerts
|
||||
5. Restrict network access to miranda via firewall rules
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- [GitHub MCP Server Repository](https://github.com/github/github-mcp-server)
|
||||
- [Model Context Protocol Specification](https://modelcontextprotocol.io/)
|
||||
- [MCPO Documentation](https://github.com/open-webui/mcpo)
|
||||
- [Agathos README](../../README.md)
|
||||
- [Agathos Sandbox Documentation](../sandbox.html)
|
||||
Reference in New Issue
Block a user