45 lines
2.2 KiB
Markdown
45 lines
2.2 KiB
Markdown
# ADR 0003: tools generated from the pinned swagger
|
|
|
|
Status: accepted (2026-10-14)
|
|
|
|
## Context
|
|
|
|
Coverage target: every operation in the instance swagger gets a tool. Gitea
|
|
28.1.0 has 537 operations. Hand-writing them is error-prone and drifts.
|
|
|
|
## Decision
|
|
|
|
- Pin the instance swagger at `spec/gitea-swagger.v1.json` (sha256 matches the
|
|
live instance at time of pinning).
|
|
- `scripts/generate_catalog.py` turns it into a committed
|
|
`src/aegis_gitea_mcp/catalog/tools.json`. `--check` fails when the committed
|
|
file is stale. Runtime only reads the JSON.
|
|
- Tool name: `gitea_<domain>_<action>`, lowercase snake_case, at most 64
|
|
characters, unique. Domain comes from the path (admin, repo, issue, pull,
|
|
release, wiki, org, team, user, actions, hook, package, notification, misc),
|
|
action from the operationId with redundant domain words stripped. A small
|
|
override map handles collisions and awkward names.
|
|
- Input schema: path and query parameters as top-level properties, the JSON
|
|
body under `body`, multipart files as base64 strings. `additionalProperties:
|
|
false` everywhere we control. Owner, repo and username path parameters get
|
|
name patterns.
|
|
- Annotations: `readOnlyHint` for GET, `destructiveHint` for DELETE and for
|
|
PUT/PATCH that replace state, `idempotentHint` for GET/PUT/DELETE. A small
|
|
explicit override set in `catalog/build.py` corrects POST operations: the
|
|
render endpoints (`/markdown`, `/markdown/raw`, `/markup`) and the read-only
|
|
`file-contents` POST are read-only and idempotent; irreversible or
|
|
wide-reaching POSTs (PR merge, merge upstream, repo transfer and its
|
|
accept/reject, user and org rename, cron run, mirror sync, adopt unadopted
|
|
repository) are destructive.
|
|
- Every tool also accepts optional `sudo` (admin acts as another user).
|
|
- One extra hand-written tool, `gitea_api_request`, reaches endpoints added in
|
|
newer Gitea versions than the pinned spec.
|
|
- Filters: `TOOLSETS` (comma-separated domains, default all), `READ_ONLY`
|
|
(default false), `DISABLED_TOOLS`.
|
|
|
|
## Consequences
|
|
|
|
Upgrading Gitea means re-pinning the swagger and regenerating. Tool names are
|
|
stable for a given spec. The docs inventory is generated from the same catalog
|
|
and checked in CI.
|