Latte
8b7bb7205c
Inventory and gap analysis of the 0.2.0 codebase against the full Gitea API and the official gitea-mcp toolset, the B1..B11 + security chunk plan, ADRs 0001-0006 for the full-access rebuild, SDK/OAuth research notes, and the instance swagger pinned for tool generation. The audit-logging doc moves to docs/audit-logging.md.
39 lines
1.8 KiB
Markdown
39 lines
1.8 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.
|
|
- 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.
|