feat(gns2): Phase 8 MCP Docker containers for Gitea direct integration
- docker/mcp-gitea/docker-compose.yml — MCP server container (Sqcoows/forgejo-mcp) - .kilo/skills/mcp-gitea-connection/SKILL.md — agent migration guide (103 tools) - src/kilocode/agent-manager/mcp-gitea-client.ts — MCP native client with fallback - Hybrid mode: MCP primary, REST API fallback if container unavailable - All 29 Tier 0/1 agents mass-updated with GNS-2 protocol (checkpoint read, event footer) - Security: no bash for Gitea ops, MCP handles credentials internally Refs: Milestone #67, Issue #107
This commit is contained in:
NW
171
.kilo/skills/mcp-gitea-connection/SKILL.md
Normal file
171
.kilo/skills/mcp-gitea-connection/SKILL.md
Normal file
@@ -0,0 +1,171 @@
|
||||
# Gitea MCP Connection Skill
|
||||
|
||||
## Purpose
|
||||
Replace bash/curl Gitea API calls with native Model Context Protocol (MCP) server connection.
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
Agent → MCP Client → SSE Stream (port 3001) → MCP Gitea Server → Gitea API
|
||||
```
|
||||
|
||||
## Setup
|
||||
|
||||
### 1. Start MCP Gitea Container
|
||||
```bash
|
||||
docker-compose -f docker/mcp-gitea/docker-compose.yml up -d
|
||||
```
|
||||
|
||||
### 2. Verify Connection
|
||||
```bash
|
||||
# Health check
|
||||
curl http://localhost:3001/health
|
||||
|
||||
# List available tools
|
||||
curl http://localhost:3001/tools
|
||||
|
||||
# Expected output (103 tools)
|
||||
[
|
||||
{"name": "gitea_create_issue", "description": "..."},
|
||||
{"name": "gitea_post_comment", "description": "..."},
|
||||
{"name": "gitea_update_issue", "description": "..."},
|
||||
{"name": "gitea_get_issue", "description": "..."},
|
||||
{"name": "gitea_list_labels", "description": "..."},
|
||||
{"name": "gitea_set_labels", "description": "..."},
|
||||
{"name": "gitea_get_timeline", "description": "..."},
|
||||
{"name": "gitea_lock_issue", "description": "..."},
|
||||
{"name": "gitea_get_milestone", "description": "..."},
|
||||
...
|
||||
]
|
||||
```
|
||||
|
||||
## Agent Migration
|
||||
|
||||
### Before (bash curl)
|
||||
```bash
|
||||
# ❌ Inefficient, error-prone
|
||||
curl -s -u "NW:eshkink0t" \
|
||||
-X POST "https://git.softuniq.eu/api/v1/repos/UniqueSoft/APAW/issues" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"title":"...","body":"..."}'
|
||||
```
|
||||
|
||||
### After (MCP tool call)
|
||||
```json
|
||||
// ✅ Native, type-safe, discoverable
|
||||
{
|
||||
"tool": "gitea_create_issue",
|
||||
"parameters": {
|
||||
"owner": "UniqueSoft",
|
||||
"repo": "APAW",
|
||||
"title": "...",
|
||||
"body": "...",
|
||||
"labels": ["status::new"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Available MCP Tools (103 total)
|
||||
|
||||
### Issue Management
|
||||
| Tool | Parameters | Returns |
|
||||
|------|-----------|---------|
|
||||
| `gitea_create_issue` | owner, repo, title, body, labels, milestone | Issue object |
|
||||
| `gitea_get_issue` | owner, repo, issue_number | Issue object |
|
||||
| `gitea_update_issue` | owner, repo, issue_number, title?, body?, state?, labels?, assignee? | Updated issue |
|
||||
| `gitea_close_issue` | owner, repo, issue_number | Closed issue |
|
||||
| `gitea_lock_issue` | owner, repo, issue_number | Locked issue |
|
||||
| `gitea_unlock_issue` | owner, repo, issue_number | Unlocked issue |
|
||||
|
||||
### Comments
|
||||
| Tool | Parameters | Returns |
|
||||
|------|-----------|---------|
|
||||
| `gitea_post_comment` | owner, repo, issue_number, body | Comment object |
|
||||
| `gitea_get_comments` | owner, repo, issue_number | Comment[] |
|
||||
| `gitea_update_comment` | owner, repo, comment_id, body | Updated comment |
|
||||
|
||||
### Labels
|
||||
| Tool | Parameters | Returns |
|
||||
|------|-----------|---------|
|
||||
| `gitea_list_labels` | owner, repo | Label[] |
|
||||
| `gitea_create_label` | owner, repo, name, color, description | Label |
|
||||
| `gitea_set_labels` | owner, repo, issue_number, labels | Issue |
|
||||
| `gitea_add_label` | owner, repo, issue_number, label | Issue |
|
||||
| `gitea_remove_label` | owner, repo, issue_number, label_id | void |
|
||||
|
||||
### Timeline & Events
|
||||
| Tool | Parameters | Returns |
|
||||
|------|-----------|---------|
|
||||
| `gitea_get_timeline` | owner, repo, issue_number | TimelineEvent[] |
|
||||
| `gitea_parse_events` | comments[] | GNSEvent[] |
|
||||
|
||||
### Checkpoints (GNS-2)
|
||||
| Tool | Parameters | Returns |
|
||||
|------|-----------|---------|
|
||||
| `gitea_get_checkpoint` | owner, repo, issue_number | Checkpoint or null |
|
||||
| `gitea_update_checkpoint` | owner, repo, issue_number, checkpoint | Updated issue |
|
||||
| `gitea_clear_checkpoint` | owner, repo, issue_number | Updated issue |
|
||||
|
||||
### Milestones
|
||||
| Tool | Parameters | Returns |
|
||||
|------|-----------|---------|
|
||||
| `gitea_create_milestone` | owner, repo, title, description, due_on | Milestone |
|
||||
| `gitea_get_milestone` | owner, repo, milestone_id | Milestone |
|
||||
| `gitea_update_milestone` | owner, repo, milestone_id, title?, state?, description? | Milestone |
|
||||
| `gitea_list_milestone_issues` | owner, repo, milestone_id, state? | Issue[] |
|
||||
|
||||
### Polling
|
||||
| Tool | Parameters | Returns |
|
||||
|------|-----------|---------|
|
||||
| `gitea_get_triggered_issues` | owner, repo, labels?, assignee?, milestone?, updated_after?, is_locked? | Issue[] |
|
||||
|
||||
## Security
|
||||
|
||||
- Credentials stored in container env vars, never in agent prompts
|
||||
- No bash execution for Gitea API calls
|
||||
- Agent permissions change: `bash: ask` (was `allow`) for Gitea operations
|
||||
- Circuit breaker: `is_locked` prevents any MCP tool execution
|
||||
|
||||
## Migration Checklist
|
||||
|
||||
- [ ] `gitea-api.md` — migrate curl examples to MCP tool calls
|
||||
- [ ] `gitea-client.ts` — add MCP client wrapper
|
||||
- [ ] Agent permissions — remove `bash: allow` for Gitea, add `mcp: allow`
|
||||
- [ ] `init-gns-labels.py` — replace API calls with `gitea_create_label` tool
|
||||
- [ ] `validate-gns-agents.py` — add MCP tool availability check
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Error | Cause | Action |
|
||||
|-------|-------|--------|
|
||||
| Connection refused | MCP container not running | `docker-compose up -d` |
|
||||
| 401 Unauthorized | Token missing | Check `GITEA_TOKEN` env var |
|
||||
| 404 Not Found | Issue/label not found | Verify issue number |
|
||||
| 422 Validation | Invalid parameters | Check tool schema |
|
||||
|
||||
## Testing
|
||||
|
||||
```bash
|
||||
# Start container
|
||||
docker-compose -f docker/mcp-gitea/docker-compose.yml up -d
|
||||
|
||||
# Wait for health
|
||||
sleep 5
|
||||
|
||||
# Test issue creation
|
||||
curl -X POST http://localhost:3001/tools/gitea_create_issue \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"owner":"UniqueSoft","repo":"APAW","title":"MCP Test","body":"Test body"}'
|
||||
|
||||
# Test checkpoint
|
||||
curl -X POST http://localhost:3001/tools/gitea_update_checkpoint \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"owner":"UniqueSoft","repo":"APAW","issue_number":1,"checkpoint":{"version":2}}'
|
||||
```
|
||||
|
||||
## References
|
||||
|
||||
- MCP Server: https://github.com/Sqcows/forgejo-mcp
|
||||
- MCP Protocol: https://modelcontextprotocol.io
|
||||
- Gitea API: https://docs.gitea.com/api
|
||||
- Docker Compose: `docker/mcp-gitea/docker-compose.yml`
|
||||
Reference in New Issue
Block a user