@thammarongg/jira-mcp 0.4.0 → 0.5.1

package/README.md

@@ -11,25 +11,30 @@ Once published to npm, any MCP client can run it via `npx` — no local build ne
 ### Interactive installer (all agents at once)
 
 ```bash
-npx -y @thammarongg/jira-mcp install
+npx -y @thammarongg/jira-mcp@latest 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):
 
 ```bash
 # Jira Cloud
-npx -y @thammarongg/jira-mcp install --agents all \
+npx -y @thammarongg/jira-mcp@latest 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 \
+npx -y @thammarongg/jira-mcp@latest install --agents claude-code,codex \
   --base-url https://jira.yourcompany.com \
   --username you --token xxx --yes
 ```
@@ -39,12 +44,35 @@ 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@latest update                 # refresh configured agents
+npx -y @thammarongg/jira-mcp@latest update --agents codex
+npx -y @thammarongg/jira-mcp@latest uninstall              # choose configured agents interactively
+npx -y @thammarongg/jira-mcp@latest uninstall --agents all --yes
+npx -y @thammarongg/jira-mcp@latest --version
+npx -y @thammarongg/jira-mcp@latest --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@latest` 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
 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
+  -- npx -y @thammarongg/jira-mcp@latest
 ```
 
 ```json
@@ -53,7 +81,7 @@ claude mcp add jira --env JIRA_BASE_URL=https://your-org.atlassian.net \
   "mcpServers": {
     "jira": {
       "command": "npx",
-      "args": ["-y", "@thammarongg/jira-mcp"],
+      "args": ["-y", "@thammarongg/jira-mcp@latest"],
       "env": {
         "JIRA_BASE_URL": "https://your-org.atlassian.net",
         "JIRA_EMAIL": "you@example.com",
@@ -70,7 +98,7 @@ claude mcp add jira --env JIRA_BASE_URL=https://your-org.atlassian.net \
   "mcp": {
     "jira": {
       "type": "local",
-      "command": ["npx", "-y", "@thammarongg/jira-mcp"],
+      "command": ["npx", "-y", "@thammarongg/jira-mcp@latest"],
       "environment": {
         "JIRA_BASE_URL": "https://your-org.atlassian.net",
         "JIRA_EMAIL": "you@example.com",

package/dist/agents.js

@@ -0,0 +1,417 @@
+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();
+// An unversioned npx package spec resolves the current project when the MCP
+// client starts in this repository, but this package's own bin is not linked
+// into node_modules/.bin. The explicit dist-tag forces npx to resolve the
+// published package in every working directory.
+export const PKG_SPEC = `${PKG}@latest`;
+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_SPEC)}]`,
+        `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_SPEC],
+                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_SPEC], 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/index.js

@@ -12,14 +12,62 @@ import { registerUserTools } from "./tools/users.js";
 import { registerMetaTools } from "./tools/meta.js";
 import { registerGenericTools } from "./tools/generic.js";
 import { runInstaller } from "./install.js";
+import { runUpdate } from "./update.js";
+import { runUninstall } from "./uninstall.js";
+import { PACKAGE_VERSION } from "./agents.js";
+import { renderStatus } from "./status.js";
+function helpText() {
+    return `jira-mcp — Jira MCP server and configuration helper
+
+Commands:
+  install              Configure the jira MCP server in one or more agents
+  update               Refresh existing jira entries from their own credentials
+  uninstall            Remove jira entries from selected agents
+  --version, -v        Print the installed version
+  --help, -h           Show this help
+
+With no arguments in a terminal, jira-mcp prints a configuration status card.
+With no arguments over piped stdio, it starts the MCP server.
+`;
+}
+function printHelp() {
+    console.log(helpText());
+}
 async function main() {
-    if (process.argv[2] === "install") {
+    const command = process.argv[2];
+    if (command === "install") {
         await runInstaller(process.argv.slice(3));
         return;
     }
+    if (command === "update") {
+        await runUpdate(process.argv.slice(3));
+        return;
+    }
+    if (command === "uninstall") {
+        await runUninstall(process.argv.slice(3));
+        return;
+    }
+    if (command === "--version" || command === "-v") {
+        console.log(PACKAGE_VERSION);
+        return;
+    }
+    if (command === "--help" || command === "-h") {
+        printHelp();
+        return;
+    }
+    if (command !== undefined) {
+        console.error(`Unknown command: ${command}`);
+        console.error(helpText());
+        process.exitCode = 1;
+        return;
+    }
+    if (!command && process.stdin.isTTY) {
+        console.log(await renderStatus());
+        return;
+    }
     const config = loadConfig();
     const client = new JiraClient(config);
-    const server = new McpServer({ name: "jira", version: "0.4.0" });
+    const server = new McpServer({ name: "jira", version: PACKAGE_VERSION });
     registerBoardTools(server, client);
     registerSprintTools(server, client);
     registerEpicTools(server, client);
@@ -34,7 +82,10 @@ async function main() {
 }
 main().catch((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";
+    const command = process.argv[2];
+    const prefix = command === "install" || command === "update" || command === "uninstall"
+        ? `jira-mcp ${command} failed`
+        : "jira-mcp failed to start";
     console.error(`${prefix}: ${msg}`);
     process.exit(1);
 });