{"_id":"@nevzatcirak/jira-mcp","_rev":"6-f1fb3505b1965e5053e39c214fcbfb4b","name":"@nevzatcirak/jira-mcp","dist-tags":{"latest":"1.1.1"},"versions":{"0.0.0-stage":{"name":"@nevzatcirak/jira-mcp","version":"0.0.0-stage","_id":"@nevzatcirak/jira-mcp@0.0.0-stage","stub":true,"maintainers":[{"name":"nevzatcirak","email":"nevzatcirak5@gmail.com"}],"dist":{"shasum":"ab6c6cca84423c2e8aa64dd66807765761a35bc7","tarball":"https://registry.npmjs.org/@nevzatcirak/jira-mcp/-/jira-mcp-0.0.0-stage.tgz","fileCount":2,"integrity":"sha512-I+rsS2fBOK+q++7Gxw+pK5DwEzWPKhJarjuqWrs8TXP/oT4TyJikdWl2zF9LyRc7iqrt4dhwLIG/cF8IFkOuPQ==","signatures":[{"sig":"MEUCIQDyO+aJIppvxv+cjS8ejzzBbuNB3qCjaHGVdErEILMy/wIgU8s9ZktxTGnM72baQqXKwTyfbSidwsm5mhDaBwVsaC8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":343},"_npmUser":{"name":"nevzatcirak","email":"nevzatcirak5@gmail.com"},"description":"Temporary package placeholder for staged publishing","directories":{}},"1.0.0":{"name":"@nevzatcirak/jira-mcp","version":"1.0.0","keywords":["jira","mcp","model-context-protocol","atlassian","agile","board","backlog","worklog"],"author":{"name":"Nevzat Cirak"},"license":"MIT","_id":"@nevzatcirak/jira-mcp@1.0.0","maintainers":[{"name":"nevzatcirak","email":"nevzatcirak5@gmail.com"}],"homepage":"https://github.com/nevzatcirak/jira-mcp#readme","bugs":{"url":"https://github.com/nevzatcirak/jira-mcp/issues"},"bin":{"jira-mcp":"dist/index.js"},"dist":{"shasum":"7131928c8f2760f8362d3bb79af7578df262c65d","tarball":"https://registry.npmjs.org/@nevzatcirak/jira-mcp/-/jira-mcp-1.0.0.tgz","fileCount":75,"integrity":"sha512-KLrUJc/N/b5NF9DC12U/RePYbQIBpJ14SbQIO2SoL/jjpxsVg/PZkOfmSTjrDea+EMo62VffmowapcVc1uTw6g==","signatures":[{"sig":"MEUCIQDejAGg/e6OnAnFKKZfhizltJveKSk/ne6i698ofthUJQIgZzjMAdofnudUZvWTGHuRfCyhr7ZOW0prvLn8fJ/vcg8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEYCIQDPGqGV8kroJ9fYTm3ELTVf1c9PP50C7qxkoYSdWOLRDQIhAJy4AsfGI9rUuOWsUuvtbrd+hKbrCFq0k917tJoCKegS","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":149071},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=20"},"gitHead":"a0f8917143c2e954c78b0843df8f5c76e927c58f","scripts":{"lint":"eslint .","test":"vitest run","build":"tsc","start":"node dist/index.js","benchmark":"tsc -p tsconfig.benchmark.json && node dist-benchmark/benchmark/search-size.js"},"_npmUser":{"name":"nevzatcirak","email":"nevzatcirak5@gmail.com"},"repository":{"url":"git+https://github.com/nevzatcirak/jira-mcp.git","type":"git"},"_npmVersion":"10.8.2","description":"Deployment-agnostic Jira MCP server (stdio) for Jira Server, Data Center and Cloud — compact issue cards, semantic actions, full Agile board support","directories":{},"_nodeVersion":"20.20.2","dependencies":{"zod":"^3.25.76","@modelcontextprotocol/sdk":"^1.32.0"},"publishConfig":{"@nevzatcirak:registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"eslint":"^9.20.0","vitest":"^3.0.0","typescript":"^5.7.0","@types/node":"^22.10.0","typescript-eslint":"^8.20.0"},"_npmOperationalInternal":{"tmp":"tmp/jira-mcp_1.0.0_1794145350420_0.4145528030794582","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@nevzatcirak/jira-mcp","version":"1.0.1","keywords":["jira","mcp","model-context-protocol","atlassian","agile","board","backlog","worklog"],"author":{"name":"Nevzat Cirak"},"license":"MIT","_id":"@nevzatcirak/jira-mcp@1.0.1","maintainers":[{"name":"nevzatcirak","email":"nevzatcirak5@gmail.com"}],"homepage":"https://github.com/nevzatcirak/jira-mcp#readme","bugs":{"url":"https://github.com/nevzatcirak/jira-mcp/issues"},"bin":{"jira-mcp":"dist/index.js"},"dist":{"shasum":"3d65d70dba465eec8f6df372a240abdc63466349","tarball":"https://registry.npmjs.org/@nevzatcirak/jira-mcp/-/jira-mcp-1.0.1.tgz","fileCount":75,"integrity":"sha512-kpbK7/lLILMDc080kcC4He/+E49fbzi9s1BKNlt4aQbIO8izXnJRFuLuPA3yd47qRIwIhf2EASHnoIRPgaV5Sg==","signatures":[{"sig":"MEUCIQCBWIu/NVrD3yfksuCjHh8yunaXquvXu4Szb/TzPeLzPgIgBlBrlFWWT54pvkujov+2MH0PjmQ40xFIkoruri8yuZk=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEUCIHm7+QuBXhv4pT6oNRJROiVVDYxs73/4z9pMkSvHqK3dAiEAm98tILtjsTmPohbPzqmNWR6zD7AsQyVVZV3dcpX5KOQ=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":153181},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=20"},"gitHead":"95beaf70db3b3bd864779d675c539782ea07bd9d","scripts":{"lint":"eslint .","test":"vitest run","build":"tsc","start":"node dist/index.js","benchmark":"tsc -p tsconfig.benchmark.json && node dist-benchmark/benchmark/search-size.js"},"_npmUser":{"name":"nevzatcirak","email":"nevzatcirak5@gmail.com"},"repository":{"url":"git+https://github.com/nevzatcirak/jira-mcp.git","type":"git"},"_npmVersion":"10.8.2","description":"Deployment-agnostic Jira MCP server (stdio) for Jira Server, Data Center and Cloud — compact issue cards, semantic actions, full Agile board support","directories":{},"_nodeVersion":"20.20.2","dependencies":{"zod":"^3.25.76","@modelcontextprotocol/sdk":"^1.32.0"},"publishConfig":{"@nevzatcirak:registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"eslint":"^9.20.0","vitest":"^3.0.0","typescript":"^5.7.0","@types/node":"^22.10.0","typescript-eslint":"^8.20.0"},"_npmOperationalInternal":{"tmp":"tmp/jira-mcp_1.0.1_1794147431454_0.2893211575722664","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@nevzatcirak/jira-mcp","version":"1.0.2","keywords":["jira","mcp","model-context-protocol","atlassian","agile","board","backlog","worklog"],"author":{"name":"Nevzat Cirak"},"license":"MIT","_id":"@nevzatcirak/jira-mcp@1.0.2","maintainers":[{"name":"nevzatcirak","email":"nevzatcirak5@gmail.com"}],"homepage":"https://github.com/nevzatcirak/jira-mcp#readme","bugs":{"url":"https://github.com/nevzatcirak/jira-mcp/issues"},"bin":{"jira-mcp":"dist/index.js","jira-mcp-server":"dist/index.js"},"dist":{"shasum":"ff21e2ff896885d4b2b081333ddc56a71dafff40","tarball":"https://registry.npmjs.org/@nevzatcirak/jira-mcp/-/jira-mcp-1.0.2.tgz","fileCount":75,"integrity":"sha512-eRjJfGn5kuO8ZFUBpoho2a4/owuwI35NOXI5qeQ3siy8hduhEpbfnGS0jlGrqMuyrdMCOa/M2ZRrgWbv/BbE/A==","signatures":[{"sig":"MEUCIQCyFCUNDK/yCTx2+81Alki+EnAYEmgRh04wdxs2Ibp3lQIgLMf21TdKLufOIpOti17/wKOgaODP/Z45yvvjB/6RNV4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEYCIQD+EFsERLJZHIHtmrcstfa4QXvgE70l0BzarG7Gii7I1AIhAJaFb7+gL1wq6/fOiqrexnnEJD50rjAJWP/oIapzjwdw","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":153824},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=20"},"gitHead":"d78e35e79af215e96532ed4c4d704dd6083992c6","scripts":{"lint":"eslint .","test":"vitest run","build":"tsc","start":"node dist/index.js","benchmark":"tsc -p tsconfig.benchmark.json && node dist-benchmark/benchmark/search-size.js"},"_npmUser":{"name":"nevzatcirak","email":"nevzatcirak5@gmail.com"},"repository":{"url":"git+https://github.com/nevzatcirak/jira-mcp.git","type":"git"},"_npmVersion":"10.8.2","description":"Deployment-agnostic Jira MCP server (stdio) for Jira Server, Data Center and Cloud — compact issue cards, semantic actions, full Agile board support","directories":{},"_nodeVersion":"20.20.2","dependencies":{"zod":"^3.25.76","@modelcontextprotocol/sdk":"^1.32.0"},"publishConfig":{"@nevzatcirak:registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"eslint":"^9.20.0","vitest":"^3.0.0","typescript":"^5.7.0","@types/node":"^22.10.0","typescript-eslint":"^8.20.0"},"_npmOperationalInternal":{"tmp":"tmp/jira-mcp_1.0.2_1794148001611_0.43563031301397315","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@nevzatcirak/jira-mcp","version":"1.1.0","keywords":["jira","mcp","model-context-protocol","atlassian","agile","board","backlog","worklog"],"author":{"name":"Nevzat Cirak"},"license":"MIT","_id":"@nevzatcirak/jira-mcp@1.1.0","maintainers":[{"name":"nevzatcirak","email":"nevzatcirak5@gmail.com"}],"homepage":"https://github.com/nevzatcirak/jira-mcp#readme","bugs":{"url":"https://github.com/nevzatcirak/jira-mcp/issues"},"bin":{"jira-mcp":"dist/index.js","jira-mcp-server":"dist/index.js"},"dist":{"shasum":"9328d9aa6dee47ab97ef0c30a7b2c8a0341a3123","tarball":"https://registry.npmjs.org/@nevzatcirak/jira-mcp/-/jira-mcp-1.1.0.tgz","fileCount":83,"integrity":"sha512-6YGRIMw1IGeAxE2fQWS5/l9Bt4NdvWPCgSBEwa3LblN51oSiZom1NjEa9uqw8oq8rf5s0rsN6Im/uesbL2mmQw==","signatures":[{"sig":"MEUCIQDmfUMsWTicxO21Oimey/kJicxpnXyEe/jpdFsNylmZngIgaFIr//nZaiSR5R+DZu9+I3MA1gT07HBEsL8C3lfGXqA=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEQCICFr7/I3/URRa6u0cdAo207ZkvohvFzJLaxvVGpb4BZXAiAWmUv7wer8oRG2gMqW6IT7RU90apNQkcr3KUK/pIt3Hw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":181843},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=20"},"gitHead":"905bc2155df9bb8eb06625d93f9785f6cf2d1fe7","scripts":{"lint":"eslint .","test":"vitest run","build":"tsc","start":"node dist/index.js","benchmark":"tsc -p tsconfig.benchmark.json && node dist-benchmark/benchmark/search-size.js"},"_npmUser":{"name":"nevzatcirak","email":"nevzatcirak5@gmail.com"},"repository":{"url":"git+https://github.com/nevzatcirak/jira-mcp.git","type":"git"},"_npmVersion":"10.8.2","description":"Deployment-agnostic Jira MCP server (stdio) for Jira Server, Data Center and Cloud — compact issue cards, semantic actions, full Agile board support","directories":{},"_nodeVersion":"20.20.2","dependencies":{"zod":"^3.25.76","@modelcontextprotocol/sdk":"^1.32.0"},"publishConfig":{"@nevzatcirak:registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"eslint":"^9.20.0","vitest":"^3.0.0","typescript":"^5.7.0","@types/node":"^22.10.0","typescript-eslint":"^8.20.0"},"_npmOperationalInternal":{"tmp":"tmp/jira-mcp_1.1.0_1794198805597_0.4327322202058388","host":"s3://npm-registry-packages-npm-production"}},"1.1.1":{"_id":"@nevzatcirak/jira-mcp@1.1.1","bin":{"jira-mcp":"dist/index.js","jira-mcp-server":"dist/index.js"},"bugs":{"url":"https://github.com/nevzatcirak/jira-mcp/issues"},"dist":{"shasum":"80869e85e494f882ab15b38d0a407886f262e483","tarball":"https://registry.npmjs.org/@nevzatcirak/jira-mcp/-/jira-mcp-1.1.1.tgz","fileCount":83,"integrity":"sha512-sTPQRxG0NE9mgu+kJlQ6QxBBfe/zvriL9x6gqSUCRd1lf5Dwjn+y+BslA3GMV1WjFkvqWPZoXtP2R99Kb7GipA==","signatures":[{"sig":"MEUCIFRuEtWOBL4Q59xtqUGY2y9UOJ6v2pBv/eub/wFqj25qAiEAxZYBokYD99qGtlDs2FPUvxwPq1uRY5KCltyOU+OAJwg=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIA8vVWeSIrWsdFiWoMrdlBDyiAP9rA6ZMCAJudi18XdOAiEAnf6EUNOt/5xH6MiRToDHPqk/QYjnm4t2hnJP7bLzlDA="}],"unpackedSize":186628},"main":"dist/index.js","name":"@nevzatcirak/jira-mcp","type":"module","types":"dist/index.d.ts","author":{"name":"Nevzat Cirak"},"engines":{"node":">=20"},"gitHead":"686617e75975ebb057fce51c3716031b94d2ded3","license":"MIT","scripts":{"lint":"eslint .","test":"vitest run","build":"tsc","start":"node dist/index.js","benchmark":"tsc -p tsconfig.benchmark.json && node dist-benchmark/benchmark/search-size.js"},"version":"1.1.1","_npmUser":{"name":"nevzatcirak","email":"nevzatcirak5@gmail.com"},"homepage":"https://github.com/nevzatcirak/jira-mcp#readme","keywords":["jira","mcp","model-context-protocol","atlassian","agile","board","backlog","worklog"],"repository":{"url":"git+https://github.com/nevzatcirak/jira-mcp.git","type":"git"},"_npmVersion":"10.8.2","description":"Deployment-agnostic Jira MCP server (stdio) for Jira Server, Data Center and Cloud — compact issue cards, semantic actions, full Agile board support","directories":{},"maintainers":[{"name":"nevzatcirak","email":"nevzatcirak5@gmail.com"}],"_nodeVersion":"20.20.2","dependencies":{"zod":"^3.25.76","@modelcontextprotocol/sdk":"^1.32.0"},"publishConfig":{"@nevzatcirak:registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"eslint":"^9.20.0","vitest":"^3.0.0","typescript":"^5.7.0","@types/node":"^22.10.0","typescript-eslint":"^8.20.0"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/jira-mcp_1.1.1_1794426473603_0.9857431869101123"}}},"time":{"created":"2026-11-08T13:41:13.631Z","modified":"2026-11-11T19:47:53.927Z","0.0.0-stage":"2026-11-08T13:41:13.631Z","1.0.0":"2026-11-08T13:42:30.512Z","1.0.1":"2026-11-08T14:17:11.581Z","1.0.2":"2026-11-08T14:26:41.729Z","1.1.0":"2026-11-09T04:33:25.756Z","1.1.1":"2026-11-11T19:47:53.741Z"},"bugs":{"url":"https://github.com/nevzatcirak/jira-mcp/issues"},"author":{"name":"Nevzat Cirak"},"license":"MIT","homepage":"https://github.com/nevzatcirak/jira-mcp#readme","keywords":["jira","mcp","model-context-protocol","atlassian","agile","board","backlog","worklog"],"repository":{"url":"git+https://github.com/nevzatcirak/jira-mcp.git","type":"git"},"description":"Deployment-agnostic Jira MCP server (stdio) for Jira Server, Data Center and Cloud — compact issue cards, semantic actions, full Agile board support","maintainers":[{"name":"nevzatcirak","email":"nevzatcirak5@gmail.com"}],"readme":"# ⚡ JIRA-MCP\n\nA **deployment-agnostic Jira MCP server** over stdio — works with **Jira Server, Data Center and Cloud** with zero hardcoded board IDs, project keys, status names or customfield IDs.\n\n╔══════════════════════════════════════════════════════════╗\n║  📦 **Compact output**   ·   issue cards, not raw payloads ║\n║  🧠 **Semantic actions**  ·   transition by status name     ║\n║  📋 **Full board support**·   boards, backlog, sprints      ║\n╚══════════════════════════════════════════════════════════╝\n\n[![npm version](https://img.shields.io/npm/v/@nevzatcirak/jira-mcp.svg)](https://www.npmjs.com/package/@nevzatcirak/jira-mcp)\n[![npm downloads](https://img.shields.io/npm/dm/@nevzatcirak/jira-mcp.svg)](https://www.npmjs.com/package/@nevzatcirak/jira-mcp)\n[![CI](https://github.com/nevzatcirak/jira-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/nevzatcirak/jira-mcp/actions/workflows/ci.yml)\n[![Publish](https://github.com/nevzatcirak/jira-mcp/actions/workflows/publish.yml/badge.svg)](https://github.com/nevzatcirak/jira-mcp/actions/workflows/publish.yml)\n[![node](https://img.shields.io/node/v/@nevzatcirak/jira-mcp.svg)](https://www.npmjs.com/package/@nevzatcirak/jira-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)\n\n---\n\n## 🎯 Why this package\n\nRaw Jira REST payloads are enormous — every issue drags avatars, schemas, changelogs, expand lists and renderer metadata into your LLM's context window. This server projects each issue into a **~230 byte card**, cutting context cost by **~99%** while keeping every field an agent actually needs.\n\n| | Raw Jira REST payload | jira-mcp card projection |\n|---|---|---|\n| Size per issue | ~40 KB *(typical)* | ~230 bytes *(measured)* |\n| Context cost (25 issues) | ~1 MB / ~250K tokens *(typical)* | ~5.7 KB / ~1.4K tokens *(measured)* |\n| Reduction | — | **~99% smaller** |\n\n**Measurement context** (measured values): Jira Server/DC instance, Scrum board\n(`boardId: 10212`), `jira_get_board_backlog` with `maxResults=25` — 25 issue cards\nfrom the real response, ~230 bytes per issue on average. The raw-payload column has\n**no measured baseline for this instance**: it uses the typical v2 search response\nsize of ~40 KB per issue, so those numbers are labeled *typical*, not measured.\nCard fields used in the measurement: `key`, `summary`, `type`, `status`, `assignee`,\n`priority`, `labels`, `parent`, `updated`.\n\nAn example card from that measurement, verbatim:\n\n```json\n{\n  \"key\": \"KAPI-215\",\n  \"summary\": \"Sync servisindeki OPA güncelleme yeteneğin Kapı tarafından sağlanması\",\n  \"type\": \"Task\",\n  \"status\": \"Resolved\",\n  \"assignee\": \"Barış Buğra ÖZDEMİR\",\n  \"priority\": \"Medium\",\n  \"labels\": [],\n  \"parent\": null,\n  \"updated\": \"2026-10-02\"\n}\n```\n\nRun it yourself with `npm run benchmark -- \"<your JQL>\"` — numbers depend on your instance, fields and issue size.\n\n---\n\n## ✨ Features (25 tools)\n\n### 🔍 Discovery\n\n| Tool | Purpose | Key parameters |\n|---|---|---|\n| `jira_get_server_info` | Instance version, deployment type, build number | — |\n| `jira_get_myself` | Authenticated user (accountId, name, displayName, timeZone) | — |\n| `jira_list_projects` | Projects the user can browse | `query?`, `startAt?`, `maxResults?` |\n| `jira_get_project_meta` | Required fields + allowed values per issue type — call before create/update | `project?` or `issueKey?` |\n| `jira_find_user` | Find users by username / display name before assigning | `query`, `maxResults?`, `startAt?` |\n| `jira_list_transitions` | Available workflow transitions for an issue | `issueKey` |\n\n### 📖 Reading\n\n| Tool | Purpose | Key parameters |\n|---|---|---|\n| `jira_search_issues` | JQL search returning compact issue cards | `jql`, `fields?`, `startAt?`, `maxResults?` |\n| `jira_get_issue` | One issue + truncated description, optional comments/worklogs | `issueKey`, `fields?`, `maxDescriptionChars?`, `includeComments?`, `includeWorklogs?` |\n| `jira_list_boards` | Agile boards, filter by project / type / name | `projectKeyOrId?`, `type?: scrum\\|kanban`, `name?` |\n| `jira_get_board_backlog` | Board backlog as issue cards, optional JQL | `boardId`, `jql?`, pagination |\n| `jira_list_sprints` | Sprints of a board, filter by state | `boardId`, `state?: future,active,closed` |\n\n*(also: `jira_get_board_issues` — issues currently on a board, `jira_get_sprint_issues` — issues of one sprint)*\n\n### ✍️ Writing\n\n| Tool | Purpose | Key parameters |\n|---|---|---|\n| `jira_create_issue` | Create an issue; returns `{key, id, url}` | `project`, `issueType`, `summary`, `description?`, `assignee?`, `priority?`, `labels?`, `parentKey?`, `originalEstimate?`, `remainingEstimate?` |\n| `jira_update_issue` | Partial update — only provided fields change | `issueKey` + any create field |\n| `jira_transition_issue` | Semantic move: by target status **or** transition id | `issueKey`, `toStatus?` / `transitionId?`, `comment?` |\n| `jira_assign_issue` | Assign a user, or unassign with `\"-none-\"` | `issueKey`, `assignee` |\n| `jira_add_comment` | Add a comment (wiki string on Server/DC, ADF on Cloud — automatic) | `issueKey`, `comment` |\n\n**Estimates (time tracking).** `jira_create_issue` and `jira_update_issue` accept `originalEstimate`\nand `remainingEstimate` as Jira duration strings (`\"2h\"`, `\"1d 4h\"`, `\"30m\"`, `\"1w 2d 3h\"`):\n\n```json\n{ \"tool\": \"jira_update_issue\", \"arguments\": { \"issueKey\": \"ABC-123\", \"originalEstimate\": \"2h\" } }\n```\n\n> **Note:** duration units are interpreted by the instance's time tracking settings — `1d`\n> means `hoursPerDay` hours, which can differ per instance (so `\"1d\"` is not always the same\n> number of seconds everywhere). Estimates are only sent when provided; on update, fields you\n> omit are left untouched. On Cloud, a known Atlassian bug (JRACLOUD-67539) makes a\n> single-field update overwrite the other estimate — send both together on Cloud.\n\n### ⏱️ Time & Links\n\n| Tool | Purpose | Key parameters |\n|---|---|---|\n| `jira_add_worklog` | Log work: `'3h 30m'` or decimal hours (`8.05` → `'8h 3m'`); estimate adjust modes | `issueKey`, `timeSpent`, `started?`, `startedHour?` (default `07:30`), `adjustEstimate?: auto\\|leave\\|new\\|manual` |\n| `jira_list_worklogs` | Paginated worklog list | `issueKey`, pagination |\n| `jira_link_issues` | Link two issues (`Relates`, `Blocks`, …) | `linkType`, `inwardIssueKey` / `outwardIssueKey` |\n| `jira_add_remote_link` | Attach an external URL to an issue | `issueKey`, `url`, `title?` |\n| `jira_add_attachment` | Upload a local file (max 10 MB) | `issueKey`, `filePath`, `fileName?` |\n\n### 🏃 Sprint\n\n| Tool | Purpose | Key parameters |\n|---|---|---|\n| `jira_move_issues_to_sprint` | Move up to 50 issues into a sprint; returns `{moved, errors}` | `sprintId`, `issueKeys[1..50]` |\n\n### 🧩 Extensibility\n\n| Tool | Purpose | Key parameters |\n|---|---|---|\n| `jira_provider_call` | Call a workplace-specific Jira plugin endpoint defined in `JIRA_PROVIDERS_CONFIG` (no code changes needed) | `provider`, `endpoint`, `params?` |\n\n---\n\n## 📥 Installation\n\n**1 · Run directly with npx (recommended):**\n\n```bash\nnpx @nevzatcirak/jira-mcp\n```\n\n**2 · Install globally:**\n\n```bash\nnpm install -g @nevzatcirak/jira-mcp\njira-mcp\n```\n\n**3 · From source:**\n\n```bash\ngit clone https://github.com/nevzatcirak/jira-mcp.git\ncd jira-mcp\nnpm install && npm run build\nnode dist/index.js\n```\n\n**Doğrulama:**\n\n```bash\njira-mcp --version\n# @nevzatcirak/jira-mcp 1.1.1\n```\n\n---\n\n## 🔁 Migrating from other jira-mcp packages\n\nIf a different jira-mcp package was installed earlier — one that registers the same\n`jira-mcp` bin name — a global install of this package fails with an `EEXIST` error.\nFind and remove the old package first:\n\n```bash\n# unix\nnpm ls -g | grep jira\nnpm rm -g <old-package-name>\n```\n\n```powershell\n# Windows (PowerShell)\nnpm ls -g | findstr jira\nnpm rm -g <old-package-name>\n```\n\nIf a leftover bin shim remains, check which package it points to with\n`where jira-mcp` (Windows) or `which -a jira-mcp` (unix).\n\n> MCP clients that run the server through `npx` (the recommended setup) are **not**\n> affected by this conflict — `npx` resolves the package by full name and does not use\n> the global bin shim.\n\n---\n\n## 🩺 Troubleshooting\n\n**`npx` crashes on every run.**\nCorrupted `npx` cache. Delete the cached package folder and `npx` re-downloads it on the\nnext run:\n\n- Windows: `%LocalAppData%\\npm-cache\\_npx`\n- unix: `~/.npm/_npx`\n\n**Windows: remote npx invocation fails (\"not recognized\").**\nOn Windows, the short remote form `npx -y @nevzatcirak/jira-mcp --version` can fail with\na \"not recognized\" error, while the same command works on unix. This is **known npx\nbehavior on Windows, not a package defect**. Use one of these workarounds:\n\n- Install globally and run the bin: `npm i -g @nevzatcirak/jira-mcp` then `jira-mcp`\n- Pass the package and bin separately: `npx -y -p @nevzatcirak/jira-mcp jira-mcp`\n- Skip the shim entirely — call the entry point with node in your MCP client config:\n  `node <install-path>/dist/index.js`\n\n**The old 6-tool server still seems to run.**\nA leftover global bin shim may still resolve to the old package. Check which package the\nshim points to with `where jira-mcp` (Windows) or `which jira-mcp` (unix), remove the old\npackage (`npm rm -g <old-package>`), then reinstall this one.\n\n**`\"The backlog is not available on Kanban boards\"`**\nJira platform restriction: the backlog endpoint exists only on **Scrum** boards. For a\nKanban board, use `jira_get_board_issues` with a JQL filter instead.\n\n---\n\n## ⚙️ Configuration\n\n| Variable | Required | Description |\n|---|---|---|\n| `JIRA_BASE_URL` | ✅ | Instance base URL, e.g. `https://acme-jira.example.com` |\n| `JIRA_API_TOKEN` | ✅ | PAT (Server/DC) or API token (Cloud) |\n| `JIRA_EMAIL` | Cloud only | Cloud account email (required when instance type is cloud) |\n| `JIRA_INSTANCE_TYPE` | — | `auto` (default) \\| `server` \\| `cloud` |\n| `JIRA_PROVIDERS_CONFIG` | — | Path to a JSONC file defining custom provider endpoints for `jira_provider_call` (see [Custom providers](#-custom-providers)) |\n\n**Server/DC vs Cloud authentication:**\n\n| | Jira Server / Data Center | Jira Cloud |\n|---|---|---|\n| Auth scheme | `Authorization: Bearer <token>` | `Authorization: Basic base64(email:token)` |\n| `JIRA_EMAIL` | not used | **required** |\n| User identity | username | accountId |\n| Comments | wiki string | ADF document |\n| Auto-detect | `JIRA_INSTANCE_TYPE=auto` probes `/rest/api/2/serverInfo` once and caches the deployment type | |\n\nConfig problems never crash the server — the tool call fails with a structured `CONFIG_MISSING` error listing the missing fields.\n\n---\n\n## 🧩 Custom providers\n\nMany workplaces run Jira plugins with their own REST endpoints (timesheet/attendance, custom reporting, …).\nThe `jira_provider_call` tool lets agents call those endpoints **without any code changes**: the endpoints are\ndefined in a JSONC config file, and `jira-mcp` stays deployment-agnostic — it ships **no** endpoint knowledge itself.\n\n**1 · Create a providers file** (copy [`examples/providers.example.jsonc`](./examples/providers.example.jsonc)):\n\n```jsonc\n{\n  \"providers\": {\n    \"workplaceTimesheet\": {\n      \"description\": \"Timesheet/attendance plugin\",\n      \"endpoints\": {\n        \"dailyWorked\": {\n          \"method\": \"GET\",                    // \"GET\" | \"POST\" (required)\n          \"path\": \"/rest/<plugin>/1.0/daily-worked?period={start}+-+{end}&timesheetUser=currentUser()\",\n          //           ^ path template (required); {param} placeholders are filled from `params`\n          \"responseMapping\": {                // optional projection of the raw JSON\n            \"total\": \"total\",\n            \"dailyHours\": \"items[].hour\"\n          },\n          \"maxResponseBytes\": 20000           // optional response size guard (default 200000)\n        }\n      }\n    }\n  }\n}\n```\n\n**2 · Point the server at the file** with `JIRA_PROVIDERS_CONFIG` (absolute path recommended):\n\nOpenCode (`opencode.json`):\n\n```json\n{\n  \"mcp\": {\n    \"jira\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@nevzatcirak/jira-mcp\"],\n      \"environment\": {\n        \"JIRA_BASE_URL\": \"https://acme-jira.example.com\",\n        \"JIRA_API_TOKEN\": \"your-personal-access-token\",\n        \"JIRA_PROVIDERS_CONFIG\": \"C:\\\\config\\\\jira-mcp.providers.jsonc\"\n      }\n    }\n  }\n}\n```\n\nLibreChat (`librechat.yaml`):\n\n```yaml\nmcp_servers:\n  jira:\n    command: npx\n    args:\n      - -y\n      - \"@nevzatcirak/jira-mcp\"\n    env:\n      JIRA_BASE_URL: https://acme-jira.example.com\n      JIRA_API_TOKEN: your-personal-access-token\n      JIRA_PROVIDERS_CONFIG: /opt/librechat/config/jira-mcp.providers.jsonc\n```\n\n(Docker deployments: volume-mount the providers file into the container and pass the in-container path.)\n\n**3 · Call it:**\n\n```json\n{ \"tool\": \"jira_provider_call\", \"arguments\": { \"provider\": \"workplaceTimesheet\", \"endpoint\": \"dailyWorked\", \"params\": { \"start\": \"2026-11-02\", \"end\": \"2026-11-08\" } } }\n```\n\n**Behavior:**\n\n- Requests go through the shared HTTP layer — same Bearer/Basic auth, 30s timeout and 429/5xx retry as every other tool.\n- `{param}` placeholders in `path` are filled (URL-encoded) from `params`; parameters not used by the template are sent as the POST body on `POST` endpoints.\n- With `responseMapping`, only the projected fields are returned (simple paths: `total`, `summary.name`, `items[].hour`). Without it, the raw JSON is returned — capped by `maxResponseBytes` (`RESPONSE_TOO_LARGE` when exceeded).\n- The config file is re-read on every call, so edits apply without restarting the server.\n- Errors are structured: `CONFIG_MISSING` (env var unset, with setup hint), `PROVIDERS_CONFIG_INVALID` (missing/broken file), `PROVIDER_UNKNOWN` / `ENDPOINT_UNKNOWN` (both list the available names so the agent can self-correct), `RESPONSE_TOO_LARGE`.\n\n---\n\n## 🔌 MCP client configuration\n\n### OpenCode (`opencode.json`)\n\n```json\n{\n  \"mcp\": {\n    \"jira\": {\n      \"type\": \"local\",\n      \"command\": [\n        \"npx\",\n        \"-y\",\n        \"@nevzatcirak/jira-mcp\"\n      ],\n      \"environment\": {\n        \"JIRA_BASE_URL\": \"https://acme-jira.example.com\",\n        \"JIRA_API_TOKEN\": \"your-personal-access-token\",\n        \"JIRA_INSTANCE_TYPE\": \"server\"\n      }\n    }\n  }\n}\n```\n\n### Claude Desktop (`claude_desktop_config.json`)\n\n```json\n{\n  \"mcpServers\": {\n    \"jira\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@nevzatcirak/jira-mcp\"],\n      \"env\": {\n        \"JIRA_BASE_URL\": \"https://acme-jira.example.com\",\n        \"JIRA_API_TOKEN\": \"your-personal-access-token\",\n        \"JIRA_INSTANCE_TYPE\": \"server\"\n      }\n    }\n  }\n}\n```\n\n### VS Code (`.vscode/mcp.json`)\n\n```json\n{\n  \"servers\": {\n    \"jira\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@nevzatcirak/jira-mcp\"],\n      \"env\": {\n        \"JIRA_BASE_URL\": \"https://acme-jira.example.com\",\n        \"JIRA_API_TOKEN\": \"your-personal-access-token\",\n        \"JIRA_INSTANCE_TYPE\": \"server\"\n      }\n    }\n  }\n}\n```\n\n> ☁️ **Cloud:** add `\"JIRA_EMAIL\": \"you@example.com\"`, set `JIRA_INSTANCE_TYPE` to `cloud` (or leave `auto`), and use an API token from `id.atlassian.com`.\n\n---\n\n## 🧪 Tool usage examples\n\n**1 · Pull a board backlog:**\n\n```json\n{ \"tool\": \"jira_get_board_backlog\", \"arguments\": { \"boardId\": 42, \"maxResults\": 25 } }\n```\n\n**2 · JQL search with extra fields:**\n\n```json\n{ \"tool\": \"jira_search_issues\", \"arguments\": { \"jql\": \"project = ABC AND status != Done ORDER BY updated DESC\", \"fields\": [\"storypoints\"], \"maxResults\": 25 } }\n```\n\n**3 · Issue details with comments:**\n\n```json\n{ \"tool\": \"jira_get_issue\", \"arguments\": { \"issueKey\": \"ABC-123\", \"includeComments\": true } }\n```\n\n**4 · Log work:**\n\n```json\n{ \"tool\": \"jira_add_worklog\", \"arguments\": { \"issueKey\": \"ABC-123\", \"timeSpent\": \"3h 30m\", \"comment\": \"Implemented retry logic and tests\" } }\n```\n\nDecimal hours work too (`8.05` → `8h 3m`, rounded to the nearest minute), and a date-only `started`\ngets its time-of-day from `startedHour` (default `07:30`):\n\n```json\n{ \"tool\": \"jira_add_worklog\", \"arguments\": { \"issueKey\": \"ABC-123\", \"timeSpent\": 8.05, \"started\": \"2026-11-09\", \"startedHour\": \"08:45\", \"comment\": \"Turnstile-tracked day\" } }\n```\n\n**5 · Set estimates (time tracking):**\n\n```json\n{ \"tool\": \"jira_update_issue\", \"arguments\": { \"issueKey\": \"ABC-123\", \"originalEstimate\": \"2h\", \"remainingEstimate\": \"1d\" } }\n```\n\n**6 · Attach a web link:**\n\n```json\n{ \"tool\": \"jira_add_remote_link\", \"arguments\": { \"issueKey\": \"ABC-123\", \"url\": \"https://design.example.com/spec-7\", \"title\": \"Design spec\" } }\n```\n\n**7 · Semantic transition (no transition IDs needed):**\n\n```json\n{ \"tool\": \"jira_transition_issue\", \"arguments\": { \"issueKey\": \"ABC-123\", \"toStatus\": \"Done\", \"comment\": \"Verified on staging\" } }\n```\n\n**8 · Move issues into a sprint:**\n\n```json\n{ \"tool\": \"jira_move_issues_to_sprint\", \"arguments\": { \"sprintId\": 318, \"issueKeys\": [\"ABC-123\", \"ABC-124\", \"ABC-125\"] } }\n```\n\n**9 · Find a user, then assign:**\n\n```json\n{ \"tool\": \"jira_find_user\", \"arguments\": { \"query\": \"Jane Doe\" } }\n```\n\n```json\n{ \"tool\": \"jira_assign_issue\", \"arguments\": { \"issueKey\": \"ABC-123\", \"assignee\": \"jdoe\" } }\n```\n\n**10 · Call a workplace plugin endpoint (custom provider):**\n\n```json\n{ \"tool\": \"jira_provider_call\", \"arguments\": { \"provider\": \"workplaceTimesheet\", \"endpoint\": \"dailyWorked\", \"params\": { \"start\": \"2026-11-02\", \"end\": \"2026-11-08\" } } }\n```\n\n---\n\n## 📝 Behavior notes\n\n**Card projection.** Every list/search result is a compact card — never avatars, schemas, changelogs or raw payloads:\n\n```json\n{\n  \"key\": \"ABC-123\",\n  \"summary\": \"Fix login redirect loop\",\n  \"type\": \"Bug\",\n  \"status\": \"In Progress\",\n  \"assignee\": \"jdoe\",\n  \"priority\": \"High\",\n  \"labels\": [\"backend\", \"auth\"],\n  \"parent\": \"ABC-100\",\n  \"updated\": \"2026-01-14\"\n}\n```\n\nExtra fields can be merged in via `fields` (deduplicated; `*all`/`*navigable` are dropped on list endpoints).\n\n**Pagination.** All paginated tools return top-level meta:\n\n```json\n{ \"total\": 120, \"startAt\": 0, \"maxResults\": 25, \"hasMore\": true, \"nextStartAt\": 25 }\n```\n\nKeep passing `startAt: nextStartAt` until `hasMore` is `false`.\n\n**Truncation rules.**\n\n- Issue descriptions: capped by `maxDescriptionChars` (default 500, max 20000)\n- Comments / worklog bodies in `jira_get_issue`: 500 chars each, capped at 1000 items\n- Worklog comments in `jira_list_worklogs`: 300 chars\n- Every truncated item reports `{ \"truncated\": true, \"totalLength\": 4211 }`\n- `maxResults` is hard-capped at 100 on every list tool\n\n**Structured errors.** Failures never throw raw stack traces — every error is a structured payload:\n\n```json\n{\n  \"error\": {\n    \"code\": \"JIRA_400\",\n    \"message\": \"Jira HTTP 400: ...\",\n    \"hint\": \"parentKey may be rejected for Cloud team-managed projects...\",\n    \"jiraErrors\": {\n      \"errorMessages\": [\"Issue does not exist or you do not have permission to see it.\"],\n      \"errors\": { \"assignee\": \"User 'jdoe' does not exist.\" }\n    }\n  }\n}\n```\n\nFixed codes include `CONFIG_MISSING`, `INVALID_ARGUMENT`, `JIRA_TIMEOUT`, `JIRA_NETWORK`, `AMBIGUOUS_TRANSITION`, `TRANSITION_NOT_FOUND`, `USER_NOT_FOUND`, `AMBIGUOUS_USER`, `FILE_TOO_LARGE`, `PROVIDERS_CONFIG_INVALID`, `PROVIDER_UNKNOWN`, `ENDPOINT_UNKNOWN`, `RESPONSE_TOO_LARGE`. Jira's own field errors are preserved verbatim in `jiraErrors`.\n\n**Resilience.** 30s per-request timeout, up to 2 retries on 429/5xx with `Retry-After` awareness, and an automatic `agile/1.0` → `greenhopper/1.0` fallback for older Server instances.\n\n---\n\n## 🛠️ Development\n\n```bash\nnpm install          # install dependencies\nnpm test             # unit tests (vitest, no Jira connection needed)\nnpm run build        # compile to dist/\nnpm run lint         # eslint\nnpm run benchmark    # payload-size benchmark (needs a live Jira)\n```\n\n**Integration tests (optional, against a real instance):**\n\n| Variable | Purpose |\n|---|---|\n| `JIRA_IT=1` | Enables integration tests (read-only scenario — connection env only) |\n| `JIRA_E2E_PROJECT` | Project key for the write scenario (issues are created **and deleted**) |\n| `JIRA_E2E_ISSUE_TYPE` | Optional issue type for the write scenario (default: `Task`) |\n\n---\n\n## 🚀 Publishing\n\nReleases are published to npm **automatically by CI** — never publish manually from a laptop.\n\n**Flow:**\n\n1. **Release workflow** (`.github/workflows/release.yml`, manual `workflow_dispatch`):\n   give it a semver version (e.g. `1.0.1`) — it bumps `package.json` + `package-lock.json`,\n   commits as `github-actions[bot]` with `chore: release vX`, creates tag `vX` and pushes both.\n2. The `v*` tag push triggers the **Publish workflow** (`.github/workflows/publish.yml`),\n   which runs tests + build and then `npm publish --access public` to\n   <https://registry.npmjs.org/>.\n\n**One-time setup (required):**\n\n- Create an npm **automation** token with **Read & Write** permission at\n  [npmjs.com → Access Tokens](https://www.npmjs.com/settings/~/tokens) (Classic Tokens section).\n- Add it as a repository secret: **GitHub repo → Settings → Secrets and variables →\n  Actions → New repository secret**, name it `NPM_TOKEN`.\n- The publish job uses `registry-url: https://registry.npmjs.org/` and passes the token\n  via `NODE_AUTH_TOKEN`.\n\n**Guards (the publish job fails fast on):**\n\n- **Version ↔ tag mismatch:** `package.json` version must match the pushed tag\n  (`v` + version, e.g. version `1.0.0` ↔ tag `v1.0.0`).\n- **Package name check:** `package.json` `name` must be exactly\n  `@nevzatcirak/jira-mcp` — prevents accidentally publishing the wrong package.\n\n> 📌 **Scoped package note:** `@nevzatcirak/jira-mcp` is a scoped package, so\n> `npm publish --access public` is **mandatory** (scoped packages default to\n> restricted, which requires a paid plan).\n>\n> 🖐️ **Manual dispatch note:** the Publish workflow also supports `workflow_dispatch`,\n> but a manual run skips the tag guard — it publishes whatever `version` is currently in\n> `package.json` (tests + build still run). Prefer the Release workflow so tags and\n> versions stay in sync.\n\n---\n\n## 📄 License\n\n[MIT](./LICENSE) © Nevzat Cirak\n","readmeFilename":"README.md"}