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.md).

## 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](raw-api.md) 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).