236 lines
7.4 KiB
Markdown
236 lines
7.4 KiB
Markdown
# Gitea MCP Setup for OpenClaw
|
|
|
|
This guide explains how to set up Gitea MCP with per-agent Gitea account isolation in OpenClaw.
|
|
|
|
## Structure
|
|
|
|
```
|
|
gitea-mcp/
|
|
├── mcp/ # MCP server source code (Go)
|
|
└── AGENTS.md # This file - OpenClaw setup guide
|
|
```
|
|
|
|
## Architecture Overview
|
|
|
|
The Gitea MCP server provides Gitea tools via the Model Context Protocol (MCP). Each MCP instance uses a single Gitea token, making it ideal for per-agent isolation.
|
|
|
|
**Key Features:**
|
|
- stdio mode (default): For local MCP clients
|
|
- HTTP mode: For remote MCP servers on configurable ports
|
|
- 50+ tools: repos, issues, PRs, branches, files, wiki, search, actions, commit status, repo structure
|
|
|
|
**New Wave 2 Tools:**
|
|
- `check_gitea_version` - Check Gitea server version and API capabilities
|
|
- `get_workflow_file_content` - Get workflow files from .gitea/workflows/ or .github/workflows/
|
|
- `list_repo_structure` - List complete repository structure using Git tree API
|
|
- `monitor_workflow_dispatch` - Dispatch and monitor workflows until completion (Gitea 1.23+)
|
|
- `list_action_runners` - List self-hosted action runners (Gitea 1.23+)
|
|
- `create_commit_status` - Create commit status checks for CI/CD
|
|
- `list_action_artifacts` - List and download workflow artifacts (Gitea 1.23+)
|
|
|
|
**Gitea Version Compatibility:**
|
|
- Gitea 1.22.5: Limited Actions API support (no artifacts, runners, or workflow monitoring)
|
|
- Gitea 1.23+: Full Actions API support including all Wave 2 tools
|
|
|
|
## Setup for OpenClaw with Per-Agent Isolation
|
|
|
|
### Step 1: Build the MCP Server
|
|
|
|
```bash
|
|
cd mcp
|
|
make build
|
|
cp gitea-mcp ~/.bun/bin/gitea-mcp
|
|
```
|
|
|
|
### Step 2: Run Multiple MCP Instances
|
|
|
|
Each agent needs its own MCP server instance with its own token:
|
|
|
|
```bash
|
|
# Friday's MCP (runs on port 8081)
|
|
gitea-mcp --host https://gitea.example.com --port 8081 --token <YOUR_GITEA_TOKEN> &
|
|
|
|
# Karti's MCP (runs on port 8082)
|
|
gitea-mcp --host https://gitea.example.com --port 8082 --token <YOUR_GITEA_TOKEN> &
|
|
```
|
|
|
|
### Step 3: Configure MCP Servers in OpenClaw
|
|
|
|
Add to `~/.openclaw/openclaw.json`:
|
|
|
|
```json
|
|
{
|
|
"plugins": {
|
|
"entries": {
|
|
"acpx": {
|
|
"config": {
|
|
"mcpServers": {
|
|
"gitea-mcp-friday": {
|
|
"command": "gitea-mcp",
|
|
"args": ["--host", "https://gitea.example.com", "--port", "8081"],
|
|
"env": {
|
|
"GITEA_ACCESS_TOKEN": "<YOUR_GITEA_TOKEN>"
|
|
}
|
|
},
|
|
"gitea-mcp-karti": {
|
|
"command": "gitea-mcp",
|
|
"args": ["--host", "https://gitea.example.com", "--port", "8082"],
|
|
"env": {
|
|
"GITEA_ACCESS_TOKEN": "<YOUR_GITEA_TOKEN>"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Step 4: Add Per-Agent Tool Restrictions
|
|
|
|
The key for isolation is `tools.allow/deny` per agent. This guarantees each agent can only use its own Gitea MCP:
|
|
|
|
```json
|
|
{
|
|
"agents": {
|
|
"list": [
|
|
{
|
|
"id": "friday",
|
|
"name": "Friday Agent",
|
|
"agentDir": "~/.openclaw/agents/friday/agent",
|
|
"workspace": "/Users/karti/.openclaw/agents/friday/workspace",
|
|
"tools": {
|
|
"allow": ["gitea-mcp-friday:*", "group:fs", "group:runtime"],
|
|
"deny": ["gitea-mcp-karti:*"]
|
|
}
|
|
},
|
|
{
|
|
"id": "karti",
|
|
"name": "Karti Agent",
|
|
"agentDir": "~/.openclaw/agents/karti/agent",
|
|
"workspace": "/Users/karti/.openclaw/agents/karti/workspace",
|
|
"tools": {
|
|
"allow": ["gitea-mcp-karti:*", "group:fs", "group:runtime"],
|
|
"deny": ["gitea-mcp-friday:*"]
|
|
}
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
**Key Points:**
|
|
- `allow`: What tools the agent CAN use
|
|
- `deny`: What tools the agent CANNOT see/use
|
|
- `gitea-mcp-*:*` means all tools from that MCP server
|
|
- `group:fs`, `group:runtime` are built-in tool groups
|
|
|
|
### Step 5: Add Agent Instructions (AGENTS.md per agent)
|
|
|
|
Create per-agent AGENTS.md to enforce behavior:
|
|
|
|
**Friday's workspace** (`~/.openclaw/agents/friday/workspace/AGENTS.md`):
|
|
```markdown
|
|
# Friday Agent
|
|
|
|
You are the Friday Agent. You only have access to the gitea-mcp-friday MCP server.
|
|
|
|
When performing Git operations, use only the gitea-mcp-friday tools.
|
|
Never attempt to use gitea-mcp-karti or any other Gitea MCP server.
|
|
```
|
|
|
|
**Karti's workspace** (`~/.openclaw/agents/karti/workspace/AGENTS.md`):
|
|
```markdown
|
|
# Karti Agent
|
|
|
|
You are the Karti Agent. You only have access to the gitea-mcp-karti MCP server.
|
|
|
|
When performing Git operations, use only the gitea-mcp-karti tools.
|
|
Never attempt to use gitea-mcp-friday or any other Gitea MCP server.
|
|
```
|
|
|
|
## Available MCP Tools
|
|
|
|
Each MCP server provides these tools (prefixed with server name):
|
|
|
|
| Category | Tools |
|
|
|----------|-------|
|
|
| User | get_my_user_info, get_user_orgs, search_users |
|
|
| Repository | create_repo, fork_repo, list_my_repos, search_repos, list_repo_structure |
|
|
| Branches/Tags | create_branch, delete_branch, list_branches, create_tag, list_tags |
|
|
| Files | get_file_content, create_file, update_file, delete_file, get_dir_content |
|
|
| Issues | create_issue, list_repo_issues, create_issue_comment, edit_issue |
|
|
| Pull Requests | create_pull_request, list_repo_pull_requests, get_pull_request_by_index |
|
|
| Releases | create_release, list_releases, get_latest_release |
|
|
| Wiki | create_wiki_page, update_wiki_page, list_wiki_pages |
|
|
| Search | search_repos, search_users, search_org_teams |
|
|
| Server | get_gitea_mcp_server_version, check_gitea_version |
|
|
| Actions | get_workflow_file_content, monitor_workflow_dispatch, list_action_runners, list_action_artifacts, dispatch_repo_action_workflow, list_repo_action_runs |
|
|
| Commit Status | create_commit_status |
|
|
|
|
**Note:** Tools marked with (1.23+) require Gitea 1.23 or later:
|
|
- monitor_workflow_dispatch
|
|
- list_action_runners
|
|
- list_action_artifacts
|
|
|
|
## Testing Per-Agent Isolation
|
|
|
|
Test with TUI for each agent:
|
|
|
|
```bash
|
|
# Test Friday (should only see gitea-mcp-friday tools)
|
|
openclaw tui --session friday --message "list available gitea tools"
|
|
|
|
# Test Karti (should only see gitea-mcp-karti tools)
|
|
openclaw tui --session karti --message "list available gitea tools"
|
|
```
|
|
|
|
## Adding New Agents
|
|
|
|
To add a new agent (e.g., "edith"):
|
|
|
|
1. Run a new MCP instance:
|
|
```bash
|
|
gitea-mcp --host https://gitea.example.com --port 8083 --token <YOUR_GITEA_TOKEN> &
|
|
```
|
|
|
|
2. Add to mcpServers in openclaw.json:
|
|
```json
|
|
"gitea-mcp-edith": {
|
|
"command": "gitea-mcp",
|
|
"args": ["--host", "https://gitea.example.com", "--port", "8083"],
|
|
"env": { "GITEA_ACCESS_TOKEN": "<YOUR_GITEA_TOKEN>" }
|
|
}
|
|
```
|
|
|
|
3. Add agent with tool restrictions:
|
|
```json
|
|
{
|
|
"id": "edith",
|
|
"name": "Edith Agent",
|
|
"tools": {
|
|
"allow": ["gitea-mcp-edith:*", "group:fs", "group:runtime"],
|
|
"deny": ["gitea-mcp-friday:*", "gitea-mcp-karti:*"]
|
|
}
|
|
}
|
|
```
|
|
|
|
4. Create AGENTS.md in her workspace
|
|
|
|
## Troubleshooting
|
|
|
|
- **Agent can't see MCP tools**: Check `tools.allow` includes the MCP server name
|
|
- **Agent sees wrong tools**: Check `tools.deny` excludes other MCP servers
|
|
- **MCP not connecting**: Verify port is available and token is correct
|
|
- **Token not working**: Test directly: `curl -H "Authorization: token <YOUR_GITEA_TOKEN>" https://gitea.example.com/api/v1/user`
|
|
|
|
## Environment Variables
|
|
|
|
| Variable | Description | Default |
|
|
|----------|-------------|---------|
|
|
| `GITEA_HOST` | Gitea server URL | https://gitea.com |
|
|
| `GITEA_ACCESS_TOKEN` | Access token | (required) |
|
|
| `GITEA_READONLY` | Enable read-only mode | false |
|
|
| `GITEA_DEBUG` | Enable debug logging | false |
|
|
| `GITEA_INSECURE` | Allow insecure TLS | false | |