From 0079f3508c5810e2f5fa2c0e46c5c64f71d082af Mon Sep 17 00:00:00 2001 From: Defame1297 Date: Sun, 30 Aug 2026 12:21:11 +0000 Subject: [PATCH] fix(gitea-prs): correct reference drift against gitea-mcp v1.7.0 The reference files were last verified against v1.3.0 -- references/sources.md still said so. PR #106 re-verified the write side only, so three defects had accumulated on the read/review side. All three reproduced against the deployed server before being fixed; get_gitea_mcp_server_version reports v1.7.0. - reviews.md forbade review_comments on the "get" response and directed callers to review_scomments, which does not exist. The upstream slim.go typo was corrected; a live pull_request_read on PR #106 returns "review_comments":1 and no review_scomments key. review_comments is an integer count, not comment objects -- distinct from the get_review_comments method. Also fixed in pull-requests.md's response-shape list. - pull_request_review_write grants seven methods; only four were documented. reply_comment, resolve_thread, unresolve_thread and the comment_id parameter had zero mentions anywhere in the skill. Documented from the schema, in a Comment threads section kept outside the numbered review state machine -- they are not lifecycle states. - review_id was documented as required for get_review_comments. It is optional; omitting it lists every inline comment on the PR. Confirmed behaviourally: get_review without it errors, get_review_comments without it returns []. sources.md now records v1.7.0 as the last-verified version, so the next reader knows what these files were checked against. Refs #99 --- plugins/gitea/.apm/skills/gitea-prs/README.md | 4 +-- plugins/gitea/.apm/skills/gitea-prs/SKILL.md | 2 +- .../gitea-prs/references/pull-requests.md | 6 ++--- .../skills/gitea-prs/references/reviews.md | 27 +++++++++++++------ .../skills/gitea-prs/references/sources.md | 4 +-- 5 files changed, 27 insertions(+), 16 deletions(-) diff --git a/plugins/gitea/.apm/skills/gitea-prs/README.md b/plugins/gitea/.apm/skills/gitea-prs/README.md index b9a084a..4d07ed3 100644 --- a/plugins/gitea/.apm/skills/gitea-prs/README.md +++ b/plugins/gitea/.apm/skills/gitea-prs/README.md @@ -4,7 +4,7 @@ List, read, create, update, merge, and review Gitea pull requests. ## What it does -This skill handles the pull request lifecycle within the Gitea integration suite — listing and reading PRs (details, diff, changed files, CI status, reviews), creating them (title, body, labels), updating them (title, body, assignees, labels, milestone), adding and removing reviewers, closing/reopening, merging with a chosen strategy and post-merge branch cleanup, and the full code-review flow (create a review with inline comments, submit it, dismiss or delete it). It composes `gitea-labels-milestones` for label/milestone ID resolution rather than duplicating that logic — `milestone` applies on an update only, never on create — and defers to `gitea-issues` for anything that turns out to be an issue rather than a PR (they share one number space) and to `gitea-branches`/`gitea-files` for the underlying branch/file operations behind a PR. +This skill handles the pull request lifecycle within the Gitea integration suite — listing and reading PRs (details, diff, changed files, CI status, reviews), creating them (title, body, labels), updating them (title, body, assignees, labels, milestone), adding and removing reviewers, closing/reopening, merging with a chosen strategy and post-merge branch cleanup, and the full code-review flow (create a review with inline comments, submit it, dismiss or delete it, reply to a review comment, and resolve or unresolve a comment thread). It composes `gitea-labels-milestones` for label/milestone ID resolution rather than duplicating that logic — `milestone` applies on an update only, never on create — and defers to `gitea-issues` for anything that turns out to be an issue rather than a PR (they share one number space) and to `gitea-branches`/`gitea-files` for the underlying branch/file operations behind a PR. ## Usage @@ -20,6 +20,6 @@ Describe the PR or review task: list PRs, get a PR's status/diff/reviews, create |------|---------| | `SKILL.md` | Skill instructions for agents — Gotchas, the dispatch table, and label/milestone ID resolution via `gitea-labels-milestones` | | `references/pull-requests.md` | Execution detail for `list_pull_requests`, `pull_request_read` (get/get_diff/get_files/get_status), and `pull_request_write` (create/update/close/reopen/update_branch/add_reviewers/remove_reviewers) | -| `references/reviews.md` | Execution detail for `pull_request_review_write` (create/submit/delete/dismiss) and the review-related `pull_request_read` methods | +| `references/reviews.md` | Execution detail for `pull_request_review_write` (create/submit/delete/dismiss, plus the comment-thread methods reply_comment/resolve_thread/unresolve_thread) and the review-related `pull_request_read` methods | | `references/merging.md` | The merge workflow — CI vs. review/branch-protection gates, merge styles, branch cleanup, and the post-merge issue-close check | | `references/sources.md` | Research sources backing the PR/review guidance | diff --git a/plugins/gitea/.apm/skills/gitea-prs/SKILL.md b/plugins/gitea/.apm/skills/gitea-prs/SKILL.md index b4834ac..b14dd3f 100644 --- a/plugins/gitea/.apm/skills/gitea-prs/SKILL.md +++ b/plugins/gitea/.apm/skills/gitea-prs/SKILL.md @@ -34,7 +34,7 @@ Resolve `owner` and `repo` from context first, and confirm the number names a PR | Create a PR — subject to the silent-drop Gotcha above | `pull_request_write` | `references/pull-requests.md` | | Update, close, reopen or retarget a PR, sync it with its base, or add/remove reviewers | `pull_request_write` | `references/pull-requests.md` | | Merge a PR, or judge whether it can merge | `pull_request_write method: "merge"` | `references/merging.md` | -| Read, create, submit, dismiss or delete a code review | `pull_request_read`, `pull_request_review_write` | `references/reviews.md` | +| Read, create, submit, dismiss or delete a code review, or reply to and resolve a review comment thread | `pull_request_read`, `pull_request_review_write` | `references/reviews.md` | Whatever `"create"` dropped takes a second call once the PR exists — `"update"` for milestone and assignees, `"add_reviewers"` for reviewers. 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 05084d4..7f92032 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`, and the `review_scomments` typo covered in `references/reviews.md`). Re-verify via `ToolSearch` before trusting this file if the gitea-mcp version changes. +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. ## `list_pull_requests` @@ -29,14 +29,14 @@ List responses trim PRs down to summary fields — `head`/`base` are bare ref st - `owner` (string, required) - `repo` (string, required) - `pull_number` (number, required) -- `review_id` (number, optional) — required for `"get_review"` and `"get_review_comments"`; see `references/reviews.md` +- `review_id` (number, optional) — required for `"get_review"`, which errors with `review_id is required` without it. **Optional** for `"get_review_comments"`: omit it to list every inline comment on the PR in one call. See `references/reviews.md` - `binary` (boolean, optional) — include binary diff content for `"get_diff"` - `page` (number, optional, default 1) - `per_page` (number, optional, default 30) `"get"`, `"get_diff"`, `"get_files"`, and `"get_status"` are covered here. `"get_reviews"`, `"get_review"`, and `"get_review_comments"` are covered in `references/reviews.md`. -- `"get"` returns the full PR object: state, draft, merged, mergeable flags; `head`/`base` as full objects (`{ref, sha, repo?}`); `milestone` as a bare title string (not `{id, title}`); `review_scomments` (typo, see `references/reviews.md`). +- `"get"` returns the full PR object: state, draft, merged, mergeable flags; `head`/`base` as full objects (`{ref, sha, repo?}`); `milestone` as a bare title string (not `{id, title}`); and `review_comments` as an integer count, not comment objects (see `references/reviews.md`). - `"get_diff"` returns raw diff text. - `"get_files"` returns the list of changed file objects. - `"get_status"` returns the combined commit status for the PR's head commit — CI result only, not review/approval state (see `references/merging.md`). diff --git a/plugins/gitea/.apm/skills/gitea-prs/references/reviews.md b/plugins/gitea/.apm/skills/gitea-prs/references/reviews.md index e21d23d..77003b2 100644 --- a/plugins/gitea/.apm/skills/gitea-prs/references/reviews.md +++ b/plugins/gitea/.apm/skills/gitea-prs/references/reviews.md @@ -7,7 +7,7 @@ source_keys: # PR review execution detail -Parameter signatures below are cross-checked live against the deployed gitea-mcp server tool schema, not copied from the plugin's research doc verbatim — same sourcing discipline as `references/pull-requests.md`. +Parameter signatures below are cross-checked live against the deployed gitea-mcp server tool schema, not copied from the plugin's research doc verbatim — same sourcing discipline as `references/pull-requests.md`. Last verified against **v1.7.0**, as reported by `get_gitea_mcp_server_version`. ## Review state machine @@ -21,23 +21,34 @@ A review is not a single write. It moves through states: ## `pull_request_review_write` **Parameters:** -- `method` (string, required) — `"create"` | `"submit"` | `"delete"` | `"dismiss"` +- `method` (string, required) — `"create"` | `"submit"` | `"delete"` | `"dismiss"` | `"reply_comment"` | `"resolve_thread"` | `"unresolve_thread"` - `owner` (string, required) - `repo` (string, required) -- `pull_number` (number, required) -- `review_id` (number, required for every method except `"create"`, which returns the ID to use for the follow-up `submit`/`delete`/`dismiss` call) +- `pull_number` (number, required for every method except `"resolve_thread"` and `"unresolve_thread"`, which locate the thread from `comment_id` alone) — the schema's own `required` list is only `method`/`owner`/`repo`, so a missing `pull_number` surfaces as a runtime error, not client-side validation +- `review_id` (number) — required for `"submit"`, `"delete"` and `"dismiss"`; `"create"` returns the ID to use for that follow-up call. Not used by `"reply_comment"`, `"resolve_thread"` or `"unresolve_thread"`, which key off `comment_id` instead +- `comment_id` (number, required for `"reply_comment"`, `"resolve_thread"` and `"unresolve_thread"`) — an individual review comment's ID, obtained from `pull_request_read method: "get_review_comments"`. For the two thread methods this must be the thread's **first** comment, not an arbitrary one in it - `state` (string, optional) — `"APPROVED"` | `"REQUEST_CHANGES"` | `"COMMENT"` | `"PENDING"` — set on `"create"` (typically `"PENDING"`, or a terminal state to create-and-submit in one call if the server supports it) or `"submit"` (terminal state) -- `body` (string, optional) — overall review comment text +- `body` (string, optional) — the overall review comment text on `"create"`/`"submit"`; on `"reply_comment"` it is the reply text and is the payload of the call - `commit_id` (string, optional, for `"create"`) — anchors inline comments to a specific commit SHA (typically the PR's current head SHA from `pull_request_read method: "get"`) - `message` (string, optional, for `"dismiss"`) — dismissal reason - `comments` (array of objects, optional, for `"create"`) — inline comments, each: `{path, body, old_line_num, new_line_num}` — `path` is the file path, `body` is the comment text, `new_line_num` anchors to a line in the new (added) side of the diff, `old_line_num` anchors to a line in the old (removed) side; use whichever side the comment applies to, not both +## Comment threads + +Three further methods act on an individual review comment rather than on a review as a whole. They sit outside the state machine above — a thread can be replied to or resolved whatever state its parent review is in — and none of them takes a `review_id`. + +- **`reply_comment`** — posts `body` as a reply to the comment named by `comment_id`, threading under it rather than starting a new top-level comment. Takes `pull_number`. +- **`resolve_thread`** — marks the thread containing `comment_id` resolved. Pass the thread's **first** comment ID; another ID in the same thread is not equivalent. Does not take `pull_number`. +- **`unresolve_thread`** — reopens a resolved thread, under the same first-comment rule. + +Get the `comment_id` from `pull_request_read method: "get_review_comments"`. Call it with no `review_id` to list every inline comment on the PR, then pick the thread to act on; scoping it to one `review_id` only finds threads opened by that review. + ## Reading reviews (`pull_request_read`) - `method: "get_reviews"` — array of review summaries: `id`, `state`, `body`, `user` (login), `comments_count`, `submitted_at`, `html_url`, `stale` (bool — the PR was pushed to after this review was submitted, meaning it may be outdated), `official` (bool), `dismissed` (bool). -- `method: "get_review"` (requires `review_id`) — single review detail. -- `method: "get_review_comments"` (requires `review_id`) — array of inline comments: `id`, `body`, `path`, `position`, `old_position`, `diff_hunk`, `user`, `html_url`, `created_at`, `updated_at`. +- `method: "get_review"` (requires `review_id` — omitting it fails with `review_id is required`) — single review detail. +- `method: "get_review_comments"` (`review_id` **optional** — omit it to list every inline comment on the PR in one call, rather than one review's) — array of inline comments: `id`, `body`, `path`, `position`, `old_position`, `diff_hunk`, `user`, `html_url`, `created_at`, `updated_at`. -**`review_scomments` typo:** the full PR object returned by `pull_request_read method: "get"` includes a field named `review_scomments` (a count), not `review_comments` — a source-level misspelling in gitea-mcp v1.3.0's `slim.go`. Do not write code or instructions that reference `review_comments` on that response; it will always be `undefined`. This is distinct from the `get_review_comments` method above, which is spelled correctly and returns the actual comment objects. +**`review_comments` on the `"get"` response is a count, not the comments.** The full PR object returned by `pull_request_read method: "get"` carries `review_comments` as an integer — the number of inline review comments. It is distinct from the `get_review_comments` method above, which returns the actual comment objects; reading the count is no substitute for that call. Older gitea-mcp releases misspelled this key as `review_scomments`; the misspelling was corrected upstream and the deployed v1.7.0 response carries no such key, so treat any instruction that reaches for `review_scomments` as stale. **Inline-comment field names differ between write and read.** The `comments` array on `pull_request_review_write method: "create"` uses `old_line_num`/`new_line_num`. The `get_review_comments` read response uses different field names for the same concept — `position` (new-side line) and `old_position` (old-side line). Do not assume the same key names apply on both sides of the round trip. diff --git a/plugins/gitea/.apm/skills/gitea-prs/references/sources.md b/plugins/gitea/.apm/skills/gitea-prs/references/sources.md index d1b10ed..bc464f6 100644 --- a/plugins/gitea/.apm/skills/gitea-prs/references/sources.md +++ b/plugins/gitea/.apm/skills/gitea-prs/references/sources.md @@ -3,7 +3,7 @@ ## gitea-mcp-repo - **URL:** https://gitea.com/gitea/gitea-mcp -- **Description:** Official gitea-mcp repository (v1.3.0) — `operation/*.go` source files documenting all 55 MCP tools, their parameters, and CLI flags. Live tool schemas (`list_pull_requests`, `pull_request_read`, `pull_request_write`, `pull_request_review_write`) were verified directly against the deployed MCP server via `ToolSearch` at authoring time, per this repo's process for resolving schema-vs-docs drift, rather than copied from the derived research doc. +- **Description:** Official gitea-mcp repository — `operation/*.go` source files documenting the MCP tools, their parameters, and CLI flags. Live tool schemas (`list_pull_requests`, `pull_request_read`, `pull_request_write`, `pull_request_review_write`) are verified directly against the deployed MCP server via `ToolSearch`, per this repo's process for resolving schema-vs-docs drift, rather than copied from the derived research doc. **Last verified against v1.7.0**, as reported by `get_gitea_mcp_server_version`; the files were originally authored against v1.3.0 and the read/review side had drifted by three defects before that re-verification. - **Research doc:** plugins/gitea/docs/research/docs/gitea/sources.md - **Contributing files:** SKILL.md, references/pull-requests.md, references/reviews.md, references/merging.md - **Status:** `extracted` @@ -11,7 +11,7 @@ ## gitea-mcp-slim-go - **URL:** https://gitea.com/gitea/gitea-mcp/raw/branch/main/operation/pull/slim.go -- **Description:** Slim response shape structs from gitea-mcp source — defines exactly which fields the MCP server returns for PRs and reviews, including the `review_scomments` typo and the PR-response milestone-as-title-string quirk. +- **Description:** Slim response shape structs from gitea-mcp source — defines exactly which fields the MCP server returns for PRs and reviews, including the PR-response milestone-as-title-string quirk. The `review_scomments` misspelling this file documented at v1.3.0 was corrected upstream; v1.7.0 returns `review_comments`. - **Research doc:** plugins/gitea/docs/research/docs/gitea/sources.md - **Contributing files:** SKILL.md, references/pull-requests.md, references/reviews.md - **Status:** `extracted`