AegisGitea-MCP/docs/api-reference.md

API Reference

Core Endpoints

• GET /: server metadata.
• GET /health: health probe.
• GET /metrics: Prometheus metrics (when enabled).

OAuth Discovery and Token Exchange

• GET /.well-known/oauth-protected-resource
  • Returns OAuth protected resource metadata used by MCP clients.
• GET /.well-known/oauth-authorization-server
  • Returns OAuth authorization server metadata.
• POST /register
  • Registers an OAuth client and persists the client metadata.
• POST /oauth/token
  • Proxies OAuth authorization-code token exchange to Gitea.

MCP Endpoints

• GET /mcp/tools: list tool definitions.
• GET /mcp and POST /mcp: streamable HTTP transport.
• GET /mcp/sse and POST /mcp/sse: MCP SSE transport alias.
• POST /mcp/tool/call: direct tool-call endpoint.

Authentication requirements:

• MCP tool execution requires Authorization: Bearer <token>.
• Missing or invalid tokens return 401 with:
  • WWW-Authenticate: Bearer resource_metadata="<absolute metadata url>", scope="read:repository"

Scope requirements:

• Read tools require read:repository.
• Write tools require write:repository.
• Insufficient scope returns 403.

Automation Endpoints

• POST /automation/webhook: ingest policy-controlled webhook events.
• POST /automation/jobs/run: run policy-controlled automation jobs.

Read Tools

• list_repositories
• get_repository_info (owner, repo)
• get_file_tree (owner, repo, optional ref, recursive)
• get_file_contents (owner, repo, filepath, optional ref)
• search_code (owner, repo, query, optional ref, page, limit)
• list_commits (owner, repo, optional ref, page, limit)
• get_commit_diff (owner, repo, sha)
• compare_refs (owner, repo, base, head)
• list_issues (owner, repo, optional state, page, limit, labels)
• get_issue (owner, repo, issue_number)
• list_pull_requests (owner, repo, optional state, page, limit)
• get_pull_request (owner, repo, pull_number)
• list_labels (owner, repo, optional page, limit)
• list_tags (owner, repo, optional page, limit)
• list_releases (owner, repo, optional page, limit)
• list_pull_request_files (owner, repo, pull_number, optional page, limit)
• list_pull_request_commits (owner, repo, pull_number, optional page, limit)
• list_issue_comments (owner, repo, issue_number, optional page, limit)
• list_branches (owner, repo, optional page, limit)
• get_branch (owner, repo, branch)
• get_release (owner, repo, release_id)
• get_latest_release (owner, repo)
• list_milestones (owner, repo, optional state, page, limit)
• get_commit_status (owner, repo, sha)
• list_org_repositories (org, optional page, limit)
• list_organizations (optional page, limit)
• get_repo_languages (owner, repo)
• list_repo_topics (owner, repo)

Write Tools (Write Mode Required)

• create_issue (owner, repo, title, optional body, labels, assignees, milestone)
• update_issue (owner, repo, issue_number, one or more of title, body, state, milestone)
• create_issue_comment (owner, repo, issue_number, body)
• create_pr_comment (owner, repo, pull_number, body)
• add_labels (owner, repo, issue_number, labels by name)
• remove_labels (owner, repo, issue_number, labels by name)
• assign_issue (owner, repo, issue_number, assignees)
• create_label (owner, repo, name, color hex e.g. #00aabb, optional description, exclusive)
• update_label (owner, repo, name, one or more of new_name, color, description)
• create_pull_request (owner, repo, title, head, base, optional body)
• create_release (owner, repo, tag_name, optional name, body, draft, prerelease, target)
• edit_release (owner, repo, release_id, one or more of name, body, draft, prerelease)
• create_branch (owner, repo, new_branch_name, optional old_branch_name)
• create_milestone (owner, repo, title, optional description, due_on)
• edit_issue_comment (owner, repo, comment_id, body)

Not supported by the dedicated tools by design: merge, branch/label/release deletion, force push, repo/admin management. Endpoints not covered above are reachable through the generic gitea_request escape hatch (subject to policy, write-mode, and a sensitive-path denylist) — see Raw API Dispatch.

Raw API Dispatch

• gitea_request (method, path, optional query, body)
  • Calls an arbitrary Gitea REST endpoint. GET/HEAD are reads; other methods are writes and require write-mode plus a whitelisted repository. Admin/credential endpoints are blocked unless RAW_API_ALLOW_SENSITIVE=true. See Raw API Dispatch for the two-layer policy model and full details.

Note: create_issue, add_labels, and remove_labels accept label names; the server resolves them to Gitea label ids and returns a clear error for unknown labels.

Note: the milestone argument on create_issue/update_issue accepts either a numeric milestone id or a milestone title (resolved case-insensitively against open and closed milestones; unknown titles return a clear error). On update_issue, milestone: 0 clears the issue's milestone. Gitea Projects (Kanban boards) are intentionally unsupported: the Gitea REST API exposes no project endpoints.

Validation and Limits

• All tool argument schemas reject unknown fields.
• List responses are capped by MAX_TOOL_RESPONSE_ITEMS.
• Text payloads are capped by MAX_TOOL_RESPONSE_CHARS.
• File reads are capped by MAX_FILE_SIZE_BYTES.

Error Model

• Auth error: HTTP 401.
• Policy/scope denial: HTTP 403.
• Validation error: HTTP 400.
• Rate limit: HTTP 429.
• Internal errors: HTTP 500 (no stack traces in production).