@thammarongg/jira-mcp 0.3.0 → 0.5.0

package/dist/status.js

@@ -0,0 +1,81 @@
+import { AGENTS, hasAgentEntry, PACKAGE_VERSION, readAgentEnv } from "./agents.js";
+const REGISTRY_URL = "https://registry.npmjs.org/@thammarongg/jira-mcp/latest";
+function accountOf(env) {
+    return env?.JIRA_EMAIL ?? env?.JIRA_USERNAME ?? "unknown account";
+}
+function baseUrlOf(env) {
+    return env?.JIRA_BASE_URL ?? "unknown URL";
+}
+function versionParts(version) {
+    const match = version.trim().replace(/^v/, "").match(/^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/);
+    if (!match)
+        return undefined;
+    return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+function isNewer(candidate, installed) {
+    const next = versionParts(candidate);
+    const current = versionParts(installed);
+    if (!next || !current)
+        return false;
+    for (let i = 0; i < next.length; i++) {
+        if (next[i] !== current[i])
+            return next[i] > current[i];
+    }
+    return false;
+}
+async function latestVersion() {
+    const controller = new AbortController();
+    let deadlineTimer;
+    try {
+        const request = fetch(REGISTRY_URL, { signal: controller.signal }).then(async (response) => {
+            if (!response.ok)
+                return undefined;
+            const data = await response.json();
+            if (!data || typeof data !== "object" || Array.isArray(data))
+                return undefined;
+            const version = data.version;
+            return typeof version === "string" && isNewer(version, PACKAGE_VERSION) ? version : undefined;
+        });
+        return await Promise.race([
+            request,
+            new Promise((_, reject) => {
+                deadlineTimer = setTimeout(() => {
+                    controller.abort();
+                    reject(new Error("registry request timed out"));
+                }, 2_000);
+            }),
+        ]);
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        if (deadlineTimer !== undefined)
+            clearTimeout(deadlineTimer);
+    }
+}
+function configuredAgents() {
+    return AGENTS.filter((agent) => hasAgentEntry(agent));
+}
+export async function renderStatus() {
+    const update = await latestVersion();
+    const configured = configuredAgents();
+    const configuredIds = new Set(configured.map((agent) => agent.id));
+    const notConfigured = AGENTS.filter((agent) => !configuredIds.has(agent.id));
+    const lines = [`Installed version: ${PACKAGE_VERSION}`];
+    if (update)
+        lines.push(`update available: ${PACKAGE_VERSION} -> ${update}`);
+    lines.push("", "Configured agents:");
+    if (configured.length === 0) {
+        lines.push("  none");
+    }
+    else {
+        for (const agent of configured) {
+            const env = readAgentEnv(agent);
+            lines.push(`  - ${agent.label}: ${agent.path} — ${baseUrlOf(env)} (${accountOf(env)})`);
+        }
+    }
+    lines.push(`Not configured: ${notConfigured.length > 0 ? notConfigured.map((agent) => agent.label).join(", ") : "none"}`);
+    lines.push("", "Commands:", "  install             Configure Jira for one or more agents", "  update              Refresh existing Jira entries from their own credentials", "  uninstall           Remove Jira entries from selected agents", "  --version, -v       Print the installed version", "  --help, -h          Show command help", "", "This command is the MCP server: agents run it over stdio with JIRA_* env vars; running it bare without those variables reports a missing JIRA_BASE_URL.");
+    return lines.join("\n");
+}

package/dist/tools/boards.js

@@ -3,15 +3,15 @@ import { run } from "../util.js";
 export function registerBoardTools(server, client) {
     server.registerTool("list_boards", {
         title: "List Jira boards",
-        description: "List Jira agile boards (scrum or kanban), optionally filtered by type, name, or project keys.",
+        description: "List Jira agile boards (scrum or kanban), optionally filtered by type, name, or one project key/ID.",
         inputSchema: {
             type: z.enum(["scrum", "kanban"]).optional().describe("Board type filter"),
             name: z.string().optional().describe("Filter by board name (partial match)"),
-            projectKeys: z.string().optional().describe("Comma-separated project keys, e.g. 'PROJ1,PROJ2'"),
+            projectKeys: z.string().optional().describe("Project key or ID (the Agile API accepts one projectKeyOrId value)"),
             maxResults: z.number().int().min(1).max(1000).default(50),
             startAt: z.number().int().min(0).default(0),
         },
-    }, async ({ type, name, projectKeys, maxResults, startAt }) => run(() => client.agileGet("/board", { type, name, projectKeys, maxResults, startAt })));
+    }, async ({ type, name, projectKeys, maxResults, startAt }) => run(() => client.agileGet("/board", { type, name, projectKeyOrId: projectKeys, maxResults, startAt })));
     server.registerTool("get_board", {
         title: "Get board",
         description: "Get a single Jira board by ID, including its projects, location, and settings.",

package/dist/tools/epics.js

@@ -2,13 +2,16 @@ import { z } from "zod";
 import { JiraApiError } from "../client.js";
 import { run } from "../util.js";
 import { searchIssues } from "../search.js";
+import { richText } from "../adf.js";
 const DEFAULT_EPIC_ISSUE_FIELDS = "key,summary,status,assignee";
 /**
  * The Agile epic endpoints (/rest/agile/1.0/epic/...) only understand classic
  * (company-managed) epics: on a team-managed ("next-gen") project they answer
- * HTTP 400 "The request contains a next-gen issue". There, an epic is an ordinary
- * issue and its children are linked by `parent`, so each tool falls back to the
- * plain issue/search APIs when the Agile call rejects the project style.
+ * HTTP 400 "The request contains a next-gen issue". Cloud issue listing uses
+ * the current Software 1.0 enhanced endpoint; Data Center uses Agile 1.0.
+ * There, an epic is an ordinary issue and its children are linked by `parent`,
+ * so each tool falls back to the plain issue/search APIs when the endpoint
+ * rejects the project style.
  */
 function isNextGenRejection(err) {
     return err instanceof JiraApiError && (err.status === 400 || err.status === 404);
@@ -50,7 +53,7 @@ export function registerEpicTools(server, client) {
     }));
     server.registerTool("get_epic_issues", {
         title: "Get epic issues",
-        description: "List the issues belonging to an epic. Falls back to a JQL 'parent = <epic>' search on team-managed projects, where the Agile epic API does not apply.",
+        description: "List the issues belonging to an epic. Cloud uses the current Software API enhanced endpoint; Data Center uses Agile 1.0. Falls back to a JQL 'parent = <epic>' search on team-managed projects, where the epic API does not apply.",
         inputSchema: {
             epicIdOrKey: z.string().describe("Epic key, e.g. PROJ-1, or numeric issue ID"),
             fields: z
@@ -66,11 +69,23 @@ export function registerEpicTools(server, client) {
         },
     }, async ({ epicIdOrKey, fields, maxResults, startAt, nextPageToken }) => run(() => {
         const issueFields = fields ?? DEFAULT_EPIC_ISSUE_FIELDS;
-        return withNextGenFallback(() => client.agileGet(`/epic/${encodeURIComponent(epicIdOrKey)}/issue`, {
-            fields: issueFields,
-            maxResults,
-            startAt,
-        }), () => searchIssues(client, {
+        return withNextGenFallback(() => {
+            if (client.isCloud) {
+                if (startAt > 0) {
+                    throw new Error("Jira Cloud Software epic issue paging uses nextPageToken, not startAt.");
+                }
+                return client.softwareGet(`/epic/${encodeURIComponent(epicIdOrKey)}/issue`, {
+                    fields: issueFields,
+                    maxResults,
+                    nextPageToken,
+                });
+            }
+            return client.agileGet(`/epic/${encodeURIComponent(epicIdOrKey)}/issue`, {
+                fields: issueFields,
+                maxResults,
+                startAt,
+            });
+        }, () => searchIssues(client, {
             // JQL `parent` accepts a key or a numeric issue ID.
             jql: `parent = ${epicIdOrKey} ORDER BY rank`,
             fields: issueFields,
@@ -85,7 +100,10 @@ export function registerEpicTools(server, client) {
         inputSchema: {
             projectKey: z.string().describe("Project key, e.g. PROJ"),
             name: z.string().describe("Epic name (used as the issue summary)"),
-            description: z.string().optional(),
+            description: z
+                .string()
+                .optional()
+                .describe("Plain text; converted to ADF on Cloud/v3. Markdown is not rendered."),
             issueType: z
                 .string()
                 .optional()
@@ -103,7 +121,7 @@ export function registerEpicTools(server, client) {
                 project: { key: projectKey },
                 summary: name,
                 issuetype: /^\d+$/.test(type) ? { id: type } : { name: type },
-                description,
+                description: richText(description, client.apiVersion),
                 assignee: assignee
                     ? client.apiVersion === "3"
                         ? { accountId: assignee }
@@ -130,7 +148,7 @@ export function registerEpicTools(server, client) {
     })));
     server.registerTool("get_epic_meta", {
         title: "Get epic meta",
-        description: "List the epic-level issue types available in a project (hierarchy level above Story/Task), with the fields required to create one.",
+        description: "List the epic-level issue types available in a project (hierarchy level above Story/Task). Use get_issue_create_meta for the fields required to create one.",
         inputSchema: {
             projectKey: z.string().describe("Project key, e.g. PROJ"),
         },

package/dist/tools/issues.js

@@ -1,7 +1,92 @@
 import { z } from "zod";
 import { run } from "../util.js";
 import { searchIssues } from "../search.js";
-const DEFAULT_ISSUE_FIELDS = "summary,description,status,assignee,reporter,issuetype,labels,components,priority,created,updated,due,project";
+import { richText, richTextFields, richTextUpdate } from "../adf.js";
+const DEFAULT_ISSUE_FIELDS = "summary,description,status,assignee,reporter,issuetype,labels,components,priority,created,updated,duedate,project";
+async function getIssueCreateMeta(client, projectKeys, issuetypeIds, expand) {
+    const projectFilter = new Set(projectKeys
+        ?.split(",")
+        .map((value) => value.trim())
+        .filter(Boolean));
+    const typeFilter = new Set(issuetypeIds
+        ?.split(",")
+        .map((value) => value.trim())
+        .filter(Boolean));
+    const includeFields = !expand || expand.includes("fields");
+    if (includeFields && projectFilter.size === 0) {
+        throw new Error("projectKeys is required when expand includes fields (the default); pass one or more project keys to bound metadata requests, or use expand=projects.issuetypes for issue-type summaries.");
+    }
+    const projects = projectFilter.size > 0
+        ? await mapWithConcurrency([...projectFilter], 4, async (key) => (await client.apiGet(`/project/${encodeURIComponent(key)}`)))
+        : await listProjectsForCreateMeta(client);
+    const result = [];
+    for (const project of projects) {
+        const projectIdOrKey = project.key ?? project.id;
+        if (!projectIdOrKey) {
+            result.push({ ...project, issuetypes: [] });
+            continue;
+        }
+        const issueTypePage = await client.apiGet(`/issue/createmeta/${encodeURIComponent(projectIdOrKey)}/issuetypes`, { maxResults: 200, startAt: 0 });
+        const issueTypes = issueTypesFromMeta(issueTypePage).filter((issueType) => typeFilter.size === 0 || typeFilter.has(issueType.id));
+        const enriched = includeFields
+            ? await mapWithConcurrency(issueTypes, 4, async (issueType) => {
+                const fieldPage = await client.apiGet(`/issue/createmeta/${encodeURIComponent(projectIdOrKey)}/issuetypes/${encodeURIComponent(issueType.id)}`, { maxResults: 200, startAt: 0 });
+                const fields = fieldsFromMeta(fieldPage);
+                return { ...issueType, expand: "fields", fields };
+            })
+            : issueTypes;
+        result.push({ ...project, expand: "issuetypes", issuetypes: enriched });
+    }
+    return { expand: "projects", projects: result };
+}
+async function mapWithConcurrency(values, limit, fn) {
+    const results = new Array(values.length);
+    let nextIndex = 0;
+    async function worker() {
+        const index = nextIndex++;
+        if (index >= values.length)
+            return;
+        results[index] = await fn(values[index], index);
+        return worker();
+    }
+    await Promise.all(Array.from({ length: Math.min(limit, values.length) }, () => worker()));
+    return results;
+}
+async function listProjectsForCreateMeta(client) {
+    if (client.isCloud) {
+        const page = (await client.apiGet("/project/search", { maxResults: 100, startAt: 0 }));
+        return page.values ?? [];
+    }
+    return (await client.apiGet("/project", { maxResults: 1000, startAt: 0 }));
+}
+function issueTypesFromMeta(value) {
+    if (Array.isArray(value))
+        return value;
+    if (!value || typeof value !== "object")
+        return [];
+    const object = value;
+    if (Array.isArray(object.issueTypes))
+        return object.issueTypes;
+    return typeof object.id === "string" && typeof object.name === "string"
+        ? [object]
+        : [];
+}
+function fieldsFromMeta(value) {
+    if (!value || typeof value !== "object")
+        return {};
+    const object = value;
+    if (Array.isArray(object.fields)) {
+        return Object.fromEntries(object.fields
+            .filter((field) => typeof field.key === "string" || typeof field.fieldId === "string")
+            .map((field) => [String(field.key ?? field.fieldId), field]));
+    }
+    if (object.fields && typeof object.fields === "object" && !Array.isArray(object.fields)) {
+        return object.fields;
+    }
+    if (typeof object.fieldId === "string")
+        return { [object.fieldId]: object };
+    return {};
+}
 export function registerIssueTools(server, client) {
     server.registerTool("get_issue", {
         title: "Get issue",
@@ -9,7 +94,10 @@ export function registerIssueTools(server, client) {
         inputSchema: {
             issueKey: z.string().describe("Issue key, e.g. PROJ-123"),
             fields: z.string().optional().describe(`Comma-separated fields (default: ${DEFAULT_ISSUE_FIELDS})`),
-            expand: z.string().optional().describe("Comma-separated expansions, e.g. renderedFields,versions,changelog"),
+            expand: z
+                .string()
+                .optional()
+                .describe("Comma-separated expansions, e.g. renderedFields,names,schema,transitions,editmeta,changelog"),
         },
     }, async ({ issueKey, fields, expand }) => run(() => client.apiGet(`/issue/${encodeURIComponent(issueKey)}`, { fields: fields ?? DEFAULT_ISSUE_FIELDS, expand })));
     server.registerTool("create_issue", {
@@ -19,12 +107,15 @@ export function registerIssueTools(server, client) {
             projectKey: z.string().describe("Project key, e.g. PROJ"),
             summary: z.string().describe("Issue summary"),
             issueType: z.string().describe("Issue type name or ID, e.g. Story, Task, Bug, or 10004"),
-            description: z.string().optional(),
+            description: z
+                .string()
+                .optional()
+                .describe("Plain text; converted to ADF on Cloud/v3. Markdown is not rendered."),
             assignee: z.string().optional().describe("Account ID on Cloud/v3, username on DC/v2"),
             reporter: z.string().optional().describe("Account ID on Cloud/v3, username on DC/v2"),
             labels: z.array(z.string()).optional(),
             components: z.array(z.string()).optional().describe("Component names"),
-            dueDate: z.string().optional().describe("Due date, e.g. 2026-09-30"),
+            dueDate: z.string().optional().describe("Due date, e.g. 2026-09-30 (sent to Jira as duedate)"),
             priority: z.string().optional().describe("Priority name, e.g. High"),
             parent: z.string().optional().describe("Parent issue key (for sub-tasks)"),
             customFields: z.record(z.string(), z.unknown()).optional().describe("Custom field IDs mapped to values"),
@@ -36,12 +127,12 @@ export function registerIssueTools(server, client) {
                 project: { key: projectKey },
                 summary,
                 issuetype: /^\d+$/.test(issueType) ? { id: issueType } : { name: issueType },
-                description,
+                description: richText(description, client.apiVersion),
                 assignee: assignee ? userRef(assignee) : undefined,
                 reporter: reporter ? userRef(reporter) : undefined,
                 labels,
                 components: components?.map((name) => ({ name })),
-                dueDate,
+                duedate: dueDate,
                 priority: priority ? { name: priority } : undefined,
                 parent: parent ? { key: parent } : undefined,
                 ...customFields,
@@ -53,10 +144,16 @@ export function registerIssueTools(server, client) {
         description: "Update an issue. Pass absolute values in fields (e.g. { summary: 'new' }) and/or relative changes in update (e.g. { labels: [{ add: 'x' }, { remove: 'y' }] }).",
         inputSchema: {
             issueKey: z.string().describe("Issue key, e.g. PROJ-123"),
-            fields: z.record(z.string(), z.unknown()).optional().describe("Field values to set"),
+            fields: z
+                .record(z.string(), z.unknown())
+                .optional()
+                .describe("Field values to set. Plain-text description/environment are converted to ADF on Cloud/v3."),
             update: z.record(z.string(), z.unknown()).optional().describe("Relative updates (add/remove operations)"),
         },
-    }, async ({ issueKey, fields, update }) => run(() => client.apiPut(`/issue/${encodeURIComponent(issueKey)}`, { fields, update })));
+    }, async ({ issueKey, fields, update }) => run(() => client.apiPut(`/issue/${encodeURIComponent(issueKey)}`, {
+        fields: richTextFields(fields, client.apiVersion),
+        update: richTextUpdate(update, client.apiVersion),
+    })));
     server.registerTool("delete_issue", {
         title: "Delete issue",
         description: "Delete an issue. This is destructive.",
@@ -96,20 +193,19 @@ export function registerIssueTools(server, client) {
     })));
     server.registerTool("get_issue_create_meta", {
         title: "Get issue create metadata",
-        description: "Discover valid projects, issue types, and their fields (with required flags) before creating an issue.",
+        description: "Discover valid projects, issue types, and their fields (with required flags) before creating an issue. Uses the current per-project metadata endpoints instead of the deprecated /issue/createmeta query form. Pass projectKeys when fields are expanded (the default) to bound requests; omit it only with expand=projects.issuetypes for issue-type summaries.",
         inputSchema: {
-            projectKeys: z.string().optional().describe("Comma-separated project keys to filter"),
+            projectKeys: z
+                .string()
+                .optional()
+                .describe("Comma-separated project keys; required when expand includes fields (the default)"),
             issuetypeIds: z.string().optional().describe("Comma-separated issue type IDs to filter"),
             expand: z
                 .string()
                 .optional()
                 .describe("Use 'projects.issuetypes.fields' for full field details (default)"),
         },
-    }, async ({ projectKeys, issuetypeIds, expand }) => run(() => client.apiGet("/issue/createmeta", {
-        projectKeys,
-        issuetypeIds,
-        expand: expand ?? "projects.issuetypes.fields",
-    })));
+    }, async ({ projectKeys, issuetypeIds, expand }) => run(() => getIssueCreateMeta(client, projectKeys, issuetypeIds, expand ?? "projects.issuetypes.fields")));
     server.registerTool("get_issue_transitions", {
         title: "Get issue transitions",
         description: "List the workflow transitions available for an issue.",
@@ -127,11 +223,11 @@ export function registerIssueTools(server, client) {
         },
     }, async ({ issueKey, transitionId, fields }) => run(() => client.apiPost(`/issue/${encodeURIComponent(issueKey)}/transitions`, {
         transition: { id: transitionId },
-        fields,
+        fields: richTextFields(fields, client.apiVersion),
     })));
     server.registerTool("assign_issue", {
         title: "Assign issue",
-        description: "Assign (or unassign, with an empty value) an issue to a user.",
+        description: "Assign (or unassign, with an empty value) an issue to a user. Uses PUT /issue/{key}/assignee with accountId on v3 and name on v2.",
         inputSchema: {
             issueKey: z.string().describe("Issue key, e.g. PROJ-123"),
             accountId: z.string().optional().describe("Account ID (Jira Cloud)"),
@@ -139,28 +235,26 @@ export function registerIssueTools(server, client) {
         },
     }, async ({ issueKey, accountId, name }) => run(() => {
         const body = {};
-        if (accountId)
-            body.accountId = accountId;
-        else if (name)
-            body.name = name;
-        else if (client.apiVersion === "3")
-            body.accountId = null;
-        else
-            body.name = null;
-        return client.apiPost(`/issue/${encodeURIComponent(issueKey)}/assignee`, body);
+        if (client.apiVersion === "3") {
+            body.accountId = accountId ?? name ?? null;
+        }
+        else {
+            body.name = name ?? accountId ?? null;
+        }
+        return client.apiPut(`/issue/${encodeURIComponent(issueKey)}/assignee`, body);
     }));
     server.registerTool("add_comment", {
         title: "Add comment",
         description: "Add a comment to an issue.",
         inputSchema: {
             issueKey: z.string().describe("Issue key, e.g. PROJ-123"),
-            body: z.string().describe("Comment text"),
+            body: z.string().describe("Comment text (plain text; converted to ADF on Cloud/v3, Markdown is not rendered)"),
             visibility: z
                 .object({ type: z.string(), value: z.string() })
                 .optional()
                 .describe("Comment visibility restriction"),
         },
-    }, async ({ issueKey, body, visibility }) => run(() => client.apiPost(`/issue/${encodeURIComponent(issueKey)}/comment`, { body, visibility })));
+    }, async ({ issueKey, body, visibility }) => run(() => client.apiPost(`/issue/${encodeURIComponent(issueKey)}/comment`, { body: richText(body, client.apiVersion), visibility })));
     server.registerTool("list_comments", {
         title: "List issue comments",
         description: "List comments on an issue.",
@@ -191,12 +285,16 @@ export function registerIssueTools(server, client) {
     }, async ({ issueKey, maxResults, startAt, orderBy }) => run(() => client.apiGet(`/issue/${encodeURIComponent(issueKey)}/worklog`, { maxResults, startAt, orderBy })));
     server.registerTool("add_worklog", {
         title: "Add worklog",
-        description: "Add a worklog (time spent) to an issue. timeSpent uses Jira format, e.g. '2h 30m' or '1d'.",
+        description: "Add a worklog (time spent) to an issue. started is optional and defaults to now when omitted; timeSpent uses Jira format, e.g. '2h 30m' or '1d'.",
         inputSchema: {
             issueKey: z.string().describe("Issue key, e.g. PROJ-123"),
             timeSpent: z.string().describe("Time spent, e.g. '1h 30m'"),
-            comment: z.string().optional(),
-            started: z.string().optional().describe("Start timestamp (ISO-8601)"),
+            comment: z.string().optional().describe("Worklog comment (plain text; converted to ADF on Cloud/v3)"),
+            started: z.string().optional().describe("Start timestamp (ISO-8601; Jira defaults it to now when omitted)"),
         },
-    }, async ({ issueKey, timeSpent, comment, started }) => run(() => client.apiPost(`/issue/${encodeURIComponent(issueKey)}/worklog`, { timeSpent, comment, started })));
+    }, async ({ issueKey, timeSpent, comment, started }) => run(() => client.apiPost(`/issue/${encodeURIComponent(issueKey)}/worklog`, {
+        timeSpent,
+        comment: richText(comment, client.apiVersion),
+        started,
+    })));
 }

package/dist/tools/projects.js

@@ -3,12 +3,14 @@ import { run } from "../util.js";
 export function registerProjectTools(server, client) {
     server.registerTool("list_projects", {
         title: "List projects",
-        description: "List all Jira projects visible to the current user.",
+        description: "List all Jira projects visible to the current user. Cloud uses paginated /project/search; Data Center uses /project.",
         inputSchema: {
             maxResults: z.number().int().min(1).max(1000).default(100),
             startAt: z.number().int().min(0).default(0),
         },
-    }, async ({ maxResults, startAt }) => run(() => client.apiGet("/project", { maxResults, startAt })));
+    }, async ({ maxResults, startAt }) => run(() => client.isCloud
+        ? client.apiGet("/project/search", { maxResults, startAt })
+        : client.apiGet("/project", { maxResults, startAt })));
     server.registerTool("get_project", {
         title: "Get project",
         description: "Get a single project by key or ID.",

package/dist/tools/sprints.js

@@ -29,7 +29,7 @@ export function registerSprintTools(server, client) {
             endDate: z.string().optional().describe("End date (ISO-8601)"),
             goal: z.string().optional().describe("Sprint goal"),
         },
-    }, async ({ boardId, name, startDate, endDate, goal }) => run(() => client.agilePost(`/board/${boardId}/sprint`, { name, startDate, endDate, goal })));
+    }, async ({ boardId, name, startDate, endDate, goal }) => run(() => client.agilePost("/sprint", { name, originBoardId: boardId, startDate, endDate, goal })));
     server.registerTool("update_sprint", {
         title: "Update sprint",
         description: "Update a sprint's name, goal, dates, or state (active/closed/future). Only provided fields are changed.",
@@ -51,7 +51,7 @@ export function registerSprintTools(server, client) {
     }, async ({ sprintId }) => run(() => client.agilePut(`/sprint/${sprintId}`, { state: "closed" })));
     server.registerTool("get_sprint_issues", {
         title: "Get sprint issues",
-        description: "List the issues in a sprint.",
+        description: "List the issues in a sprint. Cloud uses the current Software API enhanced endpoint with cursor paging; Data Center uses Agile 1.0 with startAt/total.",
         inputSchema: {
             sprintId: z.number().int().describe("Sprint ID"),
             fields: z
@@ -59,16 +59,13 @@ export function registerSprintTools(server, client) {
                 .optional()
                 .describe("Comma-separated issue fields to return (default: key, summary, status, assignee)"),
             maxResults: z.number().int().min(1).max(1000).default(100),
-            startAt: z.number().int().min(0).default(0),
+            startAt: z.number().int().min(0).default(0).describe("Offset paging, Data Center only; rejected on Cloud, use nextPageToken"),
+            nextPageToken: z.string().optional().describe("Jira Cloud only: cursor from the previous response"),
         },
-    }, async ({ sprintId, fields, maxResults, startAt }) => run(() => client.agileGet(`/sprint/${sprintId}/issue`, {
-        fields: fields ?? "key,summary,status,assignee",
-        maxResults,
-        startAt,
-    })));
+    }, async ({ sprintId, fields, maxResults, startAt, nextPageToken }) => run(() => getSprintIssues(client, sprintId, fields, maxResults, startAt, nextPageToken)));
     server.registerTool("get_sprint_view", {
         title: "Get sprint view",
-        description: "Full sprint view like the Jira UI: board details, the sprint, and its issues, in one call.",
+        description: "Full sprint view like the Jira UI: board details, the sprint, and its issues, in one call. Cloud issue results use Software API cursor paging; Data Center uses Agile 1.0 offset paging.",
         inputSchema: {
             boardId: z.number().int().describe("Board ID"),
             sprintId: z.number().int().describe("Sprint ID"),
@@ -77,26 +74,21 @@ export function registerSprintTools(server, client) {
                 .optional()
                 .describe("Comma-separated issue fields to return (default: key, summary, status, assignee)"),
             maxResults: z.number().int().min(1).max(1000).default(100),
-            startAt: z.number().int().min(0).default(0),
+            startAt: z.number().int().min(0).default(0).describe("Offset paging, Data Center only; rejected on Cloud, use nextPageToken"),
+            nextPageToken: z.string().optional().describe("Jira Cloud only: cursor from the previous response"),
         },
-    }, async ({ boardId, sprintId, fields, maxResults, startAt }) => run(async () => {
-        // Composed from three documented Agile endpoints; the old /rest/agile/1.0/rapid
-        // path this used to call is not a real endpoint and answered 404.
+    }, async ({ boardId, sprintId, fields, maxResults, startAt, nextPageToken }) => run(async () => {
         const [board, sprint, issues] = await Promise.all([
             client.agileGet(`/board/${boardId}`),
             client.agileGet(`/sprint/${sprintId}`),
-            client.agileGet(`/sprint/${sprintId}/issue`, {
-                fields: fields ?? "key,summary,status,assignee",
-                maxResults,
-                startAt,
-            }),
+            getSprintIssues(client, sprintId, fields, maxResults, startAt, nextPageToken),
         ]);
         return { board, sprint, issues };
     }));
     server.registerTool("get_backlog", {
         title: "Get board backlog",
         description: "List a board's backlog issues (in the board's filter, not in a sprint), ordered by rank. " +
-            "Uses the Agile API's own backlog endpoint, so it pages with startAt/total on both Cloud and Data Center.",
+            "On Cloud this uses the current Software API enhanced backlog endpoint and cursor paging; on Data Center it uses Agile 1.0 with startAt/total.",
         inputSchema: {
             boardId: z.number().int().describe("Board ID"),
             jql: z.string().optional().describe("Extra JQL to narrow the backlog, e.g. 'assignee IS EMPTY'"),
@@ -105,12 +97,38 @@ export function registerSprintTools(server, client) {
                 .optional()
                 .describe("Comma-separated issue fields to return (default: key, summary, status, assignee)"),
             maxResults: z.number().int().min(1).max(100).default(50),
-            startAt: z.number().int().min(0).default(0),
+            startAt: z.number().int().min(0).default(0).describe("Offset paging, Data Center only; rejected on Cloud, use nextPageToken"),
+            nextPageToken: z.string().optional().describe("Jira Cloud only: cursor from the previous response"),
         },
-    }, async ({ boardId, jql, fields, maxResults, startAt }) => run(() => client.agileGet(`/board/${boardId}/backlog`, {
+    }, async ({ boardId, jql, fields, maxResults, startAt, nextPageToken }) => run(() => getBacklog(client, boardId, jql, fields, maxResults, startAt, nextPageToken)));
+}
+async function getSprintIssues(client, sprintId, fields, maxResults, startAt, nextPageToken) {
+    const issueFields = fields ?? "key,summary,status,assignee";
+    if (client.isCloud) {
+        if (startAt > 0) {
+            throw new Error("Jira Cloud Software sprint issue paging uses nextPageToken, not startAt.");
+        }
+        return client.softwareGet(`/sprint/${sprintId}/issue`, { fields: issueFields, maxResults, nextPageToken });
+    }
+    return client.agileGet(`/sprint/${sprintId}/issue`, { fields: issueFields, maxResults, startAt });
+}
+async function getBacklog(client, boardId, jql, fields, maxResults, startAt, nextPageToken) {
+    const issueFields = fields ?? "key,summary,status,assignee";
+    if (client.isCloud) {
+        if (startAt > 0) {
+            throw new Error("Jira Cloud Software backlog paging uses nextPageToken, not startAt.");
+        }
+        return client.softwareGet(`/board/${boardId}/backlog`, {
+            jql,
+            fields: issueFields,
+            maxResults,
+            nextPageToken,
+        });
+    }
+    return client.agileGet(`/board/${boardId}/backlog`, {
         jql,
-        fields: fields ?? "key,summary,status,assignee",
+        fields: issueFields,
         maxResults,
         startAt,
-    })));
+    });
 }

package/dist/tools/users.js

@@ -29,7 +29,7 @@ export function registerUserTools(server, client) {
             if (!accountId) {
                 throw new Error("API v3 requires accountId for get_user. Use find_users to look up the account ID for a username.");
             }
-            return client.apiGet(`/user/${encodeURIComponent(accountId)}`);
+            return client.apiGet("/user", { accountId });
         }
         return client.apiGet("/user", { username: username ?? accountId });
     }));