@stubbedev/atlassian-mcp 0.1.4 → 0.1.6

package/README.md

@@ -1,6 +1,6 @@
 # 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 33 tools for natural-language workflows around tickets, pull requests, review threads, and git context.
+A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for **self-hosted Jira** (Server / Data Center) and **self-hosted Bitbucket** (Server / Data Center). Exposes tools for natural-language workflows around tickets, pull requests, review threads, and git context.
 
 > **Note:** This server only supports self-hosted instances. Jira Cloud and Bitbucket Cloud use different APIs and are not supported.
 
@@ -22,9 +22,14 @@ A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for **s
 | `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_sprints` | List sprints for a board (with sprint IDs for assignment) |
 | `jira_get_issue` | Get issue details by key |
+| `jira_issue_overview` | Get one-call issue overview (details, transitions, sprint context, optional comments) |
+| `jira_board_overview` | Get one-call board overview (board info, sprints, optional sprint issues) |
 | `jira_create_issue` | Create a new issue |
 | `jira_update_issue` | Update summary, description, assignee, or priority |
+| `jira_add_issues_to_sprint` | Add one or more issues to a sprint by sprint ID |
+| `jira_mutate_issue` | Bundle create/update/sprint/transition/comment actions into one call |
 | `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 |

package/dist/bitbucket.js

@@ -158,6 +158,13 @@ export class BitbucketClient {
             Accept: 'application/json',
         };
     }
+    pullRequestUrl(projectKey, repoSlug, prId, pr) {
+        const apiUrl = pr?.links?.self?.[0]?.href?.trim();
+        if (apiUrl) {
+            return apiUrl;
+        }
+        return `${this.baseUrl}/projects/${encodeURIComponent(projectKey)}/repos/${encodeURIComponent(repoSlug)}/pull-requests/${prId}`;
+    }
     resolveProjectAndRepo(projectKey, repoSlug) {
         if (projectKey && repoSlug)
             return { projectKey, repoSlug };
@@ -375,20 +382,21 @@ export class BitbucketClient {
         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}` : ''}`);
+        const url = this.pullRequestUrl(projectKey, repoSlug, data.id, data);
+        return text(`Created PR #${data.id}: "${data.title}"\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`);
+        const url = this.pullRequestUrl(projectKey, repoSlug, args.prId);
         if (!data)
-            return text(`Approved PR #${args.prId}.`);
-        return text(`Approved PR #${args.prId} as ${data.user.displayName}.`);
+            return text(`Approved PR #${args.prId}.\n${url}`);
+        return text(`Approved PR #${args.prId} as ${data.user.displayName}.\n${url}`);
     }
     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}.`);
+        return text(`Approval removed from PR #${args.prId}.\n${this.pullRequestUrl(projectKey, repoSlug, args.prId)}`);
     }
     async declinePr(args) {
         const { projectKey, repoSlug } = this.resolveProjectAndRepo(args.projectKey, args.repoSlug);
@@ -400,8 +408,8 @@ export class BitbucketClient {
             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}".`);
+            return text(`Declined PR #${args.prId}.\n${this.pullRequestUrl(projectKey, repoSlug, args.prId)}`);
+        return text(`Declined PR #${data.id}: "${data.title}".\n${this.pullRequestUrl(projectKey, repoSlug, data.id, data)}`);
     }
     async mergePr(args) {
         const { projectKey, repoSlug } = this.resolveProjectAndRepo(args.projectKey, args.repoSlug);
@@ -415,8 +423,8 @@ export class BitbucketClient {
             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}).`);
+            return text(`Merged PR #${args.prId}.\n${this.pullRequestUrl(projectKey, repoSlug, args.prId)}`);
+        return text(`Merged PR #${data.id}: "${data.title}" (${data.fromRef.displayId} → ${data.toRef.displayId}).\n${this.pullRequestUrl(projectKey, repoSlug, data.id, data)}`);
     }
     async getBranches(args) {
         const { projectKey, repoSlug } = this.resolveProjectAndRepo(args.projectKey, args.repoSlug);

package/dist/index.js

@@ -29,6 +29,16 @@ function normalizeJiraProjectArgs(args) {
         out.projectKey = out.project;
     return out;
 }
+function normalizeJiraMutateArgs(args) {
+    const out = normalizeJiraProjectArgs(args);
+    if (out.create && typeof out.create === 'object') {
+        const create = { ...out.create };
+        if (typeof create.project === 'string' && typeof create.projectKey !== 'string')
+            create.projectKey = create.project;
+        out.create = create;
+    }
+    return out;
+}
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: [
         // ── Context ───────────────────────────────────────────────────────────
@@ -92,6 +102,20 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 },
             },
         },
+        {
+            name: 'jira_get_sprints',
+            description: 'Use when you need sprint IDs for planning or assignment. Returns sprints for a Jira board.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    boardId: { type: 'number', description: 'Jira board ID' },
+                    state: { type: 'string', description: 'Optional sprint state filter, e.g. "active", "future", or "closed"' },
+                    maxResults: { type: 'number', description: 'Max sprints per page (default 20)', default: 20 },
+                    startAt: { type: 'number', description: 'Offset for pagination (default 0)', default: 0 },
+                },
+                required: ['boardId'],
+            },
+        },
         {
             name: 'jira_search_users',
             description: 'Use when assigning tickets and you need to find the correct Jira username by name or email.',
@@ -115,6 +139,22 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 required: ['issueKey'],
             },
         },
+        {
+            name: 'jira_issue_overview',
+            description: 'Use when you want one Jira issue snapshot in a single call: details, transitions, sprint context, and optional comments.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    issueKey: { type: 'string', description: 'Jira issue key, e.g. "FOO-123"' },
+                    includeComments: { type: 'boolean', description: 'Include comments in the overview (default true)', default: true },
+                    commentsMaxResults: { type: 'number', description: 'Max comments when includeComments=true (default 10)', default: 10 },
+                    commentsStartAt: { type: 'number', description: 'Comment pagination offset (default 0)', default: 0 },
+                    includeTransitions: { type: 'boolean', description: 'Include available transitions (default true)', default: true },
+                    includeSprint: { type: 'boolean', description: 'Include sprint data via Jira Agile API (default true)', default: true },
+                },
+                required: ['issueKey'],
+            },
+        },
         {
             name: 'jira_create_issue',
             description: 'Use when you want to create a new Jira ticket (bug, story, task, etc.). If projectKey/project is omitted, the server auto-picks from branch context or asks you to choose.',
@@ -128,6 +168,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                     description: { type: 'string', description: 'Issue description (optional)' },
                     assignee: { type: 'string', description: 'Username to assign to (optional)' },
                     priority: { type: 'string', description: 'Priority name, e.g. "High" (optional)' },
+                    sprintId: { type: 'number', description: 'Sprint ID to immediately add the new issue into (optional)' },
                 },
                 required: ['issueType', 'summary'],
             },
@@ -143,10 +184,79 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                     description: { type: 'string', description: 'New description (optional)' },
                     assignee: { type: 'string', description: 'New assignee username, or empty string to unassign (optional)' },
                     priority: { type: 'string', description: 'New priority name (optional)' },
+                    sprintId: { type: 'number', description: 'Sprint ID to add this issue into (optional)' },
                 },
                 required: ['issueKey'],
             },
         },
+        {
+            name: 'jira_add_issues_to_sprint',
+            description: 'Use when you want to assign one or more Jira issues to a sprint by sprint ID.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    sprintId: { type: 'number', description: 'Sprint ID' },
+                    issueKey: { type: 'string', description: 'Single issue key (optional)' },
+                    issueKeys: { type: 'array', items: { type: 'string' }, description: 'Multiple issue keys (optional)' },
+                },
+                required: ['sprintId'],
+            },
+        },
+        {
+            name: 'jira_mutate_issue',
+            description: 'Use when you want to bundle Jira mutations in one call: create or target an issue, then optional update, sprint assignment, transition, and comment.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    issueKey: { type: 'string', description: 'Existing issue key to mutate (optional if create is provided)' },
+                    create: {
+                        type: 'object',
+                        properties: {
+                            projectKey: { type: 'string', description: 'Jira project code (optional, auto-resolved when omitted)' },
+                            project: { type: 'string', description: 'Alias for projectKey' },
+                            issueType: { type: 'string', description: 'Issue type name, e.g. Bug, Story, Task' },
+                            summary: { type: 'string', description: 'Issue title' },
+                            description: { type: 'string', description: 'Issue description (optional)' },
+                            assignee: { type: 'string', description: 'Username to assign to (optional)' },
+                            priority: { type: 'string', description: 'Priority name (optional)' },
+                        },
+                        required: ['issueType', 'summary'],
+                    },
+                    update: {
+                        type: 'object',
+                        properties: {
+                            summary: { type: 'string', description: 'New summary (optional)' },
+                            description: { type: 'string', description: 'New description (optional)' },
+                            assignee: { type: 'string', description: 'New assignee username, or empty string to unassign (optional)' },
+                            priority: { type: 'string', description: 'New priority name (optional)' },
+                        },
+                    },
+                    sprintId: { type: 'number', description: 'Sprint ID to add the issue into (optional)' },
+                    transitionId: { type: 'string', description: 'Transition ID (optional if transitionName is provided)' },
+                    transitionName: { type: 'string', description: 'Transition name, e.g. In Progress (optional if transitionId is provided)' },
+                    comment: { type: 'string', description: 'Comment to add after other mutations (optional, no emoji)' },
+                },
+            },
+        },
+        {
+            name: 'jira_board_overview',
+            description: 'Use when you want one board-level planning snapshot: board info, sprints, and optional sprint issues in one call.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    boardId: { type: 'number', description: 'Jira board ID' },
+                    sprintState: { type: 'string', description: 'Sprint state filter, e.g. "active,future" (default active,future)' },
+                    sprintMaxResults: { type: 'number', description: 'Max sprints per page (default 10)', default: 10 },
+                    sprintStartAt: { type: 'number', description: 'Sprints pagination offset (default 0)', default: 0 },
+                    includeIssues: { type: 'boolean', description: 'Include sprint issues (default true)', default: true },
+                    issueMaxResults: { type: 'number', description: 'Max issues per sprint when includeIssues=true (default 25)', default: 25 },
+                    issueStartAt: { type: 'number', description: 'Issue pagination offset per sprint (default 0)', default: 0 },
+                    assignee: { type: 'string', description: 'Optional assignee filter for sprint issues' },
+                    status: { type: 'string', description: 'Optional status filter for sprint issues' },
+                },
+                required: ['boardId'],
+            },
+        },
         {
             name: 'jira_get_comments',
             description: 'Use when you want the discussion thread on a Jira ticket, with pagination for long threads.',
@@ -542,14 +652,24 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 return await jira.getProjects(args);
             case 'jira_get_issue_types':
                 return await jira.getIssueTypes(normalizeJiraProjectArgs(args));
+            case 'jira_get_sprints':
+                return await jira.getSprints(args);
             case 'jira_search_users':
                 return await jira.searchUsers(args);
             case 'jira_get_issue':
                 return await jira.getIssue(args);
+            case 'jira_issue_overview':
+                return await jira.issueOverview(args);
             case 'jira_create_issue':
                 return await jira.createIssue(normalizeJiraProjectArgs(args));
             case 'jira_update_issue':
                 return await jira.updateIssue(args);
+            case 'jira_add_issues_to_sprint':
+                return await jira.addIssuesToSprint(args);
+            case 'jira_mutate_issue':
+                return await jira.mutateIssue(normalizeJiraMutateArgs(args));
+            case 'jira_board_overview':
+                return await jira.boardOverview(args);
             case 'jira_get_comments':
                 return await jira.getComments(args);
             case 'jira_add_comment':

package/dist/jira.js

@@ -98,8 +98,20 @@ export class JiraClient {
             Accept: 'application/json',
         };
     }
-    async request(method, path, body) {
-        const url = `${this.baseUrl}/rest/api/2${path}`;
+    issueUrl(issueKey) {
+        return `${this.baseUrl}/browse/${encodeURIComponent(issueKey)}`;
+    }
+    projectUrl(projectKey) {
+        return `${this.baseUrl}/projects/${encodeURIComponent(projectKey)}`;
+    }
+    boardUrl(boardId) {
+        return `${this.baseUrl}/secure/RapidBoard.jspa?rapidView=${boardId}`;
+    }
+    sprintUrl(boardId, sprintId) {
+        return `${this.boardUrl(boardId)}&sprint=${sprintId}`;
+    }
+    async requestWithBase(apiBase, method, path, body) {
+        const url = `${this.baseUrl}${apiBase}${path}`;
         const opts = { method, headers: this.headers };
         if (body !== undefined)
             opts.body = JSON.stringify(body);
@@ -111,6 +123,67 @@ export class JiraClient {
         }
         return res.status === 204 ? null : res.json();
     }
+    async request(method, path, body) {
+        return this.requestWithBase('/rest/api/2', method, path, body);
+    }
+    async requestAgile(method, path, body) {
+        return this.requestWithBase('/rest/agile/1.0', method, path, body);
+    }
+    async addIssuesToSprintInternal(sprintId, issueKeys) {
+        await this.requestAgile('POST', `/sprint/${sprintId}/issue`, { issues: issueKeys });
+    }
+    async createIssueInternal(args) {
+        const projectKey = await this.resolveProjectKey(args.projectKey);
+        const fields = {
+            project: { key: projectKey },
+            issuetype: { name: args.issueType },
+            summary: args.summary,
+        };
+        if (args.description)
+            fields.description = args.description;
+        if (args.assignee)
+            fields.assignee = { name: args.assignee };
+        if (args.priority)
+            fields.priority = { name: args.priority };
+        return this.request('POST', '/issue', { fields });
+    }
+    async updateIssueFieldsInternal(args) {
+        const fields = {};
+        if (args.summary !== undefined)
+            fields.summary = args.summary;
+        if (args.description !== undefined)
+            fields.description = args.description;
+        if (args.assignee !== undefined)
+            fields.assignee = { name: args.assignee };
+        if (args.priority !== undefined)
+            fields.priority = { name: args.priority };
+        if (Object.keys(fields).length === 0)
+            return false;
+        await this.request('PUT', `/issue/${args.issueKey}`, { fields });
+        return true;
+    }
+    async resolveTransitionId(issueKey, transitionId, transitionName) {
+        if (transitionId)
+            return transitionId;
+        const requestedName = transitionName?.trim();
+        if (!requestedName) {
+            throw new Error('Provide transitionId or transitionName');
+        }
+        const data = await this.request('GET', `/issue/${issueKey}/transitions`);
+        const transitions = data?.transitions ?? [];
+        const lowered = requestedName.toLowerCase();
+        const match = transitions.find((t) => t.name.toLowerCase() === lowered);
+        if (!match) {
+            const available = transitions.map((t) => t.name).join(', ') || '(none)';
+            throw new Error(`Transition "${requestedName}" not found for ${issueKey}. Available: ${available}`);
+        }
+        return match.id;
+    }
+    async transitionIssueInternal(issueKey, transitionId) {
+        await this.request('POST', `/issue/${issueKey}/transitions`, {
+            transition: { id: transitionId },
+        });
+    }
     async resolveProjectKey(projectKey) {
         if (projectKey)
             return projectKey;
@@ -147,7 +220,7 @@ export class JiraClient {
             return text('No results.');
         const lines = data.issues.map((i, idx) => {
             const assignee = i.fields.assignee?.displayName ?? 'Unassigned';
-            return `${startAt + idx + 1}. [${i.key}] ${i.fields.summary} | ${i.fields.status.name} | ${assignee}`;
+            return `${startAt + idx + 1}. [${i.key}] ${i.fields.summary} | ${i.fields.status.name} | ${assignee} | ${this.issueUrl(i.key)}`;
         });
         const page = pagination(data.total, startAt, data.issues.length);
         return text(`Found ${data.total} issues${page}:\n${lines.join('\n')}`);
@@ -164,7 +237,7 @@ export class JiraClient {
         const data = await this.request('GET', `/project?maxResults=${limit}`);
         if (!data || data.length === 0)
             return text('No projects found.');
-        const lines = data.map((p, i) => `${i + 1}. [${p.key}] ${p.name} (${p.projectTypeKey})`);
+        const lines = data.map((p, i) => `${i + 1}. [${p.key}] ${p.name} (${p.projectTypeKey}) | ${this.projectUrl(p.key)}`);
         return text(`${data.length} project(s):\n${lines.join('\n')}`);
     }
     async getIssueTypes(args) {
@@ -178,6 +251,26 @@ export class JiraClient {
         });
         return text(`Issue types and statuses for ${projectKey}:\n${lines.join('\n')}`);
     }
+    async getSprints(args) {
+        const { boardId, maxResults = 20, startAt = 0 } = args;
+        const params = new URLSearchParams({
+            maxResults: String(maxResults),
+            startAt: String(startAt),
+        });
+        if (args.state)
+            params.set('state', args.state);
+        const data = await this.requestAgile('GET', `/board/${boardId}/sprint?${params}`);
+        if (!data || data.values.length === 0)
+            return text(`No sprints found for board ${boardId}.`);
+        const lines = data.values.map((s, i) => {
+            const window = [s.startDate?.slice(0, 10), s.endDate?.slice(0, 10)].filter(Boolean).join(' -> ');
+            const goal = s.goal?.trim() ? ` | Goal: ${s.goal}` : '';
+            return `${startAt + i + 1}. [${s.id}] ${s.name} | ${s.state}${window ? ` | ${window}` : ''}${goal} | ${this.sprintUrl(boardId, s.id)}`;
+        });
+        const rangeEnd = startAt + data.values.length;
+        const page = data.isLast ? '' : ` (showing ${startAt + 1}-${rangeEnd}, use startAt=${rangeEnd} for next page)`;
+        return text(`Sprints for board ${boardId}${page}:\nBoard URL: ${this.boardUrl(boardId)}\n${lines.join('\n')}`);
+    }
     async searchUsers(args) {
         const params = new URLSearchParams({
             username: args.query,
@@ -211,38 +304,229 @@ export class JiraClient {
         ];
         return text(lines.join('\n'));
     }
-    async createIssue(args) {
-        const projectKey = await this.resolveProjectKey(args.projectKey);
-        const fields = {
-            project: { key: projectKey },
-            issuetype: { name: args.issueType },
-            summary: args.summary,
-        };
-        if (args.description)
-            fields.description = args.description;
+    async issueOverview(args) {
+        const includeComments = args.includeComments ?? true;
+        const includeTransitions = args.includeTransitions ?? true;
+        const includeSprint = args.includeSprint ?? true;
+        const commentsMaxResults = args.commentsMaxResults ?? 10;
+        const commentsStartAt = args.commentsStartAt ?? 0;
+        const fields = 'summary,description,status,assignee,priority,issuetype,labels,components';
+        const issue = await this.request('GET', `/issue/${args.issueKey}?fields=${fields}`);
+        if (!issue)
+            return text('Issue not found.');
+        const f = issue.fields;
+        const lines = [
+            `Issue: ${issue.key} — ${f.summary}`,
+            `URL:        ${this.issueUrl(issue.key)}`,
+            `Status:     ${f.status.name}`,
+            `Type:       ${f.issuetype.name}`,
+            `Priority:   ${f.priority?.name ?? 'None'}`,
+            `Assignee:   ${f.assignee?.displayName ?? 'Unassigned'}`,
+            `Labels:     ${f.labels?.join(', ') || 'None'}`,
+            `Components: ${f.components?.map((c) => c.name).join(', ') || 'None'}`,
+        ];
+        if (includeSprint) {
+            try {
+                const agileIssue = await this.requestAgile('GET', `/issue/${args.issueKey}?fields=sprint,closedSprints`);
+                const activeSprint = agileIssue?.fields?.sprint;
+                const closedSprints = agileIssue?.fields?.closedSprints ?? [];
+                if (activeSprint) {
+                    lines.push(`Sprint:     [${activeSprint.id}] ${activeSprint.name} (${activeSprint.state})`);
+                }
+                else {
+                    lines.push('Sprint:     None');
+                }
+                if (closedSprints.length > 0) {
+                    const closed = closedSprints.slice(0, 5).map((s) => `[${s.id}] ${s.name}`).join(', ');
+                    const more = closedSprints.length > 5 ? ` (+${closedSprints.length - 5} more)` : '';
+                    lines.push(`History:    ${closed}${more}`);
+                }
+            }
+            catch (err) {
+                lines.push(`Sprint:     unavailable (${err.message})`);
+            }
+        }
+        if (includeTransitions) {
+            const transitions = await this.request('GET', `/issue/${args.issueKey}/transitions`);
+            const names = (transitions?.transitions ?? []).map((t) => `${t.name} -> ${t.to.name}`);
+            lines.push(`Transitions: ${names.length > 0 ? names.join(', ') : '(none)'}`);
+        }
+        lines.push('', 'Description:', f.description ?? '(no description)');
+        if (includeComments) {
+            const comments = await this.request('GET', `/issue/${args.issueKey}/comment?startAt=${commentsStartAt}&maxResults=${commentsMaxResults}`);
+            const items = comments?.comments ?? [];
+            const total = comments?.total ?? 0;
+            const page = comments ? pagination(total, commentsStartAt, items.length) : '';
+            lines.push('', `Comments: ${total}${page}`);
+            if (items.length === 0) {
+                lines.push('(none)');
+            }
+            else {
+                for (const c of items) {
+                    const date = c.created.slice(0, 10);
+                    lines.push(`--- ${c.author.displayName} (${date}) ---`, c.body, '');
+                }
+            }
+        }
+        return text(lines.join('\n').trimEnd());
+    }
+    async boardOverview(args) {
+        const includeIssues = args.includeIssues ?? true;
+        const sprintMaxResults = args.sprintMaxResults ?? 10;
+        const sprintStartAt = args.sprintStartAt ?? 0;
+        const issueMaxResults = args.issueMaxResults ?? 25;
+        const issueStartAt = args.issueStartAt ?? 0;
+        const board = await this.requestAgile('GET', `/board/${args.boardId}`);
+        const sprintParams = new URLSearchParams({
+            maxResults: String(sprintMaxResults),
+            startAt: String(sprintStartAt),
+        });
+        if (args.sprintState) {
+            sprintParams.set('state', args.sprintState);
+        }
+        else {
+            sprintParams.set('state', 'active,future');
+        }
+        const sprints = await this.requestAgile('GET', `/board/${args.boardId}/sprint?${sprintParams}`);
+        if (!sprints || sprints.values.length === 0) {
+            return text(`Board ${args.boardId}${board?.name ? ` (${board.name})` : ''}: no matching sprints.`);
+        }
+        const issueFilterClauses = [];
         if (args.assignee)
-            fields.assignee = { name: args.assignee };
-        if (args.priority)
-            fields.priority = { name: args.priority };
-        const data = await this.request('POST', '/issue', { fields });
+            issueFilterClauses.push(`assignee = ${JSON.stringify(args.assignee)}`);
+        if (args.status)
+            issueFilterClauses.push(`status = ${JSON.stringify(args.status)}`);
+        const issueJql = issueFilterClauses.length > 0 ? issueFilterClauses.join(' AND ') : '';
+        const sprintIssueData = includeIssues
+            ? await Promise.all(sprints.values.map(async (sprint) => {
+                const params = new URLSearchParams({
+                    maxResults: String(issueMaxResults),
+                    startAt: String(issueStartAt),
+                    fields: 'summary,status,assignee,priority,issuetype',
+                });
+                if (issueJql)
+                    params.set('jql', issueJql);
+                const issues = await this.requestAgile('GET', `/sprint/${sprint.id}/issue?${params}`);
+                return { sprintId: sprint.id, issues };
+            }))
+            : [];
+        const issueBySprint = new Map(sprintIssueData.map((entry) => [entry.sprintId, entry.issues]));
+        const lines = [
+            `Board: [${args.boardId}] ${board?.name ?? '(unknown)'} | ${board?.type ?? '(unknown type)'}`,
+            `URL: ${this.boardUrl(args.boardId)}`,
+            `Sprints: ${sprints.values.length}`,
+            '',
+        ];
+        sprints.values.forEach((sprint, idx) => {
+            const window = [sprint.startDate?.slice(0, 10), sprint.endDate?.slice(0, 10)].filter(Boolean).join(' -> ');
+            lines.push(`${sprintStartAt + idx + 1}. [${sprint.id}] ${sprint.name} | ${sprint.state}${window ? ` | ${window}` : ''} | ${this.sprintUrl(args.boardId, sprint.id)}`);
+            if (sprint.goal?.trim()) {
+                lines.push(`   Goal: ${sprint.goal}`);
+            }
+            if (includeIssues) {
+                const issueData = issueBySprint.get(sprint.id);
+                const issues = issueData?.issues ?? [];
+                lines.push(`   Issues: ${issueData?.total ?? 0}`);
+                for (const issue of issues) {
+                    const assignee = issue.fields.assignee?.displayName ?? 'Unassigned';
+                    lines.push(`   - [${issue.key}] ${issue.fields.summary} | ${issue.fields.status.name} | ${assignee} | ${this.issueUrl(issue.key)}`);
+                }
+                if ((issueData?.total ?? 0) > issues.length) {
+                    lines.push(`   ...and ${(issueData?.total ?? 0) - issues.length} more (adjust issueStartAt/issueMaxResults).`);
+                }
+            }
+            lines.push('');
+        });
+        const sprintRangeEnd = sprintStartAt + sprints.values.length;
+        if (!sprints.isLast) {
+            lines.push(`More sprints available: use sprintStartAt=${sprintRangeEnd}.`);
+        }
+        return text(lines.join('\n').trimEnd());
+    }
+    async createIssue(args) {
+        const data = await this.createIssueInternal(args);
         if (!data)
             return text('Issue created.');
-        return text(`Created ${data.key}.`);
+        const url = this.issueUrl(data.key);
+        if (args.sprintId !== undefined) {
+            await this.addIssuesToSprintInternal(args.sprintId, [data.key]);
+            return text(`Created ${data.key} and added it to sprint ${args.sprintId}.\n${url}`);
+        }
+        return text(`Created ${data.key}.\n${url}`);
     }
     async updateIssue(args) {
-        const fields = {};
-        if (args.summary !== undefined)
-            fields.summary = args.summary;
-        if (args.description !== undefined)
-            fields.description = args.description;
-        if (args.assignee !== undefined)
-            fields.assignee = { name: args.assignee };
-        if (args.priority !== undefined)
-            fields.priority = { name: args.priority };
-        if (Object.keys(fields).length === 0)
+        const hasFieldUpdates = await this.updateIssueFieldsInternal(args);
+        if (!hasFieldUpdates && args.sprintId === undefined)
             return text('Nothing to update.');
-        await this.request('PUT', `/issue/${args.issueKey}`, { fields });
-        return text(`Updated ${args.issueKey}.`);
+        if (args.sprintId !== undefined) {
+            await this.addIssuesToSprintInternal(args.sprintId, [args.issueKey]);
+        }
+        if (hasFieldUpdates && args.sprintId !== undefined) {
+            return text(`Updated ${args.issueKey} and added it to sprint ${args.sprintId}.\n${this.issueUrl(args.issueKey)}`);
+        }
+        if (hasFieldUpdates) {
+            return text(`Updated ${args.issueKey}.\n${this.issueUrl(args.issueKey)}`);
+        }
+        return text(`Added ${args.issueKey} to sprint ${args.sprintId}.\n${this.issueUrl(args.issueKey)}`);
+    }
+    async addIssuesToSprint(args) {
+        const keys = new Set();
+        if (args.issueKey?.trim())
+            keys.add(args.issueKey.trim());
+        for (const issueKey of args.issueKeys ?? []) {
+            const trimmed = issueKey.trim();
+            if (trimmed)
+                keys.add(trimmed);
+        }
+        if (keys.size === 0) {
+            throw new Error('Provide issueKey or issueKeys with at least one Jira issue key.');
+        }
+        const issueKeys = Array.from(keys);
+        await this.addIssuesToSprintInternal(args.sprintId, issueKeys);
+        if (issueKeys.length === 1) {
+            return text(`Added ${issueKeys[0]} to sprint ${args.sprintId}.\n${this.issueUrl(issueKeys[0])}`);
+        }
+        const lines = [
+            `Added ${issueKeys.length} issue(s) to sprint ${args.sprintId}.`,
+            ...issueKeys.map((issueKey) => `${issueKey}: ${this.issueUrl(issueKey)}`),
+        ];
+        return text(lines.join('\n'));
+    }
+    async mutateIssue(args) {
+        let issueKey = args.issueKey?.trim();
+        const actions = [];
+        if (args.create) {
+            const created = await this.createIssueInternal(args.create);
+            if (!created)
+                throw new Error('Issue creation did not return an issue key.');
+            issueKey = created.key;
+            actions.push('created issue');
+        }
+        if (!issueKey) {
+            throw new Error('Provide issueKey, or provide create with issueType and summary.');
+        }
+        if (args.update) {
+            const updated = await this.updateIssueFieldsInternal({ issueKey, ...args.update });
+            if (updated)
+                actions.push('updated fields');
+        }
+        if (args.sprintId !== undefined) {
+            await this.addIssuesToSprintInternal(args.sprintId, [issueKey]);
+            actions.push(`added to sprint ${args.sprintId}`);
+        }
+        if (args.transitionId || args.transitionName) {
+            const transitionId = await this.resolveTransitionId(issueKey, args.transitionId, args.transitionName);
+            await this.transitionIssueInternal(issueKey, transitionId);
+            actions.push(`transitioned via ${transitionId}`);
+        }
+        if (args.comment !== undefined) {
+            await this.request('POST', `/issue/${issueKey}/comment`, { body: validateCommentBody(args.comment) });
+            actions.push('added comment');
+        }
+        if (actions.length === 0) {
+            return text('Nothing to mutate.');
+        }
+        return text(`Mutated ${issueKey}: ${actions.join(', ')}.\n${this.issueUrl(issueKey)}`);
     }
     async getComments(args) {
         const { issueKey, maxResults = 50, startAt = 0 } = args;
@@ -261,25 +545,8 @@ export class JiraClient {
         return text(`Comment added to ${args.issueKey}.`);
     }
     async transitionIssue(args) {
-        let transitionId = args.transitionId;
-        if (!transitionId) {
-            const requestedName = args.transitionName?.trim();
-            if (!requestedName) {
-                throw new Error('Provide transitionId or transitionName');
-            }
-            const data = await this.request('GET', `/issue/${args.issueKey}/transitions`);
-            const transitions = data?.transitions ?? [];
-            const lowered = requestedName.toLowerCase();
-            const match = transitions.find((t) => t.name.toLowerCase() === lowered);
-            if (!match) {
-                const available = transitions.map((t) => t.name).join(', ') || '(none)';
-                throw new Error(`Transition "${requestedName}" not found for ${args.issueKey}. Available: ${available}`);
-            }
-            transitionId = match.id;
-        }
-        await this.request('POST', `/issue/${args.issueKey}/transitions`, {
-            transition: { id: transitionId },
-        });
-        return text(`Transitioned ${args.issueKey} using transition ${transitionId}.`);
+        const transitionId = await this.resolveTransitionId(args.issueKey, args.transitionId, args.transitionName);
+        await this.transitionIssueInternal(args.issueKey, transitionId);
+        return text(`Transitioned ${args.issueKey} using transition ${transitionId}.\n${this.issueUrl(args.issueKey)}`);
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stubbedev/atlassian-mcp",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "MCP server for self-hosted Jira and Bitbucket",
   "type": "module",
   "main": "dist/index.js",