<!--
Editing notes (Claude: read before changing this file)

Audience
  External consumers of the Aerion MCP server — typically Aerion customers wiring it
  into Claude Desktop or Claude Code. As far as they're concerned this is a hosted
  service. Do not mention local mode, transports, or deployment plumbing.

Forbidden words
  Do not use: "lambda", "npm", "API spec", "swagger". These leak internal
  implementation. Rephrase with euphemisms or describe the outcome instead.

Style
  Terse and outcome-focused. Describe the user-visible effect, not the mechanism.
  Example: "Improved token-refresh behavior." beats "Expired-token responses are
  now standard 401 + WWW-Authenticate so MCP clients can refresh and retry."
  Mechanism detail like HTTP status codes, response bodies, and headers belongs in
  CHANGELOG.md, not here.

  Calibrate detail against Reilly-authored bullets already in this file — single
  short sentence, optionally one parallel clause for a distinct improvement.
  "Editorialize a little" is fine; field-by-field detail is not. Specific field
  names with deep semantics (e.g. "expectedHours capped at min(endDate, today)")
  belong in CHANGELOG.md. When in doubt, your bullet is probably already too long.

Vantage point
  Write from the consumer's POV — what they observe — not from the implementer's
  POV (the rule that produces the observation). "Clear up confusion about when
  and why gaps appear in the data" beats "spell out which entries get pruned when
  empty." Same change, but the first is what the consumer was wondering.

Surface (do mention)
  - New tools and tool capabilities.
  - Improvements to tool descriptions, titles, annotations (e.g. readOnlyHint).
  - User-visible behavior changes (error pass-through, refresh, retries).
  - Improvements to model-level guidance that the LLM now sees via `describe`.

Don't surface
  - Internal observability (User-Agent, request logging, etc.).
  - Hosting model, build, or transport details.
  - Spec extensions (x-llm-*) or other internal authoring mechanisms.
  - Refactors, file moves, dependency bumps, CI changes.

No meta-prose
  No "user-facing release notes for X" preamble. The heading below is sufficient.

Structure
  Flat bullets directly under each version heading. Do NOT introduce Keep-a-Changelog
  subheadings (Added / Changed / Fixed) — they confuse the docs site's table of
  contents and aren't used by the other Aerion changelogs at
  https://docs.aerion.dev/changelogs/.
-->

# Aerion MCP Server Release Notes

<!--
UNRELEASED — promote under a dated version heading at release time.

- Tool display names are now carried in the standard annotations field as well, so every MCP client surfaces the friendly tool name consistently.
-->

## 0.3.1 — 2026-06-19

- Tool hints are now exhaustive across every tool, so MCP clients that surface them have a complete picture of each tool's behavior.
- Fixed a configuration snag that was interrupting OpenAI's OAuth auto-discovery.

## 0.3.0 — 2026-06-18

- New tool `submit_time_entries` — submits the caller's own WORK time entries for a single day, auto-creating the day's WORKTIME entry when the account requires one.
- New tool `change_approval_status` — single entrypoint covering single-entry approval changes, bulk WORK + ProjectDay approval / locking across up to seven dates, and bulk WORKTIME approval across a date range. The variant is chosen from the fields you supply.
- `whoami` now returns the account's company name plus the account-level rules that decide which time-entry writes the LLM can attempt: worktime tracking, approval flow, and the historical-locking / grace-period windows that say when backdated edits are still allowed.

## 0.2.1 — 2026-05-29

- `user_analytics` has been annotated to disambiguate its many similar-sounding hour-variant fields, and to clear up confusion about when and why gaps appear in the data.

## 0.2.0 — 2026-05-29

- **`whoami` now returns a full session context.** Used to return just the caller's user record; now returns the caller's account settings (`timerMode` + format preferences), role + capability flags, team memberships + team-mates, active absences and upcoming planner assignments across an ~18-day window, and recently-touched projects. The tool description directs the LLM to call `whoami` before any time-entry or absence write — `timerMode` determines the time-entry shape, and capability flags gate which writes are allowed.
- `project_analytics` now carries response-shape guidance, so the LLM knows the output is bulky and can project to the fields it actually needs (e.g. `id`, `hours.spent`) for top-N or aggregate questions rather than reading the whole payload inline.
- `find`-tool descriptions now flag that the `where` parameter and the per-attribute filters are mutually exclusive — supplying `where` means the per-attribute filters are ignored.
- `describe` output now carries clearer guidance on planner assignment durations (a single assignment spanning weekends/holidays is correct — don't split)

## 0.1.3 — 2026-05-22

- Landing page at the server root with setup instructions for anyone who opens the URL in a browser.
- Tool titles ("Find records", "Get record by ID", "Delete record", etc.) and behavior annotations (`readOnlyHint` on the read tools, `destructiveHint` on `destroy`), so MCP clients can convey tool intent without inferring it from the name.
- `describe` now surfaces the model-level guidance — e.g. the full `TimeEntry` write contract covering `WORK` / `WORKTIME` / `BREAK` and how each interacts with the account-level `timerMode`. The same guidance is also surfaced through find-tool descriptions.
- `find`'s description now walks through the `where` (Waterline criteria) parameter with worked examples covering array filtering and combined criteria.
- `destroy`'s description flags the operation as irreversible and tells callers to only invoke it on explicit user request.
- Improved token-refresh behavior.
- Improved API error passthrough — failures now surface the underlying reason, not just the status code.

## 0.1.0 — 2026-04-30

Initial release. Launched with the following tools:

- `list_resources` — the discovery entry point. Returns the inventory of available Aerion resources (`users`, `projects`, `time-entries`, …) and which CRUD methods each supports. Call this first if you don't already know what's available, then `describe(resource)` for the field-level shape.
- `describe`, `find`, `find_one`, `create`, `update`, `destroy` — generic, verb-shaped tools parameterised by `resource`. New endpoints in the backend extend the catalog without changing the LLM-facing contract.
- `whoami`, `project_analytics`, `user_analytics` — named action tools wrapping non-CRUD endpoints.