@stubbedev/atlassian-mcp 0.1.1 → 0.1.5

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

@@ -1,4 +1,5 @@
 import { execSync } from 'child_process';
+const EMOJI_RE = /\p{Extended_Pictographic}/u;
 function safeExec(cmd) {
     try {
         return execSync(cmd, { encoding: 'utf-8' }).trim();
@@ -136,6 +137,16 @@ function formatBitbucketError(status, method, path, details) {
         return `${prefix}. Conflict (often stale version/state). Refresh and retry. ${details}`.trim();
     return details ? `${prefix}. ${details}` : prefix;
 }
+function validateCommentText(textValue) {
+    const trimmed = textValue.trim();
+    if (!trimmed) {
+        throw new Error('Bitbucket comment text must not be empty.');
+    }
+    if (EMOJI_RE.test(trimmed)) {
+        throw new Error('Bitbucket comments must not include emoji. Use concise plain text only.');
+    }
+    return trimmed;
+}
 export class BitbucketClient {
     baseUrl;
     headers;
@@ -510,7 +521,7 @@ export class BitbucketClient {
     }
     async addPrComment(args) {
         const { projectKey, repoSlug } = this.resolveProjectAndRepo(args.projectKey, args.repoSlug);
-        const body = { text: args.text };
+        const body = { text: validateCommentText(args.text) };
         if (args.parentCommentId)
             body.parent = { id: args.parentCommentId };
         const created = await this.request('POST', `/projects/${projectKey}/repos/${repoSlug}/pull-requests/${args.prId}/comments`, body);
@@ -531,7 +542,7 @@ export class BitbucketClient {
             throw new Error(`Comment #${args.commentId} not found.`);
         const body = {
             version: current.version,
-            text: args.text ?? current.text,
+            text: args.text !== undefined ? validateCommentText(args.text) : current.text,
         };
         if (args.state)
             body.state = args.state;

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.',
@@ -162,12 +272,12 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         },
         {
             name: 'jira_add_comment',
-            description: 'Use when you want to leave a comment on a Jira ticket.',
+            description: 'Use when you want to leave a comment on a Jira ticket. Keep comments concise, plain text, and free of filler. Never include emojis.',
             inputSchema: {
                 type: 'object',
                 properties: {
                     issueKey: { type: 'string', description: 'Jira issue key' },
-                    body: { type: 'string', description: 'Comment text (plain text or Jira wiki markup)' },
+                    body: { type: 'string', description: 'Concise comment text only. No filler. Do not include emojis.' },
                 },
                 required: ['issueKey', 'body'],
             },
@@ -406,7 +516,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         },
         {
             name: 'bitbucket_add_pr_comment',
-            description: 'Use when you want to add a PR review comment or reply to an existing thread. You can pass projectKey/repoSlug or project/repo.',
+            description: 'Use when you want to add a PR review comment or reply to an existing thread. Keep comments concise, plain text, and free of filler. Never include emojis. You can pass projectKey/repoSlug or project/repo.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -416,14 +526,14 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                     repo: { type: 'string', description: 'Alias for repoSlug' },
                     prId: { type: 'number', description: 'Pull request number (PR ID)' },
                     parentCommentId: { type: 'number', description: 'Parent comment ID for reply mode (optional)' },
-                    text: { type: 'string', description: 'Comment text' },
+                    text: { type: 'string', description: 'Concise comment text only. No filler. Do not include emojis.' },
                 },
                 required: ['prId', 'text'],
             },
         },
         {
             name: 'bitbucket_update_pr_comment',
-            description: 'Use when you want to edit PR comments, resolve/reopen them, or mark comments as task-style BLOCKER items. You can pass projectKey/repoSlug or project/repo.',
+            description: 'Use when you want to edit PR comments, resolve/reopen them, or mark comments as task-style BLOCKER items. Keep comments concise, plain text, and free of filler. Never include emojis. You can pass projectKey/repoSlug or project/repo.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -433,7 +543,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                     repo: { type: 'string', description: 'Alias for repoSlug' },
                     prId: { type: 'number', description: 'Pull request number (PR ID)' },
                     commentId: { type: 'number', description: 'Comment ID to update' },
-                    text: { type: 'string', description: 'New comment text (optional)' },
+                    text: { type: 'string', description: 'New concise comment text only. No filler. Do not include emojis. (optional)' },
                     state: { type: 'string', enum: ['OPEN', 'RESOLVED'], description: 'Comment state (optional)' },
                     severity: { type: 'string', enum: ['NORMAL', 'BLOCKER'], description: 'Comment severity (optional). BLOCKER marks it as a task/checklist item.' },
                 },
@@ -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

@@ -1,5 +1,6 @@
 import { execSync } from 'child_process';
 const JIRA_KEY_IN_BRANCH_RE = /\b([A-Z][A-Z0-9]+)-\d+\b/;
+const EMOJI_RE = /\p{Extended_Pictographic}/u;
 function text(t) {
     return { content: [{ type: 'text', text: t }] };
 }
@@ -76,6 +77,16 @@ function formatJiraError(status, method, path, details) {
         return `${prefix}. Conflict. Refresh and retry. ${details}`.trim();
     return details ? `${prefix}. ${details}` : prefix;
 }
+function validateCommentBody(body) {
+    const trimmed = body.trim();
+    if (!trimmed) {
+        throw new Error('Jira comment body must not be empty.');
+    }
+    if (EMOJI_RE.test(trimmed)) {
+        throw new Error('Jira comments must not include emoji. Use concise plain text only.');
+    }
+    return trimmed;
+}
 export class JiraClient {
     baseUrl;
     headers;
@@ -87,8 +98,8 @@ export class JiraClient {
             Accept: 'application/json',
         };
     }
-    async request(method, path, body) {
-        const url = `${this.baseUrl}/rest/api/2${path}`;
+    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);
@@ -100,6 +111,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;
@@ -167,6 +239,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}`;
+        });
+        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}:\n${lines.join('\n')}`);
+    }
     async searchUsers(args) {
         const params = new URLSearchParams({
             username: args.query,
@@ -200,38 +292,219 @@ 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}`,
+            `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)'}`,
+            `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}` : ''}`);
+            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}`);
+                }
+                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.');
+        if (args.sprintId !== undefined) {
+            await this.addIssuesToSprintInternal(args.sprintId, [data.key]);
+            return text(`Created ${data.key} and added it to sprint ${args.sprintId}.`);
+        }
         return text(`Created ${data.key}.`);
     }
     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}.`);
+        }
+        if (hasFieldUpdates) {
+            return text(`Updated ${args.issueKey}.`);
+        }
+        return text(`Added ${args.issueKey} to sprint ${args.sprintId}.`);
+    }
+    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);
+        return text(`Added ${issueKeys.length} issue(s) to sprint ${args.sprintId}.`);
+    }
+    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(', ')}.`);
     }
     async getComments(args) {
         const { issueKey, maxResults = 50, startAt = 0 } = args;
@@ -246,29 +519,12 @@ export class JiraClient {
         return text(`${data.total} comment(s) on ${issueKey}${page}:\n\n${blocks.join('\n\n')}`);
     }
     async addComment(args) {
-        await this.request('POST', `/issue/${args.issueKey}/comment`, { body: args.body });
+        await this.request('POST', `/issue/${args.issueKey}/comment`, { body: validateCommentBody(args.body) });
         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 },
-        });
+        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}.`);
     }
 }

package/package.json

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