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 /oauth/token
  • Proxies OAuth authorization-code token exchange to Gitea.

MCP Endpoints

• GET /mcp/tools: list tool definitions.
• POST /mcp/tool/call: execute a tool.
• GET /mcp/sse and POST /mcp/sse: MCP SSE transport.

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)

Write Tools (Write Mode Required)

• create_issue (owner, repo, title, optional body, labels, assignees)
• update_issue (owner, repo, issue_number, one or more of title, body, state)
• create_issue_comment (owner, repo, issue_number, body)
• create_pr_comment (owner, repo, pull_number, body)
• add_labels (owner, repo, issue_number, labels)
• assign_issue (owner, repo, issue_number, assignees)

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