Skip to main content
Glama
mergestorm-mcp

mergestorm-mcp

Official

Publish branch through Mergestorm

stack_publish
DestructiveIdempotent

Publish a local branch's commits to GitHub without credentials, letting Mergestorm write the commits as the Surge App, open a ready pull request, and stack branches for auto land, patch or review.

Instructions

Publish a local branch without any GitHub credentials. Reads the branch's commits from the local repository at cwd (never runs gh, git push or git fetch) and sends them to Mergestorm, which writes the exact commits and the branch on GitHub as the Surge App, opens a ready pull request when the branch has none, 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, so Cyclone patches Vortex findings when Auto patch is on. Use it for the first publication and for every later commit to that branch. Defaults: owner and repo from origin, the checked-out branch, the repository's trunk as base, title and body from the tip commit. Two ways to publish: with no base (or trunk as base) the branch opens as a single PR onto trunk; to stack it on another branch, pass that branch as base and extend: true. A base other than trunk without extend is refused with implicit_stack. The result says which one it made. Mergestorm verifies each commit's Git tree before it moves the branch and returns the verified head and tree. It refuses with head_changed when the branch on GitHub holds work your local branch does not, base_changed when the base commit left the base branch, protected_branch for trunk and Mergestorm-owned branches, and payload_too_large beyond 20 commits, 500 changed paths, 2 MiB a file or 8 MiB in total; submodules and merge commits are not carried. replace_head replaces that exact GitHub head with the local branch and discards its commits. Safe to call again after a lost response or a failure: it resumes and never duplicates the branch, commits, pull request or stack. Follow watch.next.args until watch.done; background watching requires a confirmed host notification. See server instructions.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "stack_publish"
  }
}

Input Schema

NameRequiredDescriptionDefault
cwdNo
baseNo
bodyNo
repoNo
ownerNo
titleNo
branchNo
extendNo
auto_landNo
replace_headNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.2.31

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations, it discloses that no gh/git push/git fetch is run, that it acts as the Surge App, the exact refusal codes (head_changed, base_changed, protected_branch, payload_too_large with concrete limits), that submodules and merge commits are not carried, and that replace_head discards the remote head. It also confirms resume-without-duplication semantics, which is consistent with idempotentHint=true and destructiveHint=true.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded and nearly every clause adds operational information, but the text is a dense multi-clause block where phrases like 'Auto patch and Auto review left to the stack, repository and account settings' are hard to parse. It is sized appropriately for a complex tool yet would benefit from sentence breaks.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 10-parameter, non-idempotent-looking write with no output schema, the description covers defaults, branching modes, refusal conditions, size limits, retry safety, and what the result reports (which mode was used, verified head and tree), plus the watch.next.args loop. Nothing essential for a correct call is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 10 parameters at 0% schema description coverage, the description carries the full burden and does: it documents defaults for owner, repo, branch, base, title and body, explains the base/extend interaction and the implicit_stack refusal, describes replace_head's exact match-and-discard behavior, notes cwd as the local repository root, and ties auto_land to new-stack registration.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource ('Publish a local branch') and immediately explains the mechanism: reads commits from the local repo at cwd, sends them to Mergestorm, which writes the branch on GitHub, opens a PR, and registers the stack. An agent can distinguish this publish action from status/restack siblings without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit when-to-use guidance ('Use it for the first publication and for every later commit to that branch') and clear branch-pointing rules: no base or trunk as base yields a single PR, while a non-trunk base with extend:true stacks it, and a non-trunk base without extend is refused with implicit_stack. It does not route to named alternatives such as stack_publish_status or stack_restack, leaving sibling choice to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.