Latte
7837ff43ad
Adds six opt-in write tools (write-mode + policy + per-user permission still
enforced; no destructive or admin actions):
- create_pull_request (POST /pulls)
- create_release / edit_release (POST/PATCH /releases)
- create_branch (POST /branches; create only, no deletion)
- create_milestone (POST /milestones)
- edit_issue_comment (PATCH /issues/comments/{id})
Each: arg schema (extra=forbid, GitRef on branch/ref-like fields), Gitea client
method with url-encoded path segments, handler that surfaces auth errors, MCP
registration (write_operation=True), server wiring, docs, and success tests.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
100 lines
4.1 KiB
Markdown
100 lines
4.1 KiB
Markdown
# 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`)
|
|
- `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 design: merge, branch/label/release deletion, force push, repo/admin
|
|
management.
|
|
|
|
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).
|