mergestorm-mcp 0.2.27 → 0.2.29

package/README.md

@@ -1,6 +1,6 @@
 # mergestorm-mcp
 
-Stdio MCP server for Mergestorm. Tools: `whoami`, `credits`, `review_list`, `review_submit`, `review_wait`, `review_wait_pr`, `review_dismiss`, `review_start_pr`, `review_stop_pr`, `cyclone_start`, `cyclone_job`, `issue_create`, `stack_adopt`, `stack_enqueue`, `stack_list`, `stack_publish`, `stack_publish_status`, `stack_restack`, `stack_set`, `stack_status`, `stack_wait`, `queue_status`, `settings_get`, `settings_set`, `repo_settings_get`, `repo_settings_set`, `surge_setup`.
+Stdio MCP server for Mergestorm. Tools: `whoami`, `credits`, `review_list`, `review_submit`, `review_wait`, `review_wait_pr`, `review_dismiss`, `review_start_pr`, `review_stop_pr`, `cyclone_start`, `cyclone_job`, `issue_create`, `issue_review_wait`, `stack_adopt`, `stack_enqueue`, `stack_list`, `stack_publish`, `stack_publish_status`, `stack_restack`, `stack_set`, `stack_status`, `stack_wait`, `queue_status`, `settings_get`, `settings_set`, `repo_settings_get`, `repo_settings_set`, `surge_setup`, `list_memories`, `search_memory`, `remember`, `update_memory`, `forget_memory`, `get_memory_mode`, `set_memory_mode`, `web_search`, `read_web_page`.
 
 Every tool declares MCP `annotations` for read-only access, destructive changes, idempotence, and external systems. Reads are read-only; submission, adoption, dismissal, and policy changes are writes. Tools that can change existing policy, topology, or review gates are marked potentially destructive even when some inputs only preview or read. Annotations describe effects; the client still controls approval and authorization.
 
@@ -16,16 +16,20 @@ Every tool declares MCP `annotations` for read-only access, destructive changes,
 - **Gates.** `gate.seam.cleared` is true only when every finding of that integration review is dismissed and it is still the member's current seam verdict. `gate.vortex.cleared` is true once every Vortex Blocker (error finding) at the live head is dismissed (every Core review merged into that head) and no Vortex review of the head is running or incomplete; with a warning still open the head reads `comment`, which Auto land accepts; otherwise `gate.vortex.reason` and `message` say what still holds it: that head's Vortex verdict becomes approve for Auto land, the stack watch, the dashboard and Cyclone. A partial dismissal clears nothing. CI and Auto land policy are unchanged (`gate.other_gates: "unchanged"`). For a stack PR the result carries `watch` with the next `stack_wait` call.
 - **No resurfacing.** Vortex does not raise a dismissed finding again on the same diff: the same head, or a restack whose diff is unchanged.
 
-`issue_create({ title, body?, labels?, owner?, repo?, cwd? })` opens a GitHub issue through Mergestorm with no GitHub credentials: the Surge App creates it and names the caller in the body. It defaults to the origin repository of `cwd`. Labels must already exist on the repository. The same title again returns the open issue it already made (`created: false`), so a retry does not duplicate it. Put `Fixes #<number>` in the commit or pull request body.
+`issue_create({ title, body?, labels?, owner?, repo?, cwd? })` opens a GitHub issue through Mergestorm with no GitHub credentials: the Surge App creates it and names the caller in the body. It defaults to the origin repository of `cwd`. Labels must already exist on the repository. The same title again returns the open issue it already made (`created: false`), so a retry does not duplicate it. Then call `issue_review_wait` and open the pull request, with `Fixes #<number>` in the commit or pull request body, only once the issue is approved.
+
+`issue_review_wait({ owner, repo, number, timeout_s? })` reads the Vortex review of an issue: `state` (`approved`, `needs_answers`, `pending`, `unreviewed`, `capped` or `off`), the round, the verdict, up to 8 points, the review comment link and `next`, one sentence saying what to do. `timeout_s: 0` reads it once; otherwise it waits while the review is pending, for up to 45s (the default), and returns `pending` when the slice ends. On `needs_answers` or `unreviewed`, answer the points in a comment on the issue and call it again; Vortex reviews each reply. On `capped`, a person approves with an issue comment whose first line is `mergestorm-issue: approve`. `stack_adopt` and `stack_publish` refuse a pull request whose linked issue is not approved with `issue_not_approved`, naming each issue's state and points.
 
 The agent tools start work on the user's own pull requests and repositories (`POST /api/v1/agents/...`):
 
 - `review_start_pr({ owner, repo, pr_number, head_sha? })` starts a Vortex review at the pull request's current head (one standard credit). With `head_sha`, nothing starts unless that is still the head. `review_stop_pr({ owner, repo, pr_number })` cancels a running review.
 - `cyclone_start({ task, owner, repo, pr_number?, failing_check?, brief? })` has Cyclone `fix_findings`, `fix_ci` or `resolve_conflicts` on a pull request and push the result, or `build` a first version of a new project from `brief` into an empty repository. A pull request with nothing to do (CI green, no conflicts, no open findings) is refused with the reason. `cyclone_job({ dispatch_id, timeout_s? })` waits up to `timeout_s` seconds (default 45, max 100, 0 reads once) until the job is pushed, completed or failed, and returns its state, outcome, pushed commit and changed files; call it again while the job is queued or running.
 - `stack_restack({ stack_id })` rebases a stack's layers onto their parents; `stack_enqueue({ stack_id })` sends it to the merge queue. Restarting a failed land is a restack, then an enqueue. Neither lands or promotes anything by itself.
+- `list_memories`, `search_memory`, `remember`, `update_memory`, `forget_memory`, `get_memory_mode` and `set_memory_mode` manage what Mergestorm remembers about you, through `/api/v1/memories`. Inside a Breeze chat, `remember` and `search_memory` follow that chat's memory setting.
+- `web_search` and `read_web_page` search the public web and read one page, through `/api/v1/web`, with a budget of 30 calls per key per hour.
 - `surge_setup({ owner, repo })` serves a repository on Surge when it is not served yet and opens the pull request that moves its CI to Surge runners.
 
-When the server serves a Breeze chat (`MERGESTORM_CHAT_ID`, or the hosted endpoint's chat header), `review_start_pr`, `cyclone_start` and `stack_enqueue` also register a wake, so the chat gets the result when the work finishes.
+When the server serves a Breeze chat (`MERGESTORM_CHAT_ID`, or the hosted endpoint's chat header), `cyclone_start`, `review_start_pr`, `stack_enqueue`, and a `review_wait_pr` or `stack_wait` that times out record the work as a background task of that chat, so the chat gets the result when the work finishes.
 
 The stack tools expose reads, one scoped policy write, and publication of your own branch: