@hanhnd/agent-kit 1.0.43 → 1.0.44

package/dist/mcp/integration.js

@@ -1,6 +1,6 @@
 /**
  * Integration Tools - Bitbucket, Jira, Confluence
- * Tools: kit_get_bitbucket_pr, kit_jira_get_ticket, kit_confluence_get_page
+ * Tools: kit_get_bitbucket_pr, kit_create_bitbucket_pr, kit_find_bitbucket_reviewers, kit_get_bitbucket_pr_comments, kit_jira_get_ticket, kit_confluence_get_page
  */
 import { writeFileSync } from 'fs';
 import { z } from 'zod';
@@ -8,7 +8,7 @@ import { getCredential } from '../services/integration/credentials.js';
 import { mcpText } from '../utils/utils.js';
 import { adfToMarkdown } from '../services/integration/parser/adf.js';
 import { storageToMarkdown } from '../services/integration/parser/storage.js';
-import { sanitize, sanitizeOutput } from '../core/security/index.js';
+import { sanitizeOutput } from '../core/security/index.js';
 /**
  * Payload size (chars) at or above which a body is spilled to a temp file
  * instead of inlined into the agent context.
@@ -24,6 +24,56 @@ const BitbucketPrSchema = z.object({
     source: z.object({ branch: z.object({ name: z.string() }) }),
     destination: z.object({ branch: z.object({ name: z.string() }) }),
 });
+// Response of POST /pullrequests (201). Permissive beyond what the output renders.
+const BitbucketCreatedPrSchema = z.object({
+    id: z.number(),
+    title: z.string(),
+    state: z.string().optional(),
+    draft: z.boolean().optional(),
+    source: z.object({ branch: z.object({ name: z.string() }) }).optional(),
+    destination: z.object({ branch: z.object({ name: z.string() }) }).optional(),
+    reviewers: z.array(z.object({ display_name: z.string().optional() }).passthrough()).optional(),
+    links: z
+        .object({ html: z.object({ href: z.string() }).optional() })
+        .passthrough()
+        .optional(),
+});
+const BitbucketCommentSchema = z
+    .object({
+    id: z.number(),
+    created_on: z.string().optional(),
+    updated_on: z.string().optional(),
+    content: z.object({ raw: z.string().nullable().optional() }).passthrough().optional(),
+    user: z.object({ display_name: z.string().optional() }).passthrough().nullable().optional(),
+    deleted: z.boolean().optional(),
+    pending: z.boolean().optional(),
+    parent: z.object({ id: z.number() }).passthrough().nullable().optional(),
+    inline: z
+        .object({
+        path: z.string(),
+        from: z.number().nullable().optional(),
+        to: z.number().nullable().optional(),
+        start_from: z.number().nullable().optional(),
+        start_to: z.number().nullable().optional(),
+    })
+        .passthrough()
+        .nullable()
+        .optional(),
+    resolution: z
+        .object({
+        type: z.string().optional(),
+        user: z.object({ display_name: z.string().optional() }).passthrough().nullable().optional(),
+        created_on: z.string().optional(),
+    })
+        .passthrough()
+        .nullable()
+        .optional(),
+})
+    .passthrough();
+const BitbucketCommentPageSchema = z.object({
+    values: z.array(BitbucketCommentSchema),
+    next: z.string().optional(),
+});
 // MEDIUM 2: Jira ticket schema for runtime validation
 // ADF (Atlassian Document Format) can have many nested content types
 // We use a more permissive schema that accepts any ADF structure
@@ -89,6 +139,32 @@ const ConfluencePageSchema = z.object({
         .optional(),
     _links: z.object({ base: z.string().optional(), webui: z.string().optional() }).passthrough().optional(),
 });
+/**
+ * API token scopes each tool needs, from Atlassian's OpenAPI specs (`x-atlassian-oauth2-scopes`).
+ * Used for 401/403 hints; mcp/README.md lists the same scopes for setup.
+ */
+export const REQUIRED_SCOPES = {
+    // The PR diff endpoint redirects to the repository diff, which needs read:repository.
+    kit_get_bitbucket_pr: ['read:pullrequest:bitbucket', 'read:repository:bitbucket'],
+    kit_get_bitbucket_pr_comments: ['read:pullrequest:bitbucket'],
+    // read:workspace resolves reviewer names; read:user skips the author (optional — degrades, never fails).
+    kit_create_bitbucket_pr: [
+        'read:pullrequest:bitbucket',
+        'write:pullrequest:bitbucket',
+        'read:workspace:bitbucket',
+        'read:user:bitbucket',
+    ],
+    kit_find_bitbucket_reviewers: ['read:workspace:bitbucket', 'read:user:bitbucket'],
+    kit_jira_get_ticket: ['read:jira-work'],
+    kit_confluence_get_page: ['read:page:confluence'],
+};
+/** Error text for a tool, with its required scopes appended on 401/403 unless a scope is already named. */
+function errorText(error, tool) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (!/\((401|403)\)/.test(message) || message.includes(':bitbucket') || message.includes('scope'))
+        return message;
+    return `${message}\n\nCheck the API token has these scopes: ${REQUIRED_SCOPES[tool].join(', ')}.`;
+}
 function buildBasicAuth(emailVar, tokenVar) {
     const email = getCredential(emailVar);
     const token = getCredential(tokenVar);
@@ -110,8 +186,15 @@ export function buildAtlassianContext(product) {
         throw new Error('Missing ATLASSIAN_CLOUD_ID');
     return { auth: buildBasicAuth('ATLASSIAN_USER_EMAIL', PRODUCT_TOKEN_KEY[product]), cloudId };
 }
-async function callRestApi(url, auth, accept = 'application/json') {
-    const resp = await fetch(url, { headers: { Authorization: auth, Accept: accept } });
+async function callRestApi(url, auth, accept = 'application/json', body) {
+    const headers = { Authorization: auth, Accept: accept };
+    const init = { headers };
+    if (body !== undefined) {
+        init.method = 'POST';
+        headers['Content-Type'] = 'application/json';
+        init.body = JSON.stringify(body);
+    }
+    const resp = await fetch(url, init);
     if (resp.status === 401)
         throw new Error(`❌ Auth failed (401): ${url}`);
     if (resp.status === 403)
@@ -119,9 +202,27 @@ async function callRestApi(url, auth, accept = 'application/json') {
     if (resp.status === 404)
         throw new Error(`❌ Not found: ${url}`);
     if (!resp.ok)
-        throw new Error(`❌ API error ${resp.status}: ${await resp.text()}`);
+        throw new Error(`❌ API error ${resp.status}: ${extractApiError(await resp.text())}`);
     return accept === 'text/plain' ? resp.text() : resp.json();
 }
+/** Bitbucket errors arrive as `{ type: 'error', error: { message, detail?, fields? } }`; surface the readable parts. */
+function extractApiError(text) {
+    try {
+        const err = JSON.parse(text).error;
+        if (err && typeof err.message === 'string') {
+            const parts = [err.message];
+            if (typeof err.detail === 'string' && err.detail)
+                parts.push(err.detail);
+            if (err.fields && typeof err.fields === 'object')
+                parts.push(JSON.stringify(err.fields));
+            return parts.join('\n');
+        }
+    }
+    catch {
+        // Not JSON — fall through to the raw body.
+    }
+    return text;
+}
 const CONFLUENCE_INPUT_FORMS = [
     'Accepted input forms:',
     '  • https://<site>.atlassian.net/wiki/spaces/<SPACEKEY>/pages/<pageId>/<Title>',
@@ -221,7 +322,434 @@ ${labels.length > 0 ? labels.join(', ') : 'None'}`;
         return mcpText(sanitizeOutput(output));
     }
     catch (error) {
-        return mcpText(`Error: ${error instanceof Error ? error.message : String(error)}`);
+        return mcpText(`Error: ${errorText(error, 'kit_confluence_get_page')}`);
+    }
+}
+const BITBUCKET_API = 'https://api.bitbucket.org/2.0';
+// Dot-only slugs ("." / "..") would let the request path climb out of /repositories/.
+const BITBUCKET_SLUG = /^(?!\.+$)[A-Za-z0-9._-]+$/;
+/** Safety cap on followed pagination pages (100 items each). */
+export const MAX_PAGES = 20;
+const MISSING_WORKSPACE = `❌ workspace is required. Pass it as a parameter or set BITBUCKET_DEFAULT_WORKSPACE in your MCP env config.`;
+function checkSlugs(ws, repo) {
+    if (!BITBUCKET_SLUG.test(ws))
+        return `❌ Invalid workspace slug: ${ws}`;
+    if (!BITBUCKET_SLUG.test(repo))
+        return `❌ Invalid repo slug: ${repo}`;
+    return undefined;
+}
+/** Resolve a PR URL, or a numeric PR id plus workspace/repoSlug, to its coordinates. */
+export function resolveBitbucketPr(input, workspace, repoSlug) {
+    const trimmed = input.trim();
+    let ws;
+    let repo;
+    let prId;
+    const urlMatch = trimmed.match(/bitbucket\.org\/([^/]+)\/([^/]+)\/pull-requests\/(\d+)/);
+    if (urlMatch) {
+        ws = urlMatch[1];
+        repo = urlMatch[2];
+        prId = parseInt(urlMatch[3], 10);
+    }
+    else if (/^\d+$/.test(trimmed)) {
+        prId = parseInt(trimmed, 10);
+        ws = workspace || getCredential('BITBUCKET_DEFAULT_WORKSPACE');
+        repo = repoSlug;
+    }
+    if (!ws)
+        return { ok: false, error: MISSING_WORKSPACE };
+    if (!repo || !prId) {
+        return { ok: false, error: `❌ Could not parse PR URL. Expected: bitbucket.org/{ws}/{repo}/pull-requests/{id}` };
+    }
+    const slugError = checkSlugs(ws, repo);
+    if (slugError)
+        return { ok: false, error: slugError };
+    return { ok: true, ws, repo, prId };
+}
+/** Resolve a repo URL, `workspace/repo`, or a bare repo slug (plus workspace or default) to its coordinates. */
+export function resolveBitbucketRepo(repository, workspace) {
+    const trimmed = repository.trim().replace(/\.git$/, '');
+    let ws;
+    let repo;
+    const urlMatch = trimmed.match(/bitbucket\.org[/:]([^/]+)\/([^/?#]+)/);
+    const pairMatch = trimmed.match(/^([^/]+)\/([^/]+)$/);
+    if (urlMatch) {
+        ws = urlMatch[1];
+        repo = urlMatch[2];
+    }
+    else if (pairMatch) {
+        ws = pairMatch[1];
+        repo = pairMatch[2];
+    }
+    else if (trimmed) {
+        ws = workspace || getCredential('BITBUCKET_DEFAULT_WORKSPACE');
+        repo = trimmed;
+    }
+    if (!repo) {
+        return { ok: false, error: `❌ repository is required: a Bitbucket repo URL, "workspace/repo", or a repo slug.` };
+    }
+    if (!ws)
+        return { ok: false, error: MISSING_WORKSPACE };
+    const slugError = checkSlugs(ws, repo);
+    if (slugError)
+        return { ok: false, error: slugError };
+    return { ok: true, ws, repo };
+}
+/** Bitbucket expects reviewer UUIDs wrapped in braces: `{xxxxxxxx-...}`. */
+function normalizeReviewerUuid(raw) {
+    const bare = raw.trim().replace(/^\{|\}$/g, '');
+    return /^[0-9a-fA-F-]{36}$/.test(bare) ? `{${bare}}` : undefined;
+}
+const BitbucketMembersPageSchema = z.object({
+    values: z.array(z
+        .object({
+        user: z
+            .object({ uuid: z.string(), display_name: z.string().optional(), nickname: z.string().optional() })
+            .passthrough(),
+    })
+        .passthrough()),
+    next: z.string().optional(),
+});
+/** Lowercase and strip diacritics so "Dũng" matches "Dung" and "Đức" matches "Duc". */
+export function normalizeName(value) {
+    return value.normalize('NFD').replace(/\p{M}/gu, '').replace(/đ/gi, 'd').toLowerCase().replace(/\s+/g, ' ').trim();
+}
+function nameTokens(value) {
+    return normalizeName(value)
+        .split(/[^\p{L}\p{N}]+/u)
+        .filter(Boolean);
+}
+/**
+ * Match reviewer queries against workspace members. A query matches a member by exact
+ * display name / nickname first; failing that, when every word of the query is a whole
+ * word of the member's name ("Dung" → "Nguyen Tien Dung"). More than one hit is ambiguous —
+ * never guessed. UUID queries must be resolved by the caller before this runs.
+ */
+export function matchReviewers(queries, members) {
+    const result = { resolved: [], ambiguous: [], unmatched: [] };
+    for (const query of queries) {
+        const q = normalizeName(query);
+        const qTokens = nameTokens(query);
+        if (qTokens.length === 0)
+            continue;
+        let hits = members.filter((m) => normalizeName(m.displayName) === q || (m.nickname !== undefined && normalizeName(m.nickname) === q));
+        if (hits.length === 0) {
+            hits = members.filter((m) => {
+                const words = new Set([...nameTokens(m.displayName), ...nameTokens(m.nickname ?? '')]);
+                return qTokens.every((t) => words.has(t));
+            });
+        }
+        if (hits.length === 1)
+            result.resolved.push({ query, member: hits[0] });
+        else if (hits.length > 1)
+            result.ambiguous.push({ query, candidates: hits });
+        else
+            result.unmatched.push(query);
+    }
+    return result;
+}
+async function fetchWorkspaceMembers(ws, auth) {
+    let url = `${BITBUCKET_API}/workspaces/${ws}/members?pagelen=100`;
+    const members = [];
+    let pages = 0;
+    while (url && pages < MAX_PAGES) {
+        let data;
+        try {
+            data = await callRestApi(url, auth);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`${message}\n\nLooking up reviewers by name lists workspace members — the API token needs the read:workspace:bitbucket scope.`);
+        }
+        const parseResult = BitbucketMembersPageSchema.safeParse(data);
+        if (!parseResult.success)
+            throw new Error(`❌ Invalid workspace members response: ${parseResult.error.message}`);
+        for (const { user } of parseResult.data.values) {
+            members.push({ uuid: user.uuid, displayName: user.display_name ?? '', nickname: user.nickname });
+        }
+        pages++;
+        url = parseResult.data.next?.startsWith(`${BITBUCKET_API}/`) ? parseResult.data.next : undefined;
+    }
+    return members;
+}
+/** UUID of the token owner, or undefined when the token lacks read:user:bitbucket. */
+async function fetchCurrentUserUuid(auth) {
+    try {
+        const data = (await callRestApi(`${BITBUCKET_API}/user`, auth));
+        return typeof data.uuid === 'string' ? data.uuid : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Resolve names, nicknames or UUIDs to workspace members. Members are fetched only when a name is given. */
+async function lookupReviewers(ws, auth, queries) {
+    const byUuid = [];
+    const names = [];
+    for (const query of queries) {
+        const uuid = normalizeReviewerUuid(query);
+        if (uuid)
+            byUuid.push({ uuid, displayName: uuid });
+        else if (query.trim())
+            names.push(query);
+    }
+    const [members, selfUuid] = await Promise.all([
+        names.length > 0 ? fetchWorkspaceMembers(ws, auth) : Promise.resolve([]),
+        fetchCurrentUserUuid(auth),
+    ]);
+    const match = matchReviewers(names, members);
+    const seen = new Set();
+    const reviewers = [];
+    let skippedSelf = false;
+    for (const member of [...byUuid, ...match.resolved.map((r) => r.member)]) {
+        const key = member.uuid.toLowerCase();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        if (selfUuid && key === selfUuid.toLowerCase()) {
+            skippedSelf = true;
+            continue;
+        }
+        reviewers.push(member);
+    }
+    return { reviewers, skippedSelf, ambiguous: match.ambiguous, unmatched: match.unmatched };
+}
+function describeMember(member) {
+    return `${member.displayName}${member.nickname ? ` (@${member.nickname})` : ''} ${member.uuid}`;
+}
+/** Markdown lines for names that did not resolve to exactly one member. */
+function describeReviewerProblems(lookup) {
+    const lines = [];
+    for (const { query, candidates } of lookup.ambiguous) {
+        lines.push(`- ❓ "${query}" matches ${candidates.length} members — use a fuller name or a UUID:`);
+        for (const candidate of candidates.slice(0, 10))
+            lines.push(`  - ${describeMember(candidate)}`);
+        if (candidates.length > 10)
+            lines.push(`  - …and ${candidates.length - 10} more`);
+    }
+    for (const query of lookup.unmatched)
+        lines.push(`- ❌ "${query}" matches no workspace member`);
+    return lines;
+}
+/**
+ * Handler for kit_find_bitbucket_reviewers: dry-run of the reviewer resolution that
+ * kit_create_bitbucket_pr performs, so callers can verify names before pushing anything.
+ * Never rejects — every failure path resolves to an actionable mcpText message.
+ */
+export async function handleFindBitbucketReviewers(args) {
+    try {
+        const ws = args.workspace?.trim() || getCredential('BITBUCKET_DEFAULT_WORKSPACE');
+        if (!ws)
+            return mcpText(MISSING_WORKSPACE);
+        if (!BITBUCKET_SLUG.test(ws))
+            return mcpText(`❌ Invalid workspace slug: ${ws}`);
+        if (args.names.every((name) => !name.trim()))
+            return mcpText('❌ names is required.');
+        const auth = buildBasicAuth('BITBUCKET_USER_EMAIL', 'BITBUCKET_API_TOKEN');
+        const lookup = await lookupReviewers(ws, auth, args.names);
+        const lines = [`## Reviewer lookup (${ws})`];
+        for (const member of lookup.reviewers)
+            lines.push(`- ✅ ${describeMember(member)}`);
+        if (lookup.skippedSelf)
+            lines.push('- ⏭️ You (the PR author) were named — skipped, Bitbucket rejects self-review');
+        lines.push(...describeReviewerProblems(lookup));
+        return mcpText(lines.join('\n'));
+    }
+    catch (error) {
+        return mcpText(errorText(error, 'kit_find_bitbucket_reviewers'));
+    }
+}
+/**
+ * Handler for kit_create_bitbucket_pr. Exported so it is unit testable without a transport.
+ * Never rejects — every failure path resolves to an actionable mcpText message.
+ */
+export async function handleCreateBitbucketPr(args) {
+    try {
+        const ref = resolveBitbucketRepo(args.repository, args.workspace);
+        if (!ref.ok)
+            return mcpText(ref.error);
+        const title = args.title.trim();
+        const sourceBranch = args.sourceBranch.trim();
+        if (!title)
+            return mcpText('❌ title is required.');
+        if (!sourceBranch)
+            return mcpText('❌ sourceBranch is required.');
+        const auth = buildBasicAuth('BITBUCKET_USER_EMAIL', 'BITBUCKET_API_TOKEN');
+        // Resolve every reviewer before creating anything: one bad name aborts with no PR made.
+        let reviewerUuids = [];
+        let skippedSelf = false;
+        if (args.reviewers && args.reviewers.some((r) => r.trim())) {
+            const lookup = await lookupReviewers(ref.ws, auth, args.reviewers);
+            const problems = describeReviewerProblems(lookup);
+            if (problems.length > 0) {
+                return mcpText(`❌ PR not created — some reviewers did not resolve to exactly one member:\n${problems.join('\n')}`);
+            }
+            reviewerUuids = lookup.reviewers.map((member) => member.uuid);
+            skippedSelf = lookup.skippedSelf;
+        }
+        // Omitted destination defaults to the repository's main branch (Bitbucket behaviour).
+        const body = { title, source: { branch: { name: sourceBranch } } };
+        const destinationBranch = args.destinationBranch?.trim();
+        if (destinationBranch)
+            body.destination = { branch: { name: destinationBranch } };
+        if (args.description)
+            body.description = args.description;
+        if (args.closeSourceBranch !== undefined)
+            body.close_source_branch = args.closeSourceBranch;
+        if (args.draft !== undefined)
+            body.draft = args.draft;
+        if (reviewerUuids.length > 0)
+            body.reviewers = reviewerUuids.map((uuid) => ({ uuid }));
+        const url = `${BITBUCKET_API}/repositories/${ref.ws}/${ref.repo}/pullrequests`;
+        const jsonData = await callRestApi(url, auth, 'application/json', body);
+        const parseResult = BitbucketCreatedPrSchema.safeParse(jsonData);
+        if (!parseResult.success) {
+            return mcpText(`⚠️ PR was likely created, but the response could not be parsed: ${parseResult.error.message}`);
+        }
+        const pr = parseResult.data;
+        const reviewers = pr.reviewers?.map((r) => r.display_name).filter(Boolean) ?? [];
+        const lines = [
+            `✅ Created PR #${pr.id}: ${pr.title}`,
+            `**URL:** ${pr.links?.html?.href ?? `https://bitbucket.org/${ref.ws}/${ref.repo}/pull-requests/${pr.id}`}`,
+            `**Branch:** ${pr.source?.branch.name ?? sourceBranch} → ${pr.destination?.branch.name ?? destinationBranch ?? '(main branch)'}`,
+            `**State:** ${pr.state ?? 'OPEN'}${pr.draft ? ' (draft)' : ''}`,
+        ];
+        if (reviewers.length > 0)
+            lines.push(`**Reviewers:** ${reviewers.join(', ')}`);
+        if (skippedSelf)
+            lines.push('⏭️ You (the PR author) were named as a reviewer — skipped, Bitbucket rejects self-review.');
+        return mcpText(lines.join('\n'));
+    }
+    catch (error) {
+        return mcpText(errorText(error, 'kit_create_bitbucket_pr'));
+    }
+}
+function describeInlineAnchor(inline) {
+    if (inline.to) {
+        return inline.start_to && inline.start_to !== inline.to
+            ? `lines ${inline.start_to}–${inline.to}`
+            : `line ${inline.to}`;
+    }
+    if (inline.from) {
+        return inline.start_from && inline.start_from !== inline.from
+            ? `old lines ${inline.start_from}–${inline.from}`
+            : `old line ${inline.from}`;
+    }
+    return 'file';
+}
+function renderComment(comment, depth, isRoot) {
+    const indent = '  '.repeat(depth);
+    const meta = [`#${comment.id}`, comment.user?.display_name || 'Unknown', comment.created_on?.slice(0, 10) ?? ''];
+    if (isRoot && comment.inline)
+        meta.push(describeInlineAnchor(comment.inline));
+    if (comment.pending)
+        meta.push('pending (unpublished)');
+    if (isRoot) {
+        meta.push(comment.resolution
+            ? `✅ resolved${comment.resolution.user?.display_name ? ` by ${comment.resolution.user.display_name}` : ''}`
+            : '🟡 open');
+    }
+    const header = `${indent}${depth > 0 ? '↳ ' : '- '}**${meta.filter(Boolean).join(' · ')}**`;
+    const raw = comment.deleted ? '_(deleted)_' : comment.content?.raw?.trim() || '_(empty)_';
+    const body = raw
+        .split('\n')
+        .map((line) => `${indent}  > ${line}`)
+        .join('\n');
+    return `${header}\n${body}`;
+}
+/**
+ * Handler for kit_get_bitbucket_pr_comments. Follows `next` links (pagelen=100) up to
+ * MAX_PAGES, then renders threads: general comments first, inline ones grouped by file.
+ * Never rejects — every failure path resolves to an actionable mcpText message.
+ */
+export async function handleGetBitbucketPrComments(args) {
+    try {
+        const ref = resolveBitbucketPr(args.input, args.workspace, args.repoSlug);
+        if (!ref.ok)
+            return mcpText(ref.error);
+        const includeResolved = args.includeResolved ?? true;
+        const includeDeleted = args.includeDeleted ?? false;
+        const auth = buildBasicAuth('BITBUCKET_USER_EMAIL', 'BITBUCKET_API_TOKEN');
+        let url = `${BITBUCKET_API}/repositories/${ref.ws}/${ref.repo}/pullrequests/${ref.prId}/comments?pagelen=100`;
+        const comments = [];
+        let pages = 0;
+        while (url && pages < MAX_PAGES) {
+            const parseResult = BitbucketCommentPageSchema.safeParse(await callRestApi(url, auth));
+            if (!parseResult.success) {
+                return mcpText(`❌ Invalid Bitbucket comments response: ${parseResult.error.message}`);
+            }
+            comments.push(...parseResult.data.values);
+            pages++;
+            // Never forward credentials to a host other than the Bitbucket API.
+            url = parseResult.data.next?.startsWith(`${BITBUCKET_API}/`) ? parseResult.data.next : undefined;
+        }
+        const truncated = Boolean(url);
+        const byId = new Map(comments.map((c) => [c.id, c]));
+        const children = new Map();
+        const roots = [];
+        for (const comment of comments) {
+            const parentId = comment.parent?.id;
+            // A reply whose parent was not returned is promoted to a root so it is never lost.
+            if (parentId !== undefined && byId.has(parentId)) {
+                children.set(parentId, [...(children.get(parentId) ?? []), comment]);
+            }
+            else {
+                roots.push(comment);
+            }
+        }
+        const renderThread = (comment, depth) => {
+            const replies = (children.get(comment.id) ?? []).flatMap((child) => renderThread(child, depth + 1));
+            // Skip a deleted comment unless asked, but keep it as a stub when live replies hang off it.
+            if (comment.deleted && !includeDeleted && replies.length === 0)
+                return [];
+            return [renderComment(comment, depth, depth === 0), ...replies];
+        };
+        const visibleRoots = roots.filter((root) => includeResolved || !root.resolution);
+        const general = [];
+        const inlineByFile = new Map();
+        for (const root of visibleRoots) {
+            const rendered = renderThread(root, 0);
+            if (rendered.length === 0)
+                continue;
+            if (root.inline) {
+                inlineByFile.set(root.inline.path, [...(inlineByFile.get(root.inline.path) ?? []), ...rendered]);
+            }
+            else {
+                general.push(...rendered);
+            }
+        }
+        const liveRoots = roots.filter((root) => !root.deleted);
+        const unresolved = liveRoots.filter((root) => !root.resolution).length;
+        const summary = `${comments.length} comments in ${liveRoots.length} threads · ${unresolved} open · ${liveRoots.length - unresolved} resolved`;
+        let output = `## PR #${ref.prId} comments\n${summary}${includeResolved ? '' : ' (resolved threads hidden)'}`;
+        if (truncated) {
+            output += `\n\n⚠️ Stopped after ${MAX_PAGES} pages (${comments.length} comments); later comments are not shown.`;
+        }
+        if (general.length === 0 && inlineByFile.size === 0) {
+            output += '\n\nNo comments to show.';
+        }
+        else {
+            if (general.length > 0)
+                output += `\n\n### General\n${general.join('\n')}`;
+            if (inlineByFile.size > 0) {
+                output += '\n\n### Inline';
+                for (const [path, rendered] of inlineByFile)
+                    output += `\n\n#### \`${path}\`\n${rendered.join('\n')}`;
+            }
+        }
+        if (output.length >= LARGE_PAYLOAD_THRESHOLD) {
+            const filePath = `/tmp/kit-pr-${ref.prId}-comments-${Date.now()}.md`;
+            try {
+                writeFileSync(filePath, sanitizeOutput(output), 'utf8');
+                return mcpText(`## PR #${ref.prId} comments\n${summary}\n\nComments are large (${output.length} chars). Full markdown written to: \`${filePath}\`. Read this file before proceeding.`);
+            }
+            catch {
+                // Fall through and inline.
+            }
+        }
+        return mcpText(sanitizeOutput(output));
+    }
+    catch (error) {
+        return mcpText(errorText(error, 'kit_get_bitbucket_pr_comments'));
     }
 }
 export function registerIntegrationTools(server) {
@@ -241,28 +769,10 @@ export function registerIntegrationTools(server) {
         annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
     }, async ({ input, workspace, repoSlug, includeDiff }) => {
         try {
-            let ws;
-            let repo;
-            let prId;
-            const urlMatch = input.match(/bitbucket\.org\/([^/]+)\/([^/]+)\/pull-requests\/(\d+)/);
-            if (urlMatch) {
-                ws = urlMatch[1];
-                repo = urlMatch[2];
-                prId = parseInt(urlMatch[3], 10);
-            }
-            else if (input.match(/^\d+$/)) {
-                prId = parseInt(input, 10);
-                ws = workspace || getCredential('BITBUCKET_DEFAULT_WORKSPACE');
-                repo = repoSlug;
-            }
-            if (!ws) {
-                return mcpText(`❌ workspace is required. Pass it as a parameter or set BITBUCKET_DEFAULT_WORKSPACE in your MCP env config.`);
-            }
-            if (!repo || !prId) {
-                return mcpText(`❌ Could not parse PR URL. Expected: bitbucket.org/{ws}/{repo}/pull-requests/{id}`);
-            }
-            const safeWs = sanitize(ws);
-            const safeRepo = sanitize(repo);
+            const ref = resolveBitbucketPr(input, workspace, repoSlug);
+            if (!ref.ok)
+                return mcpText(ref.error);
+            const { ws: safeWs, repo: safeRepo, prId } = ref;
             const auth = buildBasicAuth('BITBUCKET_USER_EMAIL', 'BITBUCKET_API_TOKEN');
             const prUrl = `https://api.bitbucket.org/2.0/repositories/${safeWs}/${safeRepo}/pullrequests/${prId}`;
             const jsonData = await callRestApi(prUrl, auth);
@@ -297,9 +807,57 @@ ${pr.description || 'No description'}`;
             return mcpText(output);
         }
         catch (error) {
-            return mcpText(error instanceof Error ? error.message : String(error));
+            return mcpText(errorText(error, 'kit_get_bitbucket_pr'));
         }
     });
+    // TOOL: CREATE BITBUCKET PR
+    server.registerTool('kit_create_bitbucket_pr', {
+        title: 'Create Bitbucket PR',
+        description: 'Create a Bitbucket Cloud pull request from an already-pushed source branch. If destinationBranch is omitted, Bitbucket targets the repository main branch. Returns the new PR id and URL.',
+        inputSchema: {
+            repository: z
+                .string()
+                .describe('Bitbucket repo URL, "workspace/repo", or a repo slug (uses workspace / BITBUCKET_DEFAULT_WORKSPACE)'),
+            workspace: z.string().optional().describe('Bitbucket workspace slug, used when repository is a bare slug'),
+            title: z.string().describe('PR title'),
+            sourceBranch: z.string().describe('Source branch name (must already exist on the remote)'),
+            destinationBranch: z.string().optional().describe('Destination branch name; defaults to the repo main branch'),
+            description: z.string().optional().describe('PR description (markdown)'),
+            closeSourceBranch: z.boolean().optional().describe('Close the source branch when the PR is merged'),
+            draft: z.boolean().optional().describe('Create the PR as a draft'),
+            reviewers: z
+                .array(z.string())
+                .optional()
+                .describe('Reviewers as names, nicknames or account UUIDs, e.g. ["Dien", "Nguyen Tien Dung"]. Matching is case- and accent-insensitive; a name that matches no member or several aborts with no PR created. The PR author is skipped.'),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    }, async (args) => handleCreateBitbucketPr(args));
+    // TOOL: FIND BITBUCKET REVIEWERS
+    server.registerTool('kit_find_bitbucket_reviewers', {
+        title: 'Find Bitbucket Reviewers',
+        description: 'Resolve reviewer names, nicknames or UUIDs to Bitbucket workspace members — the same matching kit_create_bitbucket_pr uses. Reports matched, ambiguous (with candidates) and unknown names, so reviewers can be verified before pushing or creating a PR.',
+        inputSchema: {
+            names: z.array(z.string()).describe('Names, nicknames or account UUIDs, e.g. ["Dien", "Dung"]'),
+            workspace: z.string().optional().describe('Bitbucket workspace slug (defaults to BITBUCKET_DEFAULT_WORKSPACE)'),
+        },
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+    }, async (args) => handleFindBitbucketReviewers(args));
+    // TOOL: GET BITBUCKET PR COMMENTS
+    server.registerTool('kit_get_bitbucket_pr_comments', {
+        title: 'Get Bitbucket PR Comments',
+        description: 'Get all comments on a Bitbucket PR as threads: general comments, then inline comments grouped by file with line anchors and resolved/open status. Accepts a full PR URL or a numeric PR ID with workspace + repoSlug.',
+        inputSchema: {
+            input: z.string().describe('Bitbucket PR URL or numeric PR ID'),
+            workspace: z
+                .string()
+                .optional()
+                .describe('Bitbucket workspace slug (required for numeric ID if BITBUCKET_DEFAULT_WORKSPACE not set)'),
+            repoSlug: z.string().optional().describe('Bitbucket repo slug (required for numeric ID)'),
+            includeResolved: z.boolean().optional().default(true).describe('Include resolved threads'),
+            includeDeleted: z.boolean().optional().default(false).describe('Include deleted comments'),
+        },
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+    }, async (args) => handleGetBitbucketPrComments(args));
     // TOOL: JIRA GET TICKET
     server.registerTool('kit_jira_get_ticket', {
         title: 'Get Jira Ticket',
@@ -341,7 +899,7 @@ ${ticket.fields.labels?.join(', ') || 'None'}`;
             return mcpText(output);
         }
         catch (error) {
-            return mcpText(`Error: ${error instanceof Error ? error.message : String(error)}`);
+            return mcpText(`Error: ${errorText(error, 'kit_jira_get_ticket')}`);
         }
     });
     // TOOL: CONFLUENCE GET PAGE