diff --git a/plugins/gitea/.apm/skills/gitea-issues/SKILL.md b/plugins/gitea/.apm/skills/gitea-issues/SKILL.md index b168d4a..898805e 100644 --- a/plugins/gitea/.apm/skills/gitea-issues/SKILL.md +++ b/plugins/gitea/.apm/skills/gitea-issues/SKILL.md @@ -25,7 +25,7 @@ allowed-tools: Bash mcp__gitea__list_issues mcp__gitea__issue_read mcp__gitea__i ## Gotchas -- **`list_issues` returns PRs too.** It has no `type` filter and both share one repo number space. `is_pull` appears only on `issue_read method: "get"`, never on a list item — check it there before treating a number as an issue. +- **`list_issues` mixes in PRs unless you filter.** Issues and PRs share one repo number space; pass `type: "issues"` to exclude PRs (or `"pulls"` for only PRs). Nothing on a list item flags which is which — `is_pull` appears only on `issue_read method: "get"`, never on a list item. - **Label IDs and names are not interchangeable.** `issue_write` takes numeric IDs only; `list_issues` and `search_issues` filter by name; `issue_read "get"` returns names but `"get_labels"` returns full objects with IDs. Resolve via `gitea-labels-milestones` unless the caller named exact labels. - **A merged PR leaves its issue open.** Gitea does not auto-close on merge the way GitHub does. Re-read the issue's state after a merge before closing it manually. - **A 404 may really be a 403.** Gitea hides permission errors as not-found — check the token's `write:issue` scope before concluding the issue does not exist. @@ -46,7 +46,7 @@ One invocation takes one row. Read only the reference(s) that row names — the | Invocation | Flow | Read | |---|---|---| -| `/gitea-issues` or `/gitea-issues list` | List issues, optionally filtered by state | `references/issues.md` | +| `/gitea-issues` or `/gitea-issues list` | List issues with `type: "issues"` so PRs are excluded, optionally filtered by state | `references/issues.md` | | `/gitea-issues ` | Get one issue, routing to `gitea-prs` when the number turns out to be a PR | `references/issues.md` | | `/gitea-issues comments` | Get an issue's comments | `references/issues.md` | | `/gitea-issues labels` | Get an issue's labels as full objects, IDs included | `references/issues.md` | diff --git a/plugins/gitea/.apm/skills/gitea-issues/references/issues.md b/plugins/gitea/.apm/skills/gitea-issues/references/issues.md index 41cc259..d1b0c92 100644 --- a/plugins/gitea/.apm/skills/gitea-issues/references/issues.md +++ b/plugins/gitea/.apm/skills/gitea-issues/references/issues.md @@ -7,11 +7,13 @@ source_keys: # Issue operations -Call signatures below were verified live against the deployed `gitea-mcp` server via `ToolSearch` -at authoring time, not copied from `api-reference.md` — this is deliberate: research docs are -generated from source at a point in time and can drift from the server actually deployed (see the -`list_issues` gotcha below, which is the exact drift this policy exists to catch). Re-verify against -the live schema if these tools appear to behave differently than documented here. +Call signatures below were verified live against the deployed `gitea-mcp` server via `ToolSearch`, +not copied from `api-reference.md` — this is deliberate: research docs are generated from source at +a point in time and can drift from the server actually deployed. Last verified against gitea-mcp +**v1.7.0**, as reported by `get_gitea_mcp_server_version`. Drift runs in both directions: this file +previously recorded `list_issues` as having neither a `type` nor a `milestones` parameter, and +v1.7.0 has both. Re-verify against the live schema if these tools appear to behave differently than +documented here. ## `list_issues` @@ -21,18 +23,22 @@ the live schema if these tools appear to behave differently than documented here - `state` (string, optional, default `"all"`) — conventional values `"open"`/`"closed"`/`"all"`, not schema-enforced as an enum - `labels` (array of strings, optional) — filter by label *name* (not ID) +- `milestones` (array of strings, optional) — filter by milestone name or numeric ID, both passed as + strings +- `type` (string, enum `"issues"` | `"pulls"`, optional) — omit it and the response mixes both - `since` (string, optional) — ISO 8601, issues updated after this time - `before` (string, optional) — ISO 8601, issues updated before this time - `page` (number, optional, default `1`) - `per_page` (number, optional, default `30`) -**There is no `type` parameter and no `milestones` parameter**, despite both appearing in -`api-reference.md`. This tool cannot filter issues-vs-PRs or by milestone — see the Gotchas section -of SKILL.md for the consequence (PR entries can appear in results with no way to exclude them here). +**Pass `type: "issues"` on any listing meant to show issues.** Issues and PRs share one repo number +space and the unfiltered response interleaves them; the only thing distinguishing them on a list +item is the `html_url` path segment (`/issues/` vs `/pulls/`), since `is_pull` is not returned on +list items — see the Gotchas section of SKILL.md. **Call:** ``` -list_issues owner: repo: state: "open" +list_issues owner: repo: state: "open" type: "issues" ``` **Response (list item):** `number`, `title`, `state`, `html_url`, `user`, `comments`, `created_at`, @@ -117,6 +123,13 @@ issue_write method: "add_labels" owner: repo: issue_number: l To replace all labels atomically instead of adding: `method: "replace_labels"`. To remove one: `method: "remove_label" label_id: `. +**Default to `add_labels`.** `replace_labels` clears every label not in the array, so it drops +labels the caller never mentioned. Reach for it only when the caller asked for the issue's label +set to become exactly what they listed. In particular, do not use it to enforce one-label-per-scope: +exclusivity is a per-label property — the server drops the sibling itself for a label whose +`exclusive` field is `true`, and a label whose `exclusive` is `false` (every `Kind/*` on this +instance) is legitimately stackable. See `gitea-labels-milestones` for how to read that field. + ## Token scope All of `list_issues`, `issue_read`, and `issue_write` are verified working under a token holding diff --git a/plugins/gitea/.apm/skills/gitea-issues/references/search.md b/plugins/gitea/.apm/skills/gitea-issues/references/search.md index 1a449b4..13b3714 100644 --- a/plugins/gitea/.apm/skills/gitea-issues/references/search.md +++ b/plugins/gitea/.apm/skills/gitea-issues/references/search.md @@ -13,8 +13,8 @@ time (see `references/sources.md`) — confirmed to match `api-reference.md`. **Parameters:** - `query` (string, required) — the only hard-required parameter - `state` (string, enum `"open"` | `"closed"` | `"all"`, optional) -- `type` (string, enum `"issues"` | `"pulls"`, optional) — **this tool has a working type filter**, - unlike `list_issues` (see `references/issues.md`) +- `type` (string, enum `"issues"` | `"pulls"`, optional) — the same filter, with the same values, + that `list_issues` takes (see `references/issues.md`) - `labels` (string, optional) — comma-separated label **names** — a plain string, not the array form `list_issues` uses - `owner` (string, optional) — restrict results to one owner diff --git a/plugins/gitea/.apm/skills/gitea-issues/references/sources.md b/plugins/gitea/.apm/skills/gitea-issues/references/sources.md index 904be31..7b60d71 100644 --- a/plugins/gitea/.apm/skills/gitea-issues/references/sources.md +++ b/plugins/gitea/.apm/skills/gitea-issues/references/sources.md @@ -1,12 +1,13 @@ # Sources **Note on call signatures:** per `docs/adr/0011-gitea-skill-deep-modules.md`, the tool parameter -signatures in `references/issues.md` and `references/search.md` were re-verified live via -`ToolSearch` against the deployed `gitea-mcp` server at authoring time — they are not copied -verbatim from `api-reference.md`. This resolves issue #6 comment #849's root-cause finding that a -prior skill was authored from API docs that had drifted from the actual MCP tool schema; the live -check caught exactly this drift on `list_issues` (see `references/issues.md` — the research doc -documents a `type` and a `milestones` parameter that do not exist on the deployed server). +signatures in `references/issues.md` and `references/search.md` are re-verified live via +`ToolSearch` against the deployed `gitea-mcp` server — they are not copied verbatim from +`api-reference.md`. This resolves issue #6 comment #849's root-cause finding that a prior skill was +authored from API docs that had drifted from the actual MCP tool schema. That re-verification is +ongoing, not one-off: an earlier live check recorded `list_issues` as lacking the `type` and +`milestones` parameters `api-reference.md` documents, and both are present on the deployed +gitea-mcp **v1.7.0**, which is the version these signatures are current as of. ## gitea-mcp-repo diff --git a/plugins/gitea/.apm/skills/gitea-prs/references/pull-requests.md b/plugins/gitea/.apm/skills/gitea-prs/references/pull-requests.md index 7f92032..04a6e2c 100644 --- a/plugins/gitea/.apm/skills/gitea-prs/references/pull-requests.md +++ b/plugins/gitea/.apm/skills/gitea-prs/references/pull-requests.md @@ -7,7 +7,7 @@ source_keys: # Pull request read/write execution detail -Parameter signatures below are cross-checked live against the deployed gitea-mcp server tool schemas at authoring time — not copied verbatim from the plugin's research doc for this domain, which has a known history of drifting from the deployed server (e.g. a prior `type` parameter that no longer exists on `list_issues`). These files were last verified against gitea-mcp **v1.7.0**, as reported by `get_gitea_mcp_server_version`. Re-verify via `ToolSearch` before trusting this file if the deployed version differs — drift has bitten this skill in both directions, adding methods it does not list and fixing quirks it still warns about. +Parameter signatures below are cross-checked live against the deployed gitea-mcp server tool schemas at authoring time — not copied verbatim from the plugin's research doc for this domain, which has a known history of drifting from the deployed server. These files were last verified against gitea-mcp **v1.7.0**, as reported by `get_gitea_mcp_server_version`. Re-verify via `ToolSearch` before trusting this file if the deployed version differs — drift has bitten this skill in both directions, adding methods it does not list and fixing quirks it still warns about. ## `list_pull_requests` diff --git a/plugins/gitea/skills/gitea-issues/SKILL.md b/plugins/gitea/skills/gitea-issues/SKILL.md index b168d4a..898805e 100644 --- a/plugins/gitea/skills/gitea-issues/SKILL.md +++ b/plugins/gitea/skills/gitea-issues/SKILL.md @@ -25,7 +25,7 @@ allowed-tools: Bash mcp__gitea__list_issues mcp__gitea__issue_read mcp__gitea__i ## Gotchas -- **`list_issues` returns PRs too.** It has no `type` filter and both share one repo number space. `is_pull` appears only on `issue_read method: "get"`, never on a list item — check it there before treating a number as an issue. +- **`list_issues` mixes in PRs unless you filter.** Issues and PRs share one repo number space; pass `type: "issues"` to exclude PRs (or `"pulls"` for only PRs). Nothing on a list item flags which is which — `is_pull` appears only on `issue_read method: "get"`, never on a list item. - **Label IDs and names are not interchangeable.** `issue_write` takes numeric IDs only; `list_issues` and `search_issues` filter by name; `issue_read "get"` returns names but `"get_labels"` returns full objects with IDs. Resolve via `gitea-labels-milestones` unless the caller named exact labels. - **A merged PR leaves its issue open.** Gitea does not auto-close on merge the way GitHub does. Re-read the issue's state after a merge before closing it manually. - **A 404 may really be a 403.** Gitea hides permission errors as not-found — check the token's `write:issue` scope before concluding the issue does not exist. @@ -46,7 +46,7 @@ One invocation takes one row. Read only the reference(s) that row names — the | Invocation | Flow | Read | |---|---|---| -| `/gitea-issues` or `/gitea-issues list` | List issues, optionally filtered by state | `references/issues.md` | +| `/gitea-issues` or `/gitea-issues list` | List issues with `type: "issues"` so PRs are excluded, optionally filtered by state | `references/issues.md` | | `/gitea-issues ` | Get one issue, routing to `gitea-prs` when the number turns out to be a PR | `references/issues.md` | | `/gitea-issues comments` | Get an issue's comments | `references/issues.md` | | `/gitea-issues labels` | Get an issue's labels as full objects, IDs included | `references/issues.md` | diff --git a/plugins/gitea/skills/gitea-issues/references/issues.md b/plugins/gitea/skills/gitea-issues/references/issues.md index 41cc259..d1b0c92 100644 --- a/plugins/gitea/skills/gitea-issues/references/issues.md +++ b/plugins/gitea/skills/gitea-issues/references/issues.md @@ -7,11 +7,13 @@ source_keys: # Issue operations -Call signatures below were verified live against the deployed `gitea-mcp` server via `ToolSearch` -at authoring time, not copied from `api-reference.md` — this is deliberate: research docs are -generated from source at a point in time and can drift from the server actually deployed (see the -`list_issues` gotcha below, which is the exact drift this policy exists to catch). Re-verify against -the live schema if these tools appear to behave differently than documented here. +Call signatures below were verified live against the deployed `gitea-mcp` server via `ToolSearch`, +not copied from `api-reference.md` — this is deliberate: research docs are generated from source at +a point in time and can drift from the server actually deployed. Last verified against gitea-mcp +**v1.7.0**, as reported by `get_gitea_mcp_server_version`. Drift runs in both directions: this file +previously recorded `list_issues` as having neither a `type` nor a `milestones` parameter, and +v1.7.0 has both. Re-verify against the live schema if these tools appear to behave differently than +documented here. ## `list_issues` @@ -21,18 +23,22 @@ the live schema if these tools appear to behave differently than documented here - `state` (string, optional, default `"all"`) — conventional values `"open"`/`"closed"`/`"all"`, not schema-enforced as an enum - `labels` (array of strings, optional) — filter by label *name* (not ID) +- `milestones` (array of strings, optional) — filter by milestone name or numeric ID, both passed as + strings +- `type` (string, enum `"issues"` | `"pulls"`, optional) — omit it and the response mixes both - `since` (string, optional) — ISO 8601, issues updated after this time - `before` (string, optional) — ISO 8601, issues updated before this time - `page` (number, optional, default `1`) - `per_page` (number, optional, default `30`) -**There is no `type` parameter and no `milestones` parameter**, despite both appearing in -`api-reference.md`. This tool cannot filter issues-vs-PRs or by milestone — see the Gotchas section -of SKILL.md for the consequence (PR entries can appear in results with no way to exclude them here). +**Pass `type: "issues"` on any listing meant to show issues.** Issues and PRs share one repo number +space and the unfiltered response interleaves them; the only thing distinguishing them on a list +item is the `html_url` path segment (`/issues/` vs `/pulls/`), since `is_pull` is not returned on +list items — see the Gotchas section of SKILL.md. **Call:** ``` -list_issues owner: repo: state: "open" +list_issues owner: repo: state: "open" type: "issues" ``` **Response (list item):** `number`, `title`, `state`, `html_url`, `user`, `comments`, `created_at`, @@ -117,6 +123,13 @@ issue_write method: "add_labels" owner: repo: issue_number: l To replace all labels atomically instead of adding: `method: "replace_labels"`. To remove one: `method: "remove_label" label_id: `. +**Default to `add_labels`.** `replace_labels` clears every label not in the array, so it drops +labels the caller never mentioned. Reach for it only when the caller asked for the issue's label +set to become exactly what they listed. In particular, do not use it to enforce one-label-per-scope: +exclusivity is a per-label property — the server drops the sibling itself for a label whose +`exclusive` field is `true`, and a label whose `exclusive` is `false` (every `Kind/*` on this +instance) is legitimately stackable. See `gitea-labels-milestones` for how to read that field. + ## Token scope All of `list_issues`, `issue_read`, and `issue_write` are verified working under a token holding diff --git a/plugins/gitea/skills/gitea-issues/references/search.md b/plugins/gitea/skills/gitea-issues/references/search.md index 1a449b4..13b3714 100644 --- a/plugins/gitea/skills/gitea-issues/references/search.md +++ b/plugins/gitea/skills/gitea-issues/references/search.md @@ -13,8 +13,8 @@ time (see `references/sources.md`) — confirmed to match `api-reference.md`. **Parameters:** - `query` (string, required) — the only hard-required parameter - `state` (string, enum `"open"` | `"closed"` | `"all"`, optional) -- `type` (string, enum `"issues"` | `"pulls"`, optional) — **this tool has a working type filter**, - unlike `list_issues` (see `references/issues.md`) +- `type` (string, enum `"issues"` | `"pulls"`, optional) — the same filter, with the same values, + that `list_issues` takes (see `references/issues.md`) - `labels` (string, optional) — comma-separated label **names** — a plain string, not the array form `list_issues` uses - `owner` (string, optional) — restrict results to one owner diff --git a/plugins/gitea/skills/gitea-issues/references/sources.md b/plugins/gitea/skills/gitea-issues/references/sources.md index 904be31..7b60d71 100644 --- a/plugins/gitea/skills/gitea-issues/references/sources.md +++ b/plugins/gitea/skills/gitea-issues/references/sources.md @@ -1,12 +1,13 @@ # Sources **Note on call signatures:** per `docs/adr/0011-gitea-skill-deep-modules.md`, the tool parameter -signatures in `references/issues.md` and `references/search.md` were re-verified live via -`ToolSearch` against the deployed `gitea-mcp` server at authoring time — they are not copied -verbatim from `api-reference.md`. This resolves issue #6 comment #849's root-cause finding that a -prior skill was authored from API docs that had drifted from the actual MCP tool schema; the live -check caught exactly this drift on `list_issues` (see `references/issues.md` — the research doc -documents a `type` and a `milestones` parameter that do not exist on the deployed server). +signatures in `references/issues.md` and `references/search.md` are re-verified live via +`ToolSearch` against the deployed `gitea-mcp` server — they are not copied verbatim from +`api-reference.md`. This resolves issue #6 comment #849's root-cause finding that a prior skill was +authored from API docs that had drifted from the actual MCP tool schema. That re-verification is +ongoing, not one-off: an earlier live check recorded `list_issues` as lacking the `type` and +`milestones` parameters `api-reference.md` documents, and both are present on the deployed +gitea-mcp **v1.7.0**, which is the version these signatures are current as of. ## gitea-mcp-repo diff --git a/plugins/gitea/skills/gitea-prs/references/pull-requests.md b/plugins/gitea/skills/gitea-prs/references/pull-requests.md index 7f92032..04a6e2c 100644 --- a/plugins/gitea/skills/gitea-prs/references/pull-requests.md +++ b/plugins/gitea/skills/gitea-prs/references/pull-requests.md @@ -7,7 +7,7 @@ source_keys: # Pull request read/write execution detail -Parameter signatures below are cross-checked live against the deployed gitea-mcp server tool schemas at authoring time — not copied verbatim from the plugin's research doc for this domain, which has a known history of drifting from the deployed server (e.g. a prior `type` parameter that no longer exists on `list_issues`). These files were last verified against gitea-mcp **v1.7.0**, as reported by `get_gitea_mcp_server_version`. Re-verify via `ToolSearch` before trusting this file if the deployed version differs — drift has bitten this skill in both directions, adding methods it does not list and fixing quirks it still warns about. +Parameter signatures below are cross-checked live against the deployed gitea-mcp server tool schemas at authoring time — not copied verbatim from the plugin's research doc for this domain, which has a known history of drifting from the deployed server. These files were last verified against gitea-mcp **v1.7.0**, as reported by `get_gitea_mcp_server_version`. Re-verify via `ToolSearch` before trusting this file if the deployed version differs — drift has bitten this skill in both directions, adding methods it does not list and fixing quirks it still warns about. ## `list_pull_requests`