mergestorm-mcp 0.2.26 → 0.2.27

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`, `issue_create`, `stack_adopt`, `stack_list`, `stack_publish`, `stack_publish_status`, `stack_set`, `stack_status`, `stack_wait`, `queue_status`, `settings_get`, `settings_set`, `repo_settings_get`, `repo_settings_set`.
+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`.
 
 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.
 
@@ -18,11 +18,20 @@ Every tool declares MCP `annotations` for read-only access, destructive changes,
 
 `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.
 
+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.
+- `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.
+
 The stack tools expose reads, one scoped policy write, and publication of your own branch:
 
 - `stack_adopt({ owner, repo, pr_number, auto_land?, auto_review?, auto_patch?, auto_resolve_conflicts?, auto_fix_ci? })` adopts an open PR chain with optional per-stack policy. Omitted policy does not force Cyclone off. `auto_review`, `auto_patch`, `auto_resolve_conflicts`, and `auto_fix_ci` accept `true`, `false`, or `null`; `null` clears the override. Read `stack_status` with the returned `result.stack.id` to verify policy and Cyclone ownership. Adoption needs the Mergestorm Surge GitHub App on the repository (Cyclone is the auto-patch App). A refusal keeps the code `cyclone_not_connected` or `cyclone_not_installed`; its message, and `error.reason` starting with `surge_` when Surge is the one to install, say which App is missing.
 - `stack_list` returns the current API key owner's registered stacks.
-- `stack_publish({ cwd?, owner?, repo?, branch?, base?, title?, body?, replace_head?, auto_land? })` publishes a local branch with no GitHub credentials. It reads the branch's commits from the repository at `cwd` and sends them to Mergestorm, which writes them and the branch on GitHub as the Surge App, opens a ready pull request, and registers the stack with Auto land on for a new stack, and Auto patch and Auto review left to the stack, repository and account settings. It never runs `gh`, `git push` or `git fetch`. Call it again for every later commit to that branch, and after a lost response: it resumes and does not duplicate the branch, commits, pull request or stack. It refuses with `head_changed` when the branch on GitHub holds work the local branch does not; `replace_head` names the exact GitHub head to replace. Limits: 20 commits, 500 changed paths, 2 MiB a file, 8 MiB in total; no submodules or merge commits. The result carries the verified head commit and tree, the pull request, the stack and its `watch`.
+- `stack_publish({ cwd?, owner?, repo?, branch?, base?, extend?, title?, body?, replace_head?, auto_land? })` publishes a local branch with no GitHub credentials. It reads the branch's commits from the repository at `cwd` and sends them to Mergestorm, which writes them and the branch on GitHub as the Surge App, opens a ready pull request, and registers the stack with Auto land on for a new stack, and Auto patch and Auto review left to the stack, repository and account settings. With no `base` the branch opens as a single PR onto trunk; to stack it on another branch, pass that branch as `base` with `extend: true`. A non-trunk `base` without `extend` fails with `implicit_stack`. The summary says which one it made. It never runs `gh`, `git push` or `git fetch`. Call it again for every later commit to that branch, and after a lost response: it resumes and does not duplicate the branch, commits, pull request or stack. It refuses with `head_changed` when the branch on GitHub holds work the local branch does not; `replace_head` names the exact GitHub head to replace. Limits: 20 commits, 500 changed paths, 2 MiB a file, 8 MiB in total; no submodules or merge commits. The result carries the verified head commit and tree, the pull request, the stack and its `watch`.
 - `stack_publish_status({ cwd?, owner?, repo?, branch? })` reads how far a publication got (`absent`, `pushed`, `opened`, `registered`) with the head on GitHub, the pull request and the stack's Auto patch and Auto land state. It changes nothing.
 - `stack_set({ stack_id, auto_land?, auto_review?, auto_patch?, auto_resolve_conflicts?, auto_fix_ci? })` sets per-stack policy on one owned stack. `auto_land` flips Auto land. `auto_review`, `auto_patch`, `auto_resolve_conflicts`, and `auto_fix_ci` pin Vortex auto-review, Cyclone auto-patch, Auto-resolve merge conflicts, or Auto-fix failing CI for that stack in either direction (`true` or `false`); `null` clears the pin so the stack follows the account setting. Pass at least one key. Account settings are never changed here.
 - `stack_status({ stack_id })` returns one owned stack with enriched checks and agent state, plus `attention`, `issues`, and `currentCandidate` from the same blocker rules as `stack_wait`, read against that stack's own merge queue. Attention covers every open layer, not only `currentCandidate`: it names the lowest layer with a blocker an agent must fix and no Vortex or Cyclone run working on it. It returns a structured `stack_not_found` or `rate_limited` error.
@@ -92,6 +101,10 @@ Add to project `.cursor/mcp.json`:
 
 For global `~/.cursor/mcp.json`, use an explicit sandbox path. Authentication uses the saved `mg login` on the server machine. [Cursor MCP configuration](https://cursor.com/docs/mcp).
 
+### Hosted endpoint
+
+The same server runs over Streamable HTTP at `https://api.mergestorm.ai/api/v1/mcp`. Send your `mg login` key (or any Mergestorm API key) as `Authorization: Bearer <key>` on every request; each request acts only as that key's account. The endpoint is stateless (POST only, no session) and has the API's rate limit and a 256 KiB request cap. It offers every tool except the ones that read a local checkout: `review_submit`, `stack_publish` and `stack_publish_status`, and `issue_create` there needs `owner` and `repo`.
+
 ### Connection and watch checks
 
 In each client, confirm the server connects and lists tools, then call `whoami`. It should return the account key prefix without exposing the full key. On a known owned stack, `stack_wait` with `timeout_s: 0` should return one snapshot; use `watch.next.args` for the next bounded wait. Default waits use 45-second slices, so leave the host tool timeout above 45 seconds.