holocron/plugins/kyberforge/docs/research/docs/gitea/api-reference.md

topic, source_keys

topic	source_keys
api-reference	gitea-mcp-repo gitea-mcp-slim-go

Gitea MCP — Tool Reference

Full parameter schemas and response shapes for all MCP tools. Tools marked [W] are write operations suppressed in --read-only mode. Parameters listed as required* are conditionally required depending on the method value.

---

Issues

list_issues [R]

List repository issues or pull requests.

Parameters:

• owner (string, required)
• repo (string, required)
• state (string, optional, default: "all") — "open", "closed", "all"
• type (string, optional) — "issues" or "pulls" to filter; omit for both
• labels (array of strings, optional) — filter by label names
• milestones (array, optional) — filter by milestone name or ID
• since (string, optional) — ISO 8601; issues updated after this time
• before (string, optional) — ISO 8601; issues updated before this time
• page (number, optional, default: 1)
• per_page (number, optional, default: 30)

Response shape (list item):

number, title, state, html_url, user (login), comments, created_at, updated_at
labels? ([]string), milestone? ({id, title}), ref?, deadline?

Body and closed_at are omitted from list responses.

---

issue_read [R]

Read a single issue's details, comments, or label list.

Parameters:

• method (string, required) — "get" | "get_comments" | "get_labels"
• owner (string, required)
• repo (string, required)
• issue_number (number, required)

Response shapes:

get — full issue:

number, title, body, state, html_url, user, labels ([]string),
comments, created_at, updated_at, closed_at
assignees? ([]string), milestone? ({id, title}), ref?, deadline?,
is_pull? (true — present only when backed by a PR)

get_comments — array of:

id (int64), body, user, html_url, created_at, updated_at

get_labels — array of label objects from the Gitea API (not slimmed, full label objects including id, name, color).

---

issue_write [W]

Create or mutate an issue, its comments, or its labels.

Parameters:

• method (string, required) — one of: "create" | "update" | "add_comment" | "edit_comment" | "add_labels" | "remove_label" | "replace_labels" | "clear_labels"
• owner (string, required)
• repo (string, required)
• issue_number (number, required for all except "create")
• title (string, required for "create")
• body (string, required for "create", "add_comment", "edit_comment")
• assignees (array of strings, optional) — login names
• milestone (number, optional) — milestone ID (not title, not number)
• state (string, optional) — "open" | "closed" | "all" (for "update")
• commentID (number, optional, required for "edit_comment")
• labels (array of numbers, optional) — label IDs (not names) for add/replace ops
• label_id (number, optional, required for "remove_label")
• ref (string, optional) — branch association
• deadline (string, optional) — ISO 8601
• remove_deadline (boolean, optional)

Critical: labels takes IDs (numbers), not names. Must resolve label names to IDs via label_read before labeling.

---

search_issues [R]

Search issues and PRs across repositories.

Parameters:

• query (string, required)
• state (string, optional) — "open" | "closed" | "all"
• type (string, optional) — "issues" | "pulls"
• labels (string, optional) — comma-separated label names
• owner (string, optional) — restrict to owner
• page (number, optional, default: 1)
• per_page (number, optional, default: 30)

---

Pull Requests

list_pull_requests [R]

Parameters:

• owner (string, required)
• repo (string, required)
• state (string, optional, default: "all") — "open" | "closed" | "all"
• sort (string, optional, default: "recentupdate") — "oldest" | "recentupdate" | "leastupdate" | "mostcomment" | "leastcomment" | "priority"
• milestone (number, optional) — milestone ID filter
• page (number, optional, default: 1)
• per_page (number, optional, default: 30)

Response shape (list item — heavily trimmed):

number, title, state, draft, merged, html_url, user, created_at, updated_at
head? (ref string only), base? (ref string only), labels? ([]string)

Body, mergeable, comments, closed_at, and diff stats are omitted from list responses. Head/base are bare ref strings in the list, not objects.

---

pull_request_read [R]

Parameters:

• method (string, required) — "get" | "get_diff" | "get_files" | "get_status" | "get_reviews" | "get_review" | "get_review_comments"
• owner (string, required)
• repo (string, required)
• pull_number (number, required)
• review_id (number, optional, required for "get_review" and "get_review_comments")
• binary (boolean, optional) — include binary diff
• page (number, optional, default: 1)
• per_page (number, optional, default: 30)

Response shapes:

get — full PR:

number, title, body, state, draft, merged, mergeable, html_url, user,
labels ([]string), comments, created_at, updated_at, closed_at
head? ({ref, sha, repo?: {full_name, description}}),
base? ({ref, sha, repo?: {full_name, description}}),
additions?, deletions?, changed_files?,
merged_at?, merge_commit_sha?, merged_by?,
assignees? ([]string),
milestone? (string — title only, NOT an object),
review_scomments? (int — note: misspelled key in source, not review_comments)

get_diff — raw diff text

get_files — list of changed file objects

get_status — combined commit status for the PR head commit

get_reviews — array of review objects:

id, state, body, user (login), comments_count, submitted_at, html_url,
stale (bool), official (bool), dismissed (bool)

get_review_comments — array of inline review comments:

id, body, path, position (new line), old_position, diff_hunk,
user (login), html_url, created_at, updated_at

---

pull_request_write [W]

Parameters:

• method (string, required) — "create" | "update" | "close" | "reopen" | "merge" | "update_branch" | "add_reviewers" | "remove_reviewers"
• owner (string, required)
• repo (string, required)
• pull_number (number, required except for "create")
• title (string, required for "create", optional for "update" and "merge")
• body (string, required for "create", optional for "update")
• head (string, required for "create") — source branch; use owner:branch for cross-repo
• base (string, required for "create") — target branch
• assignee (string, optional)
• assignees (array of strings, optional)
• milestone (number, optional) — milestone ID
• state (string, optional) — "open" | "closed"
• allow_maintainer_edit (boolean, optional)
• labels (array of numbers, optional) — label IDs
• deadline (string, optional) — ISO 8601
• remove_deadline (boolean, optional)
• merge_style (string, optional, default: "merge") — "merge" | "rebase" | "rebase-merge" | "squash" | "fast-forward-only"
• message (string, optional) — merge commit message or review dismissal reason
• delete_branch (boolean, optional) — delete head branch after merge
• force_merge (boolean, optional) — merge even if checks fail
• merge_when_checks_succeed (boolean, optional)
• head_commit_id (string, optional) — expected head SHA for conflict detection
• reviewers (array of strings, optional) — login names
• team_reviewers (array of strings, optional)
• draft (boolean, optional) — marks PR as draft by prefixing title with "WIP:"

---

pull_request_review_write [W]

Parameters:

• method (string, required) — "create" | "submit" | "delete" | "dismiss"
• owner (string, required)
• repo (string, required)
• pull_number (number, required)
• review_id (number, optional, required except for "create")
• state (string, optional) — "APPROVED" | "REQUEST_CHANGES" | "COMMENT" | "PENDING"
• body (string, optional)
• commit_id (string, optional) — for "create"; anchors inline comments to a commit
• message (string, optional) — dismissal reason for "dismiss"
• comments (array, optional) — inline comments for "create": each object: {path, body, old_line_num, new_line_num}

---

Labels

label_read [R]

Parameters:

• method (string, required) — "list_repo_labels" | "get_repo_label" | "list_org_labels"
• owner (string, optional, required for repo methods)
• repo (string, optional, required for repo methods)
• org (string, optional, required for org methods)
• id (number, optional, required for "get_repo_label")
• page (number, optional, default: 1)
• per_page (number, optional, default: 30)

Response: Full label objects including id, name, color, description, exclusive, is_archived. Use this to map label names to IDs before write operations.

---

label_write [W]

Parameters:

• method (string, required) — "create_repo_label" | "edit_repo_label" | "delete_repo_label" | "create_org_label" | "edit_org_label" | "delete_org_label"
• owner (string, optional, required for repo methods)
• repo (string, optional, required for repo methods)
• org (string, optional, required for org methods)
• id (number, optional, required for edit/delete)
• name (string, optional, required for create)
• color (string, optional, required for create) — hex format #RRGGBB
• description (string, optional)
• exclusive (boolean, optional) — org labels only; makes label mutually exclusive within a group
• is_archived (boolean, optional) — repo labels only

---

Milestones

milestone_read [R]

Parameters:

• method (string, required) — "get" | "list"
• owner (string, required)
• repo (string, required)
• id (number, optional, required for "get") — milestone ID
• state (string, optional, default: "all") — "open" | "closed" | "all"
• name (string, optional) — filter by title for "list"
• page (number, optional, default: 1)
• per_page (number, optional, default: 30)

Response: Full milestone objects including id, title, description, state, due_on, closed_at, open_issues, closed_issues.

---

milestone_write [W]

Parameters:

• method (string, required) — "create" | "update" | "edit" | "delete" ("update" and "edit" are aliases for the same operation)
• owner (string, required)
• repo (string, required)
• id (number, optional, required for update/delete)
• title (string, optional, required for create)
• description (string, optional)
• due_on (string, optional) — ISO 8601 date
• state (string, optional) — "open" | "closed"

---

Branches

list_branches [R]

Parameters:

• owner (string, required)
• repo (string, required)
• page (number, optional, default: 1)
• per_page (number, optional, default: 30)

Response shape per branch:

name (string), protected (bool), commit_sha? (string — present when Commit != nil)

---

create_branch [W]

Parameters:

• owner (string, required)
• repo (string, required)
• branch (string, required) — new branch name
• old_branch (string, optional) — source branch; defaults to repo default branch

---

delete_branch [W]

Parameters:

• owner (string, required)
• repo (string, required)
• branch (string, required)

---

Commits

list_commits [R]

Parameters:

• owner (string, required)
• repo (string, required)
• sha (string, optional) — starting SHA or branch name
• path (string, optional) — filter commits touching this path
• page (number, optional, default: 1, min: 1)
• per_page (number, optional, default: 30, min: 1)

Response shape per commit:

sha, html_url, created
message? (string — present when RepoCommit != nil),
author? ({name, email, date} — present when RepoCommit.Author != nil)

---

get_commit [R]

Parameters:

• owner (string, required)
• repo (string, required)
• sha (string, required)

Response: Same shape as list commit but always includes full detail.

---

Files

get_file_contents [R]

Parameters:

• owner (string, required)
• repo (string, required)
• ref (string, required) — branch name, tag, or commit SHA
• path (string, required)
• withLines (boolean, optional) — return content with line numbers

Response:

name, path, sha, type, size
content? (string, base64-encoded), encoding?, html_url?, download_url?

The sha in the response is required when updating or deleting this file.

---

create_or_update_file [W]

Parameters:

• owner (string, required)
• repo (string, required)
• path (string, required)
• content (string, required) — base64-encoded file content
• message (string, required) — commit message
• branch_name (string, required) — target branch
• sha (string, optional, required when updating an existing file) — current file SHA
• new_branch_name (string, optional) — create a new branch during the operation

To update an existing file: must provide the file's current sha (get it from get_file_contents first). Without sha, Gitea treats the operation as a create and returns 409 if the file already exists.

---

delete_file [W]

Parameters:

• owner (string, required)
• repo (string, required)
• path (string, required)
• message (string, required) — commit message
• branch_name (string, required)
• sha (string, required) — current file SHA; must match the server's current SHA

---

get_dir_contents [R]

Parameters:

• owner (string, required)
• repo (string, required)
• ref (string, required)
• path (string, required)

Response: Array of directory entry objects:

name, path, type, size

No sha, no content, no URLs in directory listings.

---

get_repository_tree [R]

Parameters:

• owner (string, required)
• repo (string, required)
• tree_sha (string, required) — SHA, branch, or tag
• recursive (boolean, optional) — recurse into subdirectories
• page (number, optional, default: 1)
• per_page (number, optional, default: 30)

Response:

{sha, truncated (bool), total_count (int), tree: [{path, mode, type, size, sha}, ...]}

---

Releases and Tags

list_releases [R]

Parameters:

• owner (string, required)
• repo (string, required)
• is_draft (boolean, optional)
• is_pre_release (boolean, optional)
• page (number, optional, default: 1, min: 1)
• per_page (number, optional, default: 20, min: 1)

Response shape per release:

id, tag_name, target (commitish), title, body (from Note field),
draft, prerelease, html_url, author (login), created_at, published_at

---

create_release [W]

Parameters:

• owner (string, required)
• repo (string, required)
• tag_name (string, required)
• target (string, required) — branch, tag, or commit SHA
• title (string, required)
• is_draft (boolean, optional)
• is_pre_release (boolean, optional)
• body (string, optional) — release notes

---

get_release / get_latest_release [R]

get_release requires id (number). get_latest_release takes only owner and repo.

---

delete_release [W]

• owner, repo, id (number) — release numeric ID from list/get response.

---

Tag tools

list_tags — owner, repo, page, per_page (default 20). Response per tag: name, commit_sha?. Message is dropped from list responses.

get_tag — owner, repo, tag_name. Full response: name, message, commit_sha?.

create_tag [W] — owner, repo, tag_name (required), target (commitish, optional), message (optional).

delete_tag [W] — owner, repo, tag_name.

---

Search

search_repos [R]

• query (string, required)
• keywordIsTopic (boolean, optional)
• keywordInDescription (boolean, optional)
• ownerID (number, optional) — filter by numeric user/org ID
• isPrivate (boolean, optional)
• isArchived (boolean, optional)
• sort, order (string, optional)
• page, per_page (default 30)

search_repos is the workaround for listing a user's repos when read:user scope is unavailable. Requires knowing the numeric ownerID.

---

search_users [R]

• query (string, required)
• page, per_page (default 30)

---

search_org_teams [R]

• org (string, required)
• query (string, required)
• includeDescription (boolean, optional)
• page, per_page (default 30)

---

Repository Management

create_repo [W]

• name (string, required)
• description, private, issue_labels, auto_init, template, gitignores, license, readme, default_branch, trust_model, object_format_name (all optional)
• organization (string, optional) — creates under org; defaults to personal account
• trust_model — "default" | "collaborator" | "committer" | "collaboratorcommitter"
• object_format_name — "sha1" | "sha256"

fork_repo [W]

• user (string, required) — source repo owner
• repo (string, required) — source repo name
• organization (string, optional) — target org
• name (string, optional) — fork name

list_my_repos [R]

Requires read:user scope. Without it, use search_repos.

• page, per_page (default 30, min 1)

list_org_repos [R]

• org (string, required)
• page, per_page (default 100, min 1)

---

User

get_me [R]

No parameters. Returns current authenticated user. Requires read:user scope.

get_user_orgs [R]

• page, per_page (default 30)

Requires read:user scope.

---

Actions (CI)

actions_config_read [R]

• method — "list_repo_secrets" | "list_org_secrets" | "list_repo_variables" | "get_repo_variable" | "list_org_variables" | "get_org_variable"
• owner, repo (for repo methods), org (for org methods)
• name (for get methods)
• page, per_page (default 30, min 1)

actions_config_write [W]

• method — "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"
• name (secret/variable name), data (secret value), value (variable value), description (optional)

actions_run_read [R]

• method — "list_workflows" | "get_workflow" | "list_runs" | "get_run" | "list_jobs" | "list_run_jobs" | "get_job_log_preview" | "download_job_log"
• owner, repo (required)
• workflow_id (string) — workflow ID or filename
• run_id, job_id (numbers) — for run/job-specific methods
• status — filter for list methods
• tail_lines (default 200, min 1), max_bytes (default 65536, min 1024) — for log methods
• output_path — for "download_job_log"
• page, per_page (default 30, min 1)

actions_run_write [W]

• method — "dispatch_workflow" | "cancel_run" | "rerun_run"
• owner, repo (required)
• workflow_id (for dispatch), ref (branch/tag for dispatch), inputs (object for dispatch)
• run_id (for cancel/rerun)

---

Notifications

notification_read [R]

• method — "list" | "get"
• owner, repo (optional, scopes to repo)
• id (thread ID for "get")
• status — "unread" | "read" | "pinned"
• subject_type — "Issue" | "Pull" | "Commit" | "Repository"
• since, before (ISO 8601)
• page, per_page (default 30)

notification_write [W]

• method — "mark_read" | "mark_all_read"
• id (thread ID for "mark_read")
• owner, repo (optional scope)
• last_read_at (ISO 8601, defaults to now)

---

Time Tracking

timetracking_read [R]

• method — "list_issue_times" | "list_repo_times" | "get_my_stopwatches" | "get_my_times"
• owner, repo (for list methods)
• issue_number (for "list_issue_times")
• page, per_page (default 30)

timetracking_write [W]

• method — "start_stopwatch" | "stop_stopwatch" | "delete_stopwatch" | "add_time" | "delete_time"
• owner, repo, issue_number (optional depending on method)
• time (seconds, for "add_time")
• id (entry ID, for "delete_time")

---

Packages

package_read [R]

• method — "list" | "list_versions" | "get"
• owner (user or org, required)
• type (package type: "container" | "npm" | "maven" | "pypi" | "cargo" | "generic") — required except for "list"
• name (package name, slashes auto-encoded) — required except for "list"
• version — for "get"
• q (search query)
• page, per_page (default 30, min 1)

package_write [W]

• method — "delete" (only operation; irreversible)
• owner, type, name, version (all required)

---

Wiki

wiki_read [R]

• method — "list" | "get" | "get_revisions"
• owner, repo (required)
• pageName (for "get" and "get_revisions")

wiki_write [W]

• method — "create" | "update" | "delete"
• owner, repo (required)
• pageName (required for update/delete)
• title (required for create)
• content (for create/update)
• message (commit message)

---

Version

get_gitea_mcp_server_version [R]

No parameters. Returns the running server version string.