@thammarongg/jira-mcp 0.3.0 → 0.5.0

package/dist/uninstall.js

@@ -0,0 +1,140 @@
+import { AGENTS, hasAgentEntry, removeAgentConfig, resolveAgents } from "./agents.js";
+import { makePrompter } from "./prompt.js";
+function parseFlags(argv) {
+    const flags = {};
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === "--agents") {
+            const value = argv[++i];
+            if (value === undefined)
+                throw new Error("Missing value for --agents");
+            flags.agents = value;
+        }
+        else if (arg === "--yes") {
+            flags.yes = true;
+        }
+        else if (arg === "--help" || arg === "-h") {
+            flags.help = true;
+        }
+        else {
+            throw new Error(`Unknown option: ${arg} (see --help)`);
+        }
+    }
+    return flags;
+}
+function printUsage() {
+    console.log(`jira-mcp uninstall — remove jira MCP entries
+
+Usage:
+  npx -y @thammarongg/jira-mcp uninstall
+  npx -y @thammarongg/jira-mcp uninstall --agents all --yes
+
+Options:
+  --agents <list>    Comma-separated agent ids or 'all'
+  --yes              Skip the confirmation prompt
+  -h, --help         Show this help
+`);
+}
+function configuredAgents() {
+    return AGENTS.filter((agent) => hasAgentEntry(agent));
+}
+function resolveConfigured(spec, configured) {
+    const norm = spec.trim().toLowerCase();
+    if (norm === "all" || norm === "a")
+        return [...configured];
+    const ids = norm.split(/[,\s]+/).filter(Boolean);
+    const selected = [];
+    for (const id of ids) {
+        const agent = /^\d+$/.test(id)
+            ? configured[Number(id) - 1]
+            : configured.find((candidate) => candidate.id === id);
+        if (!agent) {
+            throw new Error(`Unknown configured agent '${id}'. Valid: ${configured.map((candidate, index) => `${index + 1}/${candidate.id}`).join(", ")} or all`);
+        }
+        if (!selected.includes(agent))
+            selected.push(agent);
+    }
+    if (selected.length === 0)
+        throw new Error("No agents selected");
+    return selected;
+}
+async function promptSelection(p, configured) {
+    console.log("\njira-mcp uninstall — select agents to remove:\n");
+    console.log("  a) Select All");
+    configured.forEach((agent, index) => {
+        console.log(`  ${index + 1}) ${agent.label.padEnd(15)} ${agent.path}`);
+    });
+    for (;;) {
+        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 resolveConfigured(answer, configured);
+        }
+        catch (err) {
+            if (p.closed)
+                throw err;
+            console.log(`  ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}
+export async function runUninstall(argv) {
+    const flags = parseFlags(argv);
+    if (flags.help) {
+        printUsage();
+        return;
+    }
+    const configured = configuredAgents();
+    if (configured.length === 0) {
+        console.error("No jira MCP entries found. Run install to configure an agent first.");
+        process.exitCode = 1;
+        return;
+    }
+    const p = !flags.yes ? makePrompter() : undefined;
+    try {
+        const selected = flags.agents
+            ? resolveAgents(flags.agents)
+            : flags.yes
+                ? [...configured]
+                : await promptSelection(p, configured);
+        console.log("\nWill remove the jira MCP server from:");
+        for (const agent of selected) {
+            if (hasAgentEntry(agent))
+                console.log(`  - ${agent.label.padEnd(15)} ${agent.path}`);
+            else
+                console.log(`  skip ${agent.label.padEnd(15)} ${agent.path} (no jira entry)`);
+        }
+        if (!flags.yes) {
+            const answer = (await p.ask("\nProceed? [y/N] ")).trim().toLowerCase();
+            if (answer !== "y" && answer !== "yes") {
+                console.log("Aborted.");
+                return;
+            }
+        }
+        let removed = 0;
+        let failed = false;
+        for (const agent of selected) {
+            try {
+                const result = removeAgentConfig(agent);
+                if (result === "removed") {
+                    removed++;
+                    console.log(`  ok  ${agent.label.padEnd(15)} ${agent.path} (removed)`);
+                }
+                else {
+                    console.log(`  skip ${agent.label.padEnd(15)} ${agent.path} (no jira entry)`);
+                }
+            }
+            catch (err) {
+                failed = true;
+                console.error(`  ERR ${agent.label.padEnd(15)} ${agent.path}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        if (removed === 0 || failed)
+            process.exitCode = 1;
+        if (removed > 0)
+            console.log("\nDone. Restart each agent to pick up the change.");
+    }
+    finally {
+        p?.close();
+    }
+}

package/dist/update.js

@@ -0,0 +1,71 @@
+import { AGENTS, hasAgentEntry, readAgentEnv, resolveAgents, writeAgentConfig } from "./agents.js";
+function parseFlags(argv) {
+    const flags = {};
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === "--agents") {
+            const value = argv[++i];
+            if (value === undefined)
+                throw new Error("Missing value for --agents");
+            flags.agents = value;
+        }
+        else if (arg === "--yes") {
+            // Accepted for scripts that use the same non-interactive convention as install/uninstall.
+        }
+        else if (arg === "--help" || arg === "-h") {
+            flags.help = true;
+        }
+        else {
+            throw new Error(`Unknown option: ${arg} (see --help)`);
+        }
+    }
+    return flags;
+}
+function printUsage() {
+    console.log(`jira-mcp update — refresh existing jira MCP entries
+
+Usage:
+  npx -y @thammarongg/jira-mcp update [--agents <list>]
+
+Options:
+  --agents <list>    Comma-separated agent ids or 'all'
+  -h, --help         Show this help
+`);
+}
+export async function runUpdate(argv) {
+    const flags = parseFlags(argv);
+    if (flags.help) {
+        printUsage();
+        return;
+    }
+    const selected = flags.agents ? resolveAgents(flags.agents) : [...AGENTS];
+    let found = 0;
+    let failed = false;
+    for (const agent of selected) {
+        const env = readAgentEnv(agent);
+        if (!env) {
+            const reason = hasAgentEntry(agent) ? "no readable jira credentials" : "no jira entry";
+            console.log(`  skip ${agent.label.padEnd(15)} ${agent.path} (${reason})`);
+            continue;
+        }
+        found++;
+        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)}`);
+        }
+    }
+    if (found === 0) {
+        console.error("No jira MCP entries with credentials were found. Run install to configure an agent first.");
+        process.exitCode = 1;
+    }
+    else if (failed) {
+        process.exitCode = 1;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thammarongg/jira-mcp",
-  "version": "0.3.0",
+  "version": "0.5.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": {

package/skill/SKILL.md

@@ -27,11 +27,35 @@ Or non-interactive: `npx -y @thammarongg/jira-mcp install --agents all
 --yes`. Required env vars:
 
 - `JIRA_BASE_URL` — `https://your-org.atlassian.net` (Cloud) or
-  `https://jira.yourcompany.com` (DC)
+  `https://jira.yourcompany.com` (DC); a DC context path such as `/jira` is
+  supported and preserved
 - Cloud: `JIRA_EMAIL` + `JIRA_API_TOKEN` (token from id.atlassian.com →
   Security → API tokens)
 - DC: `JIRA_USERNAME` + `JIRA_API_TOKEN` (PAT) or `JIRA_PASSWORD` (app password)
 
+When a selected agent already has a `jira` entry, the interactive installer
+offers to reuse its base URL and account; `--yes` with no credential flags
+reuses those credentials without prompting.
+
+The CLI also supports these maintenance commands:
+
+```bash
+npx -y @thammarongg/jira-mcp update                 # refresh configured entries
+npx -y @thammarongg/jira-mcp update --agents codex
+npx -y @thammarongg/jira-mcp uninstall              # choose entries to remove
+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 skips agents without a `jira` entry.
+`uninstall` preserves every other config key and confirms before removing the
+selected entries unless `--yes` is supplied. Running the command with no
+arguments in a terminal shows a status card; MCP clients use piped stdio, so
+the same command starts the server and expects `JIRA_*` environment variables.
+Without those variables, a bare server start reports a missing
+`JIRA_BASE_URL`.
+
 Claude Code one-liner:
 
 ```bash
@@ -64,12 +88,17 @@ After setup, verify with the `get_current_user` tool.
 
 ## Tool map
 
-- **Boards/sprints**: `list_boards`, `get_board`, `list_sprints`, `get_sprint`,
+- **Boards/sprints**: `list_boards` (the project filter is one Agile
+  `projectKeyOrId` value), `get_board`, `list_sprints`, `get_sprint`,
   `create_sprint`, `update_sprint`, `close_sprint`, `get_sprint_issues`,
-  `get_sprint_view` (UI-like full view), `get_backlog`
+  `get_sprint_view` (UI-like full view), `get_backlog`. Cloud backlog and
+  issue-list reads use Software 1.0 enhanced endpoints with cursor paging;
+  Data Center uses Agile 1.0 with `startAt`/`total`. `create_sprint` sends
+  `originBoardId` to the top-level Agile sprint-create route.
 - **Epics**: `list_epics` (by board), `get_epic`, `get_epic_issues`,
   `create_epic`, `move_issue_to_epic`, `get_epic_meta` — epics are addressed by
-  key or numeric ID, and these work on team-managed projects too
+  key or numeric ID. Cloud `get_epic_issues` uses Software 1.0 enhanced
+  cursor paging; team-managed projects fall back to JQL/search as needed.
 - **Issues**: `get_issue`, `create_issue`, `update_issue`, `delete_issue`,
   `search_issues` (JQL), `get_issue_create_meta`, `get_issue_transitions`,
   `transition_issue`, `assign_issue`, `add_comment`, `list_comments`,
@@ -86,7 +115,8 @@ After setup, verify with the `get_current_user` tool.
 `active`) → `get_sprint_issues` or `get_sprint_view` for the full picture.
 
 **Backlog review**: `get_backlog(boardId)` — issues on the board that are not
-in a sprint, ordered by rank; pass `jql` to narrow it.
+in a sprint, ordered by rank; pass `jql` to narrow it. On Cloud, pass the
+returned `nextPageToken` for the next page; on Data Center, pass `startAt`.
 
 **Epic breakdown**: `list_epics(boardId)` → `get_epic_issues(epicIdOrKey)` for
 the children. To create one, `get_epic_meta(projectKey)` gives the epic issue
@@ -96,6 +126,16 @@ custom field via `customFields`.
 **Create an issue**: call `get_issue_create_meta(projectKeys=...)` first to
 discover valid issue types and required fields, then `create_issue`
 (custom fields go in `customFields`, e.g. `{ "customfield_10010": "..." }`).
+The metadata tool composes the current per-project and per-issue-type
+endpoints; the deprecated `/issue/createmeta` query form is not used. Pass
+`projectKeys` when fields are expanded (the default); omit it only with
+`expand: "projects.issuetypes"` for issue-type summaries. Metadata requests
+use a fixed concurrency limit of four.
+
+**Comments and descriptions**: pass plain text — `add_comment`, `create_issue`,
+`create_epic`, `update_issue` and `add_worklog` convert it to ADF automatically
+on Jira Cloud (v3). Blank lines separate paragraphs; Markdown is not rendered.
+No need to hand-build an ADF document or fall back to `jira_api`.
 
 **Move work through the workflow**: `get_issue_transitions(issueKey)` to see
 available transitions and required fields, then `transition_issue`.
@@ -120,6 +160,14 @@ available transitions and required fields, then `transition_issue`.
   On Data Center it still uses `startAt`/`total`.
 - Assignees: pass an account ID on Cloud, a username on DC — the server maps
   it to the right field shape automatically.
+- `get_user` uses `/user?accountId=...` on Cloud/v3 and `/user?username=...` on
+  Data Center/v2. `create_issue` maps its `dueDate` input to Jira's `duedate`
+  field, and `add_worklog` accepts an optional `started` timestamp (Jira
+  defaults it to now when omitted).
+- Data Center exposes REST API v2/latest, not `/rest/api/3`; do not force
+  `JIRA_API_VERSION=3` for a DC host. The default deployment detection routes
+  Cloud (`*.atlassian.net`) and DC endpoints separately, while ADF and user
+  field shapes follow the selected API version.
 - To remove an issue from an epic: `update_issue` with
   `fields: { "epic": null }`.
 - Anything not covered by a dedicated tool → `jira_api` with method, path