@softspark/jira-mcp 1.14.5 → 1.16.0

package/CHANGELOG.md

@@ -7,6 +7,72 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v1.16.0 -- Creator and reporter on every task read (2026-09-18)
+
+`@softspark/confluence-mcp` has no behaviour change in this release; it is bumped
+together with `@softspark/jira-mcp` per ADR-0002.
+
+### Added
+
+- **`creator` and `reporter` in task reads.** `search_tasks`,
+  `get_task_details`, `sync_tasks` and `read_cached_tasks` now return who filed
+  an issue and who it is reported by. Until now the connector fetched `creator`
+  only for the `delete_task` ownership guard and never asked Jira for
+  `reporter`, so an agent asked "who raised this bug" had nothing to answer
+  from and went looking for a way around the server. Both fields hold the
+  email, or the display name when Atlassian privacy settings hide the email,
+  and `null` when Jira returns none. `reporter` is editable in Jira and can be
+  empty; `creator` never changes.
+- The `search_tasks` and `get_task_details` tool descriptions name the fields a
+  result carries, so a client can tell what is available without a trial call.
+
+### Changed
+
+- **Task cache rows carry `creator` and `reporter`.** The schema defaults both
+  to `null`, so a cache file written by an older version still loads and
+  `CACHE_VERSION` stays `1.0`. Rows cached before the upgrade read `null` until
+  the next `sync_tasks`.
+
+### Fixed
+
+- `kb/reference/api.md` showed `get_task_details` answering in a plain-text
+  layout the tool never produced. The example is now the JSON it returns.
+
+## v1.15.0 -- Tempo worklogs and reports (2026-09-17)
+
+`@softspark/confluence-mcp` has no behaviour change in this release; it is bumped
+together with `@softspark/jira-mcp` per ADR-0002 and picks up the shared HTTP
+client's Bearer support without using it.
+
+### Added
+
+- **Tempo worklogs and reports.** Two new tools read Tempo Timesheets through
+  the Tempo Cloud REST API v4: `search_tempo_worklogs` lists worklogs in a date
+  range with issue keys and user names resolved, and `get_tempo_report` sums
+  hours by project, user and/or task in the order asked. Filters combine, so
+  "this person's hours on this project last month" is one call. Tempo v4
+  answers in numeric ids only, so every result is joined against Jira
+  (`issue/bulkfetch` for keys and summaries, `user/bulk` for names); an issue
+  the token cannot browse keeps its hours under `#<id>` rather than vanishing
+  from a total. A query past 50 000 worklogs fails instead of truncating.
+- **`jira-mcp config set-tempo-token`** stores the Tempo token next to the Jira
+  credential, on the default entry or per instance with `--url`. The token is
+  read from `--token` or `TEMPO_API_TOKEN`. An instance override never inherits
+  the default's Tempo token, because a Tempo token is bound to one site.
+  `tempo_api_url` in config.json selects a region host (`api.eu.tempo.io`,
+  `api.us.tempo.io`); the global host is the default.
+- **Bearer auth in the shared HTTP client.** `AtlassianHttpClient` takes a
+  `bearer_token` config alongside the Basic pair, so Tempo rides the same retry
+  and backoff loop as Jira and Confluence instead of a second `fetch` loop.
+- Four error classes: `TempoConnectionError`, `TempoAuthenticationError`,
+  `TempoPermissionError` and `TempoNotConfiguredError`. The last one is raised
+  before any network call when a site has no token.
+
+### Fixed
+
+- `config set-credentials` no longer drops a stored Tempo token when the Jira
+  token in the same slot is rotated.
+
 ## v1.14.5 -- Build and packaging documented (2026-09-10)
 
 No code change in either package. The one thing a consumer gets that 1.14.4 did

package/README.md

@@ -4,18 +4,16 @@
 
 [![CI](https://github.com/softspark/jira-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/softspark/jira-mcp/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/@softspark/jira-mcp)](https://www.npmjs.com/package/@softspark/jira-mcp)
-[![version](https://img.shields.io/badge/version-1.14.5-blue)](CHANGELOG.md)
+[![version](https://img.shields.io/badge/version-1.16.0-blue)](CHANGELOG.md)
 [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
 
 ---
 
-## What's New in v1.14.5
+## What's New in v1.16.0
 
-- No code change since 1.14.4; this release carries documentation of how the workspace builds and packages.
-- 1.14.4 is where this package started actually containing the `CHANGELOG.md` it had been listing in `files` since 1.12.0. The pattern resolved inside the package directory while the changelog sat at the repository root, so npm dropped it without a word.
-- Polish versions of all eight built-in comment templates ship with the package. Until now a templated comment was English on every project, including one configured for another language.
-- `jira-mcp template list-locales` shows which languages are available, and `jira-mcp template install-locale pl` installs them. Add `--keep-english` to keep the originals reachable as `<id>-en`.
-- Fixed in 1.14.1: `jira-mcp --help` now lists both new commands. 1.14.2 adds the test that would have caught it, on both binaries.
+- **`creator` and `reporter` on every task read.** `search_tasks`, `get_task_details`, `sync_tasks` and `read_cached_tasks` now say who filed an issue and who it is reported by. Before, neither field reached a response, so "who raised this bug" had no answer.
+- Both hold the email, or the display name when Atlassian privacy settings hide the email, and `null` when Jira returns none. To filter by them, use JQL: `creator = "pm@example.com"` or `reporter = currentUser()`.
+- An existing task cache keeps loading. Rows cached before the upgrade read `null` for both fields until the next `sync_tasks`.
 - Released together with `@softspark/confluence-mcp` under one version. See the [changelog](CHANGELOG.md).
 
 ## Table of Contents
@@ -64,6 +62,16 @@ jira-mcp config add-project
 
 All configuration lives in `~/.softspark/jira-mcp/` (created by `jira-mcp config init`). This is the standard config directory for all SoftSpark open-source tools.
 
+### 3. Tempo (optional)
+
+If the site runs Tempo Timesheets, create a Tempo API token (Tempo > Settings > API Integration) and store it next to the Jira credential:
+
+```bash
+jira-mcp config set-tempo-token --token TEMPO_TOKEN
+```
+
+That unlocks `search_tempo_worklogs` and `get_tempo_report`. Without it every other tool works as before. Sites pinned to a Tempo region set `tempo_api_url` in `config.json` (`https://api.eu.tempo.io/4` or `https://api.us.tempo.io/4`).
+
 ## CLI Commands
 
 | Command | Description |
@@ -84,6 +92,7 @@ All configuration lives in `~/.softspark/jira-mcp/` (created by `jira-mcp config
 | `jira-mcp config remove-project <key>` | Remove a project from config |
 | `jira-mcp config list-projects` | List all configured projects with language |
 | `jira-mcp config set-credentials` | Set API credentials |
+| `jira-mcp config set-tempo-token` | Set the Tempo API token (default site or `--url <jira-url>`) |
 | `jira-mcp config set-default <key>` | Set default project |
 | `jira-mcp config set-language <lang>` | Set global default language |
 | `jira-mcp config set-project-language <key> <lang>` | Set language for a specific project |
@@ -114,6 +123,8 @@ All configuration lives in `~/.softspark/jira-mcp/` (created by `jira-mcp config
 | `add_templated_comment` | Add comment using a template or raw markdown | `task_key`, `template_id?`, `variables?`, `markdown?`, `user_approved` |
 | `create_task` | Create a new Jira issue with explicit fields or a task template | `project_key`, `summary?`, `template_id?`, `variables?`, `description?`, `assignee_email?`, `labels?`, `epic_key?`, `parent_key?`, `original_estimate?` |
 | `search_tasks` | Search Jira issues with JQL (no caching) | `jql`, `max_results?`, `project_key?` |
+| `search_tempo_worklogs` | List Tempo worklogs in a date range, issue keys and user names resolved | `from`, `to`, `project_key?`, `task_key?`, `user_email?`, `limit?` |
+| `get_tempo_report` | Sum Tempo hours by project, user and/or task | `from`, `to`, `group_by?`, `project_key?`, `task_key?`, `user_email?` |
 
 ## Comment Templates
 
@@ -195,15 +206,16 @@ Configuration is automatically loaded from `~/.softspark/jira-mcp/`. Run `jira-m
 If you use `@softspark/ai-toolkit`, register the Jira rules so that Claude Code automatically follows project conventions (language checks, sync-first workflow, time format, etc.):
 
 ```bash
-ai-toolkit rules add jira-mcp --path /path/to/jira-mcp/rules/jira-mcp.md
+ai-toolkit add-rule https://raw.githubusercontent.com/softspark/jira-mcp/main/rules/jira-mcp.md
+ai-toolkit update
 ```
 
-Or copy `rules/jira-mcp.md` to your ai-toolkit rules directory manually. The rules file covers:
+The URL form is re-fetched on every `ai-toolkit update`, so the rules follow releases. A local path works too (`ai-toolkit add-rule /path/to/jira-mcp/rules/jira-mcp.md`) but stays frozen at that copy. The rules file covers:
 - **Language first** -- always check project language before writing comments/descriptions
 - **Sync before read** -- cache may be stale
 - **Status transitions** -- check valid transitions before changing status
 - **Time format** -- `"2h 30m"`, never days
-- **All 19 MCP tools** and **23 CLI commands** reference
+- **All 21 MCP tools** and **24 CLI commands** reference
 
 ### AI Toolkit Hooks
 
@@ -246,11 +258,11 @@ src/
       create.ts   Bulk task creation command
       create-monthly.ts  Monthly admin task automation
   config/         Configuration loading and Zod validation
-  connector/      Jira API client (built-in fetch, instance pool)
+  connector/      Jira and Tempo API clients (built-in fetch, instance pool)
   errors/         Typed error hierarchy
-  operations/     Business logic (status, comments, time tracking)
+  operations/     Business logic (status, comments, time tracking, Tempo reports)
   templates/      File-backed comment/task template loading and registries
-  tools/          MCP tool handlers (19 tools, one file per tool)
+  tools/          MCP tool handlers (21 tools, one file per tool)
   types/          Shared TypeScript types
   server.ts       MCP server setup and tool registration
   cli.ts          CLI entry point
@@ -272,11 +284,13 @@ src/
 
 **Per-instance credentials** -- different API tokens per Jira instance URL. Single-credential format still works (backward compatible). See [Configuration](kb/reference/configuration.md).
 
-**Supply chain protection** -- `ignore-scripts=true`, no axios, no dynamic requires. Self-contained 548KB library bundle, 1 runtime dep (commander).
+**Tempo worklogs and reports** -- `search_tempo_worklogs` and `get_tempo_report` read Tempo Timesheets (Cloud REST API v4) for hours per project, user or task over a date range, with Tempo's numeric ids resolved to issue keys and names through Jira. Needs a Tempo API token (`jira-mcp config set-tempo-token`); nothing else depends on it. See [API Reference](kb/reference/api.md).
+
+**Supply chain protection** -- `ignore-scripts=true`, no axios, no dynamic requires. Self-contained 561KB library bundle, 1 runtime dep (commander).
 
-**Typed error hierarchy** -- 26 error classes with machine-readable codes. Every tool returns structured `{ success, error, code }` responses. No stack traces leak to MCP clients.
+**Typed error hierarchy** -- 30 error classes with machine-readable codes. Every tool returns structured `{ success, error, code }` responses. No stack traces leak to MCP clients.
 
-**Strict TypeScript** -- `strict: true`, no `any`, `readonly` interfaces, Zod validation at all boundaries, 991 tests across 80 test files.
+**Strict TypeScript** -- `strict: true`, no `any`, `readonly` interfaces, Zod validation at all boundaries, 1093 tests across 85 test files.
 
 ## Documentation
 
@@ -284,7 +298,7 @@ src/
 |----------|-------------|
 | [Architecture](kb/reference/architecture.md) | System design and module overview |
 | [Local audit](kb/reference/audit.md) | JSON/SARIF formats, filesystem checks and hook permissions |
-| [API Reference](kb/reference/api.md) | All 19 MCP tools with schemas |
+| [API Reference](kb/reference/api.md) | All 21 MCP tools with schemas |
 | [Configuration](kb/reference/configuration.md) | Config files, env vars, multi-instance |
 | [ADF Format](kb/reference/adf.md) | Atlassian Document Format conversion |
 | [Caching](kb/reference/caching.md) | Task, workflow, and user caching |