@stubbedev/atlassian-mcp 0.0.1

package/README.md

@@ -0,0 +1,300 @@
+# atlassian-mcp
+
+A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for **self-hosted Jira** (Server / Data Center) and **self-hosted Bitbucket** (Server / Data Center). Exposes 34 tools to Claude for reading and managing issues, pull requests, comments, and git context.
+
+> **Note:** This server only supports self-hosted instances. Jira Cloud and Bitbucket Cloud use different APIs and are not supported.
+
+---
+
+## Tools
+
+### Context
+
+| Tool | Description |
+|---|---|
+| `get_dev_context` | Unified snapshot: git state + linked Jira tickets (from branch name) + open PR for the current branch |
+
+### Jira
+
+| Tool | Description |
+|---|---|
+| `jira_search_issues` | Search issues by text, JQL, project, status, assignee, or issue type |
+| `jira_my_issues` | List issues assigned to you, ordered by last updated |
+| `jira_get_projects` | List all accessible projects |
+| `jira_get_issue_types` | List issue types and their available statuses for a project |
+| `jira_get_issue` | Get issue details by key |
+| `jira_create_issue` | Create a new issue |
+| `jira_update_issue` | Update summary, description, assignee, or priority |
+| `jira_search_users` | Search for users by name or email |
+| `jira_get_comments` | List comments on an issue |
+| `jira_add_comment` | Add a comment to an issue |
+| `jira_get_transitions` | List available status transitions |
+| `jira_transition_issue` | Change issue status via transition ID |
+
+### Bitbucket
+
+| Tool | Description |
+|---|---|
+| `bitbucket_list_repos` | List repositories (optionally by project) |
+| `bitbucket_list_pull_requests` | List pull requests for a repository |
+| `bitbucket_my_prs` | List PRs in your inbox (authored by you or awaiting review) |
+| `bitbucket_get_pull_request` | Get pull request details |
+| `bitbucket_get_pr_diff` | Get the code diff for a pull request |
+| `bitbucket_create_pull_request` | Create a new pull request |
+| `bitbucket_create_pr_from_context` | Create a PR auto-detecting project, repo, and branch from the current git repo |
+| `bitbucket_approve_pr` | Approve a pull request |
+| `bitbucket_unapprove_pr` | Remove your approval from a pull request |
+| `bitbucket_merge_pr` | Merge a pull request |
+| `bitbucket_decline_pr` | Decline a pull request |
+| `bitbucket_get_pr_comments` | Get comment threads with IDs and states for a pull request |
+| `bitbucket_add_pr_comment` | Add a top-level PR comment or reply to an existing comment |
+| `bitbucket_update_pr_comment` | Update comment text, state, or severity (`NORMAL` / `BLOCKER`) |
+| `bitbucket_delete_pr_comment` | Delete a PR comment by comment ID |
+| `bitbucket_get_pr_commits` | List commits included in a pull request |
+| `bitbucket_get_branches` | List branches in a repository |
+| `bitbucket_get_file` | Get raw file content at a given ref |
+
+### Git
+
+| Tool | Description |
+|---|---|
+| `git_get_context` | Branch, remote, recent commits, working tree status, and any Jira keys detected in the branch name |
+| `git_get_commits` | Commit history for a branch with author and message |
+| `git_get_diff` | Diff of uncommitted changes or between two refs |
+
+All list tools support `limit` and `start`/`startAt` for pagination.
+
+---
+
+## Setup
+
+### 1. Create a config file
+
+Create `~/.atlassian-mcp.json`:
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/stubbedev/atlassian-mcp/master/atlassian-mcp.schema.json",
+  "jira": {
+    "url": "https://jira.example.com",
+    "token": "your-jira-personal-access-token"
+  },
+  "bitbucket": {
+    "url": "https://bitbucket.example.com",
+    "token": "your-bitbucket-personal-access-token"
+  }
+}
+```
+
+The `$schema` field is optional but enables editor autocomplete and validation. For Bitbucket tools, `projectKey` and `repoSlug` are auto-detected from your local `origin` remote when omitted. Jira project-specific tools still require `projectKey` in the tool call.
+
+Alternatively, use environment variables (or a `.env` file in this directory):
+
+```env
+JIRA_URL=https://jira.example.com
+JIRA_ACCESS_TOKEN=your-jira-personal-access-token
+BITBUCKET_URL=https://bitbucket.example.com
+BITBUCKET_ACCESS_TOKEN=your-bitbucket-personal-access-token
+```
+
+Config is resolved in this order: `--config <path>` CLI arg → `ATLASSIAN_MCP_CONFIG` env var → `~/.atlassian-mcp.json` → `.atlassian-mcp.json` in cwd → environment variables.
+
+### 2. Connect to your AI tool
+
+No cloning or building required — just point your tool at `npx @stubbedev/atlassian-mcp@latest` and it will install and run automatically. Add `--prefer-online` to make `npx` check npm for updates on each run.
+
+---
+
+#### Claude Code
+
+```bash
+claude mcp add atlassian -- npx --prefer-online -y @stubbedev/atlassian-mcp@latest --config ~/.atlassian-mcp.json
+```
+
+---
+
+#### Cursor
+
+Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project-only):
+
+```json
+{
+  "mcpServers": {
+    "atlassian": {
+      "command": "npx",
+      "args": ["--prefer-online", "-y", "@stubbedev/atlassian-mcp@latest", "--config", "/Users/you/.atlassian-mcp.json"]
+    }
+  }
+}
+```
+
+---
+
+#### Windsurf
+
+Add to `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "atlassian": {
+      "command": "npx",
+      "args": ["--prefer-online", "-y", "@stubbedev/atlassian-mcp@latest", "--config", "/Users/you/.atlassian-mcp.json"]
+    }
+  }
+}
+```
+
+---
+
+#### Zed
+
+Add to `~/.config/zed/settings.json`:
+
+```json
+{
+  "context_servers": {
+    "atlassian": {
+      "command": {
+        "path": "npx",
+        "args": ["--prefer-online", "-y", "@stubbedev/atlassian-mcp@latest", "--config", "/home/you/.atlassian-mcp.json"]
+      }
+    }
+  }
+}
+```
+
+---
+
+#### OpenCode
+
+Add to `opencode.json` in your project root (or `~/.config/opencode/opencode.json` for global):
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "atlassian": {
+      "type": "local",
+      "command": ["npx", "--prefer-online", "-y", "@stubbedev/atlassian-mcp@latest", "--config", "/home/you/.atlassian-mcp.json"]
+    }
+  }
+}
+```
+
+---
+
+#### Codex CLI
+
+Add to `~/.codex/config.yaml`:
+
+```yaml
+mcpServers:
+  atlassian:
+    command: npx
+    args:
+      - --prefer-online
+      - -y
+      - @stubbedev/atlassian-mcp@latest
+      - --config
+      - /home/you/.atlassian-mcp.json
+```
+
+---
+
+#### Any other MCP-compatible tool
+
+Most tools that support MCP accept the same JSON format. Use `npx` as the command with `["--prefer-online", "-y", "@stubbedev/atlassian-mcp@latest", "--config", "/path/to/config.json"]` as the args.
+
+---
+
+### Manual install (optional)
+
+If you prefer to clone and run locally:
+
+```bash
+git clone git@github.com:stubbedev/atlassian-mcp.git
+cd atlassian-mcp
+npm install
+```
+
+Then use `node /path/to/atlassian-mcp/dist/index.js` instead of the `npx` command in the configs above.
+
+---
+
+## Releases (Maintainers)
+
+This package is published to npm as `@stubbedev/atlassian-mcp`.
+
+Automatic publish is configured in `.github/workflows/publish.yml`:
+
+- Push a tag like `v1.0.1` to publish from CI
+- Or run the workflow manually via **Actions → Publish Package**
+
+Required repository secret:
+
+- `NPM_TOKEN` (npm automation token with publish rights for `@stubbedev`)
+
+Manual publish from local machine:
+
+```bash
+npm run build
+npm publish --access public
+```
+
+---
+
+## Creating Personal Access Tokens
+
+### Jira Server / Data Center
+
+Personal Access Tokens are supported from **Jira 8.14** onwards.
+
+1. Log in to your Jira instance.
+2. Click your profile avatar in the top-right corner and select **Profile**.
+3. In the left sidebar, click **Personal Access Tokens**.
+4. Click **Create token**.
+5. Give the token a name (e.g. `atlassian-mcp`) and optionally set an expiry date.
+6. Click **Create** and copy the token — it will only be shown once.
+
+Paste the token as the `token` value under `jira` in your config file.
+
+> If your Jira version is older than 8.14, you can use HTTP Basic Auth instead — but this server only supports Bearer token (PAT) authentication.
+
+### Bitbucket Server / Data Center
+
+Personal Access Tokens are supported from **Bitbucket Server 5.5** onwards.
+
+1. Log in to your Bitbucket instance.
+2. Click your profile avatar in the top-right corner and select **Manage account**.
+3. In the left sidebar, under **Security**, click **Personal access tokens**.
+4. Click **Create a token**.
+5. Give the token a name (e.g. `atlassian-mcp`).
+6. Set the permissions:
+   - **Projects**: Read
+   - **Repositories**: Read + Write (Write is needed to create pull requests and add comments)
+7. Optionally set an expiry date.
+8. Click **Create** and copy the token — it will only be shown once.
+
+Paste the token as the `token` value under `bitbucket` in your config file.
+
+---
+
+## Development
+
+```bash
+# Watch mode — recompiles on file changes
+npm run dev
+
+# Run the built server directly
+node dist/index.js
+
+# Test the tool list
+echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node dist/index.js
+```
+
+To use a specific config file:
+
+```bash
+node dist/index.js --config /path/to/config.json
+```

package/atlassian-mcp.schema.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "atlassian-mcp-config",
+  "title": "Atlassian MCP Config",
+  "description": "Configuration file for the atlassian-mcp MCP server",
+  "type": "object",
+  "required": ["jira", "bitbucket"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "jira": {
+      "type": "object",
+      "description": "Self-hosted Jira Server / Data Center connection settings",
+      "required": ["url", "token"],
+      "additionalProperties": false,
+      "properties": {
+        "url": {
+          "type": "string",
+          "format": "uri",
+          "description": "Base URL of your Jira instance, e.g. https://jira.example.com"
+        },
+        "token": {
+          "type": "string",
+          "description": "Personal Access Token (PAT) for Jira Server authentication"
+        }
+      }
+    },
+    "bitbucket": {
+      "type": "object",
+      "description": "Self-hosted Bitbucket Server / Data Center connection settings",
+      "required": ["url", "token"],
+      "additionalProperties": false,
+      "properties": {
+        "url": {
+          "type": "string",
+          "format": "uri",
+          "description": "Base URL of your Bitbucket instance, e.g. https://bitbucket.example.com"
+        },
+        "token": {
+          "type": "string",
+          "description": "Personal Access Token (PAT) for Bitbucket Server authentication"
+        }
+      }
+    }
+  }
+}

package/dist/bitbucket.js

@@ -0,0 +1,337 @@
+import { execSync } from 'child_process';
+function safeExec(cmd) {
+    try {
+        return execSync(cmd, { encoding: 'utf-8' }).trim();
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Parses a Bitbucket Server remote URL into projectKey + repoSlug.
+ * Handles SSH (ssh://git@host/PROJ/repo.git), SCP-like (git@host:PROJ/repo.git),
+ * and HTTP (https://host/scm/PROJ/repo.git) formats.
+ */
+export function parseBitbucketRemote(remoteUrl) {
+    const sshUrl = remoteUrl.match(/ssh:\/\/[^/]+\/([^/]+)\/([^/]+?)(?:\.git)?$/);
+    if (sshUrl)
+        return { projectKey: sshUrl[1], repoSlug: sshUrl[2] };
+    const scpUrl = remoteUrl.match(/^[^@]+@[^:]+:([^/]+)\/([^/]+?)(?:\.git)?$/);
+    if (scpUrl)
+        return { projectKey: scpUrl[1], repoSlug: scpUrl[2] };
+    const httpUrl = remoteUrl.match(/\/scm\/([^/]+)\/([^/]+?)(?:\.git)?$/);
+    if (httpUrl)
+        return { projectKey: httpUrl[1], repoSlug: httpUrl[2] };
+    return null;
+}
+function text(t) {
+    return { content: [{ type: 'text', text: t }] };
+}
+function toBranchRef(branch) {
+    return branch.startsWith('refs/') ? branch : `refs/heads/${branch}`;
+}
+function formatDate(ms) {
+    return new Date(ms).toISOString().slice(0, 10);
+}
+function formatCommentThread(comment, indent = '') {
+    const author = comment.author?.displayName ?? comment.author?.name ?? 'Unknown';
+    const date = comment.createdDate ? ` (${formatDate(comment.createdDate)})` : '';
+    const state = comment.state ?? 'OPEN';
+    const severity = comment.severity ?? 'NORMAL';
+    const lines = [
+        `${indent}#${comment.id} [${state}/${severity}] ${author}${date} (v${comment.version})`,
+        `${indent}${comment.text}`,
+    ];
+    if (comment.comments && comment.comments.length > 0) {
+        for (const reply of comment.comments) {
+            lines.push(...formatCommentThread(reply, `${indent}  `));
+        }
+    }
+    return lines;
+}
+function pageHint(data) {
+    return data.isLastPage ? '' : ` (use start=${data.nextPageStart} for next page)`;
+}
+function formatDiff(data, maxChars = 8000) {
+    const parts = [];
+    for (const diff of data.diffs) {
+        const from = diff.source?.toString ?? '/dev/null';
+        const to = diff.destination?.toString ?? '/dev/null';
+        parts.push(`--- a/${from}\n+++ b/${to}`);
+        for (const hunk of diff.hunks ?? []) {
+            for (const segment of hunk.segments ?? []) {
+                const prefix = segment.type === 'ADDED' ? '+' : segment.type === 'REMOVED' ? '-' : ' ';
+                for (const line of segment.lines ?? []) {
+                    parts.push(`${prefix}${line.line}`);
+                }
+            }
+        }
+    }
+    const result = parts.join('\n');
+    if (!result)
+        return '(no diff)';
+    if (result.length > maxChars) {
+        return result.slice(0, maxChars) + `\n\n... (truncated, ${result.length - maxChars} more chars)`;
+    }
+    return result;
+}
+export class BitbucketClient {
+    baseUrl;
+    headers;
+    constructor(baseUrl, token) {
+        this.baseUrl = baseUrl.replace(/\/$/, '');
+        this.headers = {
+            Authorization: `Bearer ${token}`,
+            'Content-Type': 'application/json',
+            Accept: 'application/json',
+        };
+    }
+    resolveProjectAndRepo(projectKey, repoSlug) {
+        if (projectKey && repoSlug)
+            return { projectKey, repoSlug };
+        const remote = safeExec('git remote get-url origin');
+        if (remote) {
+            const parsed = parseBitbucketRemote(remote);
+            if (parsed) {
+                return {
+                    projectKey: projectKey ?? parsed.projectKey,
+                    repoSlug: repoSlug ?? parsed.repoSlug,
+                };
+            }
+        }
+        throw new Error('Could not determine projectKey/repoSlug — provide them explicitly or run from a directory inside a git repo with a Bitbucket remote');
+    }
+    async request(method, path, body) {
+        const url = `${this.baseUrl}/rest/api/1.0${path}`;
+        const opts = { method, headers: this.headers };
+        if (body !== undefined)
+            opts.body = JSON.stringify(body);
+        const res = await fetch(url, opts);
+        if (!res.ok) {
+            const errText = await res.text();
+            throw new Error(`Bitbucket ${res.status} ${method} ${path}: ${errText}`);
+        }
+        return res.status === 204 ? null : res.json();
+    }
+    async requestText(path) {
+        const url = `${this.baseUrl}/rest/api/1.0${path}`;
+        const res = await fetch(url, {
+            method: 'GET',
+            headers: { Authorization: this.headers.Authorization },
+        });
+        if (!res.ok) {
+            const errText = await res.text();
+            throw new Error(`Bitbucket ${res.status} GET ${path}: ${errText}`);
+        }
+        return res.text();
+    }
+    // Used internally by context tools — finds the open PR for a given source branch
+    async findOpenPrForBranch(projectKey, repoSlug, branch) {
+        const data = await this.request('GET', `/projects/${projectKey}/repos/${repoSlug}/pull-requests?state=OPEN&limit=50`);
+        return data?.values.find((pr) => pr.fromRef.displayId === branch) ?? null;
+    }
+    async listRepos(args) {
+        const { limit = 50, start = 0 } = args;
+        const qs = `?limit=${limit}&start=${start}`;
+        const path = args.projectKey
+            ? `/projects/${args.projectKey}/repos${qs}`
+            : `/repos${qs}`;
+        const data = await this.request('GET', path);
+        if (!data || data.values.length === 0)
+            return text('No repositories found.');
+        const lines = data.values.map((r, i) => `${start + i + 1}. ${r.project.key}/${r.slug} — ${r.name}`);
+        return text(`${data.values.length} repo(s)${pageHint(data)}:\n${lines.join('\n')}`);
+    }
+    async listPullRequests(args) {
+        const { projectKey, repoSlug } = this.resolveProjectAndRepo(args.projectKey, args.repoSlug);
+        const { state = 'OPEN', limit = 25, start = 0 } = args;
+        const path = `/projects/${projectKey}/repos/${repoSlug}/pull-requests?state=${state}&limit=${limit}&start=${start}`;
+        const data = await this.request('GET', path);
+        if (!data || data.values.length === 0)
+            return text(`No ${state} pull requests found.`);
+        const lines = data.values.map((pr) => `#${pr.id} [${pr.state}] ${pr.title} | ${pr.fromRef.displayId} → ${pr.toRef.displayId} | by ${pr.author.user.displayName}`);
+        return text(`${data.values.length} PR(s) (${state})${pageHint(data)}:\n${lines.join('\n')}`);
+    }
+    async myPrs(args) {
+        const { limit = 25, start = 0 } = args;
+        const data = await this.request('GET', `/inbox/pull-requests?limit=${limit}&start=${start}`);
+        if (!data || data.values.length === 0)
+            return text('No pull requests in your inbox.');
+        const lines = data.values.map((pr) => {
+            const repo = `${pr.toRef.repository.project.key}/${pr.toRef.repository.slug}`;
+            return `#${pr.id} [${pr.state}] ${pr.title} | ${repo} | ${pr.fromRef.displayId} → ${pr.toRef.displayId}`;
+        });
+        return text(`${data.values.length} PR(s) in your inbox${pageHint(data)}:\n${lines.join('\n')}`);
+    }
+    async getPullRequest(args) {
+        const { projectKey, repoSlug } = this.resolveProjectAndRepo(args.projectKey, args.repoSlug);
+        const data = await this.request('GET', `/projects/${projectKey}/repos/${repoSlug}/pull-requests/${args.prId}`);
+        if (!data)
+            return text('Pull request not found.');
+        const reviewers = data.reviewers
+            .map((r) => `${r.user.displayName}${r.approved ? ' ✓' : ''}`)
+            .join(', ');
+        const lines = [
+            `PR #${data.id}: ${data.title}`,
+            `State:     ${data.state}`,
+            `Author:    ${data.author.user.displayName}`,
+            `Branch:    ${data.fromRef.displayId} → ${data.toRef.displayId}`,
+            `Reviewers: ${reviewers || 'None'}`,
+            '',
+            'Description:',
+            data.description ?? '(no description)',
+        ];
+        return text(lines.join('\n'));
+    }
+    async getPrDiff(args) {
+        const { projectKey, repoSlug } = this.resolveProjectAndRepo(args.projectKey, args.repoSlug);
+        const data = await this.request('GET', `/projects/${projectKey}/repos/${repoSlug}/pull-requests/${args.prId}/diff`);
+        if (!data)
+            return text('No diff found.');
+        return text(formatDiff(data));
+    }
+    async getPrCommits(args) {
+        const { projectKey, repoSlug } = this.resolveProjectAndRepo(args.projectKey, args.repoSlug);
+        const limit = args.limit ?? 25;
+        const data = await this.request('GET', `/projects/${projectKey}/repos/${repoSlug}/pull-requests/${args.prId}/commits?limit=${limit}`);
+        if (!data || data.values.length === 0)
+            return text('No commits found.');
+        const lines = data.values.map((c) => `${c.displayId} ${formatDate(c.authorTimestamp)} ${c.author.name}: ${c.message.split('\n')[0]}`);
+        return text(`${data.values.length} commit(s)${pageHint(data)}:\n${lines.join('\n')}`);
+    }
+    async createPullRequest(args) {
+        const { projectKey, repoSlug } = this.resolveProjectAndRepo(args.projectKey, args.repoSlug);
+        const { title, description, fromBranch, toBranch = 'master', reviewers = [] } = args;
+        const body = {
+            title,
+            description: description ?? '',
+            fromRef: { id: toBranchRef(fromBranch), repository: { slug: repoSlug, project: { key: projectKey } } },
+            toRef: { id: toBranchRef(toBranch), repository: { slug: repoSlug, project: { key: projectKey } } },
+            reviewers: reviewers.map((name) => ({ user: { name } })),
+        };
+        const data = await this.request('POST', `/projects/${projectKey}/repos/${repoSlug}/pull-requests`, body);
+        if (!data)
+            return text('Pull request created.');
+        const url = data.links?.self?.[0]?.href ?? '';
+        return text(`Created PR #${data.id}: "${data.title}"${url ? `\n${url}` : ''}`);
+    }
+    async approvePr(args) {
+        const { projectKey, repoSlug } = this.resolveProjectAndRepo(args.projectKey, args.repoSlug);
+        const data = await this.request('POST', `/projects/${projectKey}/repos/${repoSlug}/pull-requests/${args.prId}/approve`);
+        if (!data)
+            return text(`Approved PR #${args.prId}.`);
+        return text(`Approved PR #${args.prId} as ${data.user.displayName}.`);
+    }
+    async unapprovePr(args) {
+        const { projectKey, repoSlug } = this.resolveProjectAndRepo(args.projectKey, args.repoSlug);
+        await this.request('DELETE', `/projects/${projectKey}/repos/${repoSlug}/pull-requests/${args.prId}/approve`);
+        return text(`Approval removed from PR #${args.prId}.`);
+    }
+    async declinePr(args) {
+        const { projectKey, repoSlug } = this.resolveProjectAndRepo(args.projectKey, args.repoSlug);
+        const pr = await this.request('GET', `/projects/${projectKey}/repos/${repoSlug}/pull-requests/${args.prId}`);
+        if (!pr)
+            throw new Error(`PR #${args.prId} not found.`);
+        const body = { version: pr.version };
+        if (args.message)
+            body.message = args.message;
+        const data = await this.request('POST', `/projects/${projectKey}/repos/${repoSlug}/pull-requests/${args.prId}/decline`, body);
+        if (!data)
+            return text(`Declined PR #${args.prId}.`);
+        return text(`Declined PR #${data.id}: "${data.title}".`);
+    }
+    async mergePr(args) {
+        const { projectKey, repoSlug } = this.resolveProjectAndRepo(args.projectKey, args.repoSlug);
+        const pr = await this.request('GET', `/projects/${projectKey}/repos/${repoSlug}/pull-requests/${args.prId}`);
+        if (!pr)
+            throw new Error(`PR #${args.prId} not found.`);
+        const body = { version: pr.version };
+        if (args.mergeStrategy)
+            body.strategyId = args.mergeStrategy;
+        if (args.message)
+            body.message = args.message;
+        const data = await this.request('POST', `/projects/${projectKey}/repos/${repoSlug}/pull-requests/${args.prId}/merge`, body);
+        if (!data)
+            return text(`Merged PR #${args.prId}.`);
+        return text(`Merged PR #${data.id}: "${data.title}" (${data.fromRef.displayId} → ${data.toRef.displayId}).`);
+    }
+    async getBranches(args) {
+        const { projectKey, repoSlug } = this.resolveProjectAndRepo(args.projectKey, args.repoSlug);
+        const qs = new URLSearchParams({ limit: String(args.limit ?? 25), start: String(args.start ?? 0) });
+        if (args.filter)
+            qs.set('filterText', args.filter);
+        const data = await this.request('GET', `/projects/${projectKey}/repos/${repoSlug}/branches?${qs}`);
+        if (!data || data.values.length === 0)
+            return text('No branches found.');
+        const lines = data.values.map((b) => `${b.displayId}${b.isDefault ? ' (default)' : ''} — ${b.latestCommit.slice(0, 8)}`);
+        return text(`${data.values.length} branch(es)${pageHint(data)}:\n${lines.join('\n')}`);
+    }
+    async getFile(args) {
+        const { projectKey, repoSlug } = this.resolveProjectAndRepo(args.projectKey, args.repoSlug);
+        const qs = args.ref ? `?at=${encodeURIComponent(args.ref)}` : '';
+        const encodedPath = args.path.split('/').map(encodeURIComponent).join('/');
+        const content = await this.requestText(`/projects/${projectKey}/repos/${repoSlug}/raw/${encodedPath}${qs}`);
+        const MAX_CHARS = 10000;
+        if (content.length > MAX_CHARS) {
+            return text(content.slice(0, MAX_CHARS) + `\n\n... (truncated, ${content.length - MAX_CHARS} more chars)`);
+        }
+        return text(content);
+    }
+    async getPrComments(args) {
+        const { projectKey, repoSlug } = this.resolveProjectAndRepo(args.projectKey, args.repoSlug);
+        const { limit = 50, start = 0, state = 'OPEN' } = args;
+        const qs = new URLSearchParams({ limit: String(limit), start: String(start) });
+        qs.set('state', state);
+        const data = await this.request('GET', `/projects/${projectKey}/repos/${repoSlug}/pull-requests/${args.prId}/comments?${qs}`);
+        if (!data || data.values.length === 0) {
+            return text(`No ${state} comments on PR #${args.prId}.`);
+        }
+        const blocks = data.values.flatMap((comment) => formatCommentThread(comment));
+        return text(`${data.values.length} comment thread(s) on PR #${args.prId}${pageHint(data)}:\n\n${blocks.join('\n\n')}`);
+    }
+    async addPrComment(args) {
+        const { projectKey, repoSlug } = this.resolveProjectAndRepo(args.projectKey, args.repoSlug);
+        const body = { text: args.text };
+        if (args.parentCommentId)
+            body.parent = { id: args.parentCommentId };
+        const created = await this.request('POST', `/projects/${projectKey}/repos/${repoSlug}/pull-requests/${args.prId}/comments`, body);
+        if (!created)
+            return text(`Comment added to PR #${args.prId}.`);
+        if (args.parentCommentId) {
+            return text(`Reply #${created.id} added to comment #${args.parentCommentId} on PR #${args.prId}.`);
+        }
+        return text(`Comment #${created.id} added to PR #${args.prId}.`);
+    }
+    async updatePrComment(args) {
+        const { projectKey, repoSlug } = this.resolveProjectAndRepo(args.projectKey, args.repoSlug);
+        if (!args.text && !args.state && !args.severity) {
+            throw new Error('At least one field is required: text, state, or severity');
+        }
+        const current = await this.request('GET', `/projects/${projectKey}/repos/${repoSlug}/pull-requests/${args.prId}/comments/${args.commentId}`);
+        if (!current)
+            throw new Error(`Comment #${args.commentId} not found.`);
+        const body = {
+            version: current.version,
+            text: args.text ?? current.text,
+        };
+        if (args.state)
+            body.state = args.state;
+        if (args.severity)
+            body.severity = args.severity;
+        const updated = await this.request('PUT', `/projects/${projectKey}/repos/${repoSlug}/pull-requests/${args.prId}/comments/${args.commentId}`, body);
+        if (!updated)
+            return text(`Comment #${args.commentId} updated.`);
+        const state = updated.state ?? current.state ?? 'OPEN';
+        const severity = updated.severity ?? current.severity ?? 'NORMAL';
+        return text(`Comment #${updated.id} updated (${state}/${severity}).`);
+    }
+    async deletePrComment(args) {
+        const { projectKey, repoSlug } = this.resolveProjectAndRepo(args.projectKey, args.repoSlug);
+        const current = await this.request('GET', `/projects/${projectKey}/repos/${repoSlug}/pull-requests/${args.prId}/comments/${args.commentId}`);
+        if (!current)
+            throw new Error(`Comment #${args.commentId} not found.`);
+        const path = `/projects/${projectKey}/repos/${repoSlug}/pull-requests/${args.prId}/comments/${args.commentId}?version=${current.version}`;
+        await this.request('DELETE', path);
+        return text(`Comment #${args.commentId} deleted from PR #${args.prId}.`);
+    }
+}