Files

T

Latte c282ffe359 feat: complete label management (name->id resolution, update/remove)

Resolves the long-standing problem that label tools passed names while Gitea's
API requires numeric label ids.

- gitea_client: add _resolve_label_ids() helper; create_issue and add_labels now
  resolve label names to ids (case-insensitive) and raise a clear "Unknown
  label(s)" error instead of a generic 500.
- New tools: remove_labels (by name) and update_label (located by current name).
- Register both write tools and document the name-based label contract.
- Tests: resolver mapping + unknown-label error, add_labels id translation,
  update_label and remove_labels handlers.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-06-14 20:34:35 +02:00

3.5 KiB

Raw Blame History

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)

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

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.

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

3.5 KiB Raw Blame History