@thammarongg/jira-mcp 0.1.0 → 0.3.0

package/README.md

@@ -6,10 +6,42 @@ Works with both **Jira Cloud** (REST API v3) and **Jira Data Center** (REST API
 
 ## Install (one-click)
 
-Once published to npm, any MCP client can run it via `npx` — no local build needed:
+Once published to npm, any MCP client can run it via `npx` — no local build needed.
+
+### Interactive installer (all agents at once)
+
+```bash
+npx -y @thammarongg/jira-mcp install
+```
+
+Shows a menu — Select All or pick agents (Claude Code, OpenCode, Codex, Cursor,
+Claude Desktop, Gemini CLI) — then asks for the Jira base URL and credentials
+(token entry is hidden on a TTY). Existing config files are backed up to
+`.bak` before any modification, and re-running updates the `jira` entry in
+place instead of duplicating it.
+
+Non-interactive (CI / scripting):
+
+```bash
+# Jira Cloud
+npx -y @thammarongg/jira-mcp install --agents all \
+  --base-url https://your-org.atlassian.net \
+  --email you@example.com --token xxx --yes
+
+# Jira Data Center (subset of agents)
+npx -y @thammarongg/jira-mcp install --agents claude-code,codex \
+  --base-url https://jira.yourcompany.com \
+  --username you --token xxx --yes
+```
+
+Flags: `--agents all` or comma-separated ids/numbers (`claude-code`,
+`opencode`, `codex`, `cursor`, `claude-desktop`, `gemini-cli`), `--base-url`,
+`--email` (Cloud) / `--username` (Data Center), `--token` (API token or PAT),
+`--password` (DC app password), `--yes` (skip the confirm prompt).
+
+### Claude Code (manual one-liner)
 
 ```bash
-# Claude Code (one-liner)
 claude mcp add jira --env JIRA_BASE_URL=https://your-org.atlassian.net \
   --env JIRA_EMAIL=you@example.com --env JIRA_API_TOKEN=xxx \
   -- npx -y @thammarongg/jira-mcp
@@ -140,17 +172,18 @@ mkdir -p ~/.agents/skills/jira && cp skill/SKILL.md ~/.agents/skills/jira/
 | `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_view` | Full UI-like sprint view (board + sprint + issues in one call) |
+| `get_backlog` | Board backlog (Agile `/board/{id}/backlog`, 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
 
@@ -160,7 +193,7 @@ 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 |
+| `search_issues` | **JQL search** — enhanced search (`/search/jql`) on Cloud, legacy `/search` on Data Center |
 | `get_issue_create_meta` | Discover projects/types/required fields |
 | `get_issue_transitions` / `transition_issue` | Workflow transitions |
 | `assign_issue` | Assign/unassign |
@@ -198,8 +231,11 @@ 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.
+- Pagination: most list tools return Jira's native `startAt`/`maxResults`/`total`; pass `startAt` to page.
+- 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_backlog` calls the Agile API's `/board/{id}/backlog` endpoint, so it keeps `startAt`/`total` paging on Cloud and DC alike; pass `jql` to narrow it further.
 - 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).
+- 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_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/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.3.0" });
     registerBoardTools(server, client);
     registerSprintTools(server, client);
     registerEpicTools(server, client);
@@ -33,6 +33,8 @@ async function main() {
     console.error(`jira-mcp ready: ${config.baseUrl} (API v${config.apiVersion}, ${config.isCloud ? "Cloud" : "Data Center"})`);
 }
 main().catch((err) => {
-    console.error(`jira-mcp failed to start: ${err instanceof Error ? err.message : String(err)}`);
+    const msg = err instanceof Error ? err.message : String(err);
+    const prefix = process.argv[2] === "install" ? "jira-mcp install failed" : "jira-mcp failed to start";
+    console.error(`${prefix}: ${msg}`);
     process.exit(1);
 });

package/dist/install.js

@@ -1,8 +1,19 @@
-import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { homedir, platform } from "node:os";
 import { dirname, join } from "node:path";
 import * as readline from "node:readline";
-const PKG = "@thammarongg/jira-mcp";
+import { fileURLToPath } from "node:url";
+function readPackageName() {
+    try {
+        const pkgPath = join(dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+        const parsed = JSON.parse(readFileSync(pkgPath, "utf8"));
+        if (typeof parsed.name === "string" && parsed.name.length > 0)
+            return parsed.name;
+    }
+    catch { }
+    return "@thammarongg/jira-mcp";
+}
+const PKG = readPackageName();
 const claudeDesktopPath = platform() === "darwin"
     ? join(homedir(), "Library", "Application Support", "Claude", "claude_desktop_config.json")
     : join(homedir(), ".config", "Claude", "claude_desktop_config.json");
@@ -48,6 +59,37 @@ function parseFlags(argv) {
     }
     return flags;
 }
+function validateCredentialFlags(flags) {
+    const anyPresent = [flags.baseUrl, flags.email, flags.username, flags.token, flags.password].some((v) => v !== undefined);
+    if (!anyPresent)
+        return;
+    if (flags.email !== undefined && flags.username !== undefined)
+        throw new Error("--email and --username are mutually exclusive (Cloud uses --email, Data Center uses --username)");
+    if (flags.email !== undefined) {
+        const missing = [];
+        if (flags.baseUrl === undefined)
+            missing.push("--base-url");
+        if (flags.token === undefined)
+            missing.push("--token");
+        if (missing.length > 0)
+            throw new Error(`--email requires ${missing.join(" and ")}`);
+        if (flags.password !== undefined)
+            throw new Error("--password is a Data Center option and cannot be combined with --email");
+        return;
+    }
+    if (flags.username !== undefined) {
+        if (flags.baseUrl === undefined)
+            throw new Error("--username requires --base-url");
+        if (flags.token === undefined && flags.password === undefined)
+            throw new Error("--username requires --token or --password");
+        return;
+    }
+    if (flags.token !== undefined)
+        throw new Error("--token requires --email (Cloud) or --username (Data Center)");
+    if (flags.password !== undefined)
+        throw new Error("--password requires --username (Data Center)");
+    throw new Error("--base-url requires --email or --username (plus --token / --password)");
+}
 function printUsage() {
     console.log(`jira-mcp install — configure the jira MCP server in your agent(s)
 
@@ -66,40 +108,187 @@ Options:
   -h, --help         Show this help
 `);
 }
+function makePrompter() {
+    const queue = [];
+    const waiters = [];
+    let closed = false;
+    let suspended = false;
+    let rl = null;
+    const attach = (r) => {
+        r.on("line", (line) => {
+            const waiter = waiters.shift();
+            if (waiter)
+                waiter(line);
+            else
+                queue.push(line);
+        });
+        r.on("close", () => {
+            if (suspended)
+                return;
+            closed = true;
+            while (waiters.length > 0)
+                waiters.shift()("");
+        });
+    };
+    const start = () => {
+        rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout,
+            terminal: process.stdin.isTTY === true,
+        });
+        attach(rl);
+    };
+    start();
+    const prompter = {
+        get closed() {
+            return closed;
+        },
+        ask(question) {
+            process.stdout.write(question);
+            const queued = queue.shift();
+            if (queued !== undefined)
+                return Promise.resolve(queued);
+            if (closed)
+                return Promise.resolve("");
+            return new Promise((resolve) => waiters.push(resolve));
+        },
+        close() {
+            suspended = false;
+            closed = true;
+            while (waiters.length > 0)
+                waiters.shift()("");
+            rl?.close();
+            rl = null;
+        },
+        suspend() {
+            suspended = true;
+            rl?.close();
+            rl = null;
+        },
+        resume() {
+            suspended = false;
+            if (rl === null)
+                start();
+        },
+        tryQueued() {
+            return queue.shift();
+        },
+    };
+    return prompter;
+}
+function askPassword(p, promptText) {
+    const stdin = process.stdin;
+    if (typeof stdin.setRawMode !== "function") {
+        return p.ask(`${promptText} (no echo available) `).then((v) => v.trim());
+    }
+    const queued = p.tryQueued();
+    if (queued !== undefined) {
+        process.stdout.write(promptText);
+        return Promise.resolve(queued.trim());
+    }
+    return new Promise((resolve, reject) => {
+        let value = "";
+        let finished = false;
+        const cleanup = () => {
+            if (finished)
+                return;
+            finished = true;
+            stdin.removeListener("data", onData);
+            stdin.removeListener("end", onEnd);
+            stdin.removeListener("close", onClose);
+            stdin.setRawMode(false);
+        };
+        const finish = (v) => {
+            cleanup();
+            p.resume();
+            if (v === null)
+                reject(new Error("input closed while reading password"));
+            else {
+                process.stdout.write("\n");
+                resolve(v.trim());
+            }
+        };
+        const onData = (buf) => {
+            for (const ch of buf.toString("utf8")) {
+                if (ch === "\r" || ch === "\n") {
+                    finish(value);
+                    return;
+                }
+                if (ch === "\x03") {
+                    cleanup();
+                    p.resume();
+                    process.exit(130);
+                }
+                if (ch === "\x04") {
+                    finish("");
+                    return;
+                }
+                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);
+        const onClose = () => finish(null);
+        p.suspend();
+        process.stdout.write(promptText);
+        stdin.setRawMode(true);
+        stdin.resume();
+        stdin.on("data", onData);
+        stdin.on("end", onEnd);
+        stdin.on("close", onClose);
+    });
+}
 export async function runInstaller(argv) {
     const flags = parseFlags(argv);
-    const selected = flags.agents ? resolveAgents(flags.agents) : await promptSelection();
-    const env = flags.baseUrl && (flags.email || flags.username)
-        ? buildEnvFromFlags(flags)
-        : await promptCredentials();
-    console.log("\nWill configure the jira MCP server in:");
-    for (const agent of selected)
-        console.log(`  - ${agent.label.padEnd(15)} ${agent.path}`);
-    console.log(`Env vars: ${Object.keys(env).join(", ")} (values not shown)`);
-    if (!flags.yes) {
-        const rl = makeRl();
-        const answer = (await ask(rl, "\nProceed? [Y/n] ")).trim().toLowerCase();
-        rl.close();
-        if (answer !== "" && answer !== "y" && answer !== "yes") {
-            console.log("Aborted.");
-            return;
-        }
-    }
-    let failed = false;
-    for (const agent of selected) {
-        try {
-            const result = writeAgentConfig(agent, env);
-            console.log(`  ok  ${agent.label.padEnd(15)} ${agent.path} (${result})`);
+    validateCredentialFlags(flags);
+    const hasCredentials = (flags.baseUrl && flags.email && flags.token) ||
+        (flags.baseUrl && flags.username && (flags.token || flags.password));
+    const needsPrompts = !flags.agents || !hasCredentials || !flags.yes;
+    const p = needsPrompts ? makePrompter() : undefined;
+    try {
+        const selected = flags.agents ? resolveAgents(flags.agents) : await promptSelection(p);
+        const env = hasCredentials ? buildEnvFromFlags(flags) : await promptCredentials(p);
+        console.log("\nWill configure the jira MCP server in:");
+        for (const agent of selected)
+            console.log(`  - ${agent.label.padEnd(15)} ${agent.path}`);
+        console.log(`Env vars: ${Object.keys(env).join(", ")} (values not shown)`);
+        if (!flags.yes) {
+            const answer = (await p.ask("\nProceed? [Y/n] ")).trim().toLowerCase();
+            if ((p.closed && answer === "") || (answer !== "" && answer !== "y" && answer !== "yes")) {
+                console.log("Aborted.");
+                return;
+            }
         }
-        catch (err) {
-            failed = true;
-            console.error(`  ERR ${agent.label.padEnd(15)} ${agent.path}: ${err instanceof Error ? err.message : String(err)}`);
+        let failed = false;
+        for (const agent of selected) {
+            try {
+                const result = writeAgentConfig(agent, env);
+                if (result === "skipped")
+                    console.log(`  skip ${agent.label.padEnd(15)} ${agent.path}`);
+                else
+                    console.log(`  ok  ${agent.label.padEnd(15)} ${agent.path} (${result})`);
+            }
+            catch (err) {
+                failed = true;
+                console.error(`  ERR ${agent.label.padEnd(15)} ${agent.path}: ${err instanceof Error ? err.message : String(err)}`);
+            }
         }
+        console.log("\nDone. Restart each agent to pick up the new MCP server.");
+        console.log("Verify by asking your agent to call the get_current_user tool.");
+        if (failed)
+            process.exitCode = 1;
+    }
+    finally {
+        p?.close();
     }
-    console.log("\nDone. Restart each agent to pick up the new MCP server.");
-    console.log("Verify by asking your agent to call the get_current_user tool.");
-    if (failed)
-        process.exitCode = 1;
 }
 function resolveAgents(spec) {
     const norm = spec.trim().toLowerCase();
@@ -107,9 +296,9 @@ function resolveAgents(spec) {
         return [...AGENTS];
     const ids = norm.split(/[,\s]+/).filter(Boolean);
     const selected = ids.map((id) => {
-        const agent = AGENTS.find((a) => a.id === id);
+        const agent = /^\d+$/.test(id) ? AGENTS[Number(id) - 1] : AGENTS.find((a) => a.id === id);
         if (!agent)
-            throw new Error(`Unknown agent '${id}'. Valid: ${AGENTS.map((a) => a.id).join(", ")} or all`);
+            throw new Error(`Unknown agent '${id}'. Valid: ${AGENTS.map((a, i) => `${i + 1}/${a.id}`).join(", ")} or all`);
         return agent;
     });
     if (selected.length === 0)
@@ -119,14 +308,10 @@ function resolveAgents(spec) {
 function buildEnvFromFlags(flags) {
     const env = { JIRA_BASE_URL: flags.baseUrl };
     if (flags.email) {
-        if (!flags.token)
-            throw new Error("--email requires --token");
         env.JIRA_EMAIL = flags.email;
         env.JIRA_API_TOKEN = flags.token;
     }
     else {
-        if (!flags.token && !flags.password)
-            throw new Error("--username requires --token or --password");
         env.JIRA_USERNAME = flags.username;
         if (flags.token)
             env.JIRA_API_TOKEN = flags.token;
@@ -135,84 +320,37 @@ function buildEnvFromFlags(flags) {
     }
     return env;
 }
-function makeRl() {
-    return readline.createInterface({ input: process.stdin, output: process.stdout });
-}
-function ask(rl, question) {
-    return new Promise((resolve) => rl.question(question, resolve));
-}
-function askPassword(promptText) {
-    const stdin = process.stdin;
-    if (typeof stdin.setRawMode !== "function") {
-        return new Promise((resolve) => {
-            process.stdout.write(`${promptText} (non-interactive: value visible)\n`);
-            const rl = makeRl();
-            rl.question("", (v) => {
-                rl.close();
-                resolve(v.trim());
-            });
-        });
-    }
-    return new Promise((resolve) => {
-        let value = "";
-        const done = () => {
-            stdin.removeListener("data", onData);
-            stdin.setRawMode(false);
-            process.stdout.write("\n");
-            resolve(value);
-        };
-        const onData = (buf) => {
-            for (const ch of buf.toString("utf8")) {
-                if (ch === "\r" || ch === "\n") {
-                    done();
-                    return;
-                }
-                if (ch === "\u007f" || ch === "\b")
-                    value = value.slice(0, -1);
-                else if (ch >= " ")
-                    value += ch;
-            }
-        };
-        process.stdout.write(promptText);
-        stdin.setRawMode(true);
-        stdin.on("data", onData);
-    });
-}
-async function promptSelection() {
+async function promptSelection(p) {
     console.log(`\njira-mcp installer — select agents to configure:\n`);
     console.log("  a) Select All");
     AGENTS.forEach((agent, i) => {
         console.log(`  ${i + 1}) ${agent.label.padEnd(15)} ${agent.path}`);
     });
-    const rl = makeRl();
     for (;;) {
-        const answer = (await ask(rl, "\nChoice (e.g. 1,3 or a): ")).trim().toLowerCase();
-        rl.close();
+        const answer = (await p.ask("\nChoice (e.g. 1,3 or a): ")).trim().toLowerCase();
+        if (answer === "" && p.closed)
+            throw new Error("No input received (stdin closed)");
         try {
             return answer === "a" || answer === "all" ? [...AGENTS] : resolveAgents(answer);
         }
         catch (err) {
+            if (p.closed)
+                throw err;
             console.log(`  ${err instanceof Error ? err.message : String(err)}`);
         }
     }
 }
-async function promptCredentials() {
-    const rl = makeRl();
-    const baseUrl = (await ask(rl, "Jira base URL (e.g. https://your-org.atlassian.net): ")).trim();
+async function promptCredentials(p) {
+    const baseUrl = (await p.ask("Jira base URL (e.g. https://your-org.atlassian.net): ")).trim();
     if (!/^https?:\/\/.+/i.test(baseUrl)) {
-        rl.close();
         throw new Error("Jira base URL must start with http(s)://");
     }
-    const mode = (await ask(rl, "Deployment: [1] Jira Cloud  [2] Jira Data Center (default 1): ")).trim();
+    const mode = (await p.ask("Deployment: [1] Jira Cloud  [2] Jira Data Center (default 1): ")).trim();
     const isCloud = mode === "" || mode === "1";
-    const user = (await ask(rl, isCloud ? "Atlassian email: " : "Data Center username: ")).trim();
-    if (!user) {
-        rl.close();
+    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(isCloud ? "API token (hidden, from id.atlassian.com): " : "API token / app password (hidden): ");
-    rl.resume();
-    rl.close();
+    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 };
@@ -230,8 +368,14 @@ function writeAgentConfig(agent, env) {
     if (agent.kind === "codex")
         return upsertCodex(agent.path, env);
     if (agent.kind === "opencode") {
+        const jsonc = agent.path.replace(/\.json$/, ".jsonc");
+        if (existsSync(jsonc)) {
+            console.log(`  ! ${jsonc} exists — skipping automatic opencode write (JSONC may contain comments); merge the jira entry manually`);
+            return "skipped";
+        }
         return mergeJsonFile(agent.path, (obj) => {
             const mcp = (obj.mcp ??= {});
+            reportEnvChanges(envOf(mcp.jira), env, agent.path);
             mcp.jira = {
                 type: "local",
                 command: ["npx", "-y", PKG],
@@ -242,31 +386,122 @@ function writeAgentConfig(agent, env) {
     }
     return mergeJsonFile(agent.path, (obj) => {
         const mcpServers = (obj.mcpServers ??= {});
+        reportEnvChanges(envOf(mcpServers.jira), env, agent.path);
         mcpServers.jira = { command: "npx", args: ["-y", PKG], env };
     });
 }
+function envOf(entry) {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry))
+        return undefined;
+    const e = entry.env ?? entry.environment;
+    if (!e || typeof e !== "object" || Array.isArray(e))
+        return undefined;
+    return e;
+}
+function reportEnvChanges(oldEnv, newEnv, path) {
+    if (!oldEnv)
+        return;
+    const replaced = Object.keys(newEnv).filter((k) => oldEnv[k] !== newEnv[k]);
+    const removed = Object.keys(oldEnv).filter((k) => !(k in newEnv));
+    if (replaced.length > 0)
+        console.log(`  ! ${path}: existing jira entry will be replaced — env vars changed: ${replaced.join(", ")}`);
+    if (removed.length > 0)
+        console.log(`  ! ${path}: existing jira entry will be replaced — env vars removed: ${removed.join(", ")}`);
+}
+function fileStamp(path) {
+    const s = statSync(path);
+    return { mtimeMs: s.mtimeMs, size: s.size };
+}
+function assertUnchanged(path, before) {
+    const after = statSync(path);
+    if (after.mtimeMs !== before.mtimeMs || after.size !== before.size) {
+        throw new Error("changed while installing — close running agents and retry");
+    }
+}
+function atomicWrite(path, content) {
+    const tmp = `${path}.tmp-${process.pid}`;
+    writeFileSync(tmp, content);
+    renameSync(tmp, path);
+}
 function mergeJsonFile(path, mutate) {
     const existed = existsSync(path);
+    let stamp;
     let obj = {};
     if (existed) {
+        stamp = fileStamp(path);
         const raw = readFileSync(path, "utf8");
+        let parsed;
         try {
-            const parsed = raw.trim() ? JSON.parse(raw) : {};
-            if (parsed && typeof parsed === "object" && !Array.isArray(parsed))
-                obj = parsed;
+            parsed = raw.trim() ? JSON.parse(raw) : {};
         }
         catch {
-            copyFileSync(path, `${path}.bak`);
-            console.log(`  ! ${path} was not valid JSON — backed up to ${path}.bak, starting fresh`);
+            parsed = undefined;
+        }
+        if (parsed === undefined || typeof parsed !== "object" || Array.isArray(parsed)) {
+            console.log(`  ! ${path} is not a JSON object — backing up to ${path}.bak and starting fresh`);
+        }
+        else {
+            obj = parsed;
         }
     }
     mutate(obj);
     mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, JSON.stringify(obj, null, 2) + "\n");
+    if (existed) {
+        assertUnchanged(path, stamp);
+        copyFileSync(path, `${path}.bak`);
+    }
+    atomicWrite(path, JSON.stringify(obj, null, 2) + "\n");
     return existed ? "updated" : "created";
 }
 function tomlStr(v) {
-    return `"${v.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+    let out = "";
+    for (const ch of v) {
+        const code = ch.codePointAt(0);
+        if (ch === "\\")
+            out += "\\\\";
+        else if (ch === '"')
+            out += '\\"';
+        else if (ch === "\n")
+            out += "\\n";
+        else if (ch === "\t")
+            out += "\\t";
+        else if (ch === "\r")
+            out += "\\r";
+        else if (code < 0x20)
+            out += `\\u${code.toString(16).toUpperCase().padStart(4, "0")}`;
+        else
+            out += ch;
+    }
+    return `"${out}"`;
+}
+const JIRA_HEADER = /^\s*\[mcp_servers\.jira\](\s+#.*)?$/;
+function parseTomlEnv(lines, start) {
+    let end = lines.length;
+    for (let i = start + 1; i < lines.length; i++) {
+        if (/^\s*\[/.test(lines[i])) {
+            end = i;
+            break;
+        }
+    }
+    for (let i = start + 1; i < end; i++) {
+        const m = lines[i].match(/^\s*env\s*=\s*\{(.*)\}\s*$/);
+        if (!m)
+            continue;
+        const out = {};
+        for (const part of m[1].split(",")) {
+            const eq = part.indexOf("=");
+            if (eq < 0)
+                continue;
+            const k = part.slice(0, eq).trim();
+            let v = part.slice(eq + 1).trim();
+            if (v.length >= 2 && v.startsWith('"') && v.endsWith('"'))
+                v = v.slice(1, -1);
+            if (k)
+                out[k] = v;
+        }
+        return out;
+    }
+    return undefined;
 }
 function upsertCodex(path, env) {
     const block = [
@@ -279,24 +514,51 @@ function upsertCodex(path, env) {
     ];
     if (!existsSync(path)) {
         mkdirSync(dirname(path), { recursive: true });
-        writeFileSync(path, block.join("\n") + "\n");
+        atomicWrite(path, block.join("\n") + "\n");
         return "created";
     }
+    const stamp = fileStamp(path);
     const raw = readFileSync(path, "utf8");
-    const lines = raw.split("\n");
-    const start = lines.findIndex((l) => /^\s*\[mcp_servers\.jira\]\s*$/.test(l));
-    if (start >= 0) {
-        let end = lines.length;
-        for (let i = start + 1; i < lines.length; i++) {
-            if (/^\s*\[/.test(lines[i])) {
-                end = i;
-                break;
+    const eol = raw.includes("\r\n") ? "\r\n" : "\n";
+    const lines = raw.split("\n").map((l) => (l.endsWith("\r") ? l.slice(0, -1) : l));
+    const starts = [];
+    for (let i = 0; i < lines.length; i++) {
+        if (JIRA_HEADER.test(lines[i]))
+            starts.push(i);
+    }
+    let content;
+    if (starts.length === 0) {
+        content = raw.replace(/\s*$/, "") + eol + eol + block.join(eol) + eol;
+    }
+    else {
+        const remove = new Set();
+        for (const start of starts) {
+            let end = lines.length;
+            for (let i = start + 1; i < lines.length; i++) {
+                if (/^\s*\[/.test(lines[i])) {
+                    end = i;
+                    break;
+                }
             }
+            for (let i = start; i < end; i++)
+                remove.add(i);
         }
-        lines.splice(start, end - start, ...block);
-        writeFileSync(path, lines.join("\n"));
-        return "updated";
+        const kept = lines.filter((_, i) => !remove.has(i));
+        let insertIdx = 0;
+        for (let i = 0; i < starts[0]; i++)
+            if (!remove.has(i))
+                insertIdx++;
+        kept.splice(insertIdx, 0, ...block);
+        const after = insertIdx + block.length;
+        if (after < kept.length && kept[after].trim() !== "")
+            kept.splice(after, 0, "");
+        content = kept.join(eol);
+        if (!content.endsWith(eol))
+            content += eol;
     }
-    writeFileSync(path, raw.replace(/\s*$/, "") + "\n\n" + block.join("\n") + "\n");
+    reportEnvChanges(starts.length > 0 ? parseTomlEnv(lines, starts[0]) : undefined, env, path);
+    assertUnchanged(path, stamp);
+    copyFileSync(path, `${path}.bak`);
+    atomicWrite(path, content);
     return "updated";
 }

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/epics.js

@@ -1,61 +1,150 @@
 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";
+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.
+ */
+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. Falls back to a JQL 'parent = <epic>' search on team-managed projects, where the Agile 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(() => 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"),
+            projectKey: z.string().describe("Project key, e.g. PROJ"),
+            name: z.string().describe("Epic name (used as the issue summary)"),
             description: z.string().optional(),
-            lead: z.string().optional().describe("Epic lead (user account ID or username)"),
+            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,
+                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), with 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,5 +1,6 @@
 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";
 export function registerIssueTools(server, client) {
     server.registerTool("get_issue", {
@@ -65,20 +66,33 @@ 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",

package/dist/tools/projects.js

@@ -35,11 +35,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", {
@@ -68,7 +68,7 @@ export function registerSprintTools(server, client) {
     })));
     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.",
         inputSchema: {
             boardId: z.number().int().describe("Board ID"),
             sprintId: z.number().int().describe("Sprint ID"),
@@ -76,15 +76,30 @@ 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),
         },
-    }, async ({ boardId, sprintId, fields }) => run(() => client.agileGet(`/rapid/${rapidViewId(boardId, sprintId)}`, {
-        fields: fields ?? "key,summary,status,assignee",
-    })));
+    }, 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.
+        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,
+            }),
+        ]);
+        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. " +
+            "Uses the Agile API's own backlog endpoint, so it pages with startAt/total on both Cloud and Data Center.",
         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()
@@ -92,15 +107,10 @@ export function registerSprintTools(server, client) {
             maxResults: z.number().int().min(1).max(100).default(50),
             startAt: z.number().int().min(0).default(0),
         },
-    }, 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", {
-            jql,
-            fields: fields ?? "key,summary,status,assignee",
-            maxResults,
-            startAt,
-        });
-    }));
+    }, async ({ boardId, jql, fields, maxResults, startAt }) => run(() => client.agileGet(`/board/${boardId}/backlog`, {
+        jql,
+        fields: fields ?? "key,summary,status,assignee",
+        maxResults,
+        startAt,
+    })));
 }

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.1.0",
+  "version": "0.3.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

@@ -13,8 +13,18 @@ server-side.
 
 ## If the jira MCP tools are not available
 
-Tell the user the server isn't configured and offer to set it up. Required
-env vars:
+Tell the user the server isn't configured and offer to set it up. Easiest is
+the interactive installer (writes config for the selected agents — Claude
+Code, OpenCode, Codex, Cursor, Claude Desktop, Gemini CLI; backs up existing
+files to `.bak`):
+
+```bash
+npx -y @thammarongg/jira-mcp install
+```
+
+Or non-interactive: `npx -y @thammarongg/jira-mcp install --agents all
+--base-url https://your-org.atlassian.net --email you@example.com --token xxx
+--yes`. Required env vars:
 
 - `JIRA_BASE_URL` — `https://your-org.atlassian.net` (Cloud) or
   `https://jira.yourcompany.com` (DC)
@@ -57,8 +67,9 @@ After setup, verify with the `get_current_user` tool.
 - **Boards/sprints**: `list_boards`, `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`
+- **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, and these work on team-managed projects too
 - **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`,
@@ -74,8 +85,13 @@ 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.
+
+**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`
@@ -84,7 +100,9 @@ discover valid issue types and required fields, then `create_issue`
 **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`
@@ -94,6 +112,12 @@ 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.
 - To remove an issue from an epic: `update_issue` with