skills/gitea/references/mcp-tools.md

# Gitea MCP Tool Inventory

Tools exposed by the `gitea` MCP server (registered in repo `.mcp.json` at `https://git-mcp.farh.net/mcp`). All tool names below are prefixed `mcp__gitea__` when invoked.

Many tools are consolidated under a `method` discriminator (e.g. `issue_write(method="create", …)`). Where that's the case, the methods are listed in the third column.

## Repositories

| Tool | Purpose | Notes |
|------|---------|-------|
| `list_my_repos` | List repos accessible to the authenticated user | Paginated |
| `list_org_repos` | List repos for a given org | Required: `org` |
| `search_repos` | Search across the instance | Required: `query`. Filters: `isPrivate`, `isArchived`, `keywordIsTopic`, `keywordInDescription`, `ownerID`, `sort`, `order` |
| `create_repo` | Create a personal or org repo | Required: `name`. Optional: `organization`, `private`, `auto_init`, `gitignores`, `license`, `readme`, `template`, `trust_model`, `default_branch`, `object_format_name` (sha1/sha256), `issue_labels`, `description` |
| `fork_repo` | Fork a repo | Required: `user` (source owner), `repo`. Optional: `organization`, `name` |
| `get_repository_tree` | Recursive tree listing | Required: `owner`, `repo`, `tree_sha`. Optional: `recursive`, paging |

## Files

| Tool | Purpose | Notes |
|------|---------|-------|
| `get_file_contents` | Get a file at a ref | Required: `owner`, `repo`, `ref`, `path`. Optional: `withLines` (numbered output) |
| `get_dir_contents` | List a directory at a ref | Required: `owner`, `repo`, `ref`, `path` |
| `create_or_update_file` | Write a file in a single commit | Required: `owner`, `repo`, `path`, `content`, `message`, `branch_name`. Provide `sha` to update an existing file; omit to create. Use `new_branch_name` to commit onto a new branch |
| `delete_file` | Remove a file | Required: `owner`, `repo`, `path`, `message`, `branch_name`, `sha` |

## Branches

| Tool | Purpose | Notes |
|------|---------|-------|
| `list_branches` | List branches | Required: `owner`, `repo` |
| `create_branch` | Create a branch | Required: `owner`, `repo`, `branch`. Optional: `old_branch` (defaults to repo default) |
| `delete_branch` | Delete a branch | Required: `owner`, `repo`, `branch` |

## Commits / Tags

| Tool | Purpose | Notes |
|------|---------|-------|
| `list_commits` | List commits | Required: `owner`, `repo`. Optional: `sha` (start ref), `path` (filter to commits touching this path) |
| `get_commit` | Get a commit | Required: `owner`, `repo`, `sha` |
| `list_tags` | List tags | Required: `owner`, `repo` |
| `get_tag` | Get a tag | Required: `owner`, `repo`, `tag_name` |
| `create_tag` | Create a tag | Required: `owner`, `repo`, `tag_name`. Optional: `target`, `message` |
| `delete_tag` | Delete a tag | Required: `owner`, `repo`, `tag_name` |

## Releases

| Tool | Purpose | Notes |
|------|---------|-------|
| `list_releases` | List releases | Required: `owner`, `repo`. Optional: `is_draft`, `is_pre_release` |
| `get_release` | Get a release by ID | Required: `owner`, `repo`, `id` |
| `get_latest_release` | Latest non-draft release | Required: `owner`, `repo` |
| `create_release` | Create a release | Required: `owner`, `repo`, `tag_name`, `target`, `title`. Optional: `body`, `is_draft`, `is_pre_release` |
| `delete_release` | Delete a release | Required: `owner`, `repo`, `id` |

> No "edit release" or "upload asset" tool — fall back to `tea releases edit` / `tea releases assets` for those.

## Issues

| Tool | Purpose | Methods |
|------|---------|---------|
| `list_issues` | Standalone list | Filters: `state`, `labels[]`, `since`, `before` |
| `search_issues` | Cross-repo search | Required: `query`. Filters: `state`, `type` (issues/pulls), `labels`, `owner` |
| `issue_read` | Read details | `get`, `get_comments`, `get_labels` |
| `issue_write` | Mutate | `create`, `update`, `add_comment`, `edit_comment`, `add_labels`, `remove_label`, `replace_labels`, `clear_labels`. `labels` are IDs (numeric). `assignees` are usernames |

## Pull requests

| Tool | Purpose | Methods |
|------|---------|---------|
| `list_pull_requests` | List PRs | Filters: `state`, `milestone`, `sort` (`oldest`, `recentupdate`, `leastupdate`, `mostcomment`, `leastcomment`, `priority`) |
| `pull_request_read` | Read details | `get`, `get_diff`, `get_files`, `get_status` (head commit status), `get_reviews`, `get_review`, `get_review_comments` |
| `pull_request_write` | Mutate | `create`, `update`, `close`, `reopen`, `merge`, `update_branch`, `add_reviewers`, `remove_reviewers`. Merge styles: `merge`, `rebase`, `rebase-merge`, `squash`, `fast-forward-only`. Optional `head_commit_id` for conflict detection; `merge_when_checks_succeed`, `force_merge`, `delete_branch` for merge |
| `pull_request_review_write` | Reviews | `create`, `submit`, `delete`, `dismiss`. States for `create`: `APPROVED`, `REQUEST_CHANGES`, `COMMENT`, `PENDING`. Supports inline `comments[]` with `path` + `new_line_num`/`old_line_num` |

## Labels

| Tool | Purpose | Methods |
|------|---------|---------|
| `label_read` | Read | `list_repo_labels`, `get_repo_label`, `list_org_labels` |
| `label_write` | Mutate | `create_repo_label`, `edit_repo_label`, `delete_repo_label`, `create_org_label`, `edit_org_label`, `delete_org_label`. Org labels accept `exclusive`; repo labels accept `is_archived`. `color` is hex `#RRGGBB` |

## Milestones

| Tool | Purpose | Methods |
|------|---------|---------|
| `milestone_read` | Read | `list`, `get` |
| `milestone_write` | Mutate | `create`, `update` (alias `edit`), `delete`. State enum: `open`, `closed`. `due_on` is a date string |

## Wiki

| Tool | Purpose | Methods |
|------|---------|---------|
| `wiki_read` | Read | `list`, `get` (needs `pageName`), `get_revisions` (needs `pageName`) |
| `wiki_write` | Mutate | `create` (needs `title`, `content`), `update` (needs `pageName`, `content`), `delete` (needs `pageName`). Optional `message` is the commit message |

> See `../../gitea-wiki/SKILL.md` for end-to-end wiki examples.

## Actions

| Tool | Purpose | Methods |
|------|---------|---------|
| `actions_config_read` | Read secrets/variables | `list_repo_secrets`, `list_org_secrets`, `list_repo_variables`, `get_repo_variable`, `list_org_variables`, `get_org_variable` |
| `actions_config_write` | Mutate secrets/variables | `upsert_repo_secret`, `delete_repo_secret`, `upsert_org_secret`, `delete_org_secret`, `create_repo_variable`, `update_repo_variable`, `delete_repo_variable`, `create_org_variable`, `update_org_variable`, `delete_org_variable`. Secret `value` field is `data`; variable value is `value` |
| `actions_run_read` | Read workflows/runs/jobs/logs | `list_workflows`, `get_workflow` (`workflow_id` may be ID or filename), `list_runs`, `get_run`, `list_jobs`, `list_run_jobs`, `get_job_log_preview`, `download_job_log` (`output_path` required). Log methods accept `max_bytes` and `tail_lines` |
| `actions_run_write` | Trigger/control runs | `dispatch_workflow` (needs `workflow_id`, `ref`; optional `inputs`), `cancel_run`, `rerun_run` |

## Notifications

| Tool | Purpose | Methods |
|------|---------|---------|
| `notification_read` | Read | `list` (optional `owner`/`repo` to scope; filters: `status`, `subject_type`, `since`, `before`), `get` (by thread `id`) |
| `notification_write` | Mark read | `mark_read` (by thread `id`), `mark_all_read` (optionally scoped to a repo) |

## Packages

| Tool | Purpose | Methods |
|------|---------|---------|
| `package_read` | Read | `list` (one entry per version; filter via `q`/`type`), `list_versions`, `get` (needs `version`) |
| `package_write` | Mutate | `delete` (irreversible) |

Package `type`: `container`, `npm`, `maven`, `pypi`, `cargo`, `generic`.

## Time tracking

| Tool | Purpose | Methods |
|------|---------|---------|
| `timetracking_read` | Read | `list_issue_times`, `list_repo_times`, `get_my_stopwatches`, `get_my_times` |
| `timetracking_write` | Mutate | `start_stopwatch`, `stop_stopwatch`, `delete_stopwatch`, `add_time` (`time` in seconds), `delete_time` |

## Users / Orgs / Teams

| Tool | Purpose | Notes |
|------|---------|-------|
| `get_me` | Current user | No args |
| `get_user_orgs` | Orgs of the current user | Paginated |
| `search_users` | Search users | Required: `query` |
| `search_org_teams` | Search teams in an org | Required: `org`, `query`. Optional: `includeDescription` |

## Server

| Tool | Purpose |
|------|---------|
| `get_gitea_mcp_server_version` | Returns the running MCP server version. Useful for confirming connectivity. |

## Coverage gaps (use `tea` or REST API instead)

The MCP server does **not** currently expose:

- Webhook CRUD — use `tea webhooks …`.
- Admin user CRUD — use `tea admin users …`.
- Release asset upload/management — use `tea releases assets …`.
- SSH key CRUD — use `tea ssh-keys …`.
- Login / instance setup — `tea logins …`.
- Repo edit/delete — `tea repos edit / tea repos delete --owner X --name Y --force`.
- `tea pulls checkout` / `tea clone` workflows that need local git state.