@thammarongg/jira-mcp 0.1.0

package/README.md

@@ -0,0 +1,205 @@
+# jira-mcp
+
+An [MCP](https://modelcontextprotocol.io) (Model Context Protocol) server that exposes the Jira REST API to AI assistants — boards, sprints, epics, issues, JQL search, workflow transitions, comments, worklogs, projects, users, plus a generic passthrough tool for **any** Jira REST endpoint.
+
+Works with both **Jira Cloud** (REST API v3) and **Jira Data Center** (REST API v2), auto-detected from the base URL.
+
+## Install (one-click)
+
+Once published to npm, any MCP client can run it via `npx` — no local build needed:
+
+```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
+```
+
+```json
+// Claude Desktop / any MCP client (mcpServers)
+{
+  "mcpServers": {
+    "jira": {
+      "command": "npx",
+      "args": ["-y", "@thammarongg/jira-mcp"],
+      "env": {
+        "JIRA_BASE_URL": "https://your-org.atlassian.net",
+        "JIRA_EMAIL": "you@example.com",
+        "JIRA_API_TOKEN": "xxx"
+      }
+    }
+  }
+}
+```
+
+```json
+// opencode (opencode.json)
+{
+  "mcp": {
+    "jira": {
+      "type": "local",
+      "command": ["npx", "-y", "@thammarongg/jira-mcp"],
+      "environment": {
+        "JIRA_BASE_URL": "https://your-org.atlassian.net",
+        "JIRA_EMAIL": "you@example.com",
+        "JIRA_API_TOKEN": "xxx"
+      },
+      "enabled": true
+    }
+  }
+}
+```
+
+### Publishing
+
+```bash
+npm login
+npm publish          # prepublishOnly runs build + smoke test first
+```
+
+### Local development (no publish)
+
+```bash
+npm install
+npm run build
+# run directly: node dist/index.js  (or `npm run dev` via tsx)
+```
+
+### Configuration (environment variables)
+
+| Variable | Required | Description |
+| --- | --- | --- |
+| `JIRA_BASE_URL` | yes | `https://your-org.atlassian.net` (Cloud) or `https://jira.yourcompany.com` (DC) |
+| `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`) |
+| `JIRA_PASSWORD` | DC | App password (alternative to `JIRA_API_TOKEN`) |
+| `JIRA_API_VERSION` | no | Force `2` or `3`. Default: auto (Cloud → 3, DC → 2) |
+| `JIRA_TIMEOUT_MS` | no | Request timeout, default `30000` |
+
+Quick auth check:
+
+```bash
+JIRA_BASE_URL=... JIRA_EMAIL=... JIRA_API_TOKEN=... node dist/index.js
+```
+
+Then call the `get_current_user` tool from your MCP client — it verifies credentials.
+
+## Using a local checkout
+
+Prefer not to publish? Point the client at the built file instead of `npx` —
+same env vars as above:
+
+```bash
+claude mcp add jira --env JIRA_BASE_URL=https://your-org.atlassian.net \
+  --env JIRA_EMAIL=you@example.com --env JIRA_API_TOKEN=xxx \
+  -- node /absolute/path/to/jira-mcp/dist/index.js
+```
+
+```json
+// opencode (opencode.json)
+{
+  "mcp": {
+    "jira": {
+      "type": "local",
+      "command": ["node", "/absolute/path/to/jira-mcp/dist/index.js"],
+      "environment": {
+        "JIRA_BASE_URL": "https://your-org.atlassian.net",
+        "JIRA_EMAIL": "you@example.com",
+        "JIRA_API_TOKEN": "xxx"
+      },
+      "enabled": true
+    }
+  }
+}
+```
+
+## Agent skill
+
+A ready-made agent skill (setup + workflow guidance for the tools) ships in
+[`skill/SKILL.md`](skill/SKILL.md). Install it by copying to your skills
+directory:
+
+```bash
+mkdir -p ~/.claude/skills/jira && cp skill/SKILL.md ~/.claude/skills/jira/
+# or for opencode / shared agents:
+mkdir -p ~/.agents/skills/jira && cp skill/SKILL.md ~/.agents/skills/jira/
+```
+
+## Tools
+
+### Boards & sprints (Agile API)
+
+| Tool | Description |
+| --- | --- |
+| `list_boards` | List boards (filter by type/name/project) |
+| `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`) |
+
+### 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 |
+
+### Issues
+
+| Tool | Description |
+| --- | --- |
+| `get_issue` | Issue by key |
+| `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 |
+| `get_issue_transitions` / `transition_issue` | Workflow transitions |
+| `assign_issue` | Assign/unassign |
+| `add_comment` / `list_comments` / `delete_comment` | Comments |
+| `get_issue_worklogs` / `add_worklog` | Time tracking |
+
+### Projects, users, meta
+
+`list_projects`, `get_project`, `get_project_components`, `create_project_component`, `get_project_issue_types`, `get_project_roles`, `get_project_versions`, `get_current_user`, `find_users`, `get_user`, `get_fields`, `get_issue_types`
+
+### Escape hatch
+
+| Tool | Description |
+| --- | --- |
+| `jira_api` | Raw call to any `/rest/...` endpoint (method, path, query, body) — covers the full Jira REST API |
+
+## Typical agent workflow
+
+1. `list_boards` → pick a board
+2. `list_sprints` (state: active) → pick a sprint
+3. `get_sprint_issues` or `get_sprint_view` → see the work
+4. `search_issues` with JQL for anything custom
+5. `create_issue` / `transition_issue` / `add_comment` to act
+6. Anything else → `jira_api`
+
+## Development
+
+```bash
+npm run dev        # run from source via tsx
+npm run build      # compile to dist/
+npm run typecheck  # tsc --noEmit
+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.
+- 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).
+- `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/client.js

@@ -0,0 +1,102 @@
+export class JiraApiError extends Error {
+    status;
+    body;
+    constructor(status, body, message) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = "JiraApiError";
+    }
+}
+export class JiraClient {
+    cfg;
+    constructor(cfg) {
+        this.cfg = cfg;
+    }
+    get apiVersion() {
+        return this.cfg.apiVersion;
+    }
+    get isCloud() {
+        return this.cfg.isCloud;
+    }
+    async request(method, path, opts = {}) {
+        const url = new URL(`${this.cfg.baseUrl}${path.startsWith("/") ? path : `/${path}`}`);
+        if (!url.pathname.startsWith("/rest/")) {
+            throw new Error(`Jira API path must start with /rest/ (resolved to ${url.pathname})`);
+        }
+        if (opts.query) {
+            for (const [key, value] of Object.entries(opts.query)) {
+                if (value !== undefined && value !== null && value !== "") {
+                    url.searchParams.set(key, String(value));
+                }
+            }
+        }
+        const headers = {
+            Authorization: this.cfg.authHeader,
+            Accept: "application/json",
+            ...opts.headers,
+        };
+        let bodyInit;
+        if (opts.body !== undefined) {
+            headers["Content-Type"] = "application/json";
+            bodyInit = JSON.stringify(opts.body);
+        }
+        const res = await fetch(url, {
+            method,
+            headers,
+            body: bodyInit,
+            signal: AbortSignal.timeout(this.cfg.timeoutMs),
+        });
+        const text = await res.text();
+        let data;
+        try {
+            data = text ? JSON.parse(text) : null;
+        }
+        catch {
+            data = text;
+        }
+        if (!res.ok) {
+            throw new JiraApiError(res.status, data, `Jira API ${method} ${path} failed with HTTP ${res.status}: ${extractErrorMessage(data) ?? res.statusText}`);
+        }
+        return data;
+    }
+    apiGet(path, query) {
+        return this.request("GET", `/rest/api/${this.cfg.apiVersion}${path}`, { query });
+    }
+    apiPost(path, body) {
+        return this.request("POST", `/rest/api/${this.cfg.apiVersion}${path}`, { body });
+    }
+    apiPut(path, body) {
+        return this.request("PUT", `/rest/api/${this.cfg.apiVersion}${path}`, { body });
+    }
+    apiDelete(path) {
+        return this.request("DELETE", `/rest/api/${this.cfg.apiVersion}${path}`);
+    }
+    agileGet(path, query) {
+        return this.request("GET", `/rest/agile/1.0${path}`, { query });
+    }
+    agilePost(path, body) {
+        return this.request("POST", `/rest/agile/1.0${path}`, { body });
+    }
+    agilePut(path, body) {
+        return this.request("PUT", `/rest/agile/1.0${path}`, { body });
+    }
+}
+function extractErrorMessage(body) {
+    if (typeof body === "string" && body.trim()) {
+        const trimmed = body.trim();
+        return trimmed.length > 300 ? `${trimmed.slice(0, 300)}…` : trimmed;
+    }
+    if (body && typeof body === "object") {
+        const obj = body;
+        if (Array.isArray(obj.errorMessages) && obj.errorMessages.length > 0) {
+            return obj.errorMessages.map(String).join("; ");
+        }
+        if (typeof obj.message === "string" && obj.message)
+            return obj.message;
+        if (obj.errors && typeof obj.errors === "object") {
+            return Object.values(obj.errors).map(String).join("; ");
+        }
+    }
+    return undefined;
+}

package/dist/config.js

@@ -0,0 +1,38 @@
+export function loadConfig(env = process.env) {
+    const rawBase = (env.JIRA_BASE_URL ?? "").trim();
+    if (!rawBase) {
+        throw new Error("JIRA_BASE_URL is required, e.g. https://your-org.atlassian.net (Cloud) or https://jira.yourcompany.com (Data Center)");
+    }
+    let baseUrl;
+    try {
+        const url = new URL(rawBase);
+        if (!/^https?:$/.test(url.protocol))
+            throw new Error("bad protocol");
+        baseUrl = `${url.protocol}//${url.host}`;
+    }
+    catch {
+        throw new Error(`JIRA_BASE_URL is not a valid URL: ${rawBase}`);
+    }
+    const email = (env.JIRA_EMAIL ?? "").trim();
+    const username = (env.JIRA_USERNAME ?? "").trim();
+    const token = (env.JIRA_API_TOKEN ?? "").trim();
+    const password = (env.JIRA_PASSWORD ?? "").trim();
+    let authHeader;
+    if (email && token) {
+        authHeader = basicAuth(email, token);
+    }
+    else if (username && (token || password)) {
+        authHeader = basicAuth(username, token || password);
+    }
+    else {
+        throw new Error("Missing credentials. Set JIRA_EMAIL + JIRA_API_TOKEN (Jira Cloud) or JIRA_USERNAME + JIRA_API_TOKEN/JIRA_PASSWORD (Data Center).");
+    }
+    const isCloud = /(^|\.)atlassian\.net$/i.test(new URL(baseUrl).hostname);
+    const rawVersion = (env.JIRA_API_VERSION ?? "").trim();
+    const apiVersion = rawVersion === "2" || rawVersion === "3" ? rawVersion : isCloud ? "3" : "2";
+    const timeoutMs = Math.max(1000, Number(env.JIRA_TIMEOUT_MS ?? 30000) || 30000);
+    return { baseUrl, apiVersion, authHeader, isCloud, timeoutMs };
+}
+function basicAuth(user, secret) {
+    return `Basic ${Buffer.from(`${user}:${secret}`).toString("base64")}`;
+}

package/dist/index.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { loadConfig } from "./config.js";
+import { JiraClient } from "./client.js";
+import { registerBoardTools } from "./tools/boards.js";
+import { registerSprintTools } from "./tools/sprints.js";
+import { registerEpicTools } from "./tools/epics.js";
+import { registerIssueTools } from "./tools/issues.js";
+import { registerProjectTools } from "./tools/projects.js";
+import { registerUserTools } from "./tools/users.js";
+import { registerMetaTools } from "./tools/meta.js";
+import { registerGenericTools } from "./tools/generic.js";
+import { runInstaller } from "./install.js";
+async function main() {
+    if (process.argv[2] === "install") {
+        await runInstaller(process.argv.slice(3));
+        return;
+    }
+    const config = loadConfig();
+    const client = new JiraClient(config);
+    const server = new McpServer({ name: "jira", version: "0.1.0" });
+    registerBoardTools(server, client);
+    registerSprintTools(server, client);
+    registerEpicTools(server, client);
+    registerIssueTools(server, client);
+    registerProjectTools(server, client);
+    registerUserTools(server, client);
+    registerMetaTools(server, client);
+    registerGenericTools(server, client);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    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)}`);
+    process.exit(1);
+});

package/dist/install.js

@@ -0,0 +1,302 @@
+import { copyFileSync, existsSync, mkdirSync, readFileSync, 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";
+const claudeDesktopPath = platform() === "darwin"
+    ? join(homedir(), "Library", "Application Support", "Claude", "claude_desktop_config.json")
+    : join(homedir(), ".config", "Claude", "claude_desktop_config.json");
+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" },
+];
+function parseFlags(argv) {
+    const flags = {};
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        const next = () => {
+            const v = argv[++i];
+            if (v === undefined)
+                throw new Error(`Missing value for ${arg}`);
+            return v;
+        };
+        if (arg === "--agents")
+            flags.agents = next();
+        else if (arg === "--base-url")
+            flags.baseUrl = next();
+        else if (arg === "--email")
+            flags.email = next();
+        else if (arg === "--username")
+            flags.username = next();
+        else if (arg === "--token")
+            flags.token = next();
+        else if (arg === "--password")
+            flags.password = next();
+        else if (arg === "--yes")
+            flags.yes = true;
+        else if (arg === "--help" || arg === "-h") {
+            printUsage();
+            process.exit(0);
+        }
+        else {
+            throw new Error(`Unknown option: ${arg} (see --help)`);
+        }
+    }
+    return flags;
+}
+function printUsage() {
+    console.log(`jira-mcp install — configure the jira MCP server in your agent(s)
+
+Usage:
+  npx -y ${PKG} install
+  npx -y ${PKG} install --agents all --base-url https://x.atlassian.net --email you@x.com --token xxx --yes
+
+Options:
+  --agents <list>    Comma-separated agent ids or 'all': ${AGENTS.map((a) => a.id).join(", ")}
+  --base-url <url>   Jira base URL (required)
+  --email <email>    Jira Cloud email (with --token)
+  --username <user>  Jira Data Center username (with --token or --password)
+  --token <token>    API token / PAT
+  --password <pass>  Data Center app password (alternative to --token)
+  --yes              Skip the confirmation prompt
+  -h, --help         Show this help
+`);
+}
+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})`);
+        }
+        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;
+}
+function resolveAgents(spec) {
+    const norm = spec.trim().toLowerCase();
+    if (norm === "all" || norm === "a")
+        return [...AGENTS];
+    const ids = norm.split(/[,\s]+/).filter(Boolean);
+    const selected = ids.map((id) => {
+        const agent = AGENTS.find((a) => a.id === id);
+        if (!agent)
+            throw new Error(`Unknown agent '${id}'. Valid: ${AGENTS.map((a) => a.id).join(", ")} or all`);
+        return agent;
+    });
+    if (selected.length === 0)
+        throw new Error("No agents selected");
+    return selected;
+}
+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;
+        if (flags.password)
+            env.JIRA_PASSWORD = flags.password;
+    }
+    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() {
+    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();
+        try {
+            return answer === "a" || answer === "all" ? [...AGENTS] : resolveAgents(answer);
+        }
+        catch (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();
+    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 isCloud = mode === "" || mode === "1";
+    const user = (await ask(rl, isCloud ? "Atlassian email: " : "Data Center username: ")).trim();
+    if (!user) {
+        rl.close();
+        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();
+    if (!secret)
+        throw new Error("API token is required");
+    const env = { JIRA_BASE_URL: baseUrl };
+    if (isCloud) {
+        env.JIRA_EMAIL = user;
+        env.JIRA_API_TOKEN = secret;
+    }
+    else {
+        env.JIRA_USERNAME = user;
+        env.JIRA_API_TOKEN = secret;
+    }
+    return env;
+}
+function writeAgentConfig(agent, env) {
+    if (agent.kind === "codex")
+        return upsertCodex(agent.path, env);
+    if (agent.kind === "opencode") {
+        return mergeJsonFile(agent.path, (obj) => {
+            const mcp = (obj.mcp ??= {});
+            mcp.jira = {
+                type: "local",
+                command: ["npx", "-y", PKG],
+                environment: env,
+                enabled: true,
+            };
+        });
+    }
+    return mergeJsonFile(agent.path, (obj) => {
+        const mcpServers = (obj.mcpServers ??= {});
+        mcpServers.jira = { command: "npx", args: ["-y", PKG], env };
+    });
+}
+function mergeJsonFile(path, mutate) {
+    const existed = existsSync(path);
+    let obj = {};
+    if (existed) {
+        const raw = readFileSync(path, "utf8");
+        try {
+            const parsed = raw.trim() ? JSON.parse(raw) : {};
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed))
+                obj = parsed;
+        }
+        catch {
+            copyFileSync(path, `${path}.bak`);
+            console.log(`  ! ${path} was not valid JSON — backed up to ${path}.bak, starting fresh`);
+        }
+    }
+    mutate(obj);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(obj, null, 2) + "\n");
+    return existed ? "updated" : "created";
+}
+function tomlStr(v) {
+    return `"${v.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+function upsertCodex(path, env) {
+    const block = [
+        "[mcp_servers.jira]",
+        'command = "npx"',
+        `args = ["-y", ${tomlStr(PKG)}]`,
+        `env = { ${Object.entries(env)
+            .map(([k, v]) => `${k} = ${tomlStr(v)}`)
+            .join(", ")} }`,
+    ];
+    if (!existsSync(path)) {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, block.join("\n") + "\n");
+        return "created";
+    }
+    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;
+            }
+        }
+        lines.splice(start, end - start, ...block);
+        writeFileSync(path, lines.join("\n"));
+        return "updated";
+    }
+    writeFileSync(path, raw.replace(/\s*$/, "") + "\n\n" + block.join("\n") + "\n");
+    return "updated";
+}