Branch Tools

Two tools for managing the relationship between Git branches and issues — link a branch when you start work, unlink it when you mis-linked or no longer need the association.

link-branch

Link a Git branch to an issue.

Parameters

Parameter	Type	Required	Description
issue_id	integer	One of	The numeric ID of the issue (provide issue_id or issue_key, not both)
issue_key	string	One of	The issue key, e.g. "KD-0042" (provide issue_id or issue_key, not both)
branch_name	string	Yes	The name of the Git branch (max 255 characters)
repo_id	integer	Conditional	Target GitHub repo ID. Omit on single-repo projects. On multi-repo projects, omit on the first attempt; if you get a candidate-listing error, retry with one of the listed repo IDs (look up IDs via the kendo://projects/{id}/github-repos resource) or ask the human to pick.

Behavior

• The GitHub repository is automatically resolved when the project has exactly one linked repo — no repo_id needed
• On multi-repo projects without repo_id, the tool returns a candidate-listing error rather than guessing — retry with the right repo_id
• Returns the branch link with status (Open, Merged, Closed), URL, repository, and creator
• Branch status is updated automatically via GitHub webhooks when PRs are opened, merged, or closed

Example Prompt

Link my current branch to the email validation issue

unlink-branch

Remove a Git branch link from an issue. Useful when you mis-linked a branch (wrong issue, wrong repo, typo in the branch name) or when cleaning up after a cancelled feature.

Parameters

Parameter	Type	Required	Description
issue_id	integer	One of	The numeric ID of the issue (provide issue_id or issue_key, not both)
issue_key	string	One of	The issue key, e.g. "KD-0042" (provide issue_id or issue_key, not both)
branch_name	string	Yes	The exact branch name to unlink (case-sensitive, max 255 characters)
repo_full_name	string	Conditional	Disambiguates when the issue has multiple links sharing this branch name across repos. Required only in that case — single-link issues ignore it (but reject a mismatched hint).

Behavior

• Identifies the link by (issue, branch_name) and walks the issue's existing branch links. The GitHub repository is not auto-resolved here — repo_full_name only matters when more than one repo has a link with the same branch name on this issue.
• Returns a structured payload with the deleted link's id, branch_name, repository.name, and issue.id so you can confirm exactly what was removed.
• Returns a structured error listing the candidate repo_full_names when the request is ambiguous (multi-repo without a hint, or with a hint that matches none).
• Idempotent on retry — a second call against an already-deleted link returns a "branch link not found" error.
• Authorization mirrors the web UI: the caller must have project access AND delete permission on the link (ownership bypass applies for the link's creator).
• Every invocation writes one ai_mcp_logs row — success, validation failure, authz denial, ambiguity, and unexpected errors all produce an audit-trail entry.

Example Prompts

Unlink the feature/wrong-branch branch from KD-0142

The bot linked the wrong branch — unlink hotfix/x on acme/website from KD-0207

See Also

• Resources — Read branch links via kendo://issues/{id} (includes branch_links array) and kendo://projects/{id}/github-repos (linked repositories)
• GitHub Integration — OAuth setup, webhooks, and lane triggers