@stubbedev/atlassian-mcp 0.5.10 → 0.5.12

package/README.md

@@ -13,7 +13,7 @@ A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for **s
 | Tool | Description |
 |---|---|
 | `get_dev_context` | Master entry point: git state + linked Jira ticket + open PR with reviewer/blocker status and next-step hints |
-| `start_work` | Start a Jira ticket: fetches it, creates a local branch (`feature/FOO-123-slug`) off the repository default branch, and optionally transitions the ticket |
+| `start_work` | Start a Jira ticket: resolves it by key or free-text `query` (with a picker when several match), creates a local branch (`feature/FOO-123-slug`) off the repository default branch, fetches the project README from Bitbucket so commit/PR conventions are in context, and optionally transitions the ticket |
 | `complete_work` | Close out finished work: merges the open PR and transitions the Jira ticket to Done. Refuses to merge while reviewers have not approved or a build failed (`force=true` overrides) |
 
 ### Git
@@ -28,16 +28,16 @@ A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for **s
 |---|---|
 | `jira_search` | Discover resources: `issues`, `projects`, `issue_types`, `boards`, `sprints`, `board_overview`, `versions`, `components`, `fields`, or `users` via `resource` param |
 | `jira_get` | Full details for one issue: summary, description, status, sprint, transitions, comments, and attachment list |
-| `jira_mutate` | Create, update, transition, comment (`commentAction`: `add` / `update` / `delete`), attach, link, add to sprint, log work, or manage a fix version (`version.action`: `create` / `update` / `release` / `archive` / `delete`) — several in one call. Markdown in any text field is converted to Jira wiki markup |
+| `jira_mutate` | Create, update, transition, comment (`commentAction`: `add` / `update` / `delete`), upload local files as attachments, link, add to sprint, log work, change issue type, set any custom field by name (`create.customFields` / `update.customFields`), or manage a fix version (`version.action`: `create` / `update` / `release` / `archive` / `delete`) — several in one call. Markdown in any text field is converted to Jira wiki markup |
 
 ### Bitbucket
 
 | Tool | Description |
 |---|---|
-| `bitbucket_search` | Discover resources: `pull_requests` (default), `repos`, `branches`, or `users` via `resource` param; `mine=true` for your inbox |
+| `bitbucket_search` | Discover resources: `pull_requests` (default), `repos`, `branches`, or `users` via `resource` param; `mine=true` for your inbox, narrowed with `role=author` / `reviewer` / `participant` |
 | `bitbucket_get_pr` | Full PR details: metadata, commits, comments, blockers, build status, optional diff, and any attachments referenced from the description or comments |
 | `bitbucket_mutate` | Create/update a PR, or perform lifecycle actions: `approve`, `unapprove`, `needs_work`, `merge`, `decline`. Reviewer names are verified against Bitbucket, and an update that would drop existing reviewers needs `update.replaceReviewers=true` |
-| `bitbucket_comment` | Add, update, or delete a PR comment; for code changes use `suggestion` so Bitbucket shows Apply suggestion. Enforced here: one reply per thread, no new top-level comment on your own PR (`asAuthor=true` to override), `#123` references rewritten as links |
+| `bitbucket_comment` | Add, update, or delete a PR comment; for code changes use `suggestion` so Bitbucket shows Apply suggestion. Enforced here: one reply per thread, no new top-level comment on your own PR (`asAuthor=true` to override), `#123` references rewritten as links. `pending=true` posts an unpublished draft-review comment |
 | `bitbucket_get_file` | Raw file content at a branch, tag, or commit — or pass `prId` to read the PR source branch. Every response names the path and ref it came from, and pages via `maxChars`/`charOffset` |
 | `bitbucket_pr_tasks` | Manage PR tasks (checklist items): `list`, `create`, `resolve`, `reopen`, `delete` |
 
@@ -47,6 +47,12 @@ A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for **s
 |---|---|
 | `get_attachment` | Fetch an attachment by ID from Jira (`source=jira`, IDs from `jira_get`) or Bitbucket (`source=bitbucket`, IDs from `bitbucket_get_pr`). Images, videos, animated images (GIF/APNG/animated WebP), audio, and PDFs are decoded inline so the model can see/hear them; text/JSON inline. Oversized or non-renderable attachments are auto-saved to a temp file and the path is returned. `saveTo=/absolute/path` streams the original to disk |
 
+### Resources
+
+| URI | Description |
+|---|---|
+| `dev-context://current` | The same live report as `get_dev_context` — branch state, linked Jira tickets, open PR — as an MCP resource. Re-read it for fresh state instead of spending another tool call. The repo is resolved per read from the caller's session, so the static URI serves whatever workspace the client is in |
+
 ### Natural language examples
 
 - "what am I working on?" → `get_dev_context`
@@ -137,7 +143,7 @@ The `$schema` field is optional but enables editor autocomplete and validation.
   - Jira: `project` (alias of `projectKey`)
   - Bitbucket: `project` and `repo` (aliases of `projectKey` and `repoSlug`)
 - For Bitbucket tools, `projectKey` and `repoSlug` are usually auto-detected from your local `origin` remote.
-- `bitbucket_create_pull_request` also auto-detects `fromBranch` from your current branch and returns the existing open PR if one already exists for that branch.
+- `bitbucket_mutate` with `create` auto-detects `fromBranch` from your current branch and returns the existing open PR if one already exists for that branch. Other Bitbucket tools auto-target that PR when `prId` is omitted.
 - Jira project-scoped calls accept `projectKey` and work best when provided.
 - If `projectKey` is omitted for Jira issue creation/type lookup, the server tries to infer it from your current branch ticket key, falls back to auto-select when only one project is visible, and otherwise returns a numbered project list to pick from.
 
@@ -150,12 +156,23 @@ BITBUCKET_URL=https://bitbucket.example.com
 BITBUCKET_ACCESS_TOKEN=your-bitbucket-personal-access-token
 ```
 
-Config is resolved in this order: `--config <path>` CLI arg → `ATLASSIAN_MCP_CONFIG` env var → `~/.atlassian-mcp.json` → `$XDG_CONFIG_HOME/atlassian-mcp/config.json` (default `~/.config/atlassian-mcp/config.json`) → `.atlassian-mcp.json` in cwd → environment variables.
+Config is resolved in this order: `--config <path>` CLI arg → `ATLASSIAN_MCP_CONFIG` env var → `~/.atlassian-mcp.json` → `$XDG_CONFIG_HOME/atlassian-mcp/config.json` (default `~/.config/atlassian-mcp/config.json`) → `.atlassian-mcp.json` in cwd → environment variables. A leading `~` in the first two is expanded by the server, so a client that spawns it without a shell still resolves the path. Within a file, per-field: a value in the config file wins, environment variables fill the gaps.
 
 ### 2. Connect to your AI tool
 
 No cloning or building required — just point your tool at `npx @stubbedev/atlassian-mcp@latest` and it will install and run automatically.
 
+CLI-driven clients need one line:
+
+```bash
+claude mcp add atlassian -- npx -y @stubbedev/atlassian-mcp@latest       # Claude Code
+codex mcp add atlassian -- npx -y @stubbedev/atlassian-mcp@latest        # Codex CLI / IDE / app
+code --add-mcp '{"name":"atlassian","command":"npx","args":["-y","@stubbedev/atlassian-mcp@latest"]}'   # VS Code
+```
+
+Desktop apps: **Claude Desktop** installs a one-click [`.mcpb` bundle](#claude-desktop) —
+no Node, no JSON. Everything else takes a config file; see below.
+
 > Note: `--prefer-online` can break MCP startup in some clients. Keep the command simple and use the update steps below when you want to refresh.
 
 ---
@@ -168,6 +185,66 @@ claude mcp add atlassian -- npx -y @stubbedev/atlassian-mcp@latest --config ~/.a
 
 ---
 
+#### Claude Desktop
+
+**One-click (recommended).** Grab the `.mcpb` bundle for your platform from the
+[latest release](https://github.com/stubbedev/atlassian-mcp/releases/latest) —
+`atlassian-mcp_darwin_arm64.mcpb` (Apple Silicon), `atlassian-mcp_darwin_amd64.mcpb`
+(Intel Mac), `atlassian-mcp_windows_amd64.mcpb` — then **double-click it**, drag it onto the
+Claude Desktop window, or use **Settings → Extensions → Advanced settings → Install
+Extension…**. The install dialog asks for Jira/Bitbucket URL and token (tokens are stored
+by Claude Desktop, not in a file) plus **Repository**, the working tree the git and PR tools
+default to. Leaving URL/token blank reuses an existing `~/.atlassian-mcp.json`.
+
+The bundle carries the binary, so there is no Node, no `npx`, no `PATH` to fix and no JSON
+to edit. [MCP Bundles](https://github.com/modelcontextprotocol/mcpb) are a Claude Desktop
+feature today; other clients use the config files below.
+
+**Manual config.** Claude Desktop is a GUI app: it launches the server with a minimal
+`PATH`, no shell, and `/` as the working directory. So `command` must be an **absolute
+path** (a bare `npx` fails with `spawn npx ENOENT`), a `.env` file or relative
+`--config` path never resolves, and nothing expands `~` for you — the server expands a
+leading `~` in `--config` / `ATLASSIAN_MCP_CONFIG` itself, but a client that inserts `~`
+anywhere else will not. Config file:
+
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "atlassian": {
+      "command": "/absolute/path/to/atlassian-mcp",
+      "env": {
+        "JIRA_URL": "https://jira.example.com",
+        "JIRA_ACCESS_TOKEN": "your-jira-personal-access-token",
+        "BITBUCKET_URL": "https://bitbucket.example.com",
+        "BITBUCKET_ACCESS_TOKEN": "your-bitbucket-personal-access-token",
+        "ATLASSIAN_MCP_REPO_ROOT": "/Users/you/code/my-repo"
+      }
+    }
+  }
+}
+```
+
+To keep `npx`, set `command` to the absolute path of your launcher (`which npx`, e.g.
+`/opt/homebrew/bin/npx`) with `"args": ["-y", "@stubbedev/atlassian-mcp@latest"]`.
+
+`ATLASSIAN_MCP_REPO_ROOT` is what makes `get_dev_context`, `git_get_context`,
+`start_work`, `complete_work` and Bitbucket repo auto-detection usable here: a desktop app
+has no workspace, so it advertises no MCP roots and there is no useful cwd to fall back to.
+Comma-separate several worktrees (first git repo wins); a per-call `repoPath` still
+overrides it.
+
+On Windows, Git is frequently absent from a GUI app's `PATH`. The server probes the usual
+install locations before giving up; set `ATLASSIAN_MCP_GIT_PATH` if yours lives elsewhere.
+
+Server stderr is logged to `~/Library/Logs/Claude/mcp-server-atlassian.log` (macOS) or
+`%APPDATA%\Claude\logs\mcp-server-atlassian.log` (Windows) — read that first when a
+connection fails.
+
+---
+
 #### Cursor
 
 Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project-only):
@@ -231,34 +308,116 @@ Add to `opencode.json` in your project root (or `~/.config/opencode/opencode.jso
   "mcp": {
     "atlassian": {
       "type": "local",
-      "command": ["npx", "-y", "@stubbedev/atlassian-mcp@latest", "--config", "/home/you/.atlassian-mcp.json"]
+      "command": ["npx", "-y", "@stubbedev/atlassian-mcp@latest", "--config", "/home/you/.atlassian-mcp.json"],
+      "environment": { "ATLASSIAN_MCP_REPO_ROOT": "/home/you/code/my-repo" }
     }
   }
 }
 ```
 
+`environment` also accepts the `JIRA_*` / `BITBUCKET_*` variables if you would rather not
+keep a config file. Set `"type": "remote"` with `"url"` and `"headers"` to point at a
+shared [HTTP server](#running-as-an-http-server-shared--behind-a-proxy) instead.
+
 ---
 
-#### Codex CLI
+#### Codex (CLI, IDE extension, app)
+
+One command — it writes the config for all three:
+
+```bash
+codex mcp add atlassian -- npx -y @stubbedev/atlassian-mcp@latest
+```
+
+Or edit `~/.codex/config.toml` directly (`.codex/config.toml` in a trusted project for a
+project-scoped server). Note the TOML table name is `mcp_servers`, with an underscore:
+
+```toml
+[mcp_servers.atlassian]
+command = "npx"
+args = ["-y", "@stubbedev/atlassian-mcp@latest", "--config", "/home/you/.atlassian-mcp.json"]
+
+# Optional — instead of a config file, and to pin the repo for the git/PR tools:
+[mcp_servers.atlassian.env]
+JIRA_URL = "https://jira.example.com"
+JIRA_ACCESS_TOKEN = "…"
+ATLASSIAN_MCP_REPO_ROOT = "/home/you/code/my-repo"
+```
 
-Add to `~/.codex/config.yaml`:
+Codex picks the transport from the keys present: `command` means stdio, `url` means
+streamable HTTP. To share one [HTTP server](#running-as-an-http-server-shared--behind-a-proxy):
+
+```toml
+[mcp_servers.atlassian]
+url = "http://127.0.0.1:7337/mcp"
+bearer_token_env_var = "ATLASSIAN_MCP_HTTP_TOKEN"
+```
+
+---
+
+#### VS Code / GitHub Copilot
+
+```bash
+code --add-mcp '{"name":"atlassian","command":"npx","args":["-y","@stubbedev/atlassian-mcp@latest"]}'
+```
+
+Or commit `.vscode/mcp.json` with a `servers` object of the same shape to share it with the
+repo.
+
+---
+
+#### Any other MCP-compatible tool
+
+Most clients accept the Claude Desktop shape — an `mcpServers` object keyed by name, with
+`command`, `args` and `env`:
+
+```json
+{
+  "mcpServers": {
+    "atlassian": {
+      "command": "npx",
+      "args": ["-y", "@stubbedev/atlassian-mcp@latest"],
+      "env": {
+        "JIRA_URL": "https://jira.example.com",
+        "JIRA_ACCESS_TOKEN": "…",
+        "BITBUCKET_URL": "https://bitbucket.example.com",
+        "BITBUCKET_ACCESS_TOKEN": "…",
+        "ATLASSIAN_MCP_REPO_ROOT": "/home/you/code/my-repo"
+      }
+    }
+  }
+}
+```
+
+LM Studio uses exactly that shape in its own `mcp.json` (edit it from the app's plugin
+panel); Cherry Studio, Witsy, Jan and 5ire have in-app MCP dialogs with the same fields.
+
+Goose is the exception — its `~/.config/goose/config.yaml` uses `extensions:` with `cmd`
+rather than `command`:
 
 ```yaml
-mcpServers:
+extensions:
   atlassian:
-    command: npx
-    args:
-      - -y
-      - @stubbedev/atlassian-mcp@latest
-      - --config
-      - /home/you/.atlassian-mcp.json
+    enabled: true
+    type: stdio
+    cmd: npx
+    args: ["-y", "@stubbedev/atlassian-mcp@latest"]
+    envs:
+      ATLASSIAN_MCP_REPO_ROOT: /home/you/code/my-repo
 ```
 
+Every GUI client brings the caveats from the [Claude Desktop](#claude-desktop) section:
+absolute `command` path, no usable cwd, no MCP roots — so set `ATLASSIAN_MCP_REPO_ROOT`.
+
 ---
 
-#### Any other MCP-compatible tool
+#### ChatGPT (desktop / web) — not supported
 
-Most tools that support MCP accept the same JSON format. Use `npx` as the command with `["-y", "@stubbedev/atlassian-mcp@latest", "--config", "/path/to/config.json"]` as the args.
+ChatGPT connectors accept **remote HTTPS MCP servers only** (streamable HTTP or SSE, with
+OAuth or no auth); it cannot spawn a local stdio server. This server's `--http` mode speaks
+the right protocol, but making it work would mean exposing an endpoint that reaches your
+self-hosted Jira/Bitbucket to OpenAI's servers, and ChatGPT offers no place for the static
+bearer token this server uses. Use a client from the list above.
 
 ### Updating existing installs
 
@@ -275,7 +434,9 @@ Then restart your MCP client.
 ### Install without npm
 
 The server is a single static Go binary. The `npx` path above downloads the prebuilt
-binary for your platform on first run; these alternatives skip Node entirely:
+binary for your platform on first run; these alternatives skip Node entirely — as does the
+[`.mcpb` bundle](#claude-desktop) for Claude Desktop, and the per-platform binaries
+attached to every [release](https://github.com/stubbedev/atlassian-mcp/releases/latest):
 
 ```bash
 # Go toolchain — installs to $GOBIN / $GOPATH/bin
@@ -286,9 +447,11 @@ nix run github:stubbedev/atlassian-mcp -- --config ~/.atlassian-mcp.json
 ```
 
 Then point your MCP client's `command` at the resulting `atlassian-mcp` binary
-instead of `npx`. On these paths `ffmpeg`/`ffprobe` must be available on `PATH`
-(or set `ATLASSIAN_MCP_FFMPEG_PATH` / `ATLASSIAN_MCP_FFPROBE_PATH`); the npm
-wrapper bundles them automatically.
+instead of `npx`. On these Node-free paths (`go install`, Nix, a release binary or the
+`.mcpb` bundle) `ffmpeg`/`ffprobe` must be available on `PATH` for video and
+animated-image attachments (or set `ATLASSIAN_MCP_FFMPEG_PATH` /
+`ATLASSIAN_MCP_FFPROBE_PATH`); the npm wrapper bundles them automatically. Everything
+else — still images, PDF text, JSON/text — is pure Go and needs nothing extra.
 
 ### Running as an HTTP server (shared / behind a proxy)
 
@@ -307,19 +470,21 @@ ATLASSIAN_MCP_HTTP=1 atlassian-mcp   # same, via env
   `initialize` mints a session and returns an `Mcp-Session-Id` header, which the client
   **must** echo on every subsequent request and on the SSE stream. Requests with a
   missing/unknown/expired session id get **HTTP 404** so the client re-initializes
-  (standard MCP-client behaviour). Each connected client/worktree is an isolated session.
+  (standard MCP-client behaviour). Each connected client/worktree is an isolated session;
+  per-session state (cached roots, PR review anchors) is dropped once the session ends.
 - **Auth:** on a loopback bind no token is needed. Binding a non-loopback address
   **requires** `ATLASSIAN_MCP_HTTP_TOKEN` (sent by clients as `Authorization: Bearer …`);
   the server refuses to start otherwise. Terminate TLS at your proxy.
 - **`GET /healthz`** is an unauthenticated liveness probe (returns `ok`) for proxies/load
-  balancers. Idle sessions are evicted after 1h.
+  balancers.
 
 **Repo context comes from the client, not the server's working directory.** Tools that
 need a repo (`git_get_context`, `get_dev_context`, `start_work`, `complete_work`, and
 Bitbucket project/repo auto-detection) resolve it in this order: an explicit `repoPath`
-argument → a **root pinned via request header** (see below) → the client's **MCP workspace
-roots** (the server asks via `roots/list`, caches per session, and refreshes on
-`notifications/roots/list_changed`) → the process cwd (stdio
+argument → a **root pinned via request header** (see below) → **`ATLASSIAN_MCP_REPO_ROOT`**
+(comma-separated for several worktrees — the only workspace signal a GUI desktop client
+can give) → the client's **MCP workspace roots** (the server asks via `roots/list`, caches
+per session, and refreshes on `notifications/roots/list_changed`) → the process cwd (stdio
 only). So one shared HTTP server handles many worktrees: each client's own workspace drives
 its calls. When a session exposes **several** roots (multiple worktrees), a tool with no
 `repoPath` uses the first git-repo root; pass `repoPath` (an absolute path, or a worktree
@@ -333,12 +498,19 @@ round-trip (and working even when the client never advertised the `roots` capabi
 Send a `file://` URI or absolute path (comma-separated for multiple; first git repo wins):
 
 ```
+X-Repo-Root: /srv/myrepo
 X-Mcp-Root: file:///srv/myrepo
 X-Mcp-Roots: /srv/a, /srv/b
 ```
 
-Accepted header names: `X-Mcp-Roots`, `X-Mcp-Root`, `Mcp-Roots`, `Mcp-Root`. A header value
-is authoritative — it takes precedence over `roots/list` and survives `list_changed`.
+Accepted header names, in precedence order: `X-Repo-Root`, `X-Mcp-Roots`, `X-Mcp-Root`,
+`Mcp-Roots`, `Mcp-Root`. A header value is authoritative — it takes precedence over
+`roots/list` and survives `list_changed`.
+
+> **Protocol note:** MCP revision **2026-07-28** (SEP-2322/2575) forbids server-initiated
+> JSON-RPC requests, so `roots/list` is unavailable on that revision — the server says so
+> explicitly instead of hanging. On 2026-07-28 clients, a root **header** (or an explicit
+> `repoPath` / `projectKey`+`repoSlug`) is the only way to give the server repo context.
 
 Client config for an already-running HTTP server (Claude Code example):
 
@@ -370,8 +542,8 @@ pure-Go implementation shell out to external binaries:
 - **`ffmpeg` + `ffprobe`** — video and animated-image frame sampling. The npm wrapper bundles
   [`ffmpeg-static`](https://www.npmjs.com/package/ffmpeg-static) /
   [`ffprobe-static`](https://www.npmjs.com/package/ffprobe-static) and injects their paths, so the
-  npx install path is zero-config. On the `go install` / Nix paths, install `ffmpeg` (it provides
-  `ffprobe`) or set the env vars below.
+  npx install path is zero-config. On every Node-free path (`go install`, Nix, release binary,
+  `.mcpb` bundle), install `ffmpeg` (it provides `ffprobe`) or set the env vars below.
 - **`pdftoppm` (poppler) or `mutool` (MuPDF)** — only needed to rasterize *scanned* PDFs that have no
   extractable text. If neither is on `PATH`, such PDFs are saved to disk instead.
 
@@ -381,6 +553,8 @@ pure-Go implementation shell out to external binaries:
 | --- | --- | --- |
 | `ATLASSIAN_MCP_HTTP` | Run as a Streamable HTTP server instead of stdio. `1`/`true` → `127.0.0.1:7337`; or set an explicit `host:port`. Same as `--http`. | unset (stdio) |
 | `ATLASSIAN_MCP_HTTP_TOKEN` | Bearer token for HTTP mode. Optional on loopback binds; **required** on non-loopback binds. | unset |
+| `ATLASSIAN_MCP_REPO_ROOT` | Default workspace root(s) for the git/PR tools, comma-separated. `file://` URIs, absolute paths, `~/…` and Windows drive paths all work. Needed by clients that expose no MCP roots (desktop apps). Overridden by a `repoPath` argument or a root header. | unset |
+| `ATLASSIAN_MCP_GIT_PATH` | Path to the `git` executable. Only needed when `git` is off the host app's `PATH`; the server already probes the usual install locations. | `git` on `PATH` |
 | `ATLASSIAN_MCP_FFMPEG_PATH` | Path to `ffmpeg` binary. | npm: bundled `ffmpeg-static`; otherwise `ffmpeg` on `PATH` |
 | `ATLASSIAN_MCP_FFPROBE_PATH` | Path to `ffprobe` binary. | npm: bundled `ffprobe-static`; otherwise `ffprobe` on `PATH` |
 | `ATLASSIAN_MCP_TMP_TTL_DAYS` | Auto-saved attachments older than this are pruned. | `7` |
@@ -395,19 +569,25 @@ This package is published to npm as `@stubbedev/atlassian-mcp`.
 Use semantic versioning for releases. Breaking tool-surface changes should bump the minor version while `<1.0.0` (for example `0.0.x` -> `0.1.0`).
 
 On a pushed `v*` tag, `.github/workflows/publish.yml` cross-compiles the Go binary for 14
-OS/arch targets, attaches them to a GitHub release, and publishes the npm wrapper (which
-downloads the matching binary on install).
+OS/arch targets, packs six of them into `.mcpb` bundles for one-click desktop install
+(`packaging/mcpb/pack.sh`, macOS/Windows/Linux × amd64/arm64), attaches everything to a
+GitHub release, and publishes the npm wrapper (which downloads the matching binary on
+install). `just bundle` builds a bundle for the host platform locally.
 
-Release flow:
+Release flow (`just` drives it; it refuses to run on a dirty tree):
 
 ```bash
-# choose one: patch | minor | major (also: npm run release:patch / :minor / :major)
-npm version patch          # bumps package.json, commits, tags vX.Y.Z
-git push origin HEAD --follow-tags
+just release-preview       # show the next patch/minor/major versions
+just release-patch         # or release-minor / release-major
 ```
 
-`flake.nix` reads its version from `package.json`, so the Nix package tracks the same bump
-automatically. GitHub Actions builds + publishes from the pushed tag.
+`just release-<level>` bumps the version in `package.json`, re-syncs the Nix `vendorHash`
+(`just sync-flake`), runs the gates (`just check`), commits `release: vX.Y.Z`, tags, and
+pushes both the branch and the tag. The tag push triggers `publish.yml`.
+
+`package.json` is the single source of truth for the version: the binary embeds it via
+`go:embed` (no `-ldflags`) and `flake.nix` reads it, so one bump moves everything.
+The equivalent npm scripts (`npm run release:patch` / `:minor` / `:major`) still work.
 
 - The workflow is configured for npm Trusted Publisher (OIDC), so no `NPM_TOKEN` secret is required
 
@@ -457,20 +637,24 @@ Paste the token as the `token` value under `bitbucket` in your config file.
 
 The server is a single Go module at the repo root (no `src/` tree).
 
+Tasks live in the `justfile` and mirror the CI gates, so a green `just check` predicts
+green CI:
+
 ```bash
-# Build the binary
-go build -o atlassian-mcp .
+just            # list tasks
+just check      # vet + test + build (what ci.yml runs)
+just fmt        # gofmt -w .
+just sync-flake # recompute the Nix vendorHash after a dependency change
 
-# Run it
+# Or the raw commands
+go build -o atlassian-mcp .
 ./atlassian-mcp --config /path/to/config.json
+go vet ./... && go test ./...
 
-# Vet + unit tests
-go vet ./...
-go test ./...
-
-# Test the tool list
-echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | ./atlassian-mcp
-
-# Quick release smoke check (build + tools/list validation)
+# Quick release smoke check (build + tools/list validation; CI also does a full stdio handshake)
 npm run smoke
 ```
+
+Tool schemas live in `tools.json` (embedded into the binary) and the MCP protocol layer is
+the official [`modelcontextprotocol/go-sdk`](https://github.com/modelcontextprotocol/go-sdk);
+the Go files at the repo root hold the tool logic.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stubbedev/atlassian-mcp",
-  "version": "0.5.10",
+  "version": "0.5.12",
   "description": "MCP server for self-hosted Jira and Bitbucket (Go, distributed as a prebuilt binary)",
   "license": "MIT",
   "type": "module",