@thammarongg/jira-mcp 0.2.0 → 0.4.0

package/README.md

@@ -101,7 +101,7 @@ npm run build
 
 | Variable | Required | Description |
 | --- | --- | --- |
-| `JIRA_BASE_URL` | yes | `https://your-org.atlassian.net` (Cloud) or `https://jira.yourcompany.com` (DC) |
+| `JIRA_BASE_URL` | yes | `https://your-org.atlassian.net` (Cloud) or `https://jira.yourcompany.com` (DC); a DC context path such as `/jira` is preserved |
 | `JIRA_EMAIL` | Cloud | Your Atlassian account email |
 | `JIRA_API_TOKEN` | yes | API token (Cloud: id.atlassian.com → Security → API tokens; DC: personal access token) |
 | `JIRA_USERNAME` | DC | Username (alternative to `JIRA_EMAIL`) |
@@ -160,29 +160,30 @@ mkdir -p ~/.agents/skills/jira && cp skill/SKILL.md ~/.agents/skills/jira/
 
 ## Tools
 
-### Boards & sprints (Agile API)
+### Boards & sprints (Agile + Software APIs)
 
 | Tool | Description |
 | --- | --- |
-| `list_boards` | List boards (filter by type/name/project) |
+| `list_boards` | List boards (filter by type/name/project key or ID) |
 | `get_board` | Board details incl. projects |
 | `list_sprints` | Sprints on a board (state: active/closed/future) |
 | `get_sprint` | Sprint details |
 | `create_sprint` | New sprint on a board |
 | `update_sprint` | Rename, reschedule, change goal/state |
 | `close_sprint` | Close a sprint |
-| `get_sprint_issues` | Issues in a sprint |
-| `get_sprint_view` | Full UI-like sprint view (rapid view: board + sprint + issues) |
-| `get_backlog` | Board backlog via JQL (`sprint IS NONE ORDER BY rank`) |
+| `get_sprint_issues` | Issues in a sprint (Cloud cursor or DC offset paging) |
+| `get_sprint_view` | Full UI-like sprint view (board + sprint + issues in one call) |
+| `get_backlog` | Board backlog (Cloud Software enhanced or DC Agile, rank-ordered) |
 
 ### Epics
 
 | Tool | Description |
 | --- | --- |
-| `list_epics` / `get_epic` / `get_epic_issues` | Read epics |
-| `create_epic` | New epic on a board |
-| `move_issue_to_epic` | Add an issue to an epic |
-| `get_epic_meta` | Epic issue-type metadata |
+| `list_epics` | Epics on a board (optionally filtered by `done`) |
+| `get_epic` / `get_epic_issues` | Read an epic and its children (works on team-managed projects) |
+| `create_epic` | New epic in a project |
+| `move_issue_to_epic` | Add issues to an epic (sets `parent` on team-managed) |
+| `get_epic_meta` | Epic-level issue types available in a project |
 
 ### Issues
 
@@ -192,11 +193,11 @@ mkdir -p ~/.agents/skills/jira && cp skill/SKILL.md ~/.agents/skills/jira/
 | `create_issue` | Create (supports custom fields) |
 | `update_issue` | Set fields and/or relative `update` ops |
 | `delete_issue` | Delete |
-| `search_issues` | **JQL search** with pagination |
-| `get_issue_create_meta` | Discover projects/types/required fields |
+| `search_issues` | **JQL search** — enhanced search (`/search/jql`) on Cloud, legacy `/search` on Data Center |
+| `get_issue_create_meta` | Discover projects/types/required fields (current per-project metadata endpoints) |
 | `get_issue_transitions` / `transition_issue` | Workflow transitions |
 | `assign_issue` | Assign/unassign |
-| `add_comment` / `list_comments` / `delete_comment` | Comments |
+| `add_comment` / `list_comments` / `delete_comment` | Comments (plain text in, auto-converted to ADF on Cloud/v3) |
 | `get_issue_worklogs` / `add_worklog` | Time tracking |
 
 ### Projects, users, meta
@@ -218,6 +219,17 @@ mkdir -p ~/.agents/skills/jira && cp skill/SKILL.md ~/.agents/skills/jira/
 5. `create_issue` / `transition_issue` / `add_comment` to act
 6. Anything else → `jira_api`
 
+## Rich text and ADF
+
+Jira Cloud REST v3 stores descriptions, comment bodies and worklog comments as
+[Atlassian Document Format](https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/),
+not plain strings. Pass plain text to `create_issue`, `create_epic`,
+`update_issue`, `transition_issue`, `add_comment` and `add_worklog` — the server
+wraps it in ADF when `JIRA_API_VERSION` is `3`, and leaves it alone on v2 (Data
+Center), where wiki markup applies. Blank lines start a new paragraph and single
+newlines become line breaks; **Markdown is not rendered** (`**bold**` shows
+literally). Already-built ADF objects are passed through untouched.
+
 ## Development
 
 ```bash
@@ -230,8 +242,17 @@ node scripts/smoke.mjs   # stdio handshake + tools/list smoke test
 ## Notes & limitations
 
 - Auth is HTTP Basic (email+token for Cloud, username+token/password for DC) — the standard for Jira REST.
-- Pagination: list tools return Jira's native `startAt`/`maxResults`/`total`; pass `startAt` to page.
-- `get_backlog` is implemented via JQL since the Agile API has no direct backlog endpoint.
+- `JIRA_BASE_URL` may include a Data Center context path (for example `https://jira.example.com/jira`); it is retained when resolving `/rest/...` endpoints.
+- Pagination: most list tools return Jira's native `startAt`/`maxResults`/`total`; pass `startAt` to page.
+- Platform routing: Cloud-only enhanced Software reads use `/rest/software/1.0` for backlog, sprint issues, and epic issues (cursor `nextPageToken`); Data Center uses the corresponding Agile 1.0 endpoints with `startAt`/`total`. `list_boards` passes its project filter as the Agile API's singular `projectKeyOrId` parameter.
+- `create_sprint` uses the documented top-level Agile `POST /rest/agile/1.0/sprint` route and sends the selected board as `originBoardId`.
+- JQL search on **Jira Cloud** uses `/rest/api/3/search/jql`, since Atlassian removed `GET /rest/api/{2,3}/search` on 2025-05-01 ([CHANGE-2046](https://developer.atlassian.com/changelog/#CHANGE-2046) — the old endpoint now returns HTTP 410). Consequences for `search_issues` on Cloud: the JQL must be **bounded** (include a restriction such as `project`, `assignee`, or `key`), the response carries **no `total`**, and paging is by cursor — pass the returned `nextPageToken` back and stop when `isLast` is true. `startAt` is rejected there rather than silently ignored, and `includeApproximateTotal: true` adds an approximate match count via `/search/approximate-count`.
+- Jira **Data Center** keeps the legacy `/search` endpoint with `startAt`/`total`; if a Cloud site on a custom domain is misdetected as DC, a 410 from `/search` transparently retries against `/search/jql`.
+- `get_issue_create_meta` composes the current per-project and per-issue-type metadata endpoints (`/issue/createmeta/{project}/issuetypes` and `/issue/createmeta/{project}/issuetypes/{issueType}`), because the old `/issue/createmeta` query form is deprecated on Cloud and removed from Jira Data Center 9.0+. Its output keeps the familiar `projects[].issuetypes[].fields` shape. Pass `projectKeys` when fields are expanded (the default); omitting it is allowed only with `expand: "projects.issuetypes"` for bounded issue-type summaries. Project metadata is fetched with a fixed concurrency of four, and issue-type field metadata is likewise limited to four concurrent requests.
+- `get_backlog`, `get_sprint_issues`, and `get_epic_issues` use Cloud's current Software enhanced endpoints with cursor paging; pass `nextPageToken` for the next page. Data Center keeps Agile 1.0 and `startAt`/`total`. The older Cloud Agile issue-list endpoints remain available but are deprecated.
 - Rapid view IDs are computed as `boardId * 10^13 + sprintId` (Jira's documented convention).
 - Comment bodies use the `body` field on both Cloud (v3) and Data Center (v2).
+- User references use `accountId` on API v3/Cloud and `name` on API v2/Data Center. `get_user` calls `/user?accountId=...` on v3; the v3 path form `/user/{accountId}` is not a current endpoint. `create_issue`'s `dueDate` input is sent as Jira's `duedate` field; `add_worklog` accepts an optional `started` timestamp and Jira defaults it to now when omitted.
+- Epics: the Agile epic API (`/rest/agile/1.0/epic/...`) only understands company-managed epics and returns HTTP 400 on team-managed ("next-gen") projects. `get_epic`, `get_epic_issues`, and `move_issue_to_epic` detect that and fall back to the issue/search APIs, where an epic is an ordinary issue linked to its children by `parent`.
+- Jira Data Center exposes platform REST API v2/latest, not `/rest/api/3`. Leave `JIRA_API_VERSION` at its default (`2`) for DC; forcing `3` against a DC host is unsupported and causes the server to request unavailable `/rest/api/3/...` routes. Cloud-vs-DC endpoint routing is based on the detected deployment (`*.atlassian.net` is Cloud), while field representations are based on the selected API version.
 - `jira_api` paths must resolve under `/rest/` — paths that would escape it (e.g. via `..` segments) are rejected, and `?`/`#` must be passed via `query`.

package/dist/adf.js

@@ -0,0 +1,71 @@
+/**
+ * Jira Cloud REST v3 takes rich-text fields (descriptions, comment bodies,
+ * worklog comments) as Atlassian Document Format, not plain strings. v2 (Data
+ * Center) still takes wiki-markup strings, so every conversion is gated on the
+ * API version the client is talking to.
+ */
+/** Wrap plain text in a minimal ADF document. Markdown is not interpreted. */
+export function toAdfDoc(text) {
+    const content = text
+        .replace(/\r\n/g, "\n")
+        .split(/\n{2,}/)
+        .map((block) => block.split("\n").filter((line) => line !== ""))
+        .filter((lines) => lines.length > 0)
+        .map((lines) => ({
+        type: "paragraph",
+        content: lines.flatMap((line, i) => i === 0 ? [{ type: "text", text: line }] : [{ type: "hardBreak" }, { type: "text", text: line }]),
+    }));
+    return { type: "doc", version: 1, content };
+}
+/**
+ * Convert a rich-text value for the given API version. Strings become ADF on
+ * v3; anything else (a caller-built ADF doc, undefined) passes through.
+ */
+export function richText(value, apiVersion) {
+    if (apiVersion !== "3" || typeof value !== "string")
+        return value;
+    return toAdfDoc(value);
+}
+const RICH_TEXT_FIELDS = ["description", "environment"];
+/** Convert the known rich-text keys of an issue `fields` payload in place-safe fashion. */
+export function richTextFields(fields, apiVersion) {
+    if (!fields || apiVersion !== "3")
+        return fields;
+    let out;
+    for (const key of RICH_TEXT_FIELDS) {
+        if (typeof fields[key] === "string") {
+            out ??= { ...fields };
+            out[key] = toAdfDoc(fields[key]);
+        }
+    }
+    return out ?? fields;
+}
+/**
+ * Convert comment bodies inside an issue `update` payload, e.g.
+ * { comment: [{ add: { body: "text" } }] }.
+ */
+export function richTextUpdate(update, apiVersion) {
+    if (!update || apiVersion !== "3")
+        return update;
+    const ops = update.comment;
+    if (!Array.isArray(ops))
+        return update;
+    let changed = false;
+    const comment = ops.map((op) => {
+        if (!op || typeof op !== "object")
+            return op;
+        const entry = op;
+        let next;
+        for (const verb of ["add", "edit"]) {
+            const payload = entry[verb];
+            if (payload && typeof payload === "object" && typeof payload.body === "string") {
+                next ??= { ...entry };
+                const inner = payload;
+                next[verb] = { ...inner, body: toAdfDoc(inner.body) };
+                changed = true;
+            }
+        }
+        return next ?? entry;
+    });
+    return changed ? { ...update, comment } : update;
+}

package/dist/client.js

@@ -21,7 +21,9 @@ export class JiraClient {
     }
     async request(method, path, opts = {}) {
         const url = new URL(`${this.cfg.baseUrl}${path.startsWith("/") ? path : `/${path}`}`);
-        if (!url.pathname.startsWith("/rest/")) {
+        const basePath = new URL(this.cfg.baseUrl).pathname.replace(/\/+$/, "");
+        const restPrefix = `${basePath}/rest/`;
+        if (!url.pathname.startsWith(restPrefix)) {
             throw new Error(`Jira API path must start with /rest/ (resolved to ${url.pathname})`);
         }
         if (opts.query) {
@@ -81,6 +83,9 @@ export class JiraClient {
     agilePut(path, body) {
         return this.request("PUT", `/rest/agile/1.0${path}`, { body });
     }
+    softwareGet(path, query) {
+        return this.request("GET", `/rest/software/1.0${path}`, { query });
+    }
 }
 function extractErrorMessage(body) {
     if (typeof body === "string" && body.trim()) {

package/dist/config.js

@@ -8,7 +8,7 @@ export function loadConfig(env = process.env) {
         const url = new URL(rawBase);
         if (!/^https?:$/.test(url.protocol))
             throw new Error("bad protocol");
-        baseUrl = `${url.protocol}//${url.host}`;
+        baseUrl = `${url.protocol}//${url.host}${url.pathname.replace(/\/+$/, "")}`;
     }
     catch {
         throw new Error(`JIRA_BASE_URL is not a valid URL: ${rawBase}`);

package/dist/index.js

@@ -19,7 +19,7 @@ async function main() {
     }
     const config = loadConfig();
     const client = new JiraClient(config);
-    const server = new McpServer({ name: "jira", version: "0.1.0" });
+    const server = new McpServer({ name: "jira", version: "0.4.0" });
     registerBoardTools(server, client);
     registerSprintTools(server, client);
     registerEpicTools(server, client);

package/dist/install.js

@@ -223,10 +223,16 @@ function askPassword(p, promptText) {
                     finish("");
                     return;
                 }
-                if (ch === "\u007f" || ch === "\b")
-                    value = value.slice(0, -1);
-                else if (ch >= " ")
+                if (ch === "\u007f" || ch === "\b") {
+                    if (value.length > 0) {
+                        value = value.slice(0, -1);
+                        process.stdout.write("\b \b");
+                    }
+                }
+                else if (ch >= " ") {
                     value += ch;
+                    process.stdout.write("*");
+                }
             }
         };
         const onEnd = () => finish(null);
@@ -344,7 +350,7 @@ async function promptCredentials(p) {
     const user = (await p.ask(isCloud ? "Atlassian email: " : "Data Center username: ")).trim();
     if (!user)
         throw new Error(isCloud ? "Email is required" : "Username is required");
-    const secret = await askPassword(p, isCloud ? "API token (hidden, from id.atlassian.com): " : "API token / app password (hidden): ");
+    const secret = await askPassword(p, isCloud ? "API token (masked, from id.atlassian.com): " : "API token / app password (masked): ");
     if (!secret)
         throw new Error("API token is required");
     const env = { JIRA_BASE_URL: baseUrl };

package/dist/search.js

@@ -0,0 +1,56 @@
+import { JiraApiError } from "./client.js";
+/**
+ * Jira Cloud removed GET /rest/api/{2,3}/search on 2025-05-01 (CHANGE-2046); it now
+ * answers HTTP 410. The replacement, /search/jql ("enhanced search"), differs in three
+ * ways that matter to callers: it pages with an opaque nextPageToken instead of startAt,
+ * it returns no total, and it rejects unbounded JQL. Jira Data Center still only has the
+ * legacy endpoint, so both live here behind one call.
+ */
+export class UnsupportedParameterError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "UnsupportedParameter";
+    }
+}
+export async function searchIssues(client, params) {
+    if (!client.isCloud) {
+        try {
+            return await legacySearch(client, params);
+        }
+        catch (err) {
+            // A Cloud site on a custom domain looks like Data Center to loadConfig, so let the
+            // removal response itself route us to the new endpoint.
+            if (!(err instanceof JiraApiError && err.status === 410))
+                throw err;
+        }
+    }
+    return enhancedSearch(client, params);
+}
+function legacySearch(client, params) {
+    return client.apiGet("/search", {
+        jql: params.jql,
+        fields: params.fields,
+        maxResults: params.maxResults,
+        startAt: params.startAt ?? 0,
+        expand: params.expand,
+    });
+}
+async function enhancedSearch(client, params) {
+    if (params.startAt !== undefined && params.startAt > 0) {
+        // /search/jql accepts startAt and silently ignores it, which would hand back page 1
+        // forever. Refusing is better than looping over the same issues.
+        throw new UnsupportedParameterError("Jira Cloud's enhanced search (/search/jql) pages with a cursor, not an offset: startAt is ignored. " +
+            "Omit startAt and pass nextPageToken from the previous response to get the next page.");
+    }
+    const page = await client.apiGet("/search/jql", {
+        jql: params.jql,
+        fields: params.fields,
+        maxResults: params.maxResults,
+        nextPageToken: params.nextPageToken,
+        expand: params.expand,
+    });
+    if (!params.includeApproximateTotal || !page || typeof page !== "object")
+        return page;
+    const counted = (await client.apiPost("/search/approximate-count", { jql: params.jql }));
+    return { ...page, approximateTotal: counted?.count };
+}

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

@@ -1,61 +1,168 @@
 import { z } from "zod";
-import { rapidViewId, run } from "../util.js";
+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". 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);
+}
+async function withNextGenFallback(agile, fallback) {
+    try {
+        return await agile();
+    }
+    catch (err) {
+        if (!isNextGenRejection(err))
+            throw err;
+        return fallback();
+    }
+}
 export function registerEpicTools(server, client) {
     server.registerTool("list_epics", {
         title: "List epics",
-        description: "List epics visible in a board's sprint view (agile rapid view).",
+        description: "List the epics on a board, including whether each one is done.",
         inputSchema: {
             boardId: z.number().int().describe("Board ID"),
-            sprintId: z.number().int().describe("Sprint ID (any sprint on the board works)"),
+            done: z.boolean().optional().describe("Filter by completion state; omit for all epics"),
             maxResults: z.number().int().min(1).max(1000).default(100),
             startAt: z.number().int().min(0).default(0),
         },
-    }, async ({ boardId, sprintId, maxResults, startAt }) => run(() => client.agileGet(`/rapid/${rapidViewId(boardId, sprintId)}/epic`, { maxResults, startAt })));
+    }, async ({ boardId, done, maxResults, startAt }) => run(() => client.agileGet(`/board/${boardId}/epic`, {
+        done: done === undefined ? undefined : String(done),
+        maxResults,
+        startAt,
+    })));
     server.registerTool("get_epic", {
         title: "Get epic",
-        description: "Get a single epic by its issue ID (numeric).",
+        description: "Get a single epic by key (e.g. PROJ-1) or numeric issue ID. Falls back to the issue API for team-managed projects, where epics are ordinary issues.",
         inputSchema: {
-            epicId: z.number().int().describe("Epic issue ID (numeric, not the key)"),
+            epicIdOrKey: z.string().describe("Epic key, e.g. PROJ-1, or numeric issue ID"),
         },
-    }, async ({ epicId }) => run(() => client.agileGet(`/epic/${epicId}`)));
+    }, async ({ epicIdOrKey }) => run(() => {
+        const id = encodeURIComponent(epicIdOrKey);
+        return withNextGenFallback(() => client.agileGet(`/epic/${id}`), () => client.apiGet(`/issue/${id}`, { fields: "summary,status,assignee,issuetype,project,description" }));
+    }));
     server.registerTool("get_epic_issues", {
         title: "Get epic issues",
-        description: "List the issues belonging to an epic.",
+        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: {
-            epicId: z.number().int().describe("Epic issue ID (numeric)"),
-            maxResults: z.number().int().min(1).max(1000).default(100),
+            epicIdOrKey: z.string().describe("Epic key, e.g. PROJ-1, or numeric issue ID"),
+            fields: z
+                .string()
+                .optional()
+                .describe(`Comma-separated issue fields (default: ${DEFAULT_EPIC_ISSUE_FIELDS})`),
+            maxResults: z.number().int().min(1).max(100).default(100),
             startAt: z.number().int().min(0).default(0),
+            nextPageToken: z
+                .string()
+                .optional()
+                .describe("Jira Cloud only: cursor returned by a previous fallback search"),
         },
-    }, async ({ epicId, maxResults, startAt }) => run(() => client.agileGet(`/epic/${epicId}/issue`, { maxResults, startAt })));
+    }, async ({ epicIdOrKey, fields, maxResults, startAt, nextPageToken }) => run(() => {
+        const issueFields = fields ?? DEFAULT_EPIC_ISSUE_FIELDS;
+        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,
+            maxResults,
+            startAt,
+            nextPageToken,
+        }));
+    }));
     server.registerTool("create_epic", {
         title: "Create epic",
-        description: "Create a new epic on a board (agile rapid view).",
+        description: "Create an epic in a project. Company-managed projects usually also require the 'Epic Name' custom field — call get_epic_meta or get_issue_create_meta first and pass it via customFields.",
         inputSchema: {
-            boardId: z.number().int().describe("Board ID"),
-            sprintId: z.number().int().describe("Sprint ID (any sprint on the board works)"),
-            name: z.string().describe("Epic name"),
-            description: z.string().optional(),
-            lead: z.string().optional().describe("Epic lead (user account ID or username)"),
+            projectKey: z.string().describe("Project key, e.g. PROJ"),
+            name: z.string().describe("Epic name (used as the issue summary)"),
+            description: z
+                .string()
+                .optional()
+                .describe("Plain text; converted to ADF on Cloud/v3. Markdown is not rendered."),
+            issueType: z
+                .string()
+                .optional()
+                .describe("Epic issue type name or ID (default: Epic); see get_epic_meta"),
+            assignee: z.string().optional().describe("Account ID on Cloud/v3, username on DC/v2"),
+            customFields: z
+                .record(z.string(), z.unknown())
+                .optional()
+                .describe("Extra fields, e.g. { 'customfield_10011': 'Epic name' } for company-managed projects"),
         },
-    }, async ({ boardId, sprintId, name, description, lead }) => run(() => client.agilePost(`/rapid/${rapidViewId(boardId, sprintId)}/epic`, {
-        name,
-        description,
-        lead,
-    })));
+    }, async ({ projectKey, name, description, issueType, assignee, customFields }) => run(() => {
+        const type = issueType ?? "Epic";
+        return client.apiPost("/issue", {
+            fields: {
+                project: { key: projectKey },
+                summary: name,
+                issuetype: /^\d+$/.test(type) ? { id: type } : { name: type },
+                description: richText(description, client.apiVersion),
+                assignee: assignee
+                    ? client.apiVersion === "3"
+                        ? { accountId: assignee }
+                        : { name: assignee }
+                    : undefined,
+                ...customFields,
+            },
+        });
+    }));
     server.registerTool("move_issue_to_epic", {
         title: "Move issue to epic",
-        description: 'Add an issue to an epic. To remove an issue from an epic, use `update_issue` with fields `{ "epic": null }`.',
+        description: 'Add issues to an epic. On team-managed projects this sets the issue\'s parent instead. To remove an issue from an epic, use update_issue with fields { "parent": null } (team-managed) or { "epic": null } (company-managed).',
         inputSchema: {
-            epicId: z.number().int().describe("Epic issue ID (numeric)"),
-            issueId: z.number().int().describe("Issue ID to move (numeric)"),
-            epicKey: z.string().describe("Epic key, e.g. PROJ-1"),
+            epicIdOrKey: z.string().describe("Epic key, e.g. PROJ-1, or numeric issue ID"),
+            issueKeys: z.array(z.string()).min(1).describe("Issue keys to move, e.g. ['PROJ-2', 'PROJ-3']"),
         },
-    }, async ({ epicId, issueId, epicKey }) => run(() => client.agilePut(`/epic/${epicId}/issue/${issueId}`, { epic: { key: epicKey } })));
+    }, async ({ epicIdOrKey, issueKeys }) => run(() => withNextGenFallback(() => client.agilePost(`/epic/${encodeURIComponent(epicIdOrKey)}/issue`, { issues: issueKeys }), async () => {
+        for (const issueKey of issueKeys) {
+            await client.apiPut(`/issue/${encodeURIComponent(issueKey)}`, {
+                fields: { parent: { key: epicIdOrKey } },
+            });
+        }
+        return { moved: issueKeys, parent: epicIdOrKey };
+    })));
     server.registerTool("get_epic_meta", {
         title: "Get epic meta",
-        description: "Get epic metadata (available epic issue types) for a project.",
+        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().optional().describe("Project key filter"),
+            projectKey: z.string().describe("Project key, e.g. PROJ"),
         },
-    }, async ({ projectKey }) => run(() => client.agileGet("/epic/meta", { projectKey })));
+    }, async ({ projectKey }) => run(async () => {
+        const meta = (await client.apiGet(`/issue/createmeta/${encodeURIComponent(projectKey)}/issuetypes`));
+        const all = meta.issueTypes ?? [];
+        const epicTypes = all.filter((t) => (t.hierarchyLevel ?? 0) > 0 || /epic/i.test(t.name));
+        return {
+            projectKey,
+            epicIssueTypes: epicTypes,
+            allIssueTypes: all.map((t) => ({ id: t.id, name: t.name, hierarchyLevel: t.hierarchyLevel })),
+            hint: epicTypes.length > 0
+                ? `Create one with create_epic(projectKey: "${projectKey}", issueType: "${epicTypes[0].name}", name: ...). Use get_issue_create_meta for the full required-field list.`
+                : "No epic-level issue type is available in this project.",
+        };
+    }));
 }

package/dist/tools/issues.js

@@ -1,6 +1,92 @@
 import { z } from "zod";
 import { run } from "../util.js";
-const DEFAULT_ISSUE_FIELDS = "summary,description,status,assignee,reporter,issuetype,labels,components,priority,created,updated,due,project";
+import { searchIssues } from "../search.js";
+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",
@@ -8,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", {
@@ -18,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"),
@@ -35,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,
@@ -52,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.",
@@ -65,37 +163,49 @@ export function registerIssueTools(server, client) {
     }, async ({ issueKey }) => run(() => client.apiDelete(`/issue/${encodeURIComponent(issueKey)}`)));
     server.registerTool("search_issues", {
         title: "Search issues (JQL)",
-        description: "Search issues with JQL, e.g. 'project = PROJ AND sprint = 42 ORDER BY rank' or 'project = PROJ AND sprint IS NONE'. Returns issues plus total count and pagination info.",
+        description: "Search issues with JQL, e.g. 'project = PROJ AND sprint = 42 ORDER BY rank' or 'project = PROJ AND sprint IS NONE'. " +
+            "On Jira Cloud this uses enhanced search (/search/jql): the JQL must be bounded (include a restriction such as project, assignee, or key — a bare 'ORDER BY created DESC' is rejected), " +
+            "the response has no total, and paging is by cursor — pass the returned nextPageToken back in for the next page and stop when isLast is true. " +
+            "On Jira Data Center this uses the legacy /search endpoint, which pages with startAt and returns total.",
         inputSchema: {
-            jql: z.string().describe("JQL query string"),
+            jql: z.string().describe("JQL query string (must be bounded on Jira Cloud)"),
             fields: z.string().optional().describe(`Comma-separated fields (default: ${DEFAULT_ISSUE_FIELDS})`),
             maxResults: z.number().int().min(1).max(100).default(25),
-            startAt: z.number().int().min(0).default(0),
+            startAt: z.number().int().min(0).default(0).describe("Offset paging, Jira Data Center only; rejected on Cloud, use nextPageToken"),
+            nextPageToken: z
+                .string()
+                .optional()
+                .describe("Jira Cloud only: cursor from the previous response's nextPageToken"),
             expand: z.string().optional().describe("e.g. names, uris"),
+            includeApproximateTotal: z
+                .boolean()
+                .default(false)
+                .describe("Jira Cloud only: add an extra request for an approximate match count (approximateTotal)"),
         },
-    }, async ({ jql, fields, maxResults, startAt, expand }) => run(() => client.apiGet("/search", {
+    }, async ({ jql, fields, maxResults, startAt, nextPageToken, expand, includeApproximateTotal }) => run(() => searchIssues(client, {
         jql,
         fields: fields ?? DEFAULT_ISSUE_FIELDS,
         maxResults,
         startAt,
+        nextPageToken,
         expand,
+        includeApproximateTotal,
     })));
     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.",
@@ -113,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)"),
@@ -125,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.",
@@ -177,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.",
@@ -35,11 +37,18 @@ export function registerProjectTools(server, client) {
     }, async ({ projectKey, name, description }) => run(() => client.apiPost(`/project/${encodeURIComponent(projectKey)}/components`, { name, description })));
     server.registerTool("get_project_issue_types", {
         title: "Get project issue types",
-        description: "List issue types available in a project.",
+        description: "List the issue types available in a project, with their hierarchy levels (epic = 1, story/task = 0, sub-task = -1).",
         inputSchema: {
             projectKey: z.string().describe("Project key"),
+            maxResults: z.number().int().min(1).max(1000).default(100),
+            startAt: z.number().int().min(0).default(0),
         },
-    }, async ({ projectKey }) => run(() => client.apiGet(`/project/${encodeURIComponent(projectKey)}/issuetypes`)));
+    }, 
+    // /project/{key}/issuetypes does not exist; createmeta is the supported source.
+    async ({ projectKey, maxResults, startAt }) => run(() => client.apiGet(`/issue/createmeta/${encodeURIComponent(projectKey)}/issuetypes`, {
+        maxResults,
+        startAt,
+    })));
     server.registerTool("get_project_roles", {
         title: "Get project roles",
         description: "List roles (and their actors) of a project.",

package/dist/tools/sprints.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { rapidViewId, run } from "../util.js";
+import { run } from "../util.js";
 const sprintState = z.enum(["active", "closed", "future"]).describe("Sprint state filter");
 export function registerSprintTools(server, client) {
     server.registerTool("list_sprints", {
@@ -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 info, current sprint, and all its issues. Uses the agile rapid view API (rapidViewId = boardId * 10^13 + sprintId).",
+        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"),
@@ -76,31 +73,62 @@ export function registerSprintTools(server, client) {
                 .string()
                 .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).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 }) => run(() => client.agileGet(`/rapid/${rapidViewId(boardId, sprintId)}`, {
-        fields: fields ?? "key,summary,status,assignee",
-    })));
+    }, async ({ boardId, sprintId, fields, maxResults, startAt, nextPageToken }) => run(async () => {
+        const [board, sprint, issues] = await Promise.all([
+            client.agileGet(`/board/${boardId}`),
+            client.agileGet(`/sprint/${sprintId}`),
+            getSprintIssues(client, sprintId, fields, maxResults, startAt, nextPageToken),
+        ]);
+        return { board, sprint, issues };
+    }));
     server.registerTool("get_backlog", {
         title: "Get board backlog",
-        description: "List backlog issues for a board (issues in the board's projects with no sprint), ordered by rank. Implemented via JQL: project in (<board projects>) AND sprint IS NONE ORDER BY rank.",
+        description: "List a board's backlog issues (in the board's filter, not in a sprint), ordered by rank. " +
+            "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'"),
             fields: z
                 .string()
                 .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, fields, maxResults, startAt }) => run(async () => {
-        const board = (await client.agileGet(`/board/${boardId}`));
-        const keys = (board.projects ?? []).map((p) => p.key);
-        const jql = keys.length > 0 ? `project in (${keys.join(", ")}) AND sprint IS NONE ORDER BY rank` : "sprint IS NONE ORDER BY rank";
-        return client.apiGet("/search", {
+    }, 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: fields ?? "key,summary,status,assignee",
+            fields: issueFields,
             maxResults,
-            startAt,
+            nextPageToken,
         });
-    }));
+    }
+    return client.agileGet(`/board/${boardId}/backlog`, {
+        jql,
+        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 });
     }));

package/dist/util.js

@@ -19,6 +19,3 @@ export async function run(fn) {
         };
     }
 }
-export function rapidViewId(boardId, sprintId) {
-    return boardId * 10_000_000_000_000 + sprintId;
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thammarongg/jira-mcp",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "MCP server exposing the Jira REST API (boards, sprints, issues, JQL, and a generic passthrough) for Jira Cloud and Data Center",
   "type": "module",
   "bin": {
@@ -25,7 +25,7 @@
     "claude"
   ],
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && node -e \"require('fs').chmodSync('dist/index.js', 0o755)\"",
     "typecheck": "tsc --noEmit",
     "start": "node dist/index.js",
     "dev": "tsx src/index.ts",

package/skill/SKILL.md

@@ -27,7 +27,8 @@ Or non-interactive: `npx -y @thammarongg/jira-mcp install --agents all
 --yes`. Required env vars:
 
 - `JIRA_BASE_URL` — `https://your-org.atlassian.net` (Cloud) or
-  `https://jira.yourcompany.com` (DC)
+  `https://jira.yourcompany.com` (DC); a DC context path such as `/jira` is
+  supported and preserved
 - Cloud: `JIRA_EMAIL` + `JIRA_API_TOKEN` (token from id.atlassian.com →
   Security → API tokens)
 - DC: `JIRA_USERNAME` + `JIRA_API_TOKEN` (PAT) or `JIRA_PASSWORD` (app password)
@@ -64,11 +65,17 @@ After setup, verify with the `get_current_user` tool.
 
 ## Tool map
 
-- **Boards/sprints**: `list_boards`, `get_board`, `list_sprints`, `get_sprint`,
+- **Boards/sprints**: `list_boards` (the project filter is one Agile
+  `projectKeyOrId` value), `get_board`, `list_sprints`, `get_sprint`,
   `create_sprint`, `update_sprint`, `close_sprint`, `get_sprint_issues`,
-  `get_sprint_view` (UI-like full view), `get_backlog`
-- **Epics**: `list_epics`, `get_epic`, `get_epic_issues`, `create_epic`,
-  `move_issue_to_epic`, `get_epic_meta`
+  `get_sprint_view` (UI-like full view), `get_backlog`. Cloud backlog and
+  issue-list reads use Software 1.0 enhanced endpoints with cursor paging;
+  Data Center uses Agile 1.0 with `startAt`/`total`. `create_sprint` sends
+  `originBoardId` to the top-level Agile sprint-create route.
+- **Epics**: `list_epics` (by board), `get_epic`, `get_epic_issues`,
+  `create_epic`, `move_issue_to_epic`, `get_epic_meta` — epics are addressed by
+  key or numeric ID. Cloud `get_epic_issues` uses Software 1.0 enhanced
+  cursor paging; team-managed projects fall back to JQL/search as needed.
 - **Issues**: `get_issue`, `create_issue`, `update_issue`, `delete_issue`,
   `search_issues` (JQL), `get_issue_create_meta`, `get_issue_transitions`,
   `transition_issue`, `assign_issue`, `add_comment`, `list_comments`,
@@ -84,17 +91,35 @@ After setup, verify with the `get_current_user` tool.
 **Sprint status**: `list_boards` → pick board → `list_sprints` (state
 `active`) → `get_sprint_issues` or `get_sprint_view` for the full picture.
 
-**Backlog review**: `get_backlog(boardId)` — issues in the board's projects
-with no sprint, ordered by rank.
+**Backlog review**: `get_backlog(boardId)` — issues on the board that are not
+in a sprint, ordered by rank; pass `jql` to narrow it. On Cloud, pass the
+returned `nextPageToken` for the next page; on Data Center, pass `startAt`.
+
+**Epic breakdown**: `list_epics(boardId)` → `get_epic_issues(epicIdOrKey)` for
+the children. To create one, `get_epic_meta(projectKey)` gives the epic issue
+type and then `create_epic`; company-managed projects also need the "Epic Name"
+custom field via `customFields`.
 
 **Create an issue**: call `get_issue_create_meta(projectKeys=...)` first to
 discover valid issue types and required fields, then `create_issue`
 (custom fields go in `customFields`, e.g. `{ "customfield_10010": "..." }`).
+The metadata tool composes the current per-project and per-issue-type
+endpoints; the deprecated `/issue/createmeta` query form is not used. Pass
+`projectKeys` when fields are expanded (the default); omit it only with
+`expand: "projects.issuetypes"` for issue-type summaries. Metadata requests
+use a fixed concurrency limit of four.
+
+**Comments and descriptions**: pass plain text — `add_comment`, `create_issue`,
+`create_epic`, `update_issue` and `add_worklog` convert it to ADF automatically
+on Jira Cloud (v3). Blank lines separate paragraphs; Markdown is not rendered.
+No need to hand-build an ADF document or fall back to `jira_api`.
 
 **Move work through the workflow**: `get_issue_transitions(issueKey)` to see
 available transitions and required fields, then `transition_issue`.
 
-**Search**: `search_issues` with JQL. Common queries:
+**Search**: `search_issues` with JQL. On Jira Cloud the query must be
+**bounded** — always include a restriction such as `project`, `assignee`, or
+`key`; a bare `ORDER BY created DESC` is rejected. Common queries:
 - Current sprint: `project = PROJ AND sprint = <sprintId> ORDER BY rank`
 - Unassigned in project: `project = PROJ AND assignee IS EMPTY`
 - Due this week: `project = PROJ AND duedate <= endOfWeek() ORDER BY duedate`
@@ -104,8 +129,22 @@ available transitions and required fields, then `transition_issue`.
 
 - List tools paginate with `startAt`/`maxResults`; responses include `total` —
   page with `startAt` when `total` exceeds the page size.
+- `search_issues` is the exception on **Jira Cloud**: it uses Atlassian's
+  enhanced search (`/search/jql`, which replaced the removed `/search`). There
+  is no `total`; page by passing the response's `nextPageToken` back in and
+  stop when `isLast` is true — `startAt` is rejected. Pass
+  `includeApproximateTotal: true` for a rough match count (one extra request).
+  On Data Center it still uses `startAt`/`total`.
 - Assignees: pass an account ID on Cloud, a username on DC — the server maps
   it to the right field shape automatically.
+- `get_user` uses `/user?accountId=...` on Cloud/v3 and `/user?username=...` on
+  Data Center/v2. `create_issue` maps its `dueDate` input to Jira's `duedate`
+  field, and `add_worklog` accepts an optional `started` timestamp (Jira
+  defaults it to now when omitted).
+- Data Center exposes REST API v2/latest, not `/rest/api/3`; do not force
+  `JIRA_API_VERSION=3` for a DC host. The default deployment detection routes
+  Cloud (`*.atlassian.net`) and DC endpoints separately, while ADF and user
+  field shapes follow the selected API version.
 - To remove an issue from an epic: `update_issue` with
   `fields: { "epic": null }`.
 - Anything not covered by a dedicated tool → `jira_api` with method, path