AegisGitea-MCP/docs/api-reference.md

API Reference

Endpoints

• GET /: server metadata.
• GET /health: health probe.
• GET /metrics: Prometheus metrics (when enabled).
• POST /automation/webhook: ingest policy-controlled webhook events.
• POST /automation/jobs/run: run policy-controlled automation jobs.
• GET /mcp/tools: list tool definitions.
• POST /mcp/tool/call: execute a tool (Authorization: Bearer <api-key> required except in explicitly disabled auth mode).
• GET /mcp/sse and POST /mcp/sse: MCP SSE transport.

Automation Jobs

POST /automation/jobs/run supports:

• dependency_hygiene_scan (read-only scaffold).
• stale_issue_detection (read-only issue age analysis).
• auto_issue_creation (write-mode + whitelist + policy required).

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

• Policy denial: HTTP 403.
• Validation error: HTTP 400.
• Auth error: HTTP 401.
• Rate limit: HTTP 429.
• Internal errors: HTTP 500 without stack traces in production.