@stubbedev/atlassian-mcp 0.2.10 → 0.2.12

package/dist/bitbucket.js

@@ -340,6 +340,55 @@ export class BitbucketClient {
         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 searchUsers(args) {
+        const params = new URLSearchParams();
+        if (args.query)
+            params.set('filter', args.query);
+        params.set('limit', String(args.limit ?? 25));
+        if (args.start)
+            params.set('start', String(args.start));
+        let path;
+        if (args.projectKey && args.repoSlug) {
+            path = `${this.rp(args.projectKey, args.repoSlug)}/permissions/users?${params}`;
+        }
+        else if (args.projectKey) {
+            path = `/projects/${encodeURIComponent(args.projectKey)}/permissions/users?${params}`;
+        }
+        else {
+            path = `/users?${params}`;
+        }
+        const data = await this.request('GET', path);
+        if (!data || data.values.length === 0)
+            return text('No users found.');
+        const lines = data.values.map((entry, i) => {
+            const user = entry.user ?? entry;
+            const parts = [`${i + 1}. ${user.displayName} (${user.name})`];
+            if (user.emailAddress)
+                parts.push(`— ${user.emailAddress}`);
+            if (user.active === false)
+                parts.push('[inactive]');
+            return parts.join(' ');
+        });
+        return text(`${data.values.length} user(s)${pageHint(data)}:\n${lines.join('\n')}`);
+    }
+    async searchUsersRaw(args) {
+        const params = new URLSearchParams();
+        if (args.query)
+            params.set('filter', args.query);
+        params.set('limit', String(args.limit ?? 50));
+        let path;
+        if (args.projectKey && args.repoSlug) {
+            path = `${this.rp(args.projectKey, args.repoSlug)}/permissions/users?${params}`;
+        }
+        else if (args.projectKey) {
+            path = `/projects/${encodeURIComponent(args.projectKey)}/permissions/users?${params}`;
+        }
+        else {
+            path = `/users?${params}`;
+        }
+        const data = await this.request('GET', path);
+        return (data?.values ?? []).map((entry) => entry.user ?? entry);
+    }
     async listPullRequests(args) {
         const { projectKey, repoSlug } = this.resolveProjectAndRepo(args.projectKey, args.repoSlug);
         const { state = 'OPEN', fromBranch, text: searchText, limit = 25, start = 0 } = args;
@@ -730,6 +779,16 @@ export class BitbucketClient {
         }
         return text(content);
     }
+    async fetchFileText(projectKey, repoSlug, filePath) {
+        try {
+            const encoded = filePath.split('/').map(encodeURIComponent).join('/');
+            const content = await this.requestText(`${this.rp(projectKey, repoSlug)}/raw/${encoded}`);
+            return content;
+        }
+        catch {
+            return null;
+        }
+    }
     async getPrComments(args) {
         const { projectKey, repoSlug } = this.resolveProjectAndRepo(args.projectKey, args.repoSlug);
         const limit = args.limit ?? 50;
@@ -972,7 +1031,7 @@ export class BitbucketClient {
         return text(`${data.values.length} task(s) on PR #${args.prId} (${open} open)${pageHint(data)}:\n${lines.join('\n')}`);
     }
     async mutatePrTask(args) {
-        const { projectKey, repoSlug } = this.resolveProjectAndRepo(args.projectKey, args.repoSlug);
+        this.resolveProjectAndRepo(args.projectKey, args.repoSlug);
         if (args.action === 'create') {
             if (!args.text)
                 throw new Error('text is required to create a task.');

package/dist/index.js

@@ -132,18 +132,18 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         ...(jira ? [
             {
                 name: 'start_work',
-                description: 'Start working on a Jira ticket: fetches the ticket, creates a local git branch with an auto-generated name (e.g. feature/FOO-123-add-payment-gateway), and optionally transitions the ticket. Use when told "make a branch for FOO-123", "start working on this ticket", "check out a branch for this issue", or "begin work on FOO-123".',
+                description: 'Start working on a Jira ticket end-to-end: resolves the ticket (by key or free-text search with a picker when multiple match), creates a local branch with an auto-generated name, fetches the project README from Bitbucket so you have commit/PR conventions in context, and prints a ready-to-use next-steps summary. Use when told "make a branch for FOO-123", "start working on this ticket", "I want to work on the login bug", or "begin work on the payment gateway story". If issueKey is omitted, provide query for free-text search.',
                 inputSchema: {
                     type: 'object',
                     properties: {
-                        issueKey: { type: 'string', description: 'Jira issue key, e.g. FOO-123' },
+                        issueKey: { type: 'string', description: 'Jira issue key, e.g. FOO-123 (provide this OR query)' },
+                        query: { type: 'string', description: 'Free-text search when issueKey is unknown — shows a picker if multiple tickets match' },
                         repoPath: { type: 'string', description: 'Local repo path (defaults to cwd)' },
                         baseBranch: { type: 'string', description: 'Branch to base off (default: master)' },
                         branchName: { type: 'string', description: 'Override the generated branch name' },
                         transitionName: { type: 'string', description: 'Jira transition to apply, e.g. "In Progress" (optional)' },
                         push: { type: 'boolean', description: 'Push branch to remote after creation (default false)', default: false },
                     },
-                    required: ['issueKey'],
                 },
             },
             {
@@ -263,17 +263,18 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         ] : []),
         ...(bitbucket ? [{
                 name: 'bitbucket_search',
-                description: 'Discover Bitbucket resources. Use when asked "what PRs are open?", "show me the repos", "find the PR for this branch", or "list branches". Set resource:\n• "pull_requests" (default) — list PRs by state/branch/text; mine=true for your inbox\n• "repos" — list repositories in a project\n• "branches" — list or filter branches in a repo',
+                description: 'Discover Bitbucket resources. Use when asked "what PRs are open?", "show me the repos", "find the PR for this branch", or "list branches". Set resource:\n• "pull_requests" (default) — list PRs by state/branch/text; mine=true for your inbox\n• "repos" — list repositories in a project\n• "branches" — list or filter branches in a repo\n• "users" — find users by name/email (pass query); add projectKey+repoSlug to restrict to users with repo access. ALWAYS use this to look up valid usernames before adding reviewers to a PR.',
                 inputSchema: {
                     type: 'object',
                     properties: {
-                        resource: { type: 'string', enum: ['pull_requests', 'repos', 'branches'], description: 'What to search (default: pull_requests)' },
+                        resource: { type: 'string', enum: ['pull_requests', 'repos', 'branches', 'users'], description: 'What to search (default: pull_requests)' },
                         mine: { type: 'boolean', description: 'Return your own PRs by role (resource=pull_requests only)' },
                         role: { type: 'string', enum: ['author', 'reviewer', 'participant'], description: 'Your role filter when mine=true' },
                         projectKey: { type: 'string', description: 'Bitbucket project code, e.g. "ENG"' },
                         project: { type: 'string', description: 'Alias for projectKey' },
                         repoSlug: { type: 'string', description: 'Repository slug' },
                         repo: { type: 'string', description: 'Alias for repoSlug' },
+                        query: { type: 'string', description: 'Name or email filter (resource=users only)' },
                         state: { type: 'string', enum: ['OPEN', 'MERGED', 'DECLINED'], description: 'PR state filter (default OPEN)' },
                         fromBranch: { type: 'string', description: 'Filter PRs from this source branch' },
                         text: { type: 'string', description: 'Filter PRs by title/description text' },
@@ -285,7 +286,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
             },
             {
                 name: 'bitbucket_get_pr',
-                description: 'Full details for one PR: metadata, commits, open comments, blockers, and optional diff. Use when asked to "review this PR", "show me the review comments", "what\'s blocking the merge", or after get_dev_context surfaces a prId. For full file context during review, follow up with bitbucket_get_file. The response includes a "Viewing as" line — if it says "you are the author", do NOT add review comments or a summary unless explicitly asked; just answer questions about the PR. If it says "you are a reviewer", default to posting inline comments for suggested changes and a final summary comment.',
+                description: 'Full details for one PR: metadata, commits, open comments, blockers, and optional diff. Use when asked to "review this PR", "show me the review comments", "what\'s blocking the merge", or after get_dev_context surfaces a prId. IMPORTANT: The PR branch is often not the locally checked-out branch. Do NOT read files with local tools (Read, git_get_diff, etc.) for PR context — use bitbucket_get_file with the PR\'s source branch instead. The response includes a "Viewing as" line — if it says "you are the author", do NOT add review comments or a summary unless explicitly asked; just answer questions about the PR. If it says "you are a reviewer", default to posting inline comments for suggested changes and a final summary comment.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -330,7 +331,8 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                                 description: { type: 'string', description: 'PR description (optional)' },
                                 fromBranch: { type: 'string', description: 'Source branch (defaults to current branch)' },
                                 toBranch: { type: 'string', description: 'Target branch (default: master)' },
-                                reviewers: { type: 'array', items: { type: 'string' }, description: 'Reviewer usernames (optional)' },
+                                reviewers: { type: 'array', items: { type: 'string' }, description: 'Reviewer usernames. Use bitbucket_search resource=users to look up valid usernames before setting this.' },
+                                pickReviewers: { type: 'boolean', description: 'Show an interactive reviewer picker before creating the PR (lists users with repo access)' },
                             },
                             required: ['title'],
                         },
@@ -340,7 +342,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                                 title: { type: 'string', description: 'Updated PR title (optional)' },
                                 description: { type: 'string', description: 'Updated description, or empty string to clear (optional)' },
                                 toBranch: { type: 'string', description: 'Updated target branch (optional)' },
-                                reviewers: { type: 'array', items: { type: 'string' }, description: 'Updated reviewer usernames. Empty array clears reviewers.' },
+                                reviewers: { type: 'array', items: { type: 'string' }, description: 'Updated reviewer usernames. Empty array clears reviewers. Use bitbucket_search resource=users to look up valid usernames before setting this.' },
                             },
                         },
                     },
@@ -377,7 +379,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
             },
             {
                 name: 'bitbucket_get_file',
-                description: 'Raw file content from Bitbucket at a branch, tag, or commit. Use during PR reviews to get full-file context without relying on local checkout.',
+                description: 'Raw file content from Bitbucket at a branch, tag, or commit. CRITICAL: if the PR branch being reviewed is NOT the currently checked-out local branch, ALL additional file context for that review MUST come from this tool — never from local Read, git_get_diff, or any tool that reads local disk. Pass the PR source branch as ref.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -461,8 +463,69 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 if (!jira)
                     throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
                 const a = args;
-                const fields = await jira.getIssueFields(a.issueKey);
-                const branchName = a.branchName ?? slugifyBranchName(a.issueKey, fields.summary, fields.type);
+                if (!a.issueKey && !a.query) {
+                    throw new Error('Provide issueKey (e.g. FOO-123) or query (free-text search).');
+                }
+                // Resolve issueKey from free-text query if not provided directly
+                let issueKey = a.issueKey;
+                if (!issueKey && a.query) {
+                    const candidates = await jira.findIssues(a.query, 10);
+                    if (candidates.length === 0) {
+                        return { content: [{ type: 'text', text: `No Jira tickets found for: "${a.query}"` }] };
+                    }
+                    if (candidates.length === 1) {
+                        issueKey = candidates[0].key;
+                    }
+                    else {
+                        // Multiple matches — present a picker
+                        const pickerMessage = [
+                            `Found ${candidates.length} tickets matching "${a.query}". Which one do you want to work on?`,
+                            ...candidates.map((c, i) => `${i + 1}. [${c.key}] ${c.summary} (${c.status})`),
+                        ].join('\n');
+                        try {
+                            const pickerResult = await server.elicitInput({
+                                message: pickerMessage,
+                                requestedSchema: {
+                                    type: 'object',
+                                    properties: {
+                                        ticket: {
+                                            type: 'string',
+                                            title: 'Select a ticket',
+                                            oneOf: [
+                                                ...candidates.map((c) => ({ const: c.key, title: `[${c.key}] ${c.summary}` })),
+                                                { const: '__cancel__', title: 'Cancel' },
+                                            ],
+                                        },
+                                    },
+                                    required: ['ticket'],
+                                },
+                            });
+                            if (pickerResult.action === 'cancel' ||
+                                pickerResult.action === 'decline' ||
+                                pickerResult.content?.ticket === '__cancel__') {
+                                return { content: [{ type: 'text', text: 'Cancelled.' }] };
+                            }
+                            issueKey = pickerResult.content?.ticket;
+                            if (!issueKey || issueKey === '__cancel__') {
+                                return { content: [{ type: 'text', text: 'Cancelled.' }] };
+                            }
+                        }
+                        catch {
+                            // Client doesn't support elicitation — list options and ask caller to retry with issueKey
+                            const list = candidates.map((c) => `  • ${c.key} — ${c.summary} (${c.status})`).join('\n');
+                            return {
+                                content: [{
+                                        type: 'text',
+                                        text: `Found ${candidates.length} tickets matching "${a.query}":\n${list}\n\nRe-run start_work with the desired issueKey.`,
+                                    }],
+                            };
+                        }
+                    }
+                }
+                if (!issueKey)
+                    throw new Error('Could not resolve issue key.');
+                const fields = await jira.getIssueFields(issueKey);
+                const branchName = a.branchName ?? slugifyBranchName(issueKey, fields.summary, fields.type);
                 const repoPath = a.repoPath ?? process.cwd();
                 // Check if branch already exists on remote before creating
                 const remote = checkRemoteBranch(branchName, repoPath);
@@ -474,7 +537,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     const contextLines = [authorLine, commitLine].filter(Boolean).join('\n');
                     const message = [
                         `Branch "${branchName}" already exists on remote.`,
-                        `Ticket: ${a.issueKey} — ${fields.summary}`,
+                        `Ticket: ${issueKey} — ${fields.summary}`,
                         contextLines,
                     ].filter(Boolean).join('\n');
                     try {
@@ -508,7 +571,6 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                             if (chosen === 'cancel') {
                                 return { content: [{ type: 'text', text: 'Cancelled.' }] };
                             }
-                            // new_name — instruct the model to re-run with a custom name
                             return {
                                 content: [{
                                         type: 'text',
@@ -516,11 +578,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                                     }],
                             };
                         }
-                        // Fallback: unknown action
                         return { content: [{ type: 'text', text: 'Cancelled.' }] };
                     }
                     catch {
-                        // Client doesn't support elicitation — fall back to informational text
                         return {
                             content: [{
                                     type: 'text',
@@ -542,21 +602,52 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     push: a.push ?? false,
                 });
                 const lines = [
-                    `Ticket:  ${a.issueKey} — ${fields.summary}`,
+                    `Ticket:  ${issueKey} — ${fields.summary}`,
                     `Status:  ${fields.status}`,
                     branchResult.content[0].text,
                 ];
                 if (a.transitionName) {
                     try {
-                        await jira.mutateIssue({ issueKey: a.issueKey, transitionName: a.transitionName });
+                        await jira.mutateIssue({ issueKey, transitionName: a.transitionName });
                         lines.push(`Jira:    transitioned → ${a.transitionName}`);
                     }
                     catch (err) {
                         lines.push(`Jira:    could not transition — ${err.message}`);
                     }
                 }
-                if (bitbucket)
-                    lines.push(``, `Next: push commits then use bitbucket_mutate to open a PR.`);
+                // Fetch README from Bitbucket for project conventions
+                if (bitbucket) {
+                    try {
+                        const remoteUrl = (() => {
+                            try {
+                                return execFileSync('git', ['remote', 'get-url', 'origin'], { cwd: repoPath, encoding: 'utf-8' }).trim();
+                            }
+                            catch {
+                                return '';
+                            }
+                        })();
+                        const parsed = parseBitbucketRemote(remoteUrl);
+                        if (parsed) {
+                            const readme = await bitbucket.fetchFileText(parsed.projectKey, parsed.repoSlug, 'README.md');
+                            if (readme) {
+                                const maxLen = 4000;
+                                const truncated = readme.length > maxLen ? readme.slice(0, maxLen) + '\n... (truncated)' : readme;
+                                lines.push('');
+                                lines.push('Project conventions (from README.md):');
+                                lines.push('────────────────────────────────────');
+                                lines.push(truncated);
+                                lines.push('────────────────────────────────────');
+                                lines.push('Follow the conventions above when writing commit messages and the PR description.');
+                            }
+                        }
+                    }
+                    catch { /* README fetch is best-effort */ }
+                    lines.push('');
+                    lines.push('Next steps:');
+                    lines.push('  1. Make your changes and commit following the project conventions.');
+                    lines.push('  2. Use bitbucket_mutate (create) to open a PR — the Jira summary and ticket key make a good title/description starting point.');
+                    lines.push('  3. Add reviewers: bitbucket_search resource=users to find colleagues, or pass pickReviewers=true in create to get an interactive picker.');
+                }
                 return { content: [{ type: 'text', text: lines.join('\n') }] };
             }
             // Jira
@@ -611,6 +702,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     return await bitbucket.listRepos(a);
                 if (resource === 'branches')
                     return await bitbucket.getBranches(a);
+                if (resource === 'users')
+                    return await bitbucket.searchUsers({ projectKey: a.projectKey, repoSlug: a.repoSlug, query: a.query, limit: a.limit, start: a.start });
                 // pull_requests (default)
                 if (a.mine)
                     return await bitbucket.myPrs({ limit: a.limit, start: a.start, role: a.role });
@@ -633,6 +726,42 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     return await bitbucket.declinePr({ ...a, message: a.declineMessage });
                 if (action === 'merge')
                     return await bitbucket.mergePr({ ...a, message: a.mergeMessage, mergeStrategy: a.mergeStrategy });
+                // Handle interactive reviewer picker for PR creation
+                const createArgs = a.create;
+                if (createArgs?.pickReviewers && !a.prId) {
+                    const projectKey = a.projectKey;
+                    const repoSlug = a.repoSlug;
+                    const users = await bitbucket.searchUsersRaw({ projectKey, repoSlug, limit: 30 });
+                    if (users.length > 0) {
+                        // Build boolean checkbox schema — one field per user
+                        // key must be safe for JSON schema property names
+                        const toSchemaKey = (uname) => uname.replace(/[^a-zA-Z0-9]/g, '_');
+                        const userMap = new Map(); // schemaKey -> username
+                        const properties = {};
+                        for (const u of users) {
+                            const key = toSchemaKey(u.name);
+                            userMap.set(key, u.name);
+                            properties[key] = { type: 'boolean', title: `${u.displayName} (${u.name})` };
+                        }
+                        try {
+                            const pickerResult = await server.elicitInput({
+                                message: 'Select reviewers to add to this PR:',
+                                requestedSchema: { type: 'object', properties },
+                            });
+                            if (pickerResult.action === 'accept' && pickerResult.content) {
+                                const selected = [];
+                                for (const [key, username] of userMap) {
+                                    if (pickerResult.content[key] === true)
+                                        selected.push(username);
+                                }
+                                createArgs.reviewers = selected;
+                            }
+                        }
+                        catch {
+                            // elicitation not supported — proceed without reviewer picker
+                        }
+                    }
+                }
                 return await bitbucket.mutatePullRequest(a);
             }
             case 'bitbucket_comment': {

package/dist/jira.js

@@ -285,6 +285,22 @@ export class JiraClient {
         const page = pagination(data.total, startAt, data.issues.length);
         return text(`Found ${data.total} issues${page}:\n${lines.join('\n')}`);
     }
+    async findIssues(query, maxResults = 10) {
+        const jql = buildJQL({ query });
+        const params = new URLSearchParams({
+            jql,
+            maxResults: String(maxResults),
+            startAt: '0',
+            fields: 'summary,status,issuetype',
+        });
+        const data = await this.request('GET', `/search?${params}`);
+        return (data?.issues ?? []).map((i) => ({
+            key: i.key,
+            summary: i.fields.summary,
+            status: i.fields.status.name,
+            type: i.fields.issuetype.name,
+        }));
+    }
     async myIssues(args) {
         return this.searchIssues({
             jql: 'assignee = currentUser() ORDER BY updated DESC',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stubbedev/atlassian-mcp",
-  "version": "0.2.10",
+  "version": "0.2.12",
   "description": "MCP server for self-hosted Jira and Bitbucket",
   "license": "MIT",
   "type": "module",