Defame1297
8680adf4c0
gitea-releases was the weakest skill in the plugin: no allowed-tools, no owner/repo resolution, and a checkbox list where a dispatch table belongs, so an agent reaching it had to guess both its permissions and its inputs. The id-vs-tag_name trap — deleting by tag name where the API wants the numeric id — is restored as an explicit Gotcha because it destroys the wrong release silently. Elsewhere the `exclusive` flag was documented on the wrong side of the read/write split, and label data from one instance was presented as though it were universal, which invites an agent to assume a taxonomy that does not exist on the target repo. rename_branch was missing from the branch surface. Reference prose and fences are cleaned up in passing.
77 lines
4.1 KiB
Markdown
77 lines
4.1 KiB
Markdown
---
|
|
topic: call-signatures
|
|
source_keys:
|
|
- gitea-mcp-repo
|
|
- gitea-mcp-slim-go
|
|
---
|
|
|
|
# Release and tag call signatures
|
|
|
|
Signatures and response shapes are derived from gitea-mcp source (`operation/*.go` and `slim.go`,
|
|
see `references/sources.md`) rather than copied from upstream API docs, which can drift from the
|
|
deployed gitea-mcp version — but this is a source-code extraction, not a live MCP tool call.
|
|
|
|
Input parameter schemas for all 9 tools here were additionally cross-checked live via `ToolSearch`
|
|
against the deployed `mcp__gitea__*` tools and confirmed to match exactly — required and optional
|
|
params, names, and defaults. Last verified against gitea-mcp **v1.7.0**, as reported by
|
|
`get_gitea_mcp_server_version`. That check covers input params only: the response shapes below
|
|
remain source-derived, not live-verified, so re-verify them if a response reads differently than
|
|
documented here.
|
|
|
|
`owner` and `repo` are required strings on every tool below and are omitted from the per-tool lists
|
|
for brevity.
|
|
|
|
## Releases
|
|
|
|
**`list_releases`**
|
|
- Optional: `is_draft` (boolean), `is_pre_release` (boolean), `page` (number, default 1), `per_page` (number, default 20)
|
|
- Returns an array of release objects (shape below), one page at a time.
|
|
|
|
**`get_release`**
|
|
- Required: `id` (number) — the release's numeric id, not its tag name.
|
|
- Returns a single release object.
|
|
|
|
**`get_latest_release`**
|
|
- No parameters beyond `owner`/`repo`.
|
|
- Returns a single release object for the most recently published release. The deployed tool's own description reads "the most recent published (non-draft) release" — it names drafts as excluded and is silent on prereleases, so whether prereleases are also excluded is *unconfirmed*; verify with `list_releases` if the caller depends on it. Either way a release created without `is_pre_release: true` is eligible, which is why that flag has to be set in the create call (see `conventions.md`).
|
|
|
|
**`create_release`**
|
|
- Required: `tag_name` (string), `target` (string — branch, tag, or commit SHA to cut the tag from), `title` (string)
|
|
- Optional: `body` (string — release notes), `is_draft` (boolean), `is_pre_release` (boolean)
|
|
- Assumed (not confirmed by the research docs) that if `tag_name` doesn't already exist as a tag, Gitea creates it against `target` as part of this call. Verify with `get_tag`/`list_tags` afterward if the caller needs certainty.
|
|
|
|
**`delete_release`**
|
|
- Required: `id` (number) — same numeric id as `get_release`. Does not accept `tag_name`.
|
|
- Does not delete the underlying tag.
|
|
|
|
**Release object shape** (returned by list/get/create/latest):
|
|
```text
|
|
id, tag_name, target, title, body, draft, prerelease, html_url, author, created_at, published_at
|
|
```
|
|
`author` is the creator's login. `body` holds the release notes.
|
|
|
|
## Tags
|
|
|
|
**`list_tags`**
|
|
- Optional: `page` (number, default 1), `per_page` (number, default 20)
|
|
- Returns an array of `{ name, commit_sha }` — no `message` field on list responses.
|
|
|
|
**`get_tag`**
|
|
- Required: `tag_name` (string)
|
|
- Returns `{ name, message, commit_sha }` — the only tag call that returns `message`.
|
|
|
|
**`create_tag`**
|
|
- Required: `tag_name` (string)
|
|
- Optional: `target` (string — commitish to tag; if omitted, Gitea tags the default branch tip), `message` (string — annotated tag message)
|
|
|
|
**`delete_tag`**
|
|
- Required: `tag_name` (string). Does not accept a numeric id.
|
|
- Assumed by symmetry with `delete_release` (documented above as not deleting the underlying tag) to also not delete any release wrapping the tag — but this reverse direction is not independently confirmed by the research docs, and is the more dangerous direction to get wrong: an agent might skip an explicit `delete_release` call assuming the release survives. Verify with `list_releases`/`get_release` after calling `delete_tag` rather than assume.
|
|
|
|
## Pagination
|
|
|
|
None of the list tools auto-paginate. To collect a full result set, call with `page: 1`, then
|
|
`page: 2`, etc., stopping when a page returns fewer items than `per_page`. `list_releases` and
|
|
`list_tags` default `per_page` to 20 — lower than the 30-default used by most other gitea-mcp list
|
|
tools, so a caller assuming 30 will under-count pages needed for a fixed total.
|