@thammarongg/jira-mcp 0.3.0 → 0.5.0

package/README.md

@@ -16,9 +16,14 @@ 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.
+(token entry is masked on a TTY). If a selected agent already has a `jira`
+entry, the installer offers to reuse its base URL and account without asking
+for the credentials again. Existing config files are backed up to `.bak`
+before any modification, and re-running updates the `jira` entry in place
+instead of duplicating it.
+
+With `--yes` and no credential flags, a selected existing entry's credentials
+are reused without prompting.
 
 Non-interactive (CI / scripting):
 
@@ -39,6 +44,29 @@ Flags: `--agents all` or comma-separated ids/numbers (`claude-code`,
 `--email` (Cloud) / `--username` (Data Center), `--token` (API token or PAT),
 `--password` (DC app password), `--yes` (skip the confirm prompt).
 
+### CLI commands
+
+```bash
+npx -y @thammarongg/jira-mcp update                 # refresh configured agents
+npx -y @thammarongg/jira-mcp update --agents codex
+npx -y @thammarongg/jira-mcp uninstall              # choose configured agents interactively
+npx -y @thammarongg/jira-mcp uninstall --agents all --yes
+npx -y @thammarongg/jira-mcp --version
+npx -y @thammarongg/jira-mcp --help
+```
+
+`update` is non-interactive and repairs every existing `jira` entry from that
+agent's own credentials; agents without an entry are skipped. `uninstall`
+removes only the `jira` entry, preserving the rest of each agent configuration;
+it accepts the same `--agents` selection grammar as `install` and asks for
+confirmation unless `--yes` is supplied.
+
+Running `npx -y @thammarongg/jira-mcp` bare in a terminal prints a status card
+with the installed version, configured agents, and available commands. MCP
+clients pipe stdio, so the same bare command starts the MCP server for them;
+it expects `JIRA_*` environment variables, which is why running it bare
+without those variables reports a missing `JIRA_BASE_URL`.
+
 ### Claude Code (manual one-liner)
 
 ```bash
@@ -101,7 +129,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,20 +188,20 @@ 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_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 (Agile `/board/{id}/backlog`, rank-ordered) |
+| `get_backlog` | Board backlog (Cloud Software enhanced or DC Agile, rank-ordered) |
 
 ### Epics
 
@@ -194,10 +222,10 @@ mkdir -p ~/.agents/skills/jira && cp skill/SKILL.md ~/.agents/skills/jira/
 | `update_issue` | Set fields and/or relative `update` ops |
 | `delete_issue` | Delete |
 | `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_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
@@ -219,6 +247,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
@@ -231,11 +270,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.
+- `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_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.
+- `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/agents.js

@@ -0,0 +1,412 @@
+import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { homedir, platform } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+function packageJsonPath() {
+    return join(dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+}
+function readPackage() {
+    try {
+        return JSON.parse(readFileSync(packageJsonPath(), "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+export function readPackageName() {
+    const name = readPackage().name;
+    return typeof name === "string" && name.length > 0 ? name : "@thammarongg/jira-mcp";
+}
+export function readPackageVersion() {
+    const version = readPackage().version;
+    return typeof version === "string" && version.length > 0 ? version : "0.0.0";
+}
+export const PKG = readPackageName();
+export const PACKAGE_VERSION = readPackageVersion();
+export const claudeDesktopPath = platform() === "darwin"
+    ? join(homedir(), "Library", "Application Support", "Claude", "claude_desktop_config.json")
+    : join(homedir(), ".config", "Claude", "claude_desktop_config.json");
+export const AGENTS = [
+    { id: "claude-code", label: "Claude Code", path: join(homedir(), ".claude.json"), kind: "mcpServers" },
+    { id: "opencode", label: "OpenCode", path: join(homedir(), ".config", "opencode", "opencode.json"), kind: "opencode" },
+    { id: "codex", label: "Codex", path: join(homedir(), ".codex", "config.toml"), kind: "codex" },
+    { id: "cursor", label: "Cursor", path: join(homedir(), ".cursor", "mcp.json"), kind: "mcpServers" },
+    { id: "claude-desktop", label: "Claude Desktop", path: claudeDesktopPath, kind: "mcpServers" },
+    { id: "gemini-cli", label: "Gemini CLI", path: join(homedir(), ".gemini", "settings.json"), kind: "mcpServers" },
+];
+export function envOf(entry) {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry))
+        return undefined;
+    const record = entry;
+    const env = record.env ?? record.environment;
+    if (!env || typeof env !== "object" || Array.isArray(env))
+        return undefined;
+    return env;
+}
+function readJsonObject(path) {
+    if (!existsSync(path))
+        return undefined;
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return undefined;
+        return parsed;
+    }
+    catch {
+        return undefined;
+    }
+}
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+}
+const JIRA_HEADER = /^\s*\[mcp_servers\.jira\](\s+#.*)?$/;
+function tomlLines(raw) {
+    const eol = raw.includes("\r\n") ? "\r\n" : "\n";
+    const lines = raw.split("\n").map((line) => (line.endsWith("\r") ? line.slice(0, -1) : line));
+    return { lines, eol };
+}
+function sectionEnd(lines, start) {
+    for (let i = start + 1; i < lines.length; i++) {
+        if (/^\s*\[/.test(lines[i]))
+            return i;
+    }
+    return lines.length;
+}
+function parseTomlString(raw, start) {
+    if (raw[start] !== '"')
+        return undefined;
+    let value = "";
+    for (let i = start + 1; i < raw.length; i++) {
+        const ch = raw[i];
+        if (ch === '"')
+            return { value, next: i + 1 };
+        if (ch !== "\\") {
+            value += ch;
+            continue;
+        }
+        const escaped = raw[++i];
+        if (escaped === undefined)
+            return undefined;
+        if (escaped === "n")
+            value += "\n";
+        else if (escaped === "r")
+            value += "\r";
+        else if (escaped === "t")
+            value += "\t";
+        else if (escaped === "u") {
+            const code = raw.slice(i + 1, i + 5);
+            if (!/^[0-9a-f]{4}$/i.test(code))
+                return undefined;
+            value += String.fromCodePoint(Number.parseInt(code, 16));
+            i += 4;
+        }
+        else
+            value += escaped;
+    }
+    return undefined;
+}
+function parseTomlEnvValue(raw) {
+    const out = {};
+    let i = 0;
+    while (i < raw.length) {
+        while (i < raw.length && /[\s,]/.test(raw[i]))
+            i++;
+        if (i >= raw.length)
+            break;
+        const keyStart = i;
+        while (i < raw.length && raw[i] !== "=" && raw[i] !== ",")
+            i++;
+        const key = raw.slice(keyStart, i).trim();
+        if (raw[i] !== "=")
+            break;
+        i++;
+        while (i < raw.length && /\s/.test(raw[i]))
+            i++;
+        let value;
+        if (raw[i] === '"') {
+            const parsed = parseTomlString(raw, i);
+            if (!parsed)
+                break;
+            value = parsed.value;
+            i = parsed.next;
+        }
+        else {
+            const valueStart = i;
+            while (i < raw.length && raw[i] !== ",")
+                i++;
+            value = raw.slice(valueStart, i).trim();
+        }
+        if (key)
+            out[key] = value;
+        while (i < raw.length && raw[i] !== ",")
+            i++;
+        if (raw[i] === ",")
+            i++;
+    }
+    return out;
+}
+function parseTomlEnv(lines, start, end) {
+    for (let i = start + 1; i < end; i++) {
+        const match = lines[i].match(/^\s*env\s*=\s*\{(.*)\}\s*$/);
+        if (match)
+            return parseTomlEnvValue(match[1]);
+    }
+    return {};
+}
+function readCodexJira(path) {
+    if (!existsSync(path))
+        return undefined;
+    try {
+        const { lines } = tomlLines(readFileSync(path, "utf8"));
+        for (let i = 0; i < lines.length; i++) {
+            if (!JIRA_HEADER.test(lines[i]))
+                continue;
+            const end = sectionEnd(lines, i);
+            return { start: i, end, env: parseTomlEnv(lines, i, end) };
+        }
+    }
+    catch { }
+    return undefined;
+}
+export function readAgentEntry(agent) {
+    if (agent.kind === "codex") {
+        const section = readCodexJira(agent.path);
+        return section ? { env: section.env } : undefined;
+    }
+    const object = readJsonObject(agent.path);
+    if (!object)
+        return undefined;
+    const container = asRecord(object[agent.kind === "opencode" ? "mcp" : "mcpServers"]);
+    return container && Object.hasOwn(container, "jira") ? container.jira : undefined;
+}
+export function hasAgentEntry(agent) {
+    if (agent.kind === "codex")
+        return readCodexJira(agent.path) !== undefined;
+    const object = readJsonObject(agent.path);
+    if (!object)
+        return false;
+    const container = asRecord(object[agent.kind === "opencode" ? "mcp" : "mcpServers"]);
+    return container !== undefined && Object.hasOwn(container, "jira");
+}
+export function readAgentEnv(agent) {
+    const env = envOf(readAgentEntry(agent));
+    if (!env)
+        return undefined;
+    const result = {};
+    for (const [key, value] of Object.entries(env)) {
+        if (typeof value === "string")
+            result[key] = value;
+    }
+    return Object.keys(result).length > 0 ? result : undefined;
+}
+export function resolveAgents(spec) {
+    const norm = spec.trim().toLowerCase();
+    if (norm === "all" || norm === "a")
+        return [...AGENTS];
+    const ids = norm.split(/[,\s]+/).filter(Boolean);
+    const selected = [];
+    for (const id of ids) {
+        const agent = /^\d+$/.test(id) ? AGENTS[Number(id) - 1] : AGENTS.find((candidate) => candidate.id === id);
+        if (!agent)
+            throw new Error(`Unknown agent '${id}'. Valid: ${AGENTS.map((a, i) => `${i + 1}/${a.id}`).join(", ")} or all`);
+        if (!selected.includes(agent))
+            selected.push(agent);
+    }
+    if (selected.length === 0)
+        throw new Error("No agents selected");
+    return selected;
+}
+function reportEnvChanges(oldEnv, newEnv, path) {
+    if (!oldEnv)
+        return;
+    const replaced = Object.keys(newEnv).filter((key) => oldEnv[key] !== newEnv[key]);
+    const removed = Object.keys(oldEnv).filter((key) => !(key 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 stat = statSync(path);
+    return { mtimeMs: stat.mtimeMs, size: stat.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 object = {};
+    if (existed) {
+        stamp = fileStamp(path);
+        const raw = readFileSync(path, "utf8");
+        let parsed;
+        try {
+            parsed = raw.trim() ? JSON.parse(raw) : {};
+        }
+        catch {
+            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 {
+            object = parsed;
+        }
+    }
+    mutate(object);
+    mkdirSync(dirname(path), { recursive: true });
+    if (existed) {
+        assertUnchanged(path, stamp);
+        copyFileSync(path, `${path}.bak`);
+    }
+    atomicWrite(path, JSON.stringify(object, null, 2) + "\n");
+    return existed ? "updated" : "created";
+}
+function tomlStr(value) {
+    let output = "";
+    for (const ch of value) {
+        const code = ch.codePointAt(0);
+        if (ch === "\\")
+            output += "\\\\";
+        else if (ch === '"')
+            output += '\\"';
+        else if (ch === "\n")
+            output += "\\n";
+        else if (ch === "\t")
+            output += "\\t";
+        else if (ch === "\r")
+            output += "\\r";
+        else if (code < 0x20)
+            output += `\\u${code.toString(16).toUpperCase().padStart(4, "0")}`;
+        else
+            output += ch;
+    }
+    return `"${output}"`;
+}
+function upsertCodex(path, env) {
+    const block = [
+        "[mcp_servers.jira]",
+        'command = "npx"',
+        `args = ["-y", ${tomlStr(PKG)}]`,
+        `env = { ${Object.entries(env)
+            .map(([key, value]) => `${key} = ${tomlStr(value)}`)
+            .join(", ")} }`,
+    ];
+    if (!existsSync(path)) {
+        mkdirSync(dirname(path), { recursive: true });
+        atomicWrite(path, block.join("\n") + "\n");
+        return "created";
+    }
+    const stamp = fileStamp(path);
+    const raw = readFileSync(path, "utf8");
+    const { lines, eol } = tomlLines(raw);
+    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) {
+            const end = sectionEnd(lines, start);
+            for (let i = start; i < end; i++)
+                remove.add(i);
+        }
+        const kept = lines.filter((_, index) => !remove.has(index));
+        let insertIndex = 0;
+        for (let i = 0; i < starts[0]; i++)
+            if (!remove.has(i))
+                insertIndex++;
+        kept.splice(insertIndex, 0, ...block);
+        const after = insertIndex + block.length;
+        if (after < kept.length && kept[after].trim() !== "")
+            kept.splice(after, 0, "");
+        content = kept.join(eol);
+        if (!content.endsWith(eol))
+            content += eol;
+    }
+    reportEnvChanges(starts.length > 0 ? parseTomlEnv(lines, starts[0], sectionEnd(lines, starts[0])) : undefined, env, path);
+    assertUnchanged(path, stamp);
+    copyFileSync(path, `${path}.bak`);
+    atomicWrite(path, content);
+    return "updated";
+}
+export 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, (object) => {
+            const mcp = (object.mcp ??= {});
+            reportEnvChanges(envOf(mcp.jira), env, agent.path);
+            mcp.jira = {
+                type: "local",
+                command: ["npx", "-y", PKG],
+                environment: env,
+                enabled: true,
+            };
+        });
+    }
+    return mergeJsonFile(agent.path, (object) => {
+        const mcpServers = (object.mcpServers ??= {});
+        reportEnvChanges(envOf(mcpServers.jira), env, agent.path);
+        mcpServers.jira = { command: "npx", args: ["-y", PKG], env };
+    });
+}
+function removeJsonEntry(agent) {
+    if (!hasAgentEntry(agent))
+        return "skipped";
+    mergeJsonFile(agent.path, (object) => {
+        const key = agent.kind === "opencode" ? "mcp" : "mcpServers";
+        const container = asRecord(object[key]);
+        if (container)
+            delete container.jira;
+    });
+    return "removed";
+}
+function removeCodex(path) {
+    if (!existsSync(path))
+        return "skipped";
+    const stamp = fileStamp(path);
+    const raw = readFileSync(path, "utf8");
+    const { lines, eol } = tomlLines(raw);
+    const starts = [];
+    for (let i = 0; i < lines.length; i++)
+        if (JIRA_HEADER.test(lines[i]))
+            starts.push(i);
+    if (starts.length === 0)
+        return "skipped";
+    const remove = new Set();
+    for (const start of starts) {
+        const end = sectionEnd(lines, start);
+        for (let i = start; i < end; i++)
+            remove.add(i);
+    }
+    const content = lines.filter((_, index) => !remove.has(index)).join(eol);
+    assertUnchanged(path, stamp);
+    copyFileSync(path, `${path}.bak`);
+    atomicWrite(path, content);
+    return "removed";
+}
+export function removeAgentConfig(agent) {
+    if (agent.kind === "codex")
+        return removeCodex(agent.path);
+    return removeJsonEntry(agent);
+}

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}`);