jira-mcp-ai 0.9.0

package/CHANGELOG.md

@@ -0,0 +1,139 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
+this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+Because registrations pin an exact version (see README), this file is the thing a
+user reads before bumping the pin. Entries describe what changes for **them** —
+new or renamed tools, changed tool input/output shapes, changed defaults, changed
+env var names — not internal refactors.
+
+## [0.9.0] — 2026-08-17
+
+The first release. Everything below is "added" relative to nothing, so this
+entry is the whole surface rather than a diff — later entries will be diffs
+against it.
+
+It is `0.9.0` and not `1.0.0` deliberately. The surface is complete and the
+gate is green, but this build has never been run against a real Atlassian
+tenant — every test in it answers a fake. A pre-1.0 number is the honest way to
+say so, and it keeps the semver promise unspent until a live run has been made:
+under 1.0.0 the same discovery would have to arrive as a breaking major.
+
+### Added
+
+- **52 tools in 10 packages**, registered as a set you choose with
+  `JIRA_TOOL_PACKAGES`:
+  - `core` (2) — `jira_capabilities`, `jira_get_myself`.
+  - `search` (4) — JQL search and approximate count, plus the saved-filter
+    reads `jira_list_filters` / `jira_get_filter`. Neither filter tool runs the
+    stored JQL; `jira_search` is the only tool that executes one.
+  - `issues` (5) — issue, comments, transitions, changelog and worklog reads.
+  - `issues-write` (8) — create, update, transition, add comment, edit comment,
+    assign, worklog, link.
+  - `issues-delete` (3) — delete issue, comment and worklog, behind the
+    irreversible tier below. Not in the `reader` profile and in no read-only
+    selection; `JIRA_PACKAGES_DENY=issues-delete` removes the surface entirely.
+  - `attachments` (3) — list attachment metadata, download a file to disk,
+    upload a file from disk.
+  - `collab` (12) — watchers, votes, components, versions and project roles:
+    the surface around an issue rather than inside it. Nothing in this package
+    deletes anything — "remove watcher" and "remove vote" are links their `add`
+    twin restores exactly.
+  - `meta` (6) — projects, fields, create-meta, statuses and link types.
+  - `users` (1) — `jira_search_users`.
+  - `agile` (8) — boards, sprints, sprint issues, move to sprint and to
+    backlog, plus the sprint lifecycle (create, start, close).
+- **Markdown on the way in and on the way out.** `jira_get_issue` and
+  `jira_get_comments` take `format: "text" | "markdown"`, and every rich-text
+  input on the 7 write tools that has one (`description`, `body`, `comment`)
+  takes the same option. The default is `text` and its output is byte-identical
+  to having no option at all, so nothing you already call changes. The dialect
+  is deliberately narrow — headings, lists, fenced code, inline code, bold,
+  italic, links — and anything outside it degrades exactly the way plain-text
+  flattening always did. Two safety rules travel with it: a mention renders
+  one-way (`@name` out, literal text back in), and only `http(s):` and
+  `mailto:` links keep their href.
+- **A plan/apply gate on all 25 write tools.** `JIRA_WRITE_MODE` defaults to
+  `plan`, where a write tool describes the change and returns a single-use
+  `plan_id` instead of performing it. Executing takes all three:
+  `JIRA_WRITE_MODE=apply`, an explicit `apply: true`, and that `plan_id` echoed
+  back with identical arguments. Ids die with the server process, and unsafe
+  writes are never replayed after an ambiguous failure.
+- **An irreversible tier for the three deletes**, which the normal gate does
+  not cover. On top of plan → apply they need `JIRA_ALLOW_IRREVERSIBLE=true`:
+  a blanket `JIRA_WRITE_MODE=apply` is never enough, because the variable is
+  set by the person who starts the server and the model cannot fill it in.
+  Planning a delete always works, even on a server that will never permit the
+  apply, and a refusal costs you nothing — no request is made and the
+  `plan_id` is not consumed, so flipping the variable and restarting does not
+  mean re-planning. The plan carries a `before` snapshot of what the apply
+  would destroy (for an issue: its summary, status and subtask keys; for a
+  comment or worklog: author, timestamps and an excerpt of the text), and a
+  successful apply echoes that same snapshot back — Jira answers a delete with
+  an empty 204, so this is the only receipt there is.
+- **Attachments, with the bytes on disk instead of in the conversation.**
+  `JIRA_MEDIA_DIR` is the one directory the server reads from and writes to.
+  Unset, the download and upload tools refuse with a configuration error and
+  make no Jira call at all; metadata listing needs no directory and keeps
+  working. A download sanitizes the Jira-supplied filename (it is tenant-authored
+  text, and `../../etc/passwd` lands as `passwd` inside your media directory),
+  never overwrites — a collision gets a suffixed name and the result tells you
+  it was renamed — and writes the file `0600`; the untouched original name is
+  still reported. An upload takes a plain file name inside that same directory
+  and **refuses** paths, `..` and subdirectories rather than rewriting them. Both
+  directions are size-capped, and an upload that fails ambiguously is never
+  retried for you.
+- **Tenant text arrives branded.** Any result that can carry free text written
+  inside Jira — issue and comment bodies, changelogs, worklogs, filter
+  descriptions, attachment filenames, delete `before` snapshots — is marked
+  `_untrusted` with a note that its content is data, never instructions.
+- **`jira-mcp-ai doctor`** — checks the configuration and probes the site, with
+  `--version` and `--help` alongside it. Its report goes to stdout only on these
+  non-server paths; under the server, stdout is the MCP protocol and every
+  diagnostic goes to stderr.
+- **Credential profiles** — `JIRA_PROFILE_<NAME>_SITE` / `_EMAIL` /
+  `_API_TOKEN`, selected with `JIRA_ACTIVE_PROFILE`. `JIRA_LOCK_PROFILE`
+  defaults to `true`, so a single tool call cannot switch tenant unless you
+  unlock it deliberately.
+- **Package trimming** — `JIRA_PACKAGES_DENY` wins over the selection (`core` is
+  force-re-added, so the server is never left with no tools), and
+  `JIRA_PACKAGES_READONLY` drops just the write-tier tools out of a package it
+  otherwise keeps.
+- **Budgets and loop guards** — `JIRA_REQUEST_TIMEOUT_MS` (30000),
+  `JIRA_CALL_BUDGET_MS` (120000), `JIRA_HOST_CONCURRENCY` (4),
+  `JIRA_RETRY_ATTEMPTS` (3), `JIRA_MAX_RESULT_CHARS` (25000) and
+  `JIRA_MAX_PAGES` (20). Results are truncated to a stated budget rather than
+  returned whole.
+- **Host allowlisting** — outbound requests go to the configured site and to
+  `JIRA_ALLOWED_HOSTS` entries only, matched exactly or by anchored regex. No
+  suffix matching. Redirects are not followed, with one deliberate exception:
+  an attachment download follows exactly one hop to the signed media URL Jira
+  answers with. That hop must be `https:` and not a private or link-local
+  address, and it carries no credentials — your API token is never sent to it.
+- **Secret redaction and an optional write journal** — the API token is
+  registered with the redactor and never logged; `JIRA_JOURNAL_PATH` records
+  every write tool call as JSONL.
+- **API token expiry warnings** — `JIRA_TOKEN_EXPIRES` makes startup and
+  `doctor` warn 30 days out.
+- **Transport: stdio.** `JIRA_TRANSPORT`, `JIRA_HTTP_PORT` and `JIRA_HTTP_TOKEN`
+  are still read and validated, but the HTTP transport is deferred past 1.0:
+  starting with `JIRA_TRANSPORT=http` fails immediately with a message saying
+  so, rather than silently falling back to stdio.
+- Distribution manifests: `server.json` for the MCP registry, `.claude-plugin/`
+  for Claude Code, and a release workflow that publishes with provenance — over
+  GitHub OIDC once a trusted publisher can be registered, which for a package's
+  own first version is not yet possible.
+- Repository furniture: build, lint, format, coverage and CI configuration; the
+  `npm run check` gate; the docs consistency linter (`scripts/docs-lint.mjs`)
+  and the tarball-content assertion (`scripts/check-tarball.mjs`).
+
+### Notes
+
+- Jira Cloud REST v3 only, so issue and comment bodies are ADF. Users are
+  addressed by `accountId`; there is no name or email lookup shortcut.
+- Search runs on `/rest/api/3/search/jql` with `nextPageToken` paging. The
+  legacy `/rest/api/3/search` endpoint was removed by Atlassian on 2025-08-01
+  and is not called.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ivan Baev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,247 @@
+# jira-mcp-ai
+
+An [MCP](https://modelcontextprotocol.io) server for **Jira Cloud**: it gives an
+MCP-capable agent (Claude Code, Claude Desktop, or any other client) tools to
+search, read and — behind an explicit gate — write Jira issues, using your own
+Atlassian account and API token.
+
+Two things shape the design:
+
+- **Writes are gated.** Write tools default to describing what they *would* do
+  instead of doing it. Executing requires both an opt-in configuration and an
+  explicit flag on the call. See [`docs/THREAT-MODEL.md`](docs/THREAT-MODEL.md).
+- **Jira content is untrusted input.** Issue text arrives from whoever filed the
+  ticket. It is labelled as data, never merged into the agent's instructions.
+
+> **Status: implemented.** The specification in [`docs/`](docs/README.md) is
+> normative and the code ships with it; drift is a bug. Nothing is published to
+> npm yet, so the registration example below will not resolve until the first
+> release.
+
+## Requirements
+
+- Node.js ≥ 22 (env files are read with `process.loadEnvFile()`, not dotenv)
+- A Jira Cloud site and an Atlassian API token
+
+## Registration
+
+Put this in `.mcp.json` (project scope), or paste the inner `"jira"` object
+into `claude mcp add-json jira '<object>'` — `claude mcp add` takes CLI
+arguments, not JSON.
+
+```json
+{
+  "mcpServers": {
+    "jira": {
+      "command": "npx",
+      "args": ["-y", "jira-mcp-ai@0.9.0"],
+      "env": {
+        "JIRA_SITE": "mycompany",
+        "JIRA_EMAIL": "me@example.com",
+        "JIRA_API_TOKEN": "<api-token>",
+        "JIRA_WRITE_MODE": "plan"
+      }
+    }
+  }
+}
+```
+
+The version is pinned on purpose: an unpinned `npx -y` re-resolves to whatever is
+newest at spawn time, so a fresh publish could start running new code inside an
+agent session with no review step. Bump the pin once you have read the changelog.
+
+Before wiring the server into a client, run
+`npx -y jira-mcp-ai@0.9.0 doctor` with the same environment variables set: it
+runs the configuration and credential probes from a plain terminal and prints a
+report — the fastest way to learn whether the site, email and token actually
+work. `--help` and `--version` are also available.
+
+**If the server does not appear, it is almost always PATH.** Claude Desktop
+launches MCP servers from a minimal environment that does not include your
+shell's PATH, so a `node`/`npx` installed by nvm, Homebrew or fnm is invisible to
+it and the launch fails inside the client, before this server runs — you get the
+client's generic "server failed" message and nothing on this server's stderr,
+because there was no process. Fix it by giving an absolute path:
+`"command": "/usr/local/bin/npx"` (`which npx` prints yours). Claude Code, run
+from a terminal, inherits your PATH and is not affected.
+
+Every diagnostic this server writes goes to **stderr**, never stdout — stdout is
+the MCP protocol. Claude Code keeps it in `~/.claude/logs/`; Claude Desktop in
+`~/Library/Logs/Claude/mcp*.log` (macOS) or `%APPDATA%\Claude\logs\` (Windows).
+That is where the startup report and any `JIRA_*` configuration error will be.
+
+## Configuration
+
+Every setting is an environment variable with the `JIRA_` prefix. The full table
+— names, defaults, required-ness, and where credentials may live — is in
+[`docs/CONFIGURATION.md`](docs/CONFIGURATION.md); [`.env.example`](.env.example)
+is a fill-in-the-blanks copy.
+
+## Tools
+
+<!-- GENERATED:TOOLS:START -->
+
+<!-- Generated by scripts/generate-readme.mjs from the tool manifest.
+     Do not edit by hand — run `npm run readme`. -->
+
+52 tools in 10 packages, 25 of them write tools
+behind the plan/apply gate. `JIRA_TOOL_PACKAGES`, `JIRA_PACKAGES_DENY` and
+`JIRA_PACKAGES_READONLY` decide which of them a session actually sees; the
+`core` package is always registered. Full input and output shapes are in
+[`docs/TOOLS.md`](docs/TOOLS.md).
+
+### Core — `core`
+
+Server self-description and credential check — always registered, even when every other package is denied.
+
+| Tool | Title | Access | What it does |
+| --- | --- | --- | --- |
+| `jira_capabilities` | Describe this server | read-only | Describe this server without calling Jira: the packages and tools that are registered, the site, the active profile, the write mode (plan vs apply) and the per-call limits. |
+| `jira_get_myself` | Get authenticated user | read-only | Verify the configured credentials and return the account they belong to: accountId, displayName, active, accountType, timeZone and locale. |
+
+### Search — `search`
+
+JQL search over issues, approximate result counts, and the saved filters that store reusable JQL — one page per call.
+
+| Tool | Title | Access | What it does |
+| --- | --- | --- | --- |
+| `jira_search` | Search issues | read-only | Run JQL and return ONE page of issues plus data.nextPageToken — pass it back to read the next page. There is no total; use jira_count. |
+| `jira_count` | Count issues | read-only | Count the issues a JQL matches without fetching any of them. |
+| `jira_list_filters` | List saved filters | read-only | Finds saved filters — named, stored JQL — by name substring or owner, and returns each one with its jql. |
+| `jira_get_filter` | Get saved filter | read-only | Reads one saved filter by numeric id (from jira_list_filters): name, description, owner, the JQL it stores and whether you favourited it. |
+
+### Issues (read) — `issues`
+
+One issue and its comments, available transitions, change history and worklogs — reads only; the matching writes live in issues-write.
+
+| Tool | Title | Access | What it does |
+| --- | --- | --- | --- |
+| `jira_get_issue` | Get issue | read-only | Read one Jira issue by key or id. Name the fields you need — omitting fields returns Jira's whole navigable set and burns the result budget. |
+| `jira_get_comments` | Get comments | read-only | List the comments on an issue, newest first by default (orderBy -created; Jira's own default is oldest first). |
+| `jira_get_transitions` | Get transitions | read-only | List the workflow transitions available from this issue's CURRENT status: id, name and target status. |
+| `jira_get_changelog` | Get changelog | read-only | Read an issue's change history — field, from → to, author, created. |
+| `jira_get_worklogs` | Get worklogs | read-only | List the work logged on an issue: timeSpentSeconds, timeSpent, started, author and the flattened comment. Sum timeSpentSeconds rather than parsing timeSpent strings. |
+
+### Issues (write) — `issues-write`
+
+Issue changes: creation, fields, workflow transitions, comments and comment edits, assignee, worklogs and links — every tool is plan-gated.
+
+| Tool | Title | Access | What it does |
+| --- | --- | --- | --- |
+| `jira_create_issue` | Create issue | write · standard | Create one issue. project and issueType are instance-specific — resolve them with jira_list_projects and jira_get_create_meta, which also names the custom fields this project requires. |
+| `jira_update_issue` | Update issue | write · standard | Update fields on one issue. REPLACE semantics: description (text or ADF) replaces the WHOLE rich-text field, so tables and panels in the old value are lost — never "append" a paragraph this way. |
+| `jira_transition_issue` | Transition issue | write · standard | Move one issue through its workflow. |
+| `jira_add_comment` | Add comment | write · standard | Add a comment to one issue. body takes plain text (converted to ADF) or a raw ADF document; format: "markdown" parses a string body as the markdown subset. |
+| `jira_update_comment` | Update comment | write · standard | Edit one existing comment. |
+| `jira_assign_issue` | Assign issue | write · standard | Set or clear the assignee of one issue. Pass exactly one of accountId (assign) or unassign: true (clear) — both together is rejected as ambiguous, neither is rejected as intentless. |
+| `jira_add_worklog` | Add worklog | write · standard | Log work against one issue. Pass exactly one of timeSpentSeconds (preferred) or timeSpent ("2h 30m"). |
+| `jira_link_issues` | Link issues | write · standard | Link two issues. linkType is the link type NAME ("Blocks", "Relates"), and those names are instance-specific — read them from jira_list_link_types and spell them exactly. |
+
+### Issues (delete) — `issues-delete`
+
+Irreversible deletions: an issue, a comment, a worklog entry. Every tool is plan-gated AND needs JIRA_ALLOW_IRREVERSIBLE; every plan shows what would be destroyed.
+
+| Tool | Title | Access | What it does |
+| --- | --- | --- | --- |
+| `jira_delete_issue` | Delete issue | write · irreversible | Permanently delete one issue. IRREVERSIBLE: Jira has no undo and no trash for this, the issue and its comments, worklogs and attachments are gone. |
+| `jira_delete_comment` | Delete comment | write · irreversible | Permanently delete one comment from an issue. IRREVERSIBLE: the comment is not recoverable and the deletion is not recorded in the issue changelog. |
+| `jira_delete_worklog` | Delete worklog | write · irreversible | Permanently delete one worklog entry from an issue. IRREVERSIBLE: the logged time is gone and Jira gives it back to the remaining estimate (its default adjustment). |
+
+### Attachments — `attachments`
+
+Files on issues: list what is attached, download one into the server's media directory, and attach a file from it. The two byte-moving tools need JIRA_MEDIA_DIR and never touch anything outside it.
+
+| Tool | Title | Access | What it does |
+| --- | --- | --- | --- |
+| `jira_list_attachments` | List attachments | read-only | Lists the files attached to one issue: id, filename, size in bytes, mime type, author and creation time. Metadata only — no bytes are transferred and no local directory is needed. |
+| `jira_download_attachment` | Download attachment | read-only | Downloads one attachment INTO THIS SERVER'S media directory and returns the local path — the bytes never pass through the conversation. |
+| `jira_upload_attachment` | Upload attachment | write · standard | Attaches a file from this server's media directory to an issue. |
+
+### Watchers, votes & project setup — `collab`
+
+The surface around an issue: who watches it, who voted for it, and the components and versions a project files work under — including cutting a release. Reversible writes only; nothing here deletes anything.
+
+| Tool | Title | Access | What it does |
+| --- | --- | --- | --- |
+| `jira_list_watchers` | List watchers | read-only | Lists the accounts watching an issue, with the watch count and whether this server's own account is among them. |
+| `jira_add_watcher` | Add watcher | write · standard | Makes an account watch an issue, so Jira notifies it of every change. Adding an account that already watches changes nothing. |
+| `jira_remove_watcher` | Remove watcher | write · standard | Stops an account watching an issue — it no longer gets notifications. Nothing is deleted: the watch is a link, jira_add_watcher puts it back with the same accountId, and no issue content changes. |
+| `jira_add_vote` | Vote for issue | write · standard | Casts THIS SERVER'S OWN vote for an issue. There is no way to vote on behalf of another account — the endpoint takes no accountId — so a request to record someone else's vote cannot be honoured. |
+| `jira_remove_vote` | Withdraw vote | write · standard | Withdraws THIS SERVER'S OWN vote from an issue; other people's votes are untouched and unreachable. Nothing is deleted beyond the vote itself, and jira_add_vote casts it again. |
+| `jira_list_components` | List components | read-only | Lists a project's components — the sub-areas an issue's `components` field points at — with their id, name, description, lead and default assignee rule. |
+| `jira_create_component` | Create component | write · standard | Creates a component in a project — a sub-area issues can be filed under. Takes the project KEY (jira_create_version takes a numeric id instead; that asymmetry is Jira's). |
+| `jira_update_component` | Update component | write · standard | Changes a component. This is a PARTIAL update, unlike jira_update_issue: only the fields you pass are changed and everything you omit keeps its current value. |
+| `jira_list_versions` | List versions | read-only | Lists a project's versions (releases) — the values an issue's fixVersions and affectedVersions fields point at — with their id, name, dates and whether they are released or archived. |
+| `jira_create_version` | Create version | write · standard | Creates a version (a release) in a project — a value issues can then use in fixVersions. Takes the NUMERIC projectId, not the key (jira_create_component takes a key; the asymmetry is Jira's). |
+| `jira_update_version` | Update version | write · standard | Changes a version — this is how a release is cut (released: true) and how it is un-cut (released: false). |
+| `jira_list_project_roles` | List project roles | read-only | Lists a project's roles (Administrators, Developers, …) with their ids, and — when you pass a roleId — the accounts and groups in that one role. |
+
+### Metadata & discovery — `meta`
+
+Projects, fields, create metadata, statuses and link types — the reads that turn names into the ids every other package needs.
+
+| Tool | Title | Access | What it does |
+| --- | --- | --- | --- |
+| `jira_list_projects` | List projects | read-only | Lists the Jira projects you can see — id, key, name, project type and lead. This is how a project NAME becomes the KEY every other tool wants. |
+| `jira_get_project` | Get project | read-only | Reads one project in detail: description, lead, issue types, components and versions — what you need before creating an issue, because issue type ids and component/version names are per-project. |
+| `jira_list_fields` | List fields | read-only | THE discovery tool for field ids: every field with id, name, schema type and the custom flag, so "Story Points" resolves to customfield_10016 and back. |
+| `jira_get_create_meta` | Get create metadata | read-only | Reads what jira_create_issue accepts for a project. |
+| `jira_list_statuses` | List statuses | read-only | Lists workflow statuses — id, name, category and scope — so JQL like status = "In Review" names a status that really exists on this site. |
+| `jira_list_link_types` | List issue link types | read-only | Lists the issue link types configured on this site with their inward and outward phrases (for example "blocks" / "is blocked by"). |
+
+### User lookup — `users`
+
+Finding people by name or email — the one path from a human name to the accountId every other tool requires.
+
+| Tool | Title | Access | What it does |
+| --- | --- | --- | --- |
+| `jira_search_users` | Search users | read-only | Finds Jira users by display name or email and returns their accountId — the id every other tool takes, since Cloud has no usernames. |
+
+### Boards & sprints — `agile`
+
+Jira Software boards, sprints and their issues, the two moves (into a sprint, out to the backlog) and the sprint lifecycle — the only tools that speak the Agile API rather than the platform one.
+
+| Tool | Title | Access | What it does |
+| --- | --- | --- | --- |
+| `jira_list_boards` | List boards | read-only | Lists the Jira Software boards you can see — id, name, type and the project each belongs to. The board id is what jira_list_sprints takes, so this is the first call of any sprint workflow. |
+| `jira_list_sprints` | List sprints | read-only | Lists a board's sprints with their id, name, state, goal and dates. Filter with state ("active" for the sprint in flight, "future" for the ones planned). |
+| `jira_get_sprint_issues` | Get sprint issues | read-only | Lists the issues in one sprint, flattened exactly like jira_search: rich text as plain text, users as accountId + displayName. |
+| `jira_move_to_sprint` | Move issues to sprint | write · standard | Moves up to 50 issues into a sprint — the only way to set a sprint, which is not an editable field on jira_update_issue. |
+| `jira_move_to_backlog` | Move issues to backlog | write · standard | Sends up to 50 issues back to the backlog — Jira defines it as "remove the future and active sprints from these issues", so it is the inverse of jira_move_to_sprint and the only way to clear a sprint… |
+| `jira_create_sprint` | Create sprint | write · standard | Creates a sprint on a Scrum board and returns its id. The sprint is created in the "future" state — this does NOT start it, jira_start_sprint does, and only a started sprint is the work in flight. |
+| `jira_start_sprint` | Start sprint | write · standard | Starts a sprint: "future" becomes "active", which is what makes its issues the work in flight and what every board report measures from. |
+| `jira_close_sprint` | Close sprint | write · standard | Completes the active sprint. |
+
+<!-- GENERATED:TOOLS:END -->
+
+## Data handling
+
+What leaves your machine, what is written to disk, what is redacted from logs,
+and what the write gate does and does not promise are documented in
+[`docs/THREAT-MODEL.md`](docs/THREAT-MODEL.md). Credential storage and lifecycle
+are in [`docs/AUTH.md`](docs/AUTH.md).
+
+To report a vulnerability, see [`SECURITY.md`](SECURITY.md).
+
+## Development
+
+```sh
+npm install
+npm run check   # typecheck, lint, format, build, tarball, test, docs-lint, prod audit
+```
+
+[`CONTRIBUTING.md`](CONTRIBUTING.md) is the contributor entry point: the
+`npm run check` gate, the rules a PR cannot break, and how to point the server
+at a real Jira site without endangering anyone's tenant.
+[`docs/README.md`](docs/README.md) is the index to the specification and
+[`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) is the place to start; the test
+taxonomy and the coverage gate are in [`docs/TESTING.md`](docs/TESTING.md).
+Participation is governed by the [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## License
+
+[MIT](LICENSE).
+
+Jira and Atlassian are trademarks of Atlassian Pty Ltd. This project is an
+independent, unofficial client and is not affiliated with or endorsed by
+Atlassian.

package/bin/jira-mcp-ai.cjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+// CommonJS launcher whose only job is the Node version guard. It must stay
+// parseable by ancient Node (no arrow functions, no `?.`/`??`, no ESM syntax):
+// the real entry is an ESM graph that old Node fails to *parse*, so a guard
+// living inside it could never run. `import()` is deliberately the one modern
+// construct here — it has been parseable since Node 12, long before the
+// runtimes this guard exists to warn about.
+//
+// Failure sets `process.exitCode` and returns; it never calls `process.exit()`.
+// Every failure here is a diagnostic on stderr, and under an MCP client stderr
+// is a pipe: `process.exit()` tears the process down with the write still in the
+// pipe buffer, which silently truncates the message at 64 KiB (measured). The
+// same rule governs `src/index.ts` (CC-91), and for the same reason — the one
+// sentence explaining why the server did not start is the whole value of these
+// paths, so it must survive.
+'use strict';
+
+var major = parseInt(process.versions.node.split('.')[0], 10);
+if (major < 22) {
+  console.error(
+    'jira-mcp-ai requires Node.js >= 22, but this is ' +
+      process.versions.node +
+      '.\nNode 22 is the floor because the server loads env files with ' +
+      'process.loadEnvFile() instead of dotenv.\nUse a newer runtime, e.g.: nvm install 24 && nvm use 24',
+  );
+  process.exitCode = 1;
+} else {
+  // Importing the entry module is not enough to start it: its self-run guard
+  // compares process.argv[1] against its own path, and here argv[1] is *this*
+  // shim (ARCHITECTURE.md §Dependency injection boundary). So call the exported
+  // entry point explicitly, or the binary exits 0 having done nothing at all.
+  import('../build/index.js')
+    .then(function (mod) {
+      var run = mod && mod.main;
+      if (typeof run !== 'function') {
+        console.error(
+          'jira-mcp-ai: build/index.js exports no main() entry point. ' +
+            'From a source checkout, run `npm run build` first.',
+        );
+        process.exitCode = 1;
+        return undefined;
+      }
+      return run();
+    })
+    .catch(function (err) {
+      console.error(
+        'jira-mcp-ai: the compiled server could not be started. From a source ' +
+          'checkout, run `npm run build` first.\n' +
+          (err && err.stack ? err.stack : String(err)),
+      );
+      process.exitCode = 1;
+    });
+}

package/build/api/adf.d.ts

@@ -0,0 +1,97 @@
+/**
+ * A minimal ADF node. The real schema is far larger; we read a subset and emit
+ * a smaller one, so unknown keys are tolerated rather than modelled.
+ */
+export interface AdfNode {
+    type: string;
+    version?: number;
+    text?: string;
+    content?: AdfNode[];
+    attrs?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/** A whole ADF document. Jira accepts `version: 1` only (JIRA-API.md §ADF). */
+export interface AdfDoc extends AdfNode {
+    type: 'doc';
+    version: 1;
+    content: AdfNode[];
+}
+/**
+ * Hard recursion cap. ADF from a human tops out around a dozen levels; anything
+ * past this is either a generated document or an attack on the stack, and a
+ * `RangeError` from a blown stack would take the whole tool call with it.
+ * Reaching the cap emits {@link DEPTH_LIMIT_MARKER} and stops descending, so a
+ * deep tree degrades gracefully instead of failing. This also terminates a
+ * cyclic tree, which no shape check can rule out on wire data.
+ */
+export declare const MAX_NODE_DEPTH = 64;
+/**
+ * Indentation cap for nested lists. Past six levels the leading whitespace
+ * stops growing: further nesting still renders, it just shares the sixth
+ * level's indent. Unbounded indentation eats the result budget (CC-25) for a
+ * distinction no reader makes.
+ */
+export declare const MAX_LIST_INDENT_DEPTH = 6;
+/** What a subtree past {@link MAX_NODE_DEPTH} collapses to. */
+export declare const DEPTH_LIMIT_MARKER = "[\u2026]";
+/**
+ * Flatten an ADF document (or any subtree, or `null`) to readable plain text.
+ * Never throws: unknown nodes, malformed attrs, cycles and pathological depth
+ * all degrade (CC-06, CC-09). An empty or absent document is `''`, never
+ * `"undefined"` (CC-08).
+ *
+ * Delta over the donor: the result is right-trimmed, so a one-paragraph
+ * description is `'hello'` and not `'hello\n'`.
+ */
+export declare function adfToText(node: unknown): string;
+/**
+ * Flatten an ADF document to the markdown subset instead of plain text. Same
+ * guarantees as {@link adfToText} — never throws, same caps, same degradation
+ * for everything outside the subset — and the same right-trim, so a
+ * one-paragraph description is `'hello'`.
+ *
+ * This is opt-in per call (`format: 'markdown'`); plain text stays the default
+ * so existing clients keep byte-identical output.
+ */
+export declare function adfToMarkdown(node: unknown): string;
+/**
+ * Replace every ADF document inside an arbitrary JSON value with its rendered
+ * string, non-mutatingly. This is how the tool ring re-renders a payload it
+ * fetched raw: the *set* of fields that gets rendered is exactly the set
+ * {@link isAdfDoc} recognises, which is the same set the plain-text shaping
+ * path flattens, so `format: 'markdown'` cannot render a field that
+ * `format: 'text'` would have left alone.
+ */
+export declare function renderAdfDocs<T>(value: T, render: (node: unknown) => string): T;
+/**
+ * Build a minimal ADF document from plain text (CC-10):
+ * CRLF is normalised, a blank line starts a new paragraph, a single newline
+ * inside a paragraph becomes a `hardBreak`, and leading/trailing blank
+ * paragraphs are trimmed. The version is pinned — Jira accepts `1` only.
+ *
+ * Blank input yields a doc with an empty `content` array, which is how a
+ * rich-text field is cleared. Tools that require a non-empty body (a comment)
+ * validate their input; that is not this builder's job.
+ */
+export declare function adfFromText(text: string): AdfDoc;
+/**
+ * Parse the markdown subset into an ADF document. The inverse of
+ * {@link adfToMarkdown} for everything the subset covers; anything else — block
+ * quotes, tables, images, reference links, setext headings, HTML — degrades to
+ * the paragraph text it was written as, never to an exception.
+ *
+ * CC-10 parity with {@link adfFromText} is deliberate: CRLF is normalised, a
+ * blank line starts a new paragraph, a single newline inside a paragraph is a
+ * `hardBreak`, and leading/trailing blank paragraphs are trimmed.
+ */
+export declare function adfFromMarkdown(text: string): AdfDoc;
+/** Structural guard: is this value an ADF document rather than a scalar field? */
+export declare function isAdfDoc(value: unknown): value is AdfDoc;
+/**
+ * Accept either plain text or a caller-supplied ADF document for a rich-text
+ * field (TOOLS.md: `description` takes text or raw ADF, and either one replaces
+ * the whole field — CC-31). A string is built; a document is normalised to the
+ * pinned `{ type: 'doc', version: 1 }` header and otherwise passed through.
+ * Anything else is a `validation` error, not a silent coercion.
+ */
+export declare function toAdf(body: string | AdfNode): AdfDoc;