@stubbedev/atlassian-mcp 0.5.9 → 0.5.11

package/README.md

@@ -13,15 +13,14 @@ 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`), and optionally transitions the ticket |
-| `complete_work` | Close out finished work: merges the open PR and transitions the Jira ticket to Done |
+| `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
 
 | Tool | Description |
 |---|---|
-| `git_get_context` | Branch, upstream state, remote URL, recent commits, working tree status, diff stat, and Jira keys in branch name |
-| `git_get_diff` | Diff of uncommitted changes or between two refs; supports paging via `charOffset` |
+| `git_get_context` | Branch, upstream state, remote URL, recent commits, working tree status, diff stat, and Jira keys in branch name. Pass `fromRef`/`toRef` for a diff between refs instead, paged via `charOffset` |
 
 ### Jira
 
@@ -29,23 +28,31 @@ 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_get_attachment` | Fetch a Jira attachment by ID. Images, videos, animated images (GIF/APNG/animated WebP), audio, and PDFs are all 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 |
-| `jira_mutate` | Create, update, transition, comment, link, add to sprint, or log work — all in one call |
-| `jira_comment` | Add, update, or delete a comment on an issue (`action`: `add` / `update` / `delete`) |
-| `jira_version` | Manage fix versions/releases (`action`: `create` / `update` / `release` / `archive` / `delete`) |
+| `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_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`, `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_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. `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` |
 
+### Shared
+
+| Tool | Description |
+|---|---|
+| `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`
@@ -63,9 +70,9 @@ A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for **s
 - "what's in the current sprint?" → `jira_search` with `resource=board_overview`
 - "move FOO-123 to In Progress" → `jira_mutate` with `transitionName="In Progress"`
 - "log 2h on FOO-123" → `jira_mutate` with `worklog`
-- "create version 9.1.0 in PAY" → `jira_version` with `action=create`, `projectKey=PAY`, `name=9.1.0`
+- "create version 9.1.0 in PAY" → `jira_mutate` with `version.action=create`, `version.projectKey=PAY`, `version.name=9.1.0`
 - "list releases for PAY" → `jira_search` with `resource=versions`, `project=PAY`
-- "release version 12345" → `jira_version` with `action=release`, `id=12345`
+- "release version 12345" → `jira_mutate` with `version.action=release`, `version.id=12345`
 - "set fix version 9.1.0 on FOO-123" → `jira_mutate` with `update.fixVersion=9.1.0`
 - "create a task under epic FOO-100" → `jira_mutate` with `create.issueType=Task`, `create.parent=FOO-100` (auto-detects Epic and sets Epic Link)
 - "move FOO-123 under epic FOO-100" → `jira_mutate` with `update.epicLink=FOO-100`
@@ -75,6 +82,38 @@ A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for **s
 
 ---
 
+## What the server enforces
+
+These are guarantees in the code, not advice in a tool description — a client
+cannot get them wrong, and they need no prompting:
+
+- **Arguments are validated before a call runs.** Enum values and required
+  fields are checked against each tool's schema, with case and `-`/`_`
+  differences normalised. An unknown `action`/`resource` is an error, never a
+  silent fallback to some default branch of the handler.
+- **Names are resolved before anything is written.** Jira `assignee`/`reporter`,
+  components and fix versions, and Bitbucket reviewers are checked first; a bad
+  one comes back with the valid options instead of an opaque 400.
+- **Markdown is converted to Jira wiki markup** on every Jira write (comments,
+  descriptions, worklogs). Text that is already wiki markup is left alone.
+- **PR comment hygiene:** one reply per thread per author, no duplicate of a
+  comment you already posted, no new top-level comment on a PR you authored
+  (`asAuthor=true` to override), no tasks via `severity`, no emoji, and bare
+  `#123` references are rewritten as links to that comment.
+- **Inline comments anchor to what was reviewed.** Reading a PR records the
+  commit pair for that session; inline comments bind to it and are remapped onto
+  current head when the branch has moved, so a comment never lands on unrelated
+  code.
+- **Reviewers are never dropped by accident** — an update that would remove one
+  needs `update.replaceReviewers=true`.
+- **`complete_work` will not merge** while reviewers have not approved or a build
+  on the PR head has failed, unless `force=true`.
+- **Truncated output always says how to continue**, naming the argument that
+  fetches the rest. `bitbucket_get_file` also states the path and ref it read,
+  so reading the wrong branch is visible rather than silent.
+- **Tool annotations** (`readOnlyHint`, `destructiveHint`, `idempotentHint`) are
+  published for every tool, so hosts can gate confirmation on metadata.
+
 ## Setup
 
 ### 1. Create a config file
@@ -104,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.
 
@@ -274,15 +313,16 @@ 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 (the `git_*` tools, `get_dev_context`, `start_work`, `complete_work`, and
+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
@@ -300,12 +340,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):
 
@@ -315,7 +362,7 @@ claude mcp add --transport http atlassian http://127.0.0.1:7337/mcp
 
 ### Attachment decoding pipeline
 
-The attachment tools (`jira_get_attachment`, `bitbucket_get_attachment`) decode binary attachments into model-readable content before returning them:
+The `get_attachment` tool decodes binary attachments into model-readable content before returning them:
 
 | Input | What gets returned | How |
 | --- | --- | --- |
@@ -365,16 +412,20 @@ On a pushed `v*` tag, `.github/workflows/publish.yml` cross-compiles the Go bina
 OS/arch targets, attaches them to a GitHub release, and publishes the npm wrapper (which
 downloads the matching binary on install).
 
-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
 
@@ -424,20 +475,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.9",
+  "version": "0.5.11",
   "description": "MCP server for self-hosted Jira and Bitbucket (Go, distributed as a prebuilt binary)",
   "license": "MIT",
   "type": "module",