@stubbedev/atlassian-mcp 0.4.5 → 0.5.1

package/README.md

@@ -38,10 +38,10 @@ A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for **s
 
 | Tool | Description |
 |---|---|
-| `bitbucket_search` | Discover resources: `pull_requests` (default), `repos`, or `branches` 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 |
 | `bitbucket_get_pr` | Full PR details: metadata, commits, comments, blockers, build status, optional diff, and any attachments referenced from the description or comments |
 | `bitbucket_get_attachment` | Fetch a repo attachment by ID. Same decoding pipeline as `jira_get_attachment` (images, videos, animated images, audio, PDFs). Oversized or non-renderable attachments are auto-saved to a temp file and the path is returned; `saveTo` streams the original to disk |
-| `bitbucket_mutate` | Create/update a PR, or perform lifecycle actions: `approve`, `unapprove`, `merge`, `decline` |
+| `bitbucket_mutate` | Create/update a PR, or perform lifecycle actions: `approve`, `unapprove`, `needs_work`, `merge`, `decline` |
 | `bitbucket_comment` | Add, update, or delete a PR comment; for code changes use `suggestion` so Bitbucket shows Apply suggestion (no trailing text after a suggestion block) |
 | `bitbucket_get_file` | Raw file content from Bitbucket at a branch, tag, or commit |
 | `bitbucket_pr_tasks` | Manage PR tasks (checklist items): `list`, `create`, `resolve`, `reopen`, `delete` |
@@ -114,7 +114,7 @@ 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` → `.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.
 
 ### 2. Connect to your AI tool
 
@@ -236,17 +236,65 @@ Then restart your MCP client.
 
 ---
 
-### Manual install (optional)
+### Install without npm
 
-If you prefer to clone and run locally:
+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:
 
 ```bash
-git clone git@github.com:stubbedev/atlassian-mcp.git
-cd atlassian-mcp
-npm install
+# Go toolchain — installs to $GOBIN / $GOPATH/bin
+go install github.com/stubbedev/atlassian-mcp@latest
+
+# Nix flake
+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.
+
+### Running as an HTTP server (shared / behind a proxy)
+
+By default the server speaks MCP over **stdio** (one process per client, launched
+by your editor). It can instead run as a long-lived **Streamable HTTP** server that
+many clients share — useful behind a reverse proxy:
+
+```bash
+atlassian-mcp --http                 # binds 127.0.0.1:7337
+atlassian-mcp --http 127.0.0.1:9000  # custom address
+ATLASSIAN_MCP_HTTP=1 atlassian-mcp   # same, via env
 ```
 
-Then use `node /path/to/atlassian-mcp/dist/index.js` instead of the `npx` command in the configs above.
+- Single endpoint `POST /mcp` (JSON-RPC) plus an optional `GET /mcp` SSE stream that
+  carries server→client requests (`roots/list`, elicitation). The server is **stateful**:
+  `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.
+- **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.
+
+**Repo context comes from the client, not the server's working directory.** Tools that
+need a repo (the `git_*` tools, `get_dev_context`, `start_work`, `complete_work`, and
+Bitbucket project/repo auto-detection) resolve it in this order: an explicit `repoPath`
+argument → 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
+name/basename that matches one of the roots) to target a specific worktree. For Bitbucket,
+passing `projectKey`+`repoSlug` explicitly skips repo detection entirely. The repos must be
+reachable on the server's host (the git tools run `git` locally).
+
+Client config for an already-running HTTP server (Claude Code example):
+
+```bash
+claude mcp add --transport http atlassian http://127.0.0.1:7337/mcp
+```
 
 ### Attachment decoding pipeline
 
@@ -254,28 +302,37 @@ The attachment tools (`jira_get_attachment`, `bitbucket_get_attachment`) decode
 
 | Input | What gets returned | How |
 | --- | --- | --- |
-| Static images (PNG/JPEG/WebP/AVIF/SVG…) | Resized image content blocks | `sharp` (long edge ≤ `maxDimension`, default 1568) |
-| Animated images (GIF/APNG/animated WebP) | N sampled frames as image content blocks | `ffmpeg-static` + `sharp` (default 6 frames @ 768 px) |
-| Video (mp4/webm/mov/…) | N sampled frames as image content blocks | `ffmpeg-static` + `sharp`. Uniform or scene-change sampling. Re-call with `start`, `end`, `frames`, `mode`, `sceneThreshold` to zoom in |
+| Static images (PNG/JPEG/WebP/BMP/TIFF/GIF/SVG…) | Resized image content blocks | native Go (`imaging`, long edge ≤ `maxDimension`, default 1568; EXIF auto-orient; PNG for alpha, else JPEG) |
+| Animated images (GIF/APNG/animated WebP) | N sampled frames as image content blocks | `ffmpeg` + native Go re-encode (default 6 frames @ 768 px) |
+| Video (mp4/webm/mov/…) | N sampled frames as image content blocks | `ffmpeg`/`ffprobe`. Uniform or scene-change sampling. Re-call with `start`, `end`, `frames`, `mode`, `sceneThreshold` to zoom in |
 | Audio (mp3/wav/ogg/…) | MCP audio content block | passthrough |
-| PDFs | Extracted text — or rasterized pages if text is empty (scanned PDFs) | `unpdf` + `@napi-rs/canvas` |
+| PDFs | Extracted text — or rasterized pages if text is empty (scanned PDFs) | native Go text extraction (`ledongthuc/pdf`); rasterization shells to `pdftoppm`/`mutool` if present, else the original is saved to disk |
 | Text-like (json/xml/yaml/…) | Text content block | passthrough |
-| Everything else (or oversized) | Auto-saved to a temp file; path is returned | `os.tmpdir()` with `atlmcp-` prefix |
+| Everything else (or oversized) | Auto-saved to a temp file; path is returned | `os.TempDir()` with `atlmcp-` prefix |
 
 Auto-saved files are periodically pruned by TTL and total-size quota — see *Environment overrides* below.
 
-### Native dependencies
+### External tools (optional)
 
-- [`sharp`](https://sharp.pixelplumbing.com/) — image decode/resize. Ships prebuilt binaries for glibc Linux (x64/arm64), macOS, Windows. Alpine / musl users may need `npm install --cpu=x64 --os=linux --libc=musl sharp`.
-- [`ffmpeg-static`](https://www.npmjs.com/package/ffmpeg-static) + [`ffprobe-static`](https://www.npmjs.com/package/ffprobe-static) — video/audio decode. ~80 MB bundled binary per platform. Override with env vars (below) if you have system ffmpeg.
-- [`@napi-rs/canvas`](https://www.npmjs.com/package/@napi-rs/canvas) + [`unpdf`](https://www.npmjs.com/package/unpdf) — PDF text extraction and page rasterization.
+Image and PDF-text decoding are pure Go and need nothing extra. The two pipelines that have no
+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.
+- **`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.
 
 ### Environment overrides
 
 | Variable | Purpose | Default |
 | --- | --- | --- |
-| `ATLASSIAN_MCP_FFMPEG_PATH` | Path to `ffmpeg` binary. Overrides `ffmpeg-static`. Use this if you have system ffmpeg or `ffmpeg-static` doesn't ship for your platform (Alpine/musl, some ARM variants). | bundled `ffmpeg-static` |
-| `ATLASSIAN_MCP_FFPROBE_PATH` | Path to `ffprobe` binary. Overrides `ffprobe-static`. | bundled `ffprobe-static` |
+| `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_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` |
 | `ATLASSIAN_MCP_TMP_MAX_BYTES` | Total-size quota for auto-saved attachments in `os.tmpdir()`. When exceeded, oldest are evicted. | `1073741824` (1 GB) |
 
@@ -287,23 +344,20 @@ 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`).
 
-Automatic publish is configured in `.github/workflows/publish.yml` and runs when a new version tag is pushed.
+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).
 
 Release flow:
 
 ```bash
-# choose one: patch | minor | major
-increment=patch
-
-# bumps package.json + package-lock.json,
-# creates a version commit, and creates a git tag (for example v0.1.17)
-npm version "$increment"
-
-# push commit and tag to GitHub
+# 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
 ```
 
-GitHub Actions will publish the npm release from that pushed tag.
+`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.
 
 - The workflow is configured for npm Trusted Publisher (OIDC), so no `NPM_TOKEN` secret is required
 
@@ -351,22 +405,22 @@ Paste the token as the `token` value under `bitbucket` in your config file.
 
 ## Development
 
+The server is a single Go module at the repo root (no `src/` tree).
+
 ```bash
-# Watch mode — recompiles on file changes
-npm run dev
+# Build the binary
+go build -o atlassian-mcp .
+
+# Run it
+./atlassian-mcp --config /path/to/config.json
 
-# Run the built server directly
-node dist/index.js
+# Vet + unit tests
+go vet ./...
+go test ./...
 
 # Test the tool list
-echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node dist/index.js
+echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | ./atlassian-mcp
 
-# Quick release smoke check
+# Quick release smoke check (build + tools/list validation)
 npm run smoke
 ```
-
-To use a specific config file:
-
-```bash
-node dist/index.js --config /path/to/config.json
-```

package/bin/cli.mjs

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+// npm/npx launcher. Ensures the prebuilt Go binary for this platform is present
+// (npx @latest guarantees the newest version), then hands stdio to it directly.
+//
+// It also injects the bundled ffmpeg-static / ffprobe-static binaries via env so
+// video and animated-image attachments work with zero extra setup on the npm
+// install path. Users who install the Go binary directly (go install / Nix)
+// supply ffmpeg/ffprobe on PATH, or set ATLASSIAN_MCP_FFMPEG_PATH / _FFPROBE_PATH.
+//
+// Note on overhead: with stdio 'inherit' the Go binary reads/writes the real
+// stdin/stdout, so this launcher adds ZERO per-message latency — it only relays
+// signals and the exit code.
+import { spawn } from 'node:child_process';
+import { ensureBinary } from '../scripts/download.mjs';
+
+let bin;
+try {
+  bin = await ensureBinary();
+} catch (err) {
+  console.error(`[atlassian-mcp] ${err.message}`);
+  process.exit(1);
+}
+
+// Resolve bundled ffmpeg/ffprobe and expose them to the Go binary unless the
+// user already pinned a path. Best-effort: missing modules are non-fatal.
+const env = { ...process.env };
+async function resolveBundled(envKey, importer) {
+  if (env[envKey]) return;
+  try {
+    const p = await importer();
+    if (p) env[envKey] = p;
+  } catch { /* dependency absent — fall back to PATH lookup in the binary */ }
+}
+await resolveBundled('ATLASSIAN_MCP_FFMPEG_PATH', async () => {
+  const m = await import('ffmpeg-static');
+  return m.default ?? m;
+});
+await resolveBundled('ATLASSIAN_MCP_FFPROBE_PATH', async () => {
+  const m = await import('ffprobe-static');
+  return (m.default ?? m)?.path;
+});
+
+const child = spawn(bin, process.argv.slice(2), { stdio: 'inherit', env });
+
+// Forward termination signals so the Go binary shuts down cleanly with its host.
+for (const sig of ['SIGINT', 'SIGTERM', 'SIGHUP', 'SIGQUIT']) {
+  process.on(sig, () => {
+    if (!child.killed) child.kill(sig);
+  });
+}
+
+child.on('exit', (code, signal) => {
+  if (signal) process.kill(process.pid, signal);
+  else process.exit(code ?? 0);
+});
+child.on('error', (err) => {
+  console.error(`[atlassian-mcp] failed to start binary: ${err.message}`);
+  process.exit(1);
+});

package/package.json

@@ -1,45 +1,32 @@
 {
   "name": "@stubbedev/atlassian-mcp",
-  "version": "0.4.5",
-  "description": "MCP server for self-hosted Jira and Bitbucket",
+  "version": "0.5.1",
+  "description": "MCP server for self-hosted Jira and Bitbucket (Go, distributed as a prebuilt binary)",
   "license": "MIT",
   "type": "module",
-  "main": "dist/index.js",
+  "bin": {
+    "atlassian-mcp": "bin/cli.mjs"
+  },
   "files": [
-    "dist",
+    "bin/cli.mjs",
+    "scripts/download.mjs",
+    "scripts/postinstall.mjs",
     "atlassian-mcp.schema.json",
     "README.md"
   ],
-  "bin": {
-    "atlassian-mcp": "dist/index.js"
-  },
   "scripts": {
-    "build": "tsc",
-    "start": "node dist/index.js",
-    "dev": "tsx src/index.ts",
-    "release:patch": "npm version patch && git push origin && git push origin --tags && gh release create $(git describe --tags) --generate-notes",
-    "release:minor": "npm version minor && git push origin && git push origin --tags && gh release create $(git describe --tags) --generate-notes",
-    "release:major": "npm version major && git push origin && git push origin --tags && gh release create $(git describe --tags) --generate-notes",
-    "smoke": "npm run build && npm run smoke:tools",
-    "smoke:tools": "printf '%s\\n' '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\",\"params\":{}}' | node dist/index.js",
-    "smoke:validate": "printf '%s\\n' '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\",\"params\":{}}' | node dist/index.js | node -e \"let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{try{const r=JSON.parse(d.trim());if(r.error)throw new Error('server error: '+r.error.message);const t=r.result?.tools;if(!Array.isArray(t)||!t.length)throw new Error('no tools in response');const bad=t.filter(x=>!x.name||!x.inputSchema);if(bad.length)throw new Error('malformed tools: '+bad.map(x=>x.name??'(unnamed)').join(', '));console.log('smoke OK — '+t.length+' tool(s): '+t.map(x=>x.name).join(', '))}catch(e){console.error('smoke FAIL:',e.message);process.exit(1)}})\"",
-    "prerelease": "npm run build && npm run smoke:validate && ncu"
+    "postinstall": "node scripts/postinstall.mjs",
+    "build": "go build -o atlassian-mcp .",
+    "test": "go test ./...",
+    "smoke": "go build -o atlassian-mcp . && printf '%s\\n' '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\",\"params\":{}}' | ATLASSIAN_MCP_CONFIG=/nonexistent JIRA_URL=https://github.com JIRA_ACCESS_TOKEN=smoke BITBUCKET_URL=https://github.com BITBUCKET_ACCESS_TOKEN=smoke ./atlassian-mcp | node -e \"let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{try{const r=JSON.parse(d.trim());if(r.error)throw new Error('server error: '+r.error.message);const t=r.result?.tools;if(!Array.isArray(t)||!t.length)throw new Error('no tools in response');const bad=t.filter(x=>!x.name||!x.inputSchema);if(bad.length)throw new Error('malformed tools: '+bad.map(x=>x.name??'(unnamed)').join(', '));console.log('smoke OK — '+t.length+' tool(s): '+t.map(x=>x.name).join(', '))}catch(e){console.error('smoke FAIL:',e.message);process.exit(1)}})\"",
+    "preversion": "go vet ./... && npm run test && npm run smoke",
+    "release:patch": "npm version patch && git push origin HEAD --follow-tags",
+    "release:minor": "npm version minor && git push origin HEAD --follow-tags",
+    "release:major": "npm version major && git push origin HEAD --follow-tags"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0",
-    "@napi-rs/canvas": "^0.1.100",
-    "dotenv": "^17.4.2",
     "ffmpeg-static": "^5.3.0",
-    "ffprobe-static": "^3.1.0",
-    "pdfjs-dist": "^5.7.284",
-    "sharp": "^0.35.2",
-    "unpdf": "^1.6.2"
-  },
-  "devDependencies": {
-    "@types/node": "^25.9.4",
-    "npm-check-updates": "^21.0.3",
-    "tsx": "^4.22.4",
-    "typescript": "^6.0.3"
+    "ffprobe-static": "^3.1.0"
   },
   "engines": {
     "node": ">=18.0.0"

package/scripts/download.mjs

@@ -0,0 +1,86 @@
+// Resolves (and, if needed, downloads) the prebuilt Go binary that matches the
+// current platform. Shared by the postinstall script and the CLI launcher so a
+// failed install (e.g. offline) self-heals on first run.
+import { createWriteStream } from 'node:fs';
+import { chmod, mkdir, rm, stat, rename } from 'node:fs/promises';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readFileSync } from 'node:fs';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const root = join(here, '..');
+const binDir = join(root, 'bin');
+
+const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf-8'));
+const REPO = 'stubbedev/atlassian-mcp';
+
+// Map Node's platform/arch onto the Go release asset naming. Anything not
+// listed falls back to the "go install" hint in target().
+const PLATFORMS = {
+  'linux:x64': { os: 'linux', arch: 'amd64', ext: '' },
+  'linux:arm64': { os: 'linux', arch: 'arm64', ext: '' },
+  'linux:arm': { os: 'linux', arch: 'arm', ext: '' },
+  'linux:ia32': { os: 'linux', arch: '386', ext: '' },
+  'linux:ppc64': { os: 'linux', arch: 'ppc64le', ext: '' },
+  'linux:s390x': { os: 'linux', arch: 's390x', ext: '' },
+  'linux:riscv64': { os: 'linux', arch: 'riscv64', ext: '' },
+  'darwin:x64': { os: 'darwin', arch: 'amd64', ext: '' },
+  'darwin:arm64': { os: 'darwin', arch: 'arm64', ext: '' },
+  'win32:x64': { os: 'windows', arch: 'amd64', ext: '.exe' },
+  'win32:arm64': { os: 'windows', arch: 'arm64', ext: '.exe' },
+  'win32:ia32': { os: 'windows', arch: '386', ext: '.exe' },
+  'freebsd:x64': { os: 'freebsd', arch: 'amd64', ext: '' },
+  'freebsd:arm64': { os: 'freebsd', arch: 'arm64', ext: '' },
+};
+
+function target() {
+  const key = `${process.platform}:${process.arch}`;
+  const t = PLATFORMS[key];
+  if (!t) {
+    throw new Error(
+      `Unsupported platform ${key}. Build from source with: go install github.com/${REPO}@latest`,
+    );
+  }
+  return t;
+}
+
+export function binaryPath() {
+  const { ext } = target();
+  return join(binDir, `atlassian-mcp-native${ext}`);
+}
+
+function assetUrl() {
+  const { os, arch, ext } = target();
+  return `https://github.com/${REPO}/releases/download/v${pkg.version}/atlassian-mcp_${os}_${arch}${ext}`;
+}
+
+async function exists(path) {
+  try {
+    const s = await stat(path);
+    return s.isFile() && s.size > 0;
+  } catch {
+    return false;
+  }
+}
+
+// ensureBinary returns the path to the platform binary, downloading it from the
+// matching GitHub release if it is not already present.
+export async function ensureBinary() {
+  const dest = binaryPath();
+  if (await exists(dest)) return dest;
+
+  await mkdir(binDir, { recursive: true });
+  const url = assetUrl();
+  const res = await fetch(url, { redirect: 'follow' });
+  if (!res.ok || !res.body) {
+    throw new Error(`Failed to download ${url}: HTTP ${res.status}`);
+  }
+  const tmp = `${dest}.download`;
+  await pipeline(Readable.fromWeb(res.body), createWriteStream(tmp));
+  await chmod(tmp, 0o755).catch(() => {});
+  await rm(dest, { force: true });
+  await rename(tmp, dest);
+  return dest;
+}

package/scripts/postinstall.mjs

@@ -0,0 +1,15 @@
+// Best-effort download of the prebuilt binary at install time. Failures are not
+// fatal — the CLI launcher retries the download on first run — so installs in
+// offline/CI environments still succeed.
+import { ensureBinary } from './download.mjs';
+
+if (process.env.ATLASSIAN_MCP_SKIP_DOWNLOAD === '1') {
+  process.exit(0);
+}
+
+try {
+  await ensureBinary();
+} catch (err) {
+  console.error(`[atlassian-mcp] postinstall: ${err.message}`);
+  console.error('[atlassian-mcp] The binary will be fetched on first run instead.');
+}