Branches & Merge Requests — MCP Tools
10 tools in the Branches & Merge Requests group of the Routebase MCP server.
get_branch
Get one branch with how many endpoints, schemas and folders live on it. Set includeDiff for the change summary against main, the conflicts and the classified (breaking / non-breaking) changes — that is the read to trust before merging. Set includeRebasePreview to see how far the branch is behind main and what a rebase would have to resolve. Requires project context.
Required scope: specs:read
| Parameter | Type | Required | Description |
|---|---|---|---|
specId |
string | Yes | Public ID (GUID) of the API specification |
branchId |
string | Yes | Public ID (GUID) of the branch |
includeDiff |
boolean | No (default false) |
Also return the diff against main: counts, conflicts, classified changes (default false) |
includeRebasePreview |
boolean | No (default false) |
Also return the rebase preview: behind count and conflicting clones (default false) |
get_merge_policy
Get the merge policy of a spec: how many reviewers a merge request needs and which guards apply. isDefault true means no policy was configured and these are the defaults. Requires project context.
Required scope: specs:read
| Parameter | Type | Required | Description |
|---|---|---|---|
specId |
string | Yes | Public ID (GUID) of the API specification |
get_merge_request
Get one merge request with its reviewers, their decisions and the comment thread. The userId values under reviewers are what manage_merge_request('create') expects. Set includeAuditTrail for the who-did-what history of the spec's merge requests. For what the merge would actually change, use get_branch(includeDiff). Requires project context.
Required scope: specs:read
| Parameter | Type | Required | Description |
|---|---|---|---|
specId |
string | Yes | Public ID (GUID) of the API specification |
mergeRequestId |
string | Yes | Public ID (GUID) of the merge request |
includeAuditTrail |
boolean | No (default false) |
Also return the audit trail of this spec's merge requests (default false) |
list_branches
List the branches of a draft version, with their status (active, merged or closed). Requires project context.
Required scope: specs:read
| Parameter | Type | Required | Description |
|---|---|---|---|
specId |
string | Yes | Public ID (GUID) of the API specification |
versionId |
string | Yes | Public ID (GUID) of the spec version the branches belong to |
list_merge_requests
List the merge requests of a spec with their status (open, inReview, approved, merged, rejected, closed) and how many of the assigned reviewers have approved. Requires project context.
Required scope: specs:read
| Parameter | Type | Required | Description |
|---|---|---|---|
specId |
string | Yes | Public ID (GUID) of the API specification |
manage_branch
Work with a branch of a draft version. 'create' needs versionId and name — the version must be in draft. 'merge' applies the branch to main and fails while any conflict is left. 'rebase' pulls main's newer changes in and needs one resolution per conflicting clone from get_branch(includeRebasePreview) — pass them as 'cloneId=keepMain,cloneId=keepBranch'. 'resolve_conflicts' records field-level decisions for the audit trail but does NOT clear them for the merge — edit the branch entities or rebase for that. 'close' abandons the branch and soft-deletes everything on it; it does not check for open merge requests. Requires project context.
Required scope: specs:branch
| Parameter | Type | Required | Description |
|---|---|---|---|
specId |
string | Yes | Public ID (GUID) of the API specification |
action |
string | Yes | What to do: 'create', 'merge', 'rebase', 'resolve_conflicts' or 'close' |
branchId |
string | No | Public ID (GUID) of the branch — required for everything except 'create' |
versionId |
string | No | Public ID (GUID) of the draft version to branch from — required for 'create' |
name |
string | No | Branch name, unique within the version — required for 'create' |
description |
string | No | Optional branch description |
resolutions |
string | No | For 'rebase': one entry per conflicting clone, as 'cloneId=keepMain,cloneId=keepBranch'. The clone IDs come from get_branch(includeRebasePreview) → rebasePreview.conflicts[].cloneId |
resolutionsJson |
string | No | For 'resolve_conflicts': the decisions as a JSON array of {entityPublicId, entityType, field, resolutionType: 'keepMain'|'keepBranch'|'custom', customValue?} — take entity, type and field from get_branch(includeDiff) → diff.conflicts |
manage_merge_request
Open or close a merge request for a branch. 'create' needs branchId, title and at least one reviewer — pass reviewerUserIds as a comma-separated list of the userId values from list_members. Reviewers must be members of the same organization. Only one open merge request per branch is allowed. 'close' abandons it without merging. Reviewing is review_merge_request, merging is merge_merge_request. Requires project context.
Required scope: specs:branch
| Parameter | Type | Required | Description |
|---|---|---|---|
specId |
string | Yes | Public ID (GUID) of the API specification |
action |
string | Yes | What to do: 'create' or 'close' |
branchId |
string | No | Public ID (GUID) of the branch — required for 'create' |
mergeRequestId |
string | No | Public ID (GUID) of the merge request — required for 'close' |
title |
string | No | Title — required for 'create' |
description |
string | No | Optional description |
reviewerUserIds |
string | No | Public IDs (GUIDs) of the reviewers from list_members, comma-separated — required for 'create' |
merge_merge_request
Merge an approved merge request into main. The merge request must already be approved — that happens through review_merge_request, there is no separate approve step — and the merge policy must be satisfied. Requires project context.
Required scope: specs:merge
| Parameter | Type | Required | Description |
|---|---|---|---|
specId |
string | Yes | Public ID (GUID) of the API specification |
mergeRequestId |
string | Yes | Public ID (GUID) of the merge request |
review_merge_request
Review a merge request. 'approve' and 'request_changes' count as your review decision and you must be one of its assigned reviewers; the merge request flips to approved once enough reviewers approved (see get_merge_policy → minReviewers). 'comment' only adds to the thread and can anchor on an entity and field. Requires project context.
Required scope: specs:review
| Parameter | Type | Required | Description |
|---|---|---|---|
specId |
string | Yes | Public ID (GUID) of the API specification |
mergeRequestId |
string | Yes | Public ID (GUID) of the merge request |
action |
string | Yes | What to do: 'approve', 'request_changes' or 'comment' |
comment |
string | No | Review note, or the comment body — required for 'comment' |
parentCommentId |
string | No | For 'comment': public ID (GUID) of the comment being replied to |
entityType |
string | No | For 'comment': the entity the comment is about, e.g. 'endpoint' or 'schema' |
entityId |
string | No | For 'comment': public ID (GUID) of that entity |
field |
string | No | For 'comment': the field the comment is about |
update_merge_policy
Change the merge policy of a spec. This REPLACES the policy — values you omit are carried over from the current one, so you can change minReviewers alone. Requires project context.
Required scope: specs:write
| Parameter | Type | Required | Description |
|---|---|---|---|
specId |
string | Yes | Public ID (GUID) of the API specification |
minReviewers |
integer | No | How many reviewers must approve before a merge request can be merged |
requireAdminForBreaking |
boolean | No | Require an Admin or Owner approval when the branch diff carries breaking changes |