gitea-platform-mcp/skills/gitea/SKILL.md

---
name: gitea
description: >
  Use this skill when the user asks to work with their Gitea server:
  "покажи мои репозитории", "создай репозиторий", "открой issue", "закрой issue",
  "создай pull request", "смерджи PR", "добавь вебхук", "покажи релизы",
  "создай ветку", "покажи коммиты", "сравни ветки", "список организаций",
  "переключись на work gitea", "gitea", "list repos", "create issue",
  "open PR", "merge pull request", "create release", "add webhook",
  "list branches", "gitea notifications", "check gitea connection".
---

# Gitea Platform Assistant

Full Gitea REST API — 66 tools for repos, issues, PRs, branches, files, releases,
webhooks, organizations. One source file, two ways to call it (pick whichever your
runtime gives you):

- **CLI (this skill):** `uv run scripts/gitea_mcp.py <tool> --param value` →
  prints **one JSON object** on stdout. This is the default for Cline.
- **MCP server:** the same tools exposed as `mcp__gitea__<tool>` when the script is
  registered via `.mcp.json`. Use these instead of `execute_command` if the tools
  are already available to you.

Tool names and parameters are **identical** in both modes — only the call syntax
differs (CLI uses `--dashed-flags`, MCP uses named arguments).

## Calling via CLI

The script is bundled inside this skill at `scripts/gitea_mcp.py` and carries its
own PEP 723 dependency block, so `uv` provisions everything on first run — no
install step. Run it from the skill directory:

```
uv run scripts/gitea_mcp.py <tool> [--flags]
```

Convert snake_case params to `--dashed` flags. Booleans use `--flag` / `--no-flag`
(e.g. `--private` / `--no-private`). List params take space-separated values
(e.g. `--topics ci backend`).

Config is auto-discovered (`config.json` in the skill folder or a parent). Pass
`--config <path>` to point elsewhere.

**Output contract:** exactly one JSON object on stdout. Always check `success`:

```json
{"success": true,  "data": <Gitea response>}
{"success": false, "error": "Gitea API 404: ...", "type": "RuntimeError"}
```

The process exits 0 even on tool-level errors — read `success`, not the exit code.

## Discovery

```
uv run scripts/gitea_mcp.py list-tools
```

Returns every tool with its description and parameter spec (name / type /
required). Use it when unsure of a flag instead of guessing.

## First Use

Always start by checking the connection:

```
uv run scripts/gitea_mcp.py list_instances       → configured instances + default
uv run scripts/gitea_mcp.py get_current_user      → verifies auth works
```

If these fail with a config error, tell the user to create `config.json` in the
skill folder (copy `config.example.json` from the plugin root).

## Instance Selection

Every tool takes an optional `--instance` (default `""` = use config default).

- User says "на work" / "on the work server" → add `--instance work`.
- No instance mentioned → omit `--instance` (uses config default).

## Tool Categories

### Meta & Health
- `list_instances` — show all configured instances
- `get_server_info --instance <name>` — Gitea version
- `get_current_user --instance <name>` — authenticated user

### Repositories
- `list_my_repos --limit 50 --page 1`
- `search_repos --query <q>`
- `get_repo --owner <o> --repo <r>`
- `create_repo --name <n> --description <d> --private/--no-private --auto-init/--no-auto-init --default-branch main`
- `create_org_repo --org <org> --name <n> …`
- `update_repo --owner <o> --repo <r> --description … --no-private --website …`
- `delete_repo --owner <o> --repo <r>` ⚠️ permanent
- `fork_repo --owner <o> --repo <r> --organization … --new-repo-name …`
- `set_repo_topics --owner <o> --repo <r> --topics ci backend`

### Branches & Tags
- `list_branches --owner <o> --repo <r>`
- `get_branch --owner <o> --repo <r> --branch <b>`
- `create_branch --owner <o> --repo <r> --new-branch-name <b> --old-branch-name <src>`
- `delete_branch --owner <o> --repo <r> --branch <b>` ⚠️
- `list_tags --owner <o> --repo <r>`

### Files
- `list_directory --owner <o> --repo <r> --path <p> --ref <branch>` — browse tree
- `get_file --owner <o> --repo <r> --filepath <p> --ref <branch>` — content + sha
- `create_file --owner <o> --repo <r> --filepath <p> --content "<text>" --message <msg> --branch <b>` — plain text, auto-encoded
- `update_file … --content "<text>" --message <msg> --sha <sha> --branch <b>` — sha from get_file
- `delete_file … --message <msg> --sha <sha> --branch <b>` — sha required

### Issues
- `list_issues --owner <o> --repo <r> --state open|closed|all --issue-type issues|pulls --labels … --assignee … --limit 20`
- `get_issue --owner <o> --repo <r> --index <n>`
- `create_issue --owner <o> --repo <r> --title <t> --body <b> --assignees alice bob --labels 1 2`
- `update_issue --owner <o> --repo <r> --index <n> --title … --body … --state open|closed`
- `close_issue` / `reopen_issue --owner <o> --repo <r> --index <n>`
- `list_issue_comments` / `add_issue_comment --body <b>` / `edit_issue_comment --comment-id <id> --body <b>` / `delete_issue_comment --comment-id <id>`

### Labels & Milestones
- `list_labels` / `create_label --name <n> --color "#rrggbb"` / `add_issue_labels --index <n> --label-ids 1 2`
- `list_milestones --state open|closed|all` / `create_milestone --title <t> --due-on 2024-12-31T00:00:00Z`

### Pull Requests
- `list_pull_requests --owner <o> --repo <r> --state open|closed|all`
- `get_pull_request --owner <o> --repo <r> --index <n>`
- `create_pull_request --owner <o> --repo <r> --title <t> --head <src-branch> --base <target-branch> --body <b>`
- `update_pull_request --owner <o> --repo <r> --index <n> --title … --body … --state …`
- `merge_pull_request --owner <o> --repo <r> --index <n> --merge-style merge|rebase|squash|fast-forward-only --delete-branch-after-merge`
- `get_pr_diff --owner <o> --repo <r> --index <n>` — returns diff text
- `list_pr_files --owner <o> --repo <r> --index <n>`
- `list_pr_reviews` / `create_pr_review --index <n> --state APPROVED|COMMENT|REQUEST_CHANGES --body <b>`

### Releases
- `list_releases` / `get_latest_release` / `create_release --tag-name <t> --name <n> --body … --draft --prerelease` / `delete_release --release-id <id>`

### Webhooks
- `list_repo_webhooks` / `create_repo_webhook --url <u> --events push issues pull_request --secret …` / `delete_repo_webhook --hook-id <id>`

### Users & Organizations
- `get_current_user` / `get_user --username <u>` / `search_users --query <q>`
- `list_my_orgs` / `get_org --org <org>` / `list_org_repos --org <org>` / `list_org_members --org <org>` / `list_org_teams --org <org>`

### Commits & Activity
- `list_commits --owner <o> --repo <r> --sha <ref> --path <p> --limit 20`
- `get_commit --owner <o> --repo <r> --sha <sha>` — `--no-stat` / `--no-files` to slim output
- `compare_branches --owner <o> --repo <r> --base <b> --head <h>` — diff + commit list
- `list_repo_contributors --owner <o> --repo <r>`

### Notifications
- `list_notifications --include-read --limit 20` / `mark_all_notifications_read`

## Typical Examples

```
# Open an issue
uv run scripts/gitea_mcp.py create_issue \
  --owner andrey --repo infra --title "CI flaky on main" --body "Fails ~1/5 runs"

# Edit then commit a file (two steps — get sha first)
uv run scripts/gitea_mcp.py get_file --owner andrey --repo infra --filepath README.md
uv run scripts/gitea_mcp.py update_file --owner andrey --repo infra --filepath README.md \
  --content "new text" --message "docs: tweak" --sha <sha-from-get_file>

# Create and merge a PR on the work instance
uv run scripts/gitea_mcp.py create_pull_request --owner team --repo svc \
  --title "Feature X" --head feature/x --base main --instance work
uv run scripts/gitea_mcp.py merge_pull_request --owner team --repo svc --index 42 \
  --merge-style squash --delete-branch-after-merge --instance work
```

## Notes / Gotchas

- **File edits are two-step:** `get_file` → use its `sha` in `update_file` /
  `delete_file`. Without the current sha Gitea rejects the write.
- **Destructive ops** (`delete_repo`, `delete_branch`, `delete_release`) are
  permanent — confirm with the user before running.
- **`list_issues --issue-type pulls`** returns PRs (Gitea treats PRs as issues).
- **Multi-value flags** (`--topics`, `--events`, `--assignees`, `--label-ids`)
  take space-separated values, not a comma string.