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

name, description

name

description

gitea

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:

{"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.