@stubbedev/atlassian-mcp 0.3.2 → 0.3.4

package/README.md

@@ -27,11 +27,12 @@ A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for **s
 
 | Tool | Description |
 |---|---|
-| `jira_search` | Discover resources: `issues`, `projects`, `issue_types`, `boards`, `sprints`, `board_overview`, or `users` via `resource` param |
+| `jira_search` | Discover resources: `issues`, `projects`, `issue_types`, `boards`, `sprints`, `board_overview`, `versions`, or `users` via `resource` param |
 | `jira_get` | Full details for one issue: summary, description, status, sprint, transitions, comments, and attachment list |
 | `jira_get_attachment` | Fetch a Jira attachment by ID; images are auto-resized via sharp and returned inline so the model can see them, text/JSON inline, larger/binary files via `saveTo` |
 | `jira_mutate` | Create, update, transition, comment, link, add to sprint, or log work — all in one call |
 | `jira_comment` | Add, update, or delete a comment on an issue (`action`: `add` / `update` / `delete`) |
+| `jira_version` | Manage fix versions/releases (`action`: `create` / `update` / `release` / `archive` / `delete`) |
 
 ### Bitbucket
 
@@ -62,6 +63,10 @@ A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for **s
 - "what's in the current sprint?" → `jira_search` with `resource=board_overview`
 - "move FOO-123 to In Progress" → `jira_mutate` with `transitionName="In Progress"`
 - "log 2h on FOO-123" → `jira_mutate` with `worklog`
+- "create version 9.1.0 in PAY" → `jira_version` with `action=create`, `projectKey=PAY`, `name=9.1.0`
+- "list releases for PAY" → `jira_search` with `resource=versions`, `project=PAY`
+- "release version 12345" → `jira_version` with `action=release`, `id=12345`
+- "set fix version 9.1.0 on FOO-123" → `jira_mutate` with `update.fixVersion=9.1.0`
 
 ---
 

package/dist/bitbucket.js

@@ -133,11 +133,20 @@ function pageHint(data) {
 }
 function formatDiff(data, maxChars = 8000) {
     const parts = [];
+    if (data.fromHash && data.toHash) {
+        parts.push(`# fromHash=${data.fromHash} toHash=${data.toHash}`);
+        parts.push('# Pass these to bitbucket_comment as fromHash/toHash to anchor inline comments to this exact diff.');
+    }
     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 ?? []) {
+            const srcLine = hunk.sourceLine ?? 0;
+            const srcSpan = hunk.sourceSpan ?? 0;
+            const dstLine = hunk.destinationLine ?? 0;
+            const dstSpan = hunk.destinationSpan ?? 0;
+            parts.push(`@@ -${srcLine},${srcSpan} +${dstLine},${dstSpan} @@`);
             for (const segment of hunk.segments ?? []) {
                 const prefix = segment.type === 'ADDED' ? '+' : segment.type === 'REMOVED' ? '-' : ' ';
                 for (const line of segment.lines ?? []) {
@@ -327,6 +336,49 @@ export class BitbucketClient {
         }
         return res.status === 204 ? null : res.json();
     }
+    /**
+     * Remap a source-side line number through an interim diff.
+     *
+     * Returns the destination line if the source line survives unchanged through the diff
+     * (in a CONTEXT segment), or null if the line was modified/removed and cannot be remapped.
+     */
+    async remapLineThroughDiff(projectKey, repoSlug, filePath, sinceHash, untilHash, sourceLine) {
+        const diff = await this.request('GET', `${this.rp(projectKey, repoSlug)}/diff/${filePath.split('/').map(encodeURIComponent).join('/')}?since=${encodeURIComponent(sinceHash)}&until=${encodeURIComponent(untilHash)}&contextLines=0`).catch(() => null);
+        if (!diff || !diff.diffs?.length)
+            return sourceLine;
+        let offset = 0;
+        for (const fileDiff of diff.diffs) {
+            for (const hunk of fileDiff.hunks ?? []) {
+                const srcStart = hunk.sourceLine ?? 0;
+                const srcSpan = hunk.sourceSpan ?? 0;
+                const srcEnd = srcStart + srcSpan - 1;
+                if (srcSpan > 0 && sourceLine >= srcStart && sourceLine <= srcEnd) {
+                    for (const segment of hunk.segments ?? []) {
+                        if (segment.type === 'ADDED')
+                            continue;
+                        for (const ln of segment.lines ?? []) {
+                            if (ln.source === sourceLine) {
+                                if (segment.type === 'CONTEXT' && ln.destination !== undefined)
+                                    return ln.destination;
+                                return null;
+                            }
+                        }
+                    }
+                    return null;
+                }
+                if (sourceLine > srcEnd || srcSpan === 0) {
+                    const dstSpan = hunk.destinationSpan ?? 0;
+                    if (srcSpan === 0 && (hunk.destinationLine ?? 0) <= sourceLine + offset) {
+                        offset += dstSpan;
+                    }
+                    else if (sourceLine > srcEnd) {
+                        offset += dstSpan - srcSpan;
+                    }
+                }
+            }
+        }
+        return sourceLine + offset;
+    }
     /** Returns true if the given remote URL belongs to this Bitbucket instance. */
     isRemoteForThisInstance(remoteUrl) {
         return this.remoteMatchesInstance(remoteUrl);
@@ -495,11 +547,17 @@ export class BitbucketClient {
         collectAttachmentRefs(pr.description, 'description', attachmentRefs);
         const reviewers = pr.reviewers.map((r) => `${r.user.displayName}${r.approved ? ' ✓' : ''}`).join(', ');
         const url = pr.links?.self?.[0]?.href;
+        const fromHash = pr.toRef.latestCommit;
+        const toHash = pr.fromRef.latestCommit;
+        const commitsLine = fromHash && toHash
+            ? `Commits:   fromHash=${fromHash} toHash=${toHash} (pass to bitbucket_comment to anchor inline comments to this exact state)`
+            : '';
         const header = [
             `PR #${pr.id}: ${pr.title}`,
             `State:     ${pr.state}`,
             `Author:    ${pr.author.user.displayName}`,
             `Branch:    ${pr.fromRef.displayId} → ${pr.toRef.displayId}`,
+            commitsLine,
             `Reviewers: ${reviewers || 'None'}`,
             url ? `URL:       ${url}` : '',
             '',
@@ -949,7 +1007,9 @@ export class BitbucketClient {
                 || args.lineType !== undefined
                 || args.fileType !== undefined
                 || args.multilineStartLine !== undefined
-                || args.multilineStartLineType !== undefined)) {
+                || args.multilineStartLineType !== undefined
+                || args.fromHash !== undefined
+                || args.toHash !== undefined)) {
             throw new Error('Replies must target an existing comment thread only. Omit filePath/line and other anchor fields when replying.');
         }
         if (args.text === undefined && args.suggestion === undefined) {
@@ -974,11 +1034,14 @@ export class BitbucketClient {
         if (replyToCommentId !== undefined)
             body.parent = { id: replyToCommentId };
         let inlineAnchor;
+        let usedFallbackHashes = false;
+        let currentToHash;
+        let currentFromHash;
+        let remapNote;
         if (args.filePath !== undefined || args.line !== undefined) {
             if (args.filePath === undefined || args.line === undefined) {
                 throw new Error('filePath and line must be provided together for inline comments.');
             }
-            const pr = await this.request('GET', `${this.rp(projectKey, repoSlug)}/pull-requests/${args.prId}`);
             inlineAnchor = {
                 diffType: 'EFFECTIVE',
                 fileType: args.fileType ?? 'TO',
@@ -989,14 +1052,49 @@ export class BitbucketClient {
             if (args.srcPath !== undefined) {
                 inlineAnchor.srcPath = args.srcPath;
             }
-            const fromHash = pr?.toRef.latestCommit;
-            const toHash = pr?.fromRef.latestCommit;
+            const pr = await this.request('GET', `${this.rp(projectKey, repoSlug)}/pull-requests/${args.prId}`).catch(() => null);
+            currentToHash = pr?.fromRef.latestCommit;
+            currentFromHash = pr?.toRef.latestCommit;
+            let fromHash = args.fromHash ?? currentFromHash;
+            let toHash = args.toHash ?? currentToHash;
+            usedFallbackHashes = args.fromHash === undefined && args.toHash === undefined;
+            const fileType = args.fileType ?? 'TO';
+            const reviewedToHash = args.toHash;
+            if (reviewedToHash
+                && currentToHash
+                && reviewedToHash !== currentToHash
+                && fileType === 'TO') {
+                const remappedLine = await this.remapLineThroughDiff(projectKey, repoSlug, args.filePath, reviewedToHash, currentToHash, args.line);
+                let remappedMultilineStart;
+                if (args.multilineStartLine !== undefined) {
+                    remappedMultilineStart = await this.remapLineThroughDiff(projectKey, repoSlug, args.filePath, reviewedToHash, currentToHash, args.multilineStartLine);
+                }
+                const lineOk = remappedLine !== null;
+                const multilineOk = remappedMultilineStart === undefined || remappedMultilineStart !== null;
+                if (lineOk && multilineOk) {
+                    if (remappedLine !== args.line) {
+                        remapNote = `Reviewed line ${args.line} remapped to ${remappedLine} on current head ${currentToHash.slice(0, 8)}.`;
+                    }
+                    inlineAnchor.line = remappedLine;
+                    if (remappedMultilineStart !== undefined && remappedMultilineStart !== null) {
+                        inlineAnchor.multilineStartLine = remappedMultilineStart;
+                    }
+                    toHash = currentToHash;
+                    if (!args.fromHash)
+                        fromHash = currentFromHash;
+                }
+                else {
+                    remapNote = `Reviewed line ${args.line} was modified or removed in interim commits; anchoring to reviewed commit ${reviewedToHash.slice(0, 8)} (Bitbucket will mark the comment outdated, which is correct — the line you reviewed no longer exists at current head).`;
+                }
+            }
             if (fromHash && toHash) {
                 inlineAnchor.fromHash = fromHash;
                 inlineAnchor.toHash = toHash;
             }
-            if (args.multilineStartLine !== undefined) {
+            if (args.multilineStartLine !== undefined && inlineAnchor.multilineStartLine === undefined) {
                 inlineAnchor.multilineStartLine = args.multilineStartLine;
+            }
+            if (inlineAnchor.multilineStartLine !== undefined) {
                 inlineAnchor.multilineStartLineType = args.multilineStartLineType ?? args.lineType ?? 'ADDED';
             }
             body.anchor = inlineAnchor;
@@ -1020,7 +1118,14 @@ export class BitbucketClient {
             return text(`Reply #${created.id} added to comment #${replyToCommentId} on PR #${args.prId}.`);
         }
         const location = args.filePath && args.line ? ` on ${args.filePath}:${args.line}` : '';
-        return text(`Comment #${created.id} added to PR #${args.prId}${location}.`);
+        const warnings = [];
+        if (inlineAnchor && usedFallbackHashes) {
+            warnings.push('No fromHash/toHash passed — anchored to latest PR head. If you reviewed an older commit, the line may now point at unrelated code. Pass fromHash/toHash from bitbucket_pr_diff or bitbucket_get_pr to bind comments to the exact commit you reviewed.');
+        }
+        if (remapNote)
+            warnings.push(remapNote);
+        const warnSuffix = warnings.length ? `\n\nNote: ${warnings.join(' ')}` : '';
+        return text(`Comment #${created.id} added to PR #${args.prId}${location}.${warnSuffix}`);
     }
     async updatePrComment(args) {
         const { projectKey, repoSlug } = this.resolveProjectAndRepo(args.projectKey, args.repoSlug);

package/dist/index.js

@@ -206,11 +206,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
             },
             {
                 name: 'jira_search',
-                description: 'Discover Jira resources. Use when asked "find tickets for...", "what\'s in the backlog", "show me my issues", "list projects", or "which board is for project X". Set resource:\n• "issues" (default) — search by text, JQL, project, status, assignee, issue type, or mine=true for your queue\n• "projects" — list all projects and their keys\n• "issue_types" — valid types and statuses for a project\n• "boards" — list boards (pass project to filter by project key); use this to find the boardId before fetching sprints or board_overview\n• "sprints" — sprints for a board (pass boardId); if you don\'t know the boardId, first use resource=boards\n• "board_overview" — active/future sprints with their issues for a board (pass boardId); use when asked "what\'s in the sprint", "show me the board", or "what\'s everyone working on"\n• "users" — find users by name/email (pass query)',
+                description: 'Discover Jira resources. Use when asked "find tickets for...", "what\'s in the backlog", "show me my issues", "list projects", or "which board is for project X". Set resource:\n• "issues" (default) — search by text, JQL, project, status, assignee, issue type, or mine=true for your queue\n• "projects" — list all projects and their keys\n• "issue_types" — valid types and statuses for a project\n• "boards" — list boards (pass project to filter by project key); use this to find the boardId before fetching sprints or board_overview\n• "sprints" — sprints for a board (pass boardId); if you don\'t know the boardId, first use resource=boards\n• "board_overview" — active/future sprints with their issues for a board (pass boardId); use when asked "what\'s in the sprint", "show me the board", or "what\'s everyone working on"\n• "versions" — list fix versions/releases for a project (pass project); use this to find the exact version name or id before setting fixVersion or releasing a version\n• "users" — find users by name/email (pass query)',
                 inputSchema: {
                     type: 'object',
                     properties: {
-                        resource: { type: 'string', enum: ['issues', 'projects', 'issue_types', 'boards', 'sprints', 'board_overview', 'users'], description: 'What to search (default: issues)' },
+                        resource: { type: 'string', enum: ['issues', 'projects', 'issue_types', 'boards', 'sprints', 'board_overview', 'versions', 'users'], description: 'What to search (default: issues)' },
                         mine: { type: 'boolean', description: 'Return issues assigned to you (resource=issues only)' },
                         query: { type: 'string', description: 'Text search or user name query' },
                         jql: { type: 'string', description: 'Raw JQL (resource=issues only, overrides other filters)' },
@@ -331,6 +331,25 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                     },
                     required: ['issueKey'],
                 },
+            },
+            {
+                name: 'jira_version',
+                description: 'Manage Jira fix versions (releases). Use when asked to "create version 9.1.0", "release version X", "archive version X", "rename a version", or "delete a version". action defaults to "create". For create pass projectKey + name. For update/release/archive/delete pass id (look it up via jira_search resource=versions). "release" sets released=true and defaults releaseDate to today. Once a version exists you can set it on tickets via jira_mutate update.fixVersion.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        action: { type: 'string', enum: ['create', 'update', 'release', 'archive', 'delete'], description: 'Operation (default: create)' },
+                        projectKey: { type: 'string', description: 'Jira project code (required for create when not auto-resolvable)' },
+                        project: { type: 'string', description: 'Alias for projectKey' },
+                        id: { type: 'string', description: 'Version id (required for update/release/archive/delete; look up via jira_search resource=versions)' },
+                        name: { type: 'string', description: 'Version name, e.g. "9.1.0" (required for create; optional rename for update)' },
+                        description: { type: 'string', description: 'Version description (optional)' },
+                        startDate: { type: 'string', description: 'Start date in YYYY-MM-DD (optional)' },
+                        releaseDate: { type: 'string', description: 'Release date in YYYY-MM-DD (optional; defaults to today on action=release)' },
+                        released: { type: 'boolean', description: 'Released flag (optional; action=release forces true)' },
+                        archived: { type: 'boolean', description: 'Archived flag (optional; action=archive forces true)' },
+                    },
+                },
             }
         ] : []),
         ...(bitbucket ? [{
@@ -422,7 +441,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
             },
             {
                 name: 'bitbucket_comment',
-                description: `Add, update, or delete a PR comment. action defaults to "add". For code changes, ALWAYS use inline comments with suggestion when exact replacement code is available. Keep any explanatory text before the suggestion block only (never after), or Bitbucket may hide Apply suggestion. Replies MUST use commentId. Keep comments concise, no emojis. Only call proactively (without being asked) when you are a reviewer on the PR (i.e. "Viewing as" says "you are a reviewer") — never post unsolicited comments on PRs you authored.`,
+                description: `Add, update, or delete a PR comment. action defaults to "add". For code changes, ALWAYS use inline comments with suggestion when exact replacement code is available. Keep any explanatory text before the suggestion block only (never after), or Bitbucket may hide Apply suggestion. Replies MUST use commentId. Keep comments concise, no emojis. Only call proactively (without being asked) when you are a reviewer on the PR (i.e. "Viewing as" says "you are a reviewer") — never post unsolicited comments on PRs you authored. For inline comments: ALWAYS pass fromHash + toHash matching the commit you actually reviewed (read from bitbucket_pr_diff or bitbucket_get_pr output). Without them the anchor falls back to current PR head, and if the branch advanced between review and post the line number will point at unrelated code.`,
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -441,6 +460,8 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                         fileType: { type: 'string', enum: ['TO', 'FROM'], description: 'Diff side: TO (new, default) or FROM (old)' },
                         multilineStartLine: { type: 'number', description: 'First line of multiline anchor (pair with line as last line)' },
                         multilineStartLineType: { type: 'string', enum: ['ADDED', 'REMOVED', 'CONTEXT'], description: 'Line type for multilineStartLine' },
+                        fromHash: { type: 'string', description: 'Base/target commit of the diff you reviewed (from bitbucket_pr_diff or bitbucket_get_pr). Pair with toHash so the anchor binds to the exact commit, not whatever the PR head happens to be at post time.' },
+                        toHash: { type: 'string', description: 'Source/feature commit of the diff you reviewed (from bitbucket_pr_diff or bitbucket_get_pr). Pair with fromHash. If the PR has advanced since, Bitbucket will mark the comment outdated — that is the correct behaviour.' },
                         suggestion: { type: 'string', description: 'Replacement code to suggest. Use whenever proposing a concrete code change. Posted as the final ```suggestion``` block so Apply suggestion appears. Requires filePath + line.' },
                         state: { type: 'string', enum: ['OPEN', 'RESOLVED'], description: 'Task state for BLOCKER comments (update only)' },
                         threadResolved: { type: 'boolean', description: 'Resolve/reopen normal comment thread (update only)' },
@@ -756,6 +777,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     return await jira.getSprints({ boardId: a.boardId, state: a.sprintState, maxResults: a.maxResults, startAt: a.startAt });
                 if (resource === 'board_overview')
                     return await jira.boardOverview({ boardId: a.boardId, sprintState: a.sprintState, sprintMaxResults: a.maxResults, sprintStartAt: a.startAt, includeIssues: a.includeIssues, assignee: a.assignee, status: a.status });
+                if (resource === 'versions')
+                    return await jira.listVersions({ projectKey: a.projectKey ?? a.project, maxResults: a.maxResults });
                 if (resource === 'users')
                     return await jira.searchUsers({ query: a.query ?? '', maxResults: a.maxResults });
                 // issues (default)
@@ -788,6 +811,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     return await jira.deleteComment({ issueKey: a.issueKey, commentId: a.commentId });
                 return await jira.addComment({ issueKey: a.issueKey, body: a.body });
             }
+            case 'jira_version': {
+                if (!jira)
+                    throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
+                const a = normalizeJiraProjectArgs(args);
+                return await jira.mutateVersion(a);
+            }
             // Bitbucket
             case 'bitbucket_search': {
                 if (!bitbucket)

package/dist/jira.js

@@ -761,4 +761,96 @@ export class JiraClient {
         await this.transitionIssueInternal(args.issueKey, transitionId);
         return text(`Transitioned ${args.issueKey} using transition ${transitionId}.\n${this.issueUrl(args.issueKey)}`);
     }
+    async listVersions(args) {
+        const projectKey = await this.resolveProjectKey(args.projectKey);
+        const data = await this.request('GET', `/project/${encodeURIComponent(projectKey)}/versions`);
+        if (!data || data.length === 0)
+            return text(`No versions in ${projectKey}.`);
+        const sorted = [...data].sort((a, b) => {
+            if (a.released !== b.released)
+                return a.released ? 1 : -1;
+            if (a.archived !== b.archived)
+                return a.archived ? 1 : -1;
+            const ad = a.releaseDate ?? '';
+            const bd = b.releaseDate ?? '';
+            return bd.localeCompare(ad);
+        });
+        const limit = args.maxResults ?? sorted.length;
+        const shown = sorted.slice(0, limit);
+        const lines = shown.map((v, i) => {
+            const tags = [];
+            if (v.released)
+                tags.push('released');
+            if (v.archived)
+                tags.push('archived');
+            const tagStr = tags.length ? ` [${tags.join(', ')}]` : '';
+            const dateParts = [v.startDate ? `start ${v.startDate}` : '', v.releaseDate ? `release ${v.releaseDate}` : ''].filter(Boolean);
+            const dateStr = dateParts.length ? ` (${dateParts.join(', ')})` : '';
+            return `${i + 1}. [${v.id}] ${v.name}${tagStr}${dateStr}`;
+        });
+        const more = data.length > shown.length ? `\n...and ${data.length - shown.length} more (raise maxResults).` : '';
+        return text(`${data.length} version(s) in ${projectKey}:\n${lines.join('\n')}${more}`);
+    }
+    async mutateVersion(args) {
+        const action = args.action ?? 'create';
+        if (action === 'create') {
+            const projectKey = await this.resolveProjectKey(args.projectKey);
+            const name = args.name?.trim();
+            if (!name)
+                throw new Error('name is required to create a version.');
+            const body = { project: projectKey, name };
+            if (args.description !== undefined)
+                body.description = args.description;
+            if (args.releaseDate)
+                body.releaseDate = args.releaseDate;
+            if (args.startDate)
+                body.startDate = args.startDate;
+            if (args.released !== undefined)
+                body.released = args.released;
+            if (args.archived !== undefined)
+                body.archived = args.archived;
+            const created = await this.request('POST', '/version', body);
+            if (!created)
+                throw new Error('Jira returned no body when creating version.');
+            return text(`Created version [${created.id}] ${created.name} in ${projectKey}.`);
+        }
+        const id = args.id?.trim();
+        if (!id)
+            throw new Error(`version id is required for action=${action}.`);
+        if (action === 'delete') {
+            await this.request('DELETE', `/version/${encodeURIComponent(id)}`);
+            return text(`Deleted version ${id}.`);
+        }
+        const body = {};
+        if (args.name !== undefined)
+            body.name = args.name;
+        if (args.description !== undefined)
+            body.description = args.description;
+        if (args.startDate !== undefined)
+            body.startDate = args.startDate;
+        if (args.releaseDate !== undefined)
+            body.releaseDate = args.releaseDate;
+        if (args.released !== undefined)
+            body.released = args.released;
+        if (args.archived !== undefined)
+            body.archived = args.archived;
+        if (action === 'release') {
+            body.released = true;
+            if (body.releaseDate === undefined)
+                body.releaseDate = new Date().toISOString().slice(0, 10);
+        }
+        else if (action === 'archive') {
+            body.archived = true;
+        }
+        if (Object.keys(body).length === 0) {
+            throw new Error('Nothing to update.');
+        }
+        const updated = await this.request('PUT', `/version/${encodeURIComponent(id)}`, body);
+        const label = updated ? `[${updated.id}] ${updated.name}` : id;
+        if (action === 'release')
+            return text(`Released version ${label} on ${body.releaseDate}.`);
+        if (action === 'archive')
+            return text(`Archived version ${label}.`);
+        return text(`Updated version ${label}.`);
+    }
 }

package/package.json

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