@labelgrid/mcp 0.3.1 → 0.5.0

package/CHANGELOG.md

@@ -5,6 +5,57 @@ All notable changes to `@labelgrid/mcp` are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] - 2026-07-27
+
+### Added
+
+- `get_analytics_availability` — one static call returning the section-by-platform
+  `availability` matrix and the per-platform `platform_cadence` map (`daily` or
+  `weekly`). Fetch it once before `get_analytics` so an unreported section is
+  treated as unavailable rather than as an empty chart.
+- 22 new analytics section keys (37 total), including library adds, shazams
+  (plus by-city and by-state), playlist adds, detailed source split, discovery
+  and repeat rates, listener plan mix, listeners by region, Apple streams by
+  city, Apple discovery cohorts, average listen time, and hour-of-day.
+- 7 new `platform` filter values (10 total): `DEEZER`, `BOOMPLAY`, `AWA`,
+  `AUDIOMACK`, `KUGOU`, `KUWO`, `QQMUSIC`. The three Tencent platforms report
+  weekly — one point per week carrying the whole week.
+
+### Changed
+
+- **Breaking:** `get_analytics` now requires `metrics` (1–12 section keys per
+  request), matching the API contract. Split a larger selection across
+  requests — responses are cached per scope and window.
+- The reporting window cap rose from 30 to 400 days. Windows over 90 days draw
+  a separate, lower rate budget; a 429 response carries `retry_after_seconds`.
+- Tool descriptions across the catalog were tightened. No tool names,
+  parameters, or behavior changed beyond the items above.
+
+## [0.4.0] - 2026-07-23
+
+### Added
+
+- `LABELGRID_TIMEOUT_MS` and `LABELGRID_TRANSFER_TIMEOUT_MS` configure the JSON
+  request timeout and the upload/download transfer timeout. A non-positive-
+  integer value is ignored with a warning and the built-in default applies.
+- `LABELGRID_DOWNLOAD_DIR` — the only directory `download_statement` may write a
+  `save_to_path` into (default: `~/Downloads` if present, else the working
+  directory). A path resolving outside it is refused with a structured error.
+
+### Changed
+
+- `download_statement` now streams both the invoice PDF and a saved CSV export
+  straight to disk instead of buffering the whole file in memory. An inline CSV
+  (no `save_to_path`) is read with a 10 MB byte ceiling enforced up front and
+  mid-stream; a larger export returns `RESPONSE_TOO_LARGE` and must be saved to
+  a path.
+
+### Fixed
+
+- `download_statement` now writes a `save_to_path` file via a temp sibling that
+  is atomically linked into place, so a failed download never leaves a partial
+  file, and reports `saved_to` as the realpath-resolved canonical path.
+
 ## [0.3.1] - 2026-07-20
 
 ### Changed

package/README.md

@@ -89,6 +89,9 @@ All configuration is via environment variables in your client config.
 | `LABELGRID_FULL_WRITES_ACK` | — | Must equal the exact acknowledgment sentence to arm full writes. |
 | `LABELGRID_READ_ONLY` | `false` | Force reads only; overrides both write flags. |
 | `LABELGRID_TOOLSETS` | all except `webhooks` | Comma-separated subset of toolsets to expose. |
+| `LABELGRID_TIMEOUT_MS` | `60000` | JSON request timeout in milliseconds. Must be a positive integer; a bad value is ignored with a warning. |
+| `LABELGRID_TRANSFER_TIMEOUT_MS` | `600000` | Upload/download transfer timeout in milliseconds (for presigned uploads and statement downloads). Same validation. |
+| `LABELGRID_DOWNLOAD_DIR` | `~/Downloads` if it exists, else the working directory | The only directory `download_statement` may write a `save_to_path` into; a path outside it is refused. |
 
 Valid toolsets (8): `account`, `reference`, `catalog`, `releases`, `insights`, `finance`, `webhooks`, `distribution`.
 
@@ -101,7 +104,7 @@ The nine reference datasets are also exposed as MCP **resources** at `labelgrid:
 
 <!-- TOOLS:BEGIN -->
 
-_30 tools across 8 toolsets. This table is generated from the
+_31 tools across 8 toolsets. This table is generated from the
 tool definitions by `npm run gen-docs` — do not edit it by hand._
 
 ### Account `account`
@@ -121,32 +124,33 @@ tool definitions by `npm run gen-docs` — do not edit it by hand._
 
 | Tool | Gate | Description |
 | --- | --- | --- |
-| `search_catalog` | read | List catalog entities of one kind, paginated. Pick the kind with `entity`: label, artist, writer, publisher, release, or track. `filters` takes the endpoint’s own filter names, passed through verbatim — label: no documented filters — paginate with page/per_page. artist: artist_name (filter by artist name). writer: name (writer name), ipi (IPI number). publisher: name (publisher name), ipi (IPI number). release: label_id (owning label id), is_live (1 = live/distributed only), barcode_number (UPC/EAN), cat (catalog number). track: release_id (one release’s tracks), isrc (filter by ISRC). Use get_catalog_item for one entity's full detail. response_format:'detailed' returns the verbatim API response. |
-| `get_catalog_item` | read | Retrieve one catalog entity by id, with its full detail — a label’s settings, an artist’s identifiers and links, a writer’s PRO/IPI, a release’s metadata and track listing, a track’s contributors and royalty splits. Pick the kind with `entity`: label, artist, writer, publisher, release, or track. response_format:'detailed' returns the verbatim API response. |
-| `create_catalog_item` | write | Create a catalog entity. Pick the kind with `entity` and pass its attributes in `fields` — the API owns all validation. Required and common fields per entity: label — required: name, default_email; optional: support email, website/platform URLs, default copyright lines, isrc_base. artist — required: artist_name; optional: full_name, email, location, bios, isni, default_language, platform profile URLs. writer — required: first_name, last_name; optional: middle_name, display_credits, email, country, pro, ipi, isni, publisher_id (or publisher_name/publisher_pro/publisher_ipi). publisher — required: name; optional: ipi, pro, isni, controlled_publisher. release — required on create: content_type, label_id, artists, titles, cat (catalog number), artwork_ai_usage, primary_genre_id; many optional fields (dates, copyright lines, genres, per-outlet URLs). Once submitted or distributed some fields are locked — changing one returns a 403 with code RELEASE_LOCKED_FIELDS naming exactly which fields cannot change. track — required on create: release_id, disc, track_num, composition_type, artists, audio_ai_usage, composition_ai_usage, commercial_samples, audio_language, contributors, and recording_country (ISO 3166-1 alpha-2, e.g. "US"); optional: titles, isrc, iswc, writers, publishers, splits, and more. A release is created in DRAFT state — add tracks, then run the release checks before distributing. `idempotency_key` is honored for release and track only. |
-| `update_catalog_item` | write | Update a catalog entity. Pick the kind with `entity`, supply only the fields you want to change in `fields` (same field sets as create_catalog_item). For releases: once submitted or distributed, some fields are locked — changing one returns a 403 with code RELEASE_LOCKED_FIELDS naming exactly which fields cannot change. Track fields lock the same way once the parent release is submitted or distributed. |
-| `delete_catalog_item` | write | Delete a catalog entity by id. The API refuses deletes that would orphan data — label: refused while the label still has releases — remove or reassign its releases first. artist: refused while still referenced by releases or tracks. writer: refused while still referenced by tracks. publisher: refused while still referenced by writers. release: only a never-submitted draft can be deleted. track: allowed while the parent release is an editable draft; refused once submitted or distributed. |
-| `upload_image` | write | Upload a label image or an artist photo from a local file. `target`: label_logo, label_logo_dark (a dark-mode variant), label_background, or artist_photo. `id` is the label id for label_* and the artist id for artist_photo. `file_path` must be a local image file. |
-| `get_asset` | read | Read a track or release asset. Valid selector matrices: (1) mode='info', parent='track', asset stereo\|dolby\|lyrics — file metadata (not the bytes) incl. processing state. (2) mode='info', parent='release', asset square\|tall — animated cover (motion artwork) video metadata incl. processing state. (3) mode='download_url', parent='track', asset audio_16\|audio_24\|audio_32 (WAV master at that bit depth) or audio_preview_full\|audio_preview_clip (generated MP3 preview) — returns { download_url, expires_in }: a signed URL that expires roughly 10 minutes after issue; fetch it directly — do not send your API token to it. Any other combination has no endpoint and returns a structured error. mode defaults to info. |
+| `search_catalog` | read | List catalog entities of one kind, paginated. `filters` takes the endpoint’s own filter names, passed through verbatim — label: no documented filters — paginate with page/per_page. artist: artist_name (filter by artist name). writer: name (writer name), ipi (IPI number). publisher: name (publisher name), ipi (IPI number). release: label_id (owning label id), is_live (1 = live/distributed only), barcode_number (UPC/EAN), cat (catalog number). track: release_id (one release’s tracks), isrc (filter by ISRC). Use get_catalog_item for full detail. |
+| `get_catalog_item` | read | Retrieve one catalog entity by id, with full detail (e.g. a release’s metadata and track listing, a track’s contributors and royalty splits, a writer’s PRO/IPI). |
+| `create_catalog_item` | write | Create a catalog entity: pass its attributes in `fields` — the API owns all validation. Required and common fields per entity: label — required: name, default_email; optional: support email, website/platform URLs, default copyright lines, isrc_base. artist — required: artist_name; optional: full_name, email, location, bios, isni, default_language, platform profile URLs. writer — required: first_name, last_name; optional: middle_name, display_credits, email, country, pro, ipi, isni, publisher_id (or publisher_name/publisher_pro/publisher_ipi). publisher — required: name; optional: ipi, pro, isni, controlled_publisher. release — required on create: content_type, label_id, artists, titles, cat (catalog number), artwork_ai_usage, primary_genre_id; many optional fields (dates, copyright lines, genres, per-outlet URLs). Once submitted or distributed some fields are locked — changing one returns a 403 with code RELEASE_LOCKED_FIELDS naming exactly which fields cannot change. track — required on create: release_id, disc, track_num, composition_type, artists, audio_ai_usage, composition_ai_usage, commercial_samples, audio_language, contributors, and recording_country (ISO 3166-1 alpha-2, e.g. "US"); optional: titles, isrc, iswc, writers, publishers, splits, and more. A release is created in DRAFT state — add tracks, then run the release checks before distributing. |
+| `update_catalog_item` | write | Update a catalog entity: supply only the fields to change in `fields` (same field sets as create_catalog_item). Once a release is submitted or distributed, some release and track fields are locked — changing one returns a 403 with code RELEASE_LOCKED_FIELDS naming exactly which fields cannot change. |
+| `delete_catalog_item` | write | Delete a catalog entity. The API refuses deletes that would orphan data — label: refused while the label still has releases — remove or reassign its releases first. artist: refused while still referenced by releases or tracks. writer: refused while still referenced by tracks. publisher: refused while still referenced by writers. release: only a never-submitted draft can be deleted. track: allowed while the parent release is an editable draft; refused once submitted or distributed. |
+| `upload_image` | write | Upload a label image (logo, dark-mode logo, or background) or an artist photo from a local image file, per `target`. |
+| `get_asset` | read | Read a track or release asset. Valid combinations: (1) mode='info' + parent='track' + asset stereo\|dolby\|lyrics — file metadata (not the bytes) incl. processing state. (2) mode='info' + parent='release' + asset square\|tall — motion-artwork (animated cover) video metadata. (3) mode='download_url' + parent='track' + asset audio_16\|audio_24\|audio_32 (WAV master) or audio_preview_full\|audio_preview_clip (MP3 preview) — returns { download_url, expires_in }, a signed URL that expires roughly 10 minutes after issue; fetch it directly — do not send your API token to it. Any other combination returns a structured error. |
 
 ### Releases (review, delivery, links, licenses, checks) `releases`
 
 | Tool | Gate | Description |
 | --- | --- | --- |
-| `get_release_review` | read | Read a release's automated quality-check results. Pick ONE view with `view`: `issues` lists the review issues raised against the release — each carries a code (see list_reference_data type issue_definitions), severity, and whether it blocks distribution; use it to see what must be fixed before the release can go out. `quality_report` retrieves the Preflight QC quality report — the customer-facing issues found by the automated checks, to review before confirming the release into distribution; Preflight QC is an optional add-on — without it the API returns a 403, surfaced verbatim. response_format:'detailed' returns the verbatim API response. |
-| `get_delivery_queue` | read | List the distribution queue entries for your account, paginated — one entry per (release, outlet) delivery with its current status (e.g. pending review, processing, scheduled, complete, error) — where a release is in the delivery pipeline to each store. Filter by `release_id`, `outlet_id`, or `status`. response_format:'detailed' returns the verbatim API response. |
-| `get_landing_config` | read | Retrieve the smart-link landing-page configuration for a release: whether the links page is enabled, its style/mode, custom copy, the action list and any pre-order links. Pair with manage_release_links (action update_landing_config) to change it. |
-| `list_track_licenses` | read | List the licenses attached to a track (e.g. cover/mechanical or sample clearances), paginated. Pass `license_id` to retrieve one license by its id instead. |
-| `run_release_checks` | write | Run an automated check on a release. Pick ONE with `check`: `validate` returns any problems that would block distribution, as a human-readable `errors` list and a machine-readable `errors_structured` list — it changes nothing and is safe to repeat; run it before distributing. `refresh_quality_report` re-runs the Preflight QC checks and refreshes the quality report (read it with get_release_review view quality_report); the server applies an hourly refresh budget, so frequent calls may be rate-limited. Preflight QC is an optional add-on. |
-| `manage_release_links` | write | Manage a release's smart-link landing page. Pick ONE action with `action`: `update_landing_config` replaces the landing-page configuration with `config` (required for this action) — `config.actions` uses the current (v2) action-list contract (one entry per call-to-action); other keys: links_page_enabled, config_mode, page_style, custom_cta_text, custom_description, pre_order_links. `create_short_url` creates (or returns the existing) short URL for the release's smart-link landing page — safe to repeat. |
+| `get_release_review` | read | Read a release's automated quality-check results. Pick ONE view with `view`: `issues` lists the review issues raised against the release — each with a code (see list_reference_data type issue_definitions), severity, and whether it blocks distribution. `quality_report` returns the Preflight QC quality report — customer-facing issues to review before confirming distribution; Preflight QC is an optional add-on — without it the API returns a 403, surfaced verbatim. |
+| `get_delivery_queue` | read | List your account's distribution queue, paginated — one entry per (release, outlet) delivery with its status (e.g. pending review, processing, scheduled, complete, error). Filter by `release_id`, `outlet_id`, or `status`. |
+| `get_landing_config` | read | Retrieve a release's smart-link landing-page configuration: enabled state, style/mode, custom copy, action list, pre-order links. Change it via manage_release_links (action update_landing_config). |
+| `list_track_licenses` | read | List a track's licenses (e.g. cover/mechanical or sample clearances), paginated. Pass `license_id` to retrieve one license instead. |
+| `run_release_checks` | write | Run an automated check on a release. Pick ONE with `check`: `validate` returns problems that would block distribution (human-readable `errors` + machine-readable `errors_structured`); it changes nothing and is safe to repeat — run it before distributing. `refresh_quality_report` re-runs the Preflight QC checks (read the report with get_release_review view quality_report); an hourly refresh budget may rate-limit frequent calls. Preflight QC is an optional add-on. |
+| `manage_release_links` | write | Manage a release's smart-link landing page. Pick ONE action with `action`: `update_landing_config` replaces the configuration with `config` (required for this action) — `config.actions` uses the v2 action-list contract (one entry per call-to-action); other keys: links_page_enabled, config_mode, page_style, custom_cta_text, custom_description, pre_order_links. `create_short_url` creates (or returns the existing) short URL for the landing page — safe to repeat. |
 | `add_review_issue_note` | write | Add a note to a release review issue — to explain a fix or add reviewer context. `review_issue_id` comes from get_release_review view issues. |
 
 ### Insights (analytics & artificial streaming) `insights`
 
 | Tool | Gate | Description |
 | --- | --- | --- |
-| `get_analytics` | read | Retrieve a streaming analytics summary for your catalog in a single call. `start_date` and `end_date` (both YYYY-MM-DD) are required and the window is capped at 30 days by the server. Optionally narrow the result by `platform` (SPOTIFY, ITUNES, APPLE_MUSIC), `release_id`, `isrc`, `upc`, or `artist_names`. By default all 15 metric sections are returned; pass `metrics` (see its enum) to request only a subset. Rate-limited (about 60 requests per minute); a 429 response carries retry_after_seconds. |
-| `query_artificial_streaming` | read | Query artificial-streaming (streaming-integrity) data for your catalog. Pick ONE view with `view`: `flags` lists Stream Radar early-warning flags surfacing possible artificial-streaming activity so you can act early, paginated — `filters`: status, severity, dsp, isrc, release_id, detected_from/detected_to (YYYY-MM-DD). `flag_detail` retrieves one flag by `flag_id` (required). Stream Radar is an optional add-on; without it the API returns a 403, surfaced verbatim. `records` lists the artificial-streaming records reported for your catalog, cursor-paginated — the per-record detail behind any artificial-streaming fee; `filters`: dsp (spotify or apple), start_date/end_date, release_id, isrc. `fee_breakdown` retrieves the per-release breakdown of an artificial-streaming fee for one billing period — `period` (required) is YYYY-MM. response_format:'detailed' returns the verbatim API response. |
+| `get_analytics` | read | Streaming analytics summary. Window capped at 400 days; `metrics` takes 1-12 section keys per request (split larger selections — responses are cached). KUGOU/KUWO/QQMUSIC report weekly: one point per week carrying the whole week — never average it per day. `meta` carries `platform_cadence`, `section_granularity`, `sections_as_of` and `sections_complete_through` (later dates still filling in). Call get_analytics_availability first for section-per-platform support. Rate-limited ~60/min; windows over 90 days draw a separate lower ~30/min budget — prefer shorter windows for polling. A 429 carries retry_after_seconds. |
+| `get_analytics_availability` | read | Static `availability` matrix (per section, per platform) plus `platform_cadence` (daily\|weekly per platform). Account- and date-independent: fetch once, reuse. Read it before get_analytics so an unreported section is treated as unavailable, not an empty chart. |
+| `query_artificial_streaming` | read | Artificial-streaming (streaming-integrity) reads. Pick ONE `view`: `flags` — Stream Radar early-warning flags, paginated (`filters`: status, severity, dsp, isrc, release_id, detected_from/detected_to). Stream Radar is an optional add-on; without it the API returns a 403, surfaced verbatim. `flag_detail` — one flag by `flag_id`. `records` — reported artificial-streaming records, cursor-paginated; the detail behind any artificial-streaming fee (`filters`: dsp, start_date/end_date, release_id, isrc). `fee_breakdown` — per-release fee breakdown for one `period` (YYYY-MM). response_format:'detailed' returns the verbatim API response. |
 
 ### Finance (statements, transactions, royalties) `finance`
 
@@ -166,13 +170,13 @@ tool definitions by `npm run gen-docs` — do not edit it by hand._
 
 | Tool | Gate | Description |
 | --- | --- | --- |
-| `upload_asset` | full-write | Upload a finalized track or release asset from a local file. `id` is the track id for track_* targets, the release id for release_*. `track_stereo` (stereo audio, WAV/FLAC/AIFF), `track_dolby` (Dolby Atmos, WAV) and `track_lyrics` (LRC) upload directly to storage and process asynchronously — check state with get_asset (mode info). `release_cover_art` uploads or replaces the release's static cover art image. `release_motion_square` / `release_motion_tall` upload the animated cover (motion artwork) video — square or tall/portrait — also processed asynchronously. ALL of these become immutable once the release is distributed — upload the final files before distributing. |
-| `delete_asset` | full-write | Delete a track or release asset file. track_stereo\|track_dolby\|track_lyrics delete a track asset; release_motion_square\|release_motion_tall delete an animated cover (motion artwork) video. Allowed only while the parent release is still an editable draft; the API refuses once the release is locked or distributed. Cover art has no delete endpoint and cannot be deleted here. |
-| `manage_track_license` | full-write | Manage the license documents attached to a track (for a cover or a cleared sample). Pick ONE action with `action`: `upload` attaches a new license — `file_path` required, `type` ('cover' or 'sample') selects the kind; optionally record license_id, license_provider, license_provider_name, original_track_link. `update` replaces the file and/or metadata of an existing license — `track_license_id` (from list_track_licenses) and `file_path` required. `delete` permanently deletes a license and its file — `track_license_id` required; cannot be undone. Licenses are immutability-governed once the release is live. |
-| `distribute_release` | full-write | Submit a release for distribution to the stores/outlets — the FINAL, consequential action that sends the release out; run_release_checks (check validate) should pass first. The server enforces your account’s weekly submission limit and returns a structured error if exceeded. Pass idempotency_key and reuse the SAME value when retrying an unobserved call; without a key each call is a new submission. |
-| `takedown_release` | full-write | Take a release down from ALL outlets/stores — a final, consequential action that removes it everywhere it was delivered. Re-distribution afterward is a fresh submission. |
-| `confirm_review` | full-write | Confirm a release that Preflight QC placed on hold, moving it into distribution review. Use after you have reviewed the quality report and accept the release as-is. Safe to repeat. |
-| `enable_beatport` | full-write | Request Beatport onboarding for a label. A one-time action that cannot be un-requested, so confirm the label is correct first. |
+| `upload_asset` | full-write | Upload a finalized track or release asset from a local file. `id` is the track id for track_* targets, the release id for release_*. `track_stereo` (WAV/FLAC/AIFF), `track_dolby` (Dolby Atmos WAV) and `track_lyrics` (LRC) process asynchronously — check state with get_asset (mode info). `release_cover_art` uploads or replaces the static cover art image. `release_motion_square` / `release_motion_tall` upload the square or tall animated cover (motion artwork) video, also asynchronous. All assets become immutable once the release is distributed — upload final files first. |
+| `delete_asset` | full-write | Delete a track asset (track_*) or an animated cover / motion artwork video (release_motion_*). Allowed only while the parent release is an editable draft; refused once locked or distributed. Cover art cannot be deleted. |
+| `manage_track_license` | full-write | Manage license documents on a track (cover or cleared sample). `upload` attaches a new license — `file_path` required, `type` selects cover/sample; optional metadata fields. `update` replaces the file and/or metadata — `track_license_id` (from list_track_licenses) and `file_path` required. `delete` permanently removes a license and its file — `track_license_id` required; cannot be undone. Immutability-governed once the release is live. |
+| `distribute_release` | full-write | Submit a release to the stores/outlets — the FINAL action that sends it out; run_release_checks (check validate) should pass first. The server enforces the account’s weekly submission limit. Reuse the SAME idempotency_key when retrying an unobserved call; without one each call is a new submission. |
+| `takedown_release` | full-write | Take a release down from ALL outlets/stores — a final action that removes it everywhere it was delivered. Re-distribution is a fresh submission. |
+| `confirm_review` | full-write | Confirm a release Preflight QC placed on hold, moving it into distribution review, after reviewing the quality report and accepting the release as-is. Safe to repeat. |
+| `enable_beatport` | full-write | Request Beatport onboarding for a label. One-time and cannot be un-requested — confirm the label is correct first. |
 
 <!-- TOOLS:END -->
 

package/dist/config.d.ts

@@ -16,6 +16,16 @@ export type Config = {
     writes: boolean;
     fullWrites: boolean;
     toolsets: Set<string> | null;
+    /** JSON request timeout override (ms); undefined uses the client default. */
+    timeoutMs?: number;
+    /** Raw transfer (upload/download) timeout override (ms); undefined = default. */
+    rawTimeoutMs?: number;
+    /**
+     * The only directory a file-writing tool (download_statement) may write into,
+     * resolved to a real path. From LABELGRID_DOWNLOAD_DIR, else ~/Downloads if it
+     * exists, else the process cwd.
+     */
+    downloadDir?: string;
 };
 export declare const DEFAULT_BASE_URL = "https://api.labelgrid.com/api/public";
 /** The exact sentence a user must set in LABELGRID_FULL_WRITES_ACK to arm full writes. */

package/dist/config.js

@@ -7,7 +7,50 @@
  * full-write access is doubly opt-in (flag + an exact acknowledgment sentence).
  * A read-only override wins over everything.
  */
-import { log } from '@labelgrid/core';
+import { realpathSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { log, parseTimeoutMs } from '@labelgrid/core';
+/**
+ * Resolves the download allow-list root: LABELGRID_DOWNLOAD_DIR if set, else the
+ * user's ~/Downloads when it exists, else the process cwd. Resolved to a real
+ * path so a symlinked root is compared canonically.
+ */
+function resolveDownloadDir(env) {
+    const explicit = env.LABELGRID_DOWNLOAD_DIR?.trim();
+    let candidate;
+    if (explicit !== undefined && explicit.length > 0) {
+        candidate = explicit;
+    }
+    else {
+        const downloads = join(homedir(), 'Downloads');
+        let hasDownloads = false;
+        try {
+            hasDownloads = statSync(downloads).isDirectory();
+        }
+        catch {
+            hasDownloads = false;
+        }
+        candidate = hasDownloads ? downloads : process.cwd();
+    }
+    try {
+        return realpathSync(candidate);
+    }
+    catch {
+        return candidate;
+    }
+}
+/**
+ * Parses a timeout env var into a positive-integer ms, warning once (and
+ * falling back to the client default) when the value is not a positive integer.
+ */
+function timeoutFromEnv(raw, varName) {
+    const parsed = parseTimeoutMs(raw);
+    if (parsed.invalid) {
+        log('warn', `${varName} must be a positive integer of milliseconds; ignoring "${raw}".`);
+    }
+    return parsed.value;
+}
 export const DEFAULT_BASE_URL = 'https://api.labelgrid.com/api/public';
 /** The exact sentence a user must set in LABELGRID_FULL_WRITES_ACK to arm full writes. */
 export const FULL_WRITES_ACK = 'I accept responsibility for AI-driven distribution actions';
@@ -57,6 +100,9 @@ function isTruthy(value) {
 }
 export function loadConfig(env) {
     const baseUrl = env.LABELGRID_API_URL?.trim() || DEFAULT_BASE_URL;
+    const timeoutMs = timeoutFromEnv(env.LABELGRID_TIMEOUT_MS, 'LABELGRID_TIMEOUT_MS');
+    const rawTimeoutMs = timeoutFromEnv(env.LABELGRID_TRANSFER_TIMEOUT_MS, 'LABELGRID_TRANSFER_TIMEOUT_MS');
+    const downloadDir = resolveDownloadDir(env);
     const token = env.LABELGRID_API_TOKEN?.trim();
     if (!token) {
         // No token: start in setup mode instead of failing. The server registers
@@ -69,6 +115,9 @@ export function loadConfig(env) {
             writes: false,
             fullWrites: false,
             toolsets: null,
+            timeoutMs,
+            rawTimeoutMs,
+            downloadDir,
         };
     }
     const readOnly = isTruthy(env.LABELGRID_READ_ONLY);
@@ -110,5 +159,15 @@ export function loadConfig(env) {
             toolsets.add(name);
         }
     }
-    return { baseUrl, token, setupMode: false, writes, fullWrites, toolsets };
+    return {
+        baseUrl,
+        token,
+        setupMode: false,
+        writes,
+        fullWrites,
+        toolsets,
+        timeoutMs,
+        rawTimeoutMs,
+        downloadDir,
+    };
 }

package/dist/coverage.js

@@ -29,6 +29,7 @@ export const COVERAGE = {
     'GET /territories': 'list_reference_data',
     // insights
     'GET /analytics/summary': 'get_analytics',
+    'GET /analytics/availability': 'get_analytics_availability',
     // catalog reads
     'GET /labels': 'search_catalog',
     'GET /labels/{label}': 'get_catalog_item',
@@ -146,5 +147,6 @@ export const EXCLUDED = {
 };
 export const PENDING_DOCS = {
     'GET /account': 'get_account',
+    'GET /analytics/availability': 'get_analytics_availability',
     'GET /tracks/{track}/files/{assetType}/download-url': 'get_asset',
 };

package/dist/index.js

@@ -32,6 +32,8 @@ async function main() {
         baseUrl: config.baseUrl,
         token: config.token ?? '',
         version: VERSION,
+        timeoutMs: config.timeoutMs,
+        rawTimeoutMs: config.rawTimeoutMs,
     });
     if (config.setupMode) {
         const server = buildServer(config, client, allTools());

package/dist/tools/catalog.js

@@ -21,7 +21,7 @@ const idArg = z.number().int().positive().describe('The entity id.');
 const responseFormat = z
     .enum(['concise', 'detailed'])
     .optional()
-    .describe("'concise' (default) keeps only the high-signal fields (ids always kept); 'detailed' returns the verbatim API response.");
+    .describe("'concise' (default) keeps high-signal fields (ids always kept); 'detailed' returns the verbatim API response.");
 /** A permissive body of API fields, forwarded verbatim to the endpoint. */
 function fieldsBody(desc) {
     return z.record(z.string(), z.unknown()).describe(desc);
@@ -32,7 +32,7 @@ const idempotencyKey = z
     .min(8)
     .max(128)
     .optional()
-    .describe('Honored for release and track only: the server deduplicates by this key for 24h — reuse the SAME key when retrying an unobserved call. Ignored for other entities.');
+    .describe('Release and track only (ignored for other entities): the server deduplicates by this key for 24h — reuse the SAME key when retrying an unobserved call.');
 /** Rejects a path that is not an existing regular file, before any HTTP call. */
 function fileError(p) {
     let isFile = false;
@@ -54,13 +54,10 @@ const searchCatalog = {
     toolset: 'catalog',
     gate: 'read',
     title: 'Search the catalog',
-    description: `List catalog entities of one kind, paginated. Pick the kind with \`entity\`: label, artist, writer, publisher, release, or track. \`filters\` takes the endpoint’s own filter names, passed through verbatim — ${entityDoc((s) => s.filtersDoc)} Use get_catalog_item for one entity's full detail. response_format:'detailed' returns the verbatim API response.`,
+    description: `List catalog entities of one kind, paginated. \`filters\` takes the endpoint’s own filter names, passed through verbatim — ${entityDoc((s) => s.filtersDoc)} Use get_catalog_item for full detail.`,
     inputShape: {
         entity: entityArg,
-        filters: z
-            .record(z.string(), z.unknown())
-            .optional()
-            .describe('Filter names → values, passed through verbatim.'),
+        filters: z.record(z.string(), z.unknown()).optional().describe('Filter names → values.'),
         page: z.number().int().positive().optional().describe('1-based page number.'),
         per_page: z.number().int().positive().optional().describe('Items per page.'),
         response_format: responseFormat,
@@ -81,8 +78,7 @@ const getCatalogItem = {
     toolset: 'catalog',
     gate: 'read',
     title: 'Get a catalog item',
-    description: 'Retrieve one catalog entity by id, with its full detail — a label’s settings, an artist’s identifiers and links, a writer’s PRO/IPI, a release’s metadata and track listing, a track’s contributors and royalty splits. ' +
-        "Pick the kind with `entity`: label, artist, writer, publisher, release, or track. response_format:'detailed' returns the verbatim API response.",
+    description: 'Retrieve one catalog entity by id, with full detail (e.g. a release’s metadata and track listing, a track’s contributors and royalty splits, a writer’s PRO/IPI).',
     inputShape: {
         entity: entityArg,
         id: idArg,
@@ -100,7 +96,7 @@ const createCatalogItem = {
     toolset: 'catalog',
     gate: 'safe_write',
     title: 'Create a catalog item',
-    description: `Create a catalog entity. Pick the kind with \`entity\` and pass its attributes in \`fields\` — the API owns all validation. Required and common fields per entity: ${entityDoc((s) => s.fieldsDoc)} A release is created in DRAFT state — add tracks, then run the release checks before distributing. \`idempotency_key\` is honored for release and track only.`,
+    description: `Create a catalog entity: pass its attributes in \`fields\` — the API owns all validation. Required and common fields per entity: ${entityDoc((s) => s.fieldsDoc)} A release is created in DRAFT state — add tracks, then run the release checks before distributing.`,
     inputShape: {
         entity: entityArg,
         fields: fieldsBody('The entity attributes, forwarded verbatim.'),
@@ -126,8 +122,8 @@ const updateCatalogItem = {
     toolset: 'catalog',
     gate: 'safe_write',
     title: 'Update a catalog item',
-    description: 'Update a catalog entity. Pick the kind with `entity`, supply only the fields you want to change in `fields` (same field sets as create_catalog_item). ' +
-        'For releases: once submitted or distributed, some fields are locked — changing one returns a 403 with code RELEASE_LOCKED_FIELDS naming exactly which fields cannot change. Track fields lock the same way once the parent release is submitted or distributed.',
+    description: 'Update a catalog entity: supply only the fields to change in `fields` (same field sets as create_catalog_item). ' +
+        'Once a release is submitted or distributed, some release and track fields are locked — changing one returns a 403 with code RELEASE_LOCKED_FIELDS naming exactly which fields cannot change.',
     inputShape: {
         entity: entityArg,
         id: idArg,
@@ -144,7 +140,7 @@ const deleteCatalogItem = {
     toolset: 'catalog',
     gate: 'safe_write',
     title: 'Delete a catalog item',
-    description: `Delete a catalog entity by id. The API refuses deletes that would orphan data — ${entityDoc((s) => s.deleteNote)}`,
+    description: `Delete a catalog entity. The API refuses deletes that would orphan data — ${entityDoc((s) => s.deleteNote)}`,
     inputShape: { entity: entityArg, id: idArg },
     annotations: { destructiveHint: true },
     handler: (args, { client }) => {
@@ -163,13 +159,13 @@ const uploadImage = {
     toolset: 'catalog',
     gate: 'safe_write',
     title: 'Upload a catalog image',
-    description: 'Upload a label image or an artist photo from a local file. `target`: label_logo, label_logo_dark (a dark-mode variant), label_background, or artist_photo. `id` is the label id for label_* and the artist id for artist_photo. `file_path` must be a local image file.',
+    description: 'Upload a label image (logo, dark-mode logo, or background) or an artist photo from a local image file, per `target`.',
     inputShape: {
         target: z
             .enum(['label_logo', 'label_logo_dark', 'label_background', 'artist_photo'])
             .describe('Which image asset to upload.'),
         id: z.number().int().positive().describe('The label id (label_*) or artist id (artist_photo).'),
-        file_path: z.string().describe('Local path to the image file to upload.'),
+        file_path: z.string().describe('Local path to the image file.'),
     },
     annotations: {},
     handler: async (args, { client }) => {
@@ -204,11 +200,11 @@ const getAsset = {
     toolset: 'catalog',
     gate: 'read',
     title: 'Get an asset',
-    description: 'Read a track or release asset. Valid selector matrices: ' +
-        "(1) mode='info', parent='track', asset stereo|dolby|lyrics — file metadata (not the bytes) incl. processing state. " +
-        "(2) mode='info', parent='release', asset square|tall — animated cover (motion artwork) video metadata incl. processing state. " +
-        "(3) mode='download_url', parent='track', asset audio_16|audio_24|audio_32 (WAV master at that bit depth) or audio_preview_full|audio_preview_clip (generated MP3 preview) — returns { download_url, expires_in }: a signed URL that expires roughly 10 minutes after issue; fetch it directly — do not send your API token to it. " +
-        'Any other combination has no endpoint and returns a structured error. mode defaults to info.',
+    description: 'Read a track or release asset. Valid combinations: ' +
+        "(1) mode='info' + parent='track' + asset stereo|dolby|lyrics — file metadata (not the bytes) incl. processing state. " +
+        "(2) mode='info' + parent='release' + asset square|tall — motion-artwork (animated cover) video metadata. " +
+        "(3) mode='download_url' + parent='track' + asset audio_16|audio_24|audio_32 (WAV master) or audio_preview_full|audio_preview_clip (MP3 preview) — returns { download_url, expires_in }, a signed URL that expires roughly 10 minutes after issue; fetch it directly — do not send your API token to it. " +
+        'Any other combination returns a structured error.',
     inputShape: {
         parent: z.enum(['track', 'release']).describe('Whose asset.'),
         id: z.number().int().positive().describe('The track id or release id, per `parent`.'),

package/dist/tools/distribution.js

@@ -38,7 +38,7 @@ const idempotencyKey = z
     .min(8)
     .max(128)
     .optional()
-    .describe('The server deduplicates by this key for 24h — reuse the SAME key when retrying a call whose outcome you did not observe.');
+    .describe('Deduplicated by the server for 24h — reuse the SAME key when retrying a call whose outcome you did not observe.');
 /** Optional license metadata shared by the license upload/update actions. */
 const licenseMeta = {
     license_id: z.string().optional().describe('The license/clearance reference number, if any.'),
@@ -71,10 +71,10 @@ const uploadAsset = {
     gate: 'full_write',
     title: 'Upload a release/track asset',
     description: 'Upload a finalized track or release asset from a local file. `id` is the track id for track_* targets, the release id for release_*. ' +
-        '`track_stereo` (stereo audio, WAV/FLAC/AIFF), `track_dolby` (Dolby Atmos, WAV) and `track_lyrics` (LRC) upload directly to storage and process asynchronously — check state with get_asset (mode info). ' +
-        "`release_cover_art` uploads or replaces the release's static cover art image. " +
-        '`release_motion_square` / `release_motion_tall` upload the animated cover (motion artwork) video — square or tall/portrait — also processed asynchronously. ' +
-        'ALL of these become immutable once the release is distributed — upload the final files before distributing.',
+        '`track_stereo` (WAV/FLAC/AIFF), `track_dolby` (Dolby Atmos WAV) and `track_lyrics` (LRC) process asynchronously — check state with get_asset (mode info). ' +
+        '`release_cover_art` uploads or replaces the static cover art image. ' +
+        '`release_motion_square` / `release_motion_tall` upload the square or tall animated cover (motion artwork) video, also asynchronous. ' +
+        'All assets become immutable once the release is distributed — upload final files first.',
     inputShape: {
         target: z
             .enum([
@@ -126,7 +126,7 @@ const deleteAsset = {
     toolset: 'distribution',
     gate: 'full_write',
     title: 'Delete a release/track asset',
-    description: 'Delete a track or release asset file. track_stereo|track_dolby|track_lyrics delete a track asset; release_motion_square|release_motion_tall delete an animated cover (motion artwork) video. Allowed only while the parent release is still an editable draft; the API refuses once the release is locked or distributed. Cover art has no delete endpoint and cannot be deleted here.',
+    description: 'Delete a track asset (track_*) or an animated cover / motion artwork video (release_motion_*). Allowed only while the parent release is an editable draft; refused once locked or distributed. Cover art cannot be deleted.',
     inputShape: {
         target: z
             .enum([
@@ -157,11 +157,11 @@ const manageTrackLicense = {
     toolset: 'distribution',
     gate: 'full_write',
     title: 'Manage a track license',
-    description: 'Manage the license documents attached to a track (for a cover or a cleared sample). Pick ONE action with `action`: ' +
-        "`upload` attaches a new license — `file_path` required, `type` ('cover' or 'sample') selects the kind; optionally record license_id, license_provider, license_provider_name, original_track_link. " +
-        '`update` replaces the file and/or metadata of an existing license — `track_license_id` (from list_track_licenses) and `file_path` required. ' +
-        '`delete` permanently deletes a license and its file — `track_license_id` required; cannot be undone. ' +
-        'Licenses are immutability-governed once the release is live.',
+    description: 'Manage license documents on a track (cover or cleared sample). ' +
+        '`upload` attaches a new license — `file_path` required, `type` selects cover/sample; optional metadata fields. ' +
+        '`update` replaces the file and/or metadata — `track_license_id` (from list_track_licenses) and `file_path` required. ' +
+        '`delete` permanently removes a license and its file — `track_license_id` required; cannot be undone. ' +
+        'Immutability-governed once the release is live.',
     inputShape: {
         action: z.enum(['upload', 'update', 'delete']).describe('Which license action.'),
         track_id: z.number().int().positive().describe('The track id.'),
@@ -216,7 +216,7 @@ const distributeRelease = {
     toolset: 'distribution',
     gate: 'full_write',
     title: 'Distribute a release',
-    description: 'Submit a release for distribution to the stores/outlets — the FINAL, consequential action that sends the release out; run_release_checks (check validate) should pass first. The server enforces your account’s weekly submission limit and returns a structured error if exceeded. Pass idempotency_key and reuse the SAME value when retrying an unobserved call; without a key each call is a new submission.',
+    description: 'Submit a release to the stores/outlets — the FINAL action that sends it out; run_release_checks (check validate) should pass first. The server enforces the account’s weekly submission limit. Reuse the SAME idempotency_key when retrying an unobserved call; without one each call is a new submission.',
     inputShape: { release_id: releaseId, idempotency_key: idempotencyKey },
     annotations: { destructiveHint: true },
     handler: (args, { client }) => client.post(`/releases/${args.release_id}/distribute`, undefined, {
@@ -229,7 +229,7 @@ const takedownRelease = {
     toolset: 'distribution',
     gate: 'full_write',
     title: 'Take down a release',
-    description: 'Take a release down from ALL outlets/stores — a final, consequential action that removes it everywhere it was delivered. Re-distribution afterward is a fresh submission.',
+    description: 'Take a release down from ALL outlets/stores — a final action that removes it everywhere it was delivered. Re-distribution is a fresh submission.',
     inputShape: { release_id: releaseId },
     annotations: { destructiveHint: true },
     handler: (args, { client }) => client.post(`/releases/${args.release_id}/takedown-all`),
@@ -239,7 +239,7 @@ const confirmReview = {
     toolset: 'distribution',
     gate: 'full_write',
     title: 'Confirm a held release into review',
-    description: 'Confirm a release that Preflight QC placed on hold, moving it into distribution review. Use after you have reviewed the quality report and accept the release as-is. Safe to repeat.',
+    description: 'Confirm a release Preflight QC placed on hold, moving it into distribution review, after reviewing the quality report and accepting the release as-is. Safe to repeat.',
     inputShape: { release_id: releaseId },
     annotations: { destructiveHint: true, idempotentHint: true },
     handler: (args, { client }) => client.post(`/releases/${args.release_id}/confirm-review`),
@@ -249,7 +249,7 @@ const enableBeatport = {
     toolset: 'distribution',
     gate: 'full_write',
     title: 'Request Beatport onboarding for a label',
-    description: 'Request Beatport onboarding for a label. A one-time action that cannot be un-requested, so confirm the label is correct first.',
+    description: 'Request Beatport onboarding for a label. One-time and cannot be un-requested — confirm the label is correct first.',
     inputShape: { label_id: z.number().int().positive().describe('The label id.') },
     annotations: { destructiveHint: true },
     handler: (args, { client }) => client.post(`/labels/${args.label_id}/enable-beatport`),

package/dist/tools/finance.js

@@ -8,19 +8,92 @@
  * shared client's JSON path would corrupt binary PDFs), with the same auth
  * headers the client sends.
  */
-import { realpathSync, statSync, writeFileSync } from 'node:fs';
-import { dirname, isAbsolute } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { copyFileSync, createWriteStream, constants as fsConstants, linkSync, openSync, realpathSync, statSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { basename, dirname, isAbsolute, join, relative } from 'node:path';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
 import { z } from 'zod';
 import { applyProjection } from '../projection.js';
-import { VERSION } from '../version.js';
 const INLINE_CSV_LIMIT = 100 * 1024;
+/**
+ * Hard ceiling on the CSV body read into memory when NO save_to_path is given.
+ * A larger export must be written to disk (save_to_path streams it); reading an
+ * unbounded body inline is exactly the memory blow-up this bound prevents.
+ */
+const MAX_INLINE_DOWNLOAD_BYTES = 10 * 1024 * 1024;
+/**
+ * Reads a text body with a byte ceiling enforced up front (Content-Length) AND
+ * mid-stream: it aborts the moment the running byte count crosses `max`, so an
+ * oversized body is never fully buffered. Returns the decoded text or a
+ * RESPONSE_TOO_LARGE error naming save_to_path as the way to handle a big export.
+ */
+async function readBoundedText(res, max) {
+    const tooLarge = {
+        code: 'RESPONSE_TOO_LARGE',
+        message: `The export exceeds the ${max}-byte inline limit. Pass save_to_path to stream it to a file instead.`,
+        status: res.status,
+    };
+    const declared = Number.parseInt(res.headers.get('Content-Length') ?? '', 10);
+    if (!Number.isNaN(declared) && declared > max) {
+        // Cancel the still-live body so the connection is released rather than held
+        // open (the mid-stream path below cancels via the reader).
+        await res.body?.cancel().catch(() => { });
+        return tooLarge;
+    }
+    if (!res.body) {
+        const text = await res.text();
+        return Buffer.byteLength(text) > max ? tooLarge : text;
+    }
+    const reader = res.body.getReader();
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        if (value) {
+            total += value.byteLength;
+            if (total > max) {
+                try {
+                    await reader.cancel();
+                }
+                catch {
+                    // best-effort — the size bound is what matters
+                }
+                return tooLarge;
+            }
+            chunks.push(value);
+        }
+    }
+    const merged = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        merged.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return new TextDecoder('utf-8').decode(merged);
+}
+/** True when `child` is `root` itself or nested beneath it (after realpath). */
+function isWithin(root, child) {
+    const rel = relative(root, child);
+    return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+}
 /**
  * Validates that save_to_path is absolute and its parent resolves (via
  * realpathSync, so a dangling/symlinked parent is rejected) to an existing real
- * directory. Writing itself is exclusive (see writeNewFile), so this never
- * overwrites an existing file.
+ * directory, AND — when an `allowedRoot` is given — that the resolved parent is
+ * inside that allow-list root, so a tool can only write under a sanctioned
+ * directory even if an injected path points elsewhere. The parent is resolved
+ * to its real target BEFORE the prefix check (the file itself does not exist
+ * yet), so a symlinked parent cannot escape the root. On success it RETURNS the
+ * canonical write path — `join(realpath(parent), basename)` — so the caller
+ * writes to the resolved location, not the caller-supplied path whose parent
+ * symlink could be swapped between this check and the write (a TOCTOU escape).
+ * Writing itself is exclusive (see writeNewFile), so this never overwrites an
+ * existing file.
  */
-function validateSavePath(p) {
+function validateSavePath(p, allowedRoot) {
     if (!isAbsolute(p)) {
         return {
             code: 'INVALID_PATH',
@@ -54,7 +127,25 @@ function validateSavePath(p) {
             status: 0,
         };
     }
-    return null;
+    if (allowedRoot !== undefined && !isWithin(allowedRoot, realDir)) {
+        return {
+            code: 'DOWNLOAD_DIR_NOT_ALLOWED',
+            message: `save_to_path must be inside the allowed download directory (${allowedRoot}). Set LABELGRID_DOWNLOAD_DIR to change it.`,
+            status: 0,
+        };
+    }
+    return { canonicalPath: join(realDir, basename(p)) };
+}
+/** Filesystem errors that mean "hardlinks are not supported here". */
+const HARDLINK_UNSUPPORTED = new Set(['EPERM', 'ENOTSUP', 'EOPNOTSUPP', 'EXDEV', 'ENOSYS']);
+/** Best-effort removal of a temp file — a missing file is not an error. */
+function unlinkSafe(p) {
+    try {
+        unlinkSync(p);
+    }
+    catch {
+        // already gone / never created — nothing to clean up
+    }
 }
 /**
  * Writes a file with exclusive creation ('wx'): an existing path is NEVER
@@ -81,65 +172,120 @@ function writeNewFile(path, data) {
         };
     }
 }
-/** Maps an error HTTP status from a raw download into a structured code. */
-function statusToCode(status) {
-    if (status === 401)
-        return 'TOKEN_INVALID';
-    if (status === 403)
-        return 'FORBIDDEN';
-    if (status === 404)
-        return 'NOT_FOUND';
-    if (status >= 500)
-        return 'SERVER_ERROR';
-    return 'ERROR';
+/**
+ * Streams a web response body to a NEW file, never overwriting an existing one
+ * and never leaving a partial file at the destination. The body is streamed to
+ * a temp sibling in the SAME directory (`<path>.partial-<pid>`, created 'wx'),
+ * then atomically hard-linked into place — the link is both atomic AND exclusive
+ * (EEXIST → FILE_EXISTS), so a transfer that fails mid-stream leaves NO file at
+ * `path` and NO temp sibling behind. On a filesystem without hardlinks
+ * (EPERM/ENOTSUP/EXDEV/…) it falls back to an exclusive copy (COPYFILE_EXCL).
+ * Never buffers the whole body in memory.
+ */
+async function streamNewFile(path, body) {
+    if (body === null) {
+        const err = writeNewFile(path, Buffer.alloc(0));
+        return err ?? { bytes: 0 };
+    }
+    const source = Readable.fromWeb(body);
+    const tmpResult = await streamToTempSibling(path, source);
+    if ('code' in tmpResult)
+        return tmpResult;
+    return finalizeNewFile(tmpResult.tmp, path);
 }
-/** Authenticated raw GET for file downloads; returns the Response or an error. */
-async function authedGet(ctx, path) {
-    const base = ctx.config.baseUrl.replace(/\/+$/, '');
-    let res;
+/**
+ * Streams `source` into a temp sibling of `finalPath`, created exclusively
+ * ('wx'). A collision with a stale temp (a dead process) is retried once with a
+ * random suffix. On a mid-stream failure the partial temp is removed. Returns
+ * the temp path, or a structured error.
+ */
+async function streamToTempSibling(finalPath, source) {
+    const candidates = [
+        `${finalPath}.partial-${process.pid}`,
+        `${finalPath}.partial-${process.pid}-${randomBytes(6).toString('hex')}`,
+    ];
+    // Secure the temp fd BEFORE attaching the pipeline: pipeline() destroys its
+    // streams on failure, so an open-time EEXIST (stale temp) must be resolved
+    // without touching the source, or the retry would pipe a destroyed body.
+    let tmp;
+    let fd;
+    let lastErr;
+    for (const candidate of candidates) {
+        try {
+            fd = openSync(candidate, 'wx', 0o600);
+            tmp = candidate;
+            break;
+        }
+        catch (err) {
+            lastErr = err;
+            if (err.code !== 'EEXIST')
+                return writeFailed(finalPath, err);
+        }
+    }
+    if (tmp === undefined || fd === undefined)
+        return writeFailed(finalPath, lastErr);
+    const ws = createWriteStream(tmp, { fd }); // autoClose closes the fd either way
     try {
-        res = await ctx.client.raw(`${base}${path}`, {
-            method: 'GET',
-            headers: {
-                Authorization: `Bearer ${ctx.config.token}`,
-                Accept: 'application/json',
-                'User-Agent': `labelgrid-mcp/${VERSION}`,
-            },
-        });
+        await pipeline(source, ws);
+        return { tmp };
     }
     catch (err) {
-        return {
-            ok: false,
-            error: {
-                code: 'NETWORK_ERROR',
-                message: err instanceof Error ? err.message : 'Network request failed.',
-                status: 0,
-            },
-        };
+        unlinkSafe(tmp); // we created it, then the transfer failed — drop the partial
+        return writeFailed(finalPath, err);
     }
-    if (!res.ok) {
-        let message = `Request failed with status ${res.status}.`;
-        try {
-            const text = await res.text();
-            if (text) {
-                try {
-                    const body = JSON.parse(text);
-                    if (typeof body.message === 'string')
-                        message = body.message;
-                    else if (typeof body.error === 'string')
-                        message = body.error;
-                }
-                catch {
-                    message = text;
-                }
+}
+/**
+ * Moves a finished temp file into `path` exclusively: a hard link (atomic +
+ * exclusive) with an exclusive-copy fallback where hardlinks are unavailable.
+ * The temp is always removed. Returns the byte count or a structured error.
+ */
+function finalizeNewFile(tmp, path) {
+    try {
+        linkSync(tmp, path);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'EEXIST') {
+            unlinkSafe(tmp);
+            return fileExists(path);
+        }
+        if (code !== undefined && HARDLINK_UNSUPPORTED.has(code)) {
+            // Non-atomic fallback for filesystems without hardlinks: a reader can see
+            // the destination mid-copy (accepted for these rare filesystems), but an
+            // interrupted copy must not LEAVE a partial destination — COPYFILE_EXCL
+            // proved it did not pre-exist, so removing it on failure is safe.
+            try {
+                copyFileSync(tmp, path, fsConstants.COPYFILE_EXCL);
+            }
+            catch (copyErr) {
+                unlinkSafe(tmp);
+                if (copyErr.code === 'EEXIST')
+                    return fileExists(path);
+                unlinkSafe(path);
+                return writeFailed(path, copyErr);
             }
         }
-        catch {
-            // keep the default message
+        else {
+            unlinkSafe(tmp);
+            return writeFailed(path, err);
         }
-        return { ok: false, error: { code: statusToCode(res.status), message, status: res.status } };
     }
-    return { ok: true, res };
+    unlinkSafe(tmp);
+    return { bytes: statSync(path).size };
+}
+function fileExists(path) {
+    return {
+        code: 'FILE_EXISTS',
+        message: `A file already exists at ${path}. This tool never overwrites — choose a new path.`,
+        status: 0,
+    };
+}
+function writeFailed(path, err) {
+    return {
+        code: 'WRITE_FAILED',
+        message: `Could not write to ${path}: ${err instanceof Error ? err.message : 'unknown error'}.`,
+        status: 0,
+    };
 }
 const queryFinancials = {
     name: 'query_financials',
@@ -240,7 +386,7 @@ const downloadStatement = {
             .describe('Absolute path (existing parent dir) to write the file to. Optional for csv (otherwise returned inline); required for invoice_pdf.'),
     },
     annotations: { readOnlyHint: true },
-    handler: async (args, ctx) => {
+    handler: async (args, { client, config }) => {
         const invoice = args.invoice_number;
         const savePath = args.save_to_path;
         if (args.format === 'invoice_pdf') {
@@ -262,47 +408,52 @@ const downloadStatement = {
                     },
                 };
             }
-            const err = validateSavePath(savePath);
-            if (err)
-                return { error: err };
-            const result = await authedGet(ctx, `/statements/${encodeURIComponent(invoice)}/invoice`);
+            const validated = validateSavePath(savePath, config.downloadDir);
+            if ('code' in validated)
+                return { error: validated };
+            const canonicalPath = validated.canonicalPath;
+            const result = await client.getRaw(`/statements/${encodeURIComponent(invoice)}/invoice`);
             if (!result.ok)
                 return { error: result.error };
-            const bytes = Buffer.from(await result.res.arrayBuffer());
-            const writeErr = writeNewFile(savePath, bytes);
-            if (writeErr)
-                return { error: writeErr };
-            return { data: { saved_to: savePath, bytes: bytes.length } };
+            const written = await streamNewFile(canonicalPath, result.res.body);
+            if ('code' in written)
+                return { error: written };
+            return { data: { saved_to: canonicalPath, bytes: written.bytes } };
         }
         // format === 'csv'
+        let canonicalPath;
         if (savePath !== undefined) {
-            const err = validateSavePath(savePath);
-            if (err)
-                return { error: err };
+            const validated = validateSavePath(savePath, config.downloadDir);
+            if ('code' in validated)
+                return { error: validated };
+            canonicalPath = validated.canonicalPath;
         }
         let path;
+        let query;
         if (invoice !== undefined && invoice !== '') {
             path = `/statements/${encodeURIComponent(invoice)}/csv`;
         }
         else {
-            const parts = [];
-            if (args.start_date !== undefined)
-                parts.push(`start_date=${encodeURIComponent(String(args.start_date))}`);
-            if (args.end_date !== undefined)
-                parts.push(`end_date=${encodeURIComponent(String(args.end_date))}`);
-            path = `/statements/export/csv${parts.length > 0 ? `?${parts.join('&')}` : ''}`;
+            // Let the core client serialize the range (its buildQuery), not a
+            // hand-rolled query string.
+            path = '/statements/export/csv';
+            query = { start_date: args.start_date, end_date: args.end_date };
         }
-        const result = await authedGet(ctx, path);
+        const result = await client.getRaw(path, query);
         if (!result.ok)
             return { error: result.error };
-        const text = await result.res.text();
-        const totalBytes = Buffer.byteLength(text);
-        if (savePath !== undefined) {
-            const writeErr = writeNewFile(savePath, text);
-            if (writeErr)
-                return { error: writeErr };
-            return { data: { saved_to: savePath, bytes: totalBytes } };
+        if (canonicalPath !== undefined) {
+            // Stream the export straight to disk — never buffer the whole CSV.
+            const written = await streamNewFile(canonicalPath, result.res.body);
+            if ('code' in written)
+                return { error: written };
+            return { data: { saved_to: canonicalPath, bytes: written.bytes } };
         }
+        // Inline: read with the byte ceiling enforced (Content-Length + mid-stream).
+        const text = await readBoundedText(result.res, MAX_INLINE_DOWNLOAD_BYTES);
+        if (typeof text !== 'string')
+            return { error: text };
+        const totalBytes = Buffer.byteLength(text);
         const truncated = text.length > INLINE_CSV_LIMIT;
         const content = truncated ? text.slice(0, INLINE_CSV_LIMIT) : text;
         return { data: { content, truncated, bytes: totalBytes } };

package/dist/tools/insights.d.ts

@@ -1,7 +1,7 @@
 /**
- * Insights toolset: the streaming analytics summary and the consolidated
- * artificial-streaming query (early-warning flags, reported records, and the
- * fee breakdown). All read-only.
+ * Insights toolset: the streaming analytics summary, the availability-discovery
+ * endpoint, and the consolidated artificial-streaming query (early-warning
+ * flags, reported records, and the fee breakdown). All read-only.
  */
 import type { ToolDef } from './types.js';
 export declare const insightsTools: ToolDef[];

package/dist/tools/insights.js

@@ -1,11 +1,14 @@
 /**
- * Insights toolset: the streaming analytics summary and the consolidated
- * artificial-streaming query (early-warning flags, reported records, and the
- * fee breakdown). All read-only.
+ * Insights toolset: the streaming analytics summary, the availability-discovery
+ * endpoint, and the consolidated artificial-streaming query (early-warning
+ * flags, reported records, and the fee breakdown). All read-only.
  */
 import { z } from 'zod';
 import { applyProjection } from '../projection.js';
-/** The 15 metric sections the summary endpoint can return. */
+/**
+ * The 37 metric sections the summary endpoint can return, in the server's
+ * canonical order.
+ */
 const METRICS = [
     'streams',
     'listeners',
@@ -22,24 +25,62 @@ const METRICS = [
     'streams-by-gender',
     'streams-by-age',
     'shares-by-country',
+    'library-adds',
+    'shazams',
+    'playlist-adds',
+    'source-split-detailed',
+    'discovery-rate',
+    'repeat-rate',
+    'listener-plan-mix',
+    'listeners-by-age',
+    'listeners-by-gender',
+    'listeners-by-region',
+    'apple-streams-by-city',
+    'apple-streams-by-storefront',
+    'apple-discovery-cohorts',
+    'avg-listen-time',
+    'shuffle-rate',
+    'promoted-rate',
+    'device-breakdown',
+    'os-split',
+    'audio-format-split',
+    'hour-of-day',
+    'shazams-by-city',
+    'shazams-by-state',
+];
+/** The maximum number of section keys the server accepts per summary request. */
+const MAX_METRICS_PER_REQUEST = 12;
+/** The platform values `filter[platform]` accepts (APPLE_MUSIC aliases ITUNES). */
+const PLATFORMS = [
+    'SPOTIFY',
+    'ITUNES',
+    'APPLE_MUSIC',
+    'DEEZER',
+    'BOOMPLAY',
+    'AWA',
+    'AUDIOMACK',
+    'KUGOU',
+    'KUWO',
+    'QQMUSIC',
 ];
 const getAnalytics = {
     name: 'get_analytics',
     toolset: 'insights',
     gate: 'read',
     title: 'Get streaming analytics',
-    description: 'Retrieve a streaming analytics summary for your catalog in a single call. `start_date` and `end_date` (both YYYY-MM-DD) are required and the window is capped at 30 days by the server. ' +
-        'Optionally narrow the result by `platform` (SPOTIFY, ITUNES, APPLE_MUSIC), `release_id`, `isrc`, `upc`, or `artist_names`. ' +
-        'By default all 15 metric sections are returned; pass `metrics` (see its enum) to request only a subset. ' +
-        'Rate-limited (about 60 requests per minute); a 429 response carries retry_after_seconds.',
+    description: 'Streaming analytics summary. Window capped at 400 days; `metrics` takes 1-12 section keys per request (split larger selections — responses are cached). ' +
+        'KUGOU/KUWO/QQMUSIC report weekly: one point per week carrying the whole week — never average it per day. `meta` carries `platform_cadence`, `section_granularity`, `sections_as_of` and `sections_complete_through` (later dates still filling in). ' +
+        'Call get_analytics_availability first for section-per-platform support. ' +
+        'Rate-limited ~60/min; windows over 90 days draw a separate lower ~30/min budget — prefer shorter windows for polling. A 429 carries retry_after_seconds.',
     inputShape: {
         start_date: z.string().describe('Start of the reporting window, YYYY-MM-DD.'),
-        end_date: z.string().describe('End of the reporting window, YYYY-MM-DD (max 30-day span).'),
+        end_date: z.string().describe('End of the reporting window, YYYY-MM-DD (max 400-day span).'),
         metrics: z
             .array(z.enum(METRICS))
-            .optional()
-            .describe('Subset of metric sections to return; omit for all 15.'),
-        platform: z.enum(['SPOTIFY', 'ITUNES', 'APPLE_MUSIC']).optional(),
+            .min(1)
+            .max(MAX_METRICS_PER_REQUEST)
+            .describe('Section keys to return, 1-12 per request.'),
+        platform: z.enum(PLATFORMS).optional(),
         release_id: z.number().int().positive().optional(),
         isrc: z.string().optional(),
         upc: z.string().optional(),
@@ -61,16 +102,27 @@ const getAnalytics = {
         limit: args.limit,
     }),
 };
+const getAnalyticsAvailability = {
+    name: 'get_analytics_availability',
+    toolset: 'insights',
+    gate: 'read',
+    title: 'Get analytics availability',
+    description: 'Static `availability` matrix (per section, per platform) plus `platform_cadence` (daily|weekly per platform). Account- and date-independent: fetch once, reuse. ' +
+        'Read it before get_analytics so an unreported section is treated as unavailable, not an empty chart.',
+    inputShape: {},
+    annotations: { readOnlyHint: true },
+    handler: (_args, { client }) => client.get('/analytics/availability'),
+};
 const queryArtificialStreaming = {
     name: 'query_artificial_streaming',
     toolset: 'insights',
     gate: 'read',
     title: 'Query artificial-streaming data',
-    description: 'Query artificial-streaming (streaming-integrity) data for your catalog. Pick ONE view with `view`: ' +
-        '`flags` lists Stream Radar early-warning flags surfacing possible artificial-streaming activity so you can act early, paginated — `filters`: status, severity, dsp, isrc, release_id, detected_from/detected_to (YYYY-MM-DD). ' +
-        '`flag_detail` retrieves one flag by `flag_id` (required). Stream Radar is an optional add-on; without it the API returns a 403, surfaced verbatim. ' +
-        '`records` lists the artificial-streaming records reported for your catalog, cursor-paginated — the per-record detail behind any artificial-streaming fee; `filters`: dsp (spotify or apple), start_date/end_date, release_id, isrc. ' +
-        '`fee_breakdown` retrieves the per-release breakdown of an artificial-streaming fee for one billing period — `period` (required) is YYYY-MM. ' +
+    description: 'Artificial-streaming (streaming-integrity) reads. Pick ONE `view`: ' +
+        '`flags` — Stream Radar early-warning flags, paginated (`filters`: status, severity, dsp, isrc, release_id, detected_from/detected_to). Stream Radar is an optional add-on; without it the API returns a 403, surfaced verbatim. ' +
+        '`flag_detail` — one flag by `flag_id`. ' +
+        '`records` — reported artificial-streaming records, cursor-paginated; the detail behind any artificial-streaming fee (`filters`: dsp, start_date/end_date, release_id, isrc). ' +
+        '`fee_breakdown` — per-release fee breakdown for one `period` (YYYY-MM). ' +
         "response_format:'detailed' returns the verbatim API response.",
     inputShape: {
         view: z
@@ -136,4 +188,8 @@ const queryArtificialStreaming = {
         return applyProjection(result, 'query_artificial_streaming', args.response_format);
     },
 };
-export const insightsTools = [getAnalytics, queryArtificialStreaming];
+export const insightsTools = [
+    getAnalytics,
+    getAnalyticsAvailability,
+    queryArtificialStreaming,
+];

package/dist/tools/releases.js

@@ -20,9 +20,8 @@ const getReleaseReview = {
     gate: 'read',
     title: 'Get release review results',
     description: "Read a release's automated quality-check results. Pick ONE view with `view`: " +
-        '`issues` lists the review issues raised against the release — each carries a code (see list_reference_data type issue_definitions), severity, and whether it blocks distribution; use it to see what must be fixed before the release can go out. ' +
-        '`quality_report` retrieves the Preflight QC quality report — the customer-facing issues found by the automated checks, to review before confirming the release into distribution; Preflight QC is an optional add-on — without it the API returns a 403, surfaced verbatim. ' +
-        "response_format:'detailed' returns the verbatim API response.",
+        '`issues` lists the review issues raised against the release — each with a code (see list_reference_data type issue_definitions), severity, and whether it blocks distribution. ' +
+        '`quality_report` returns the Preflight QC quality report — customer-facing issues to review before confirming distribution; Preflight QC is an optional add-on — without it the API returns a 403, surfaced verbatim.',
     inputShape: {
         release_id: releaseId,
         view: z.enum(['issues', 'quality_report']).describe('Which review read.'),
@@ -41,8 +40,7 @@ const getDeliveryQueue = {
     toolset: 'releases',
     gate: 'read',
     title: 'Get the distribution queue',
-    description: 'List the distribution queue entries for your account, paginated — one entry per (release, outlet) delivery with its current status (e.g. pending review, processing, scheduled, complete, error) — where a release is in the delivery pipeline to each store. Filter by `release_id`, `outlet_id`, or `status`. ' +
-        "response_format:'detailed' returns the verbatim API response.",
+    description: "List your account's distribution queue, paginated — one entry per (release, outlet) delivery with its status (e.g. pending review, processing, scheduled, complete, error). Filter by `release_id`, `outlet_id`, or `status`.",
     inputShape: {
         release_id: z.number().int().positive().optional().describe('Filter to one release.'),
         outlet_id: z.number().int().positive().optional().describe('Filter to one outlet/store.'),
@@ -70,7 +68,7 @@ const getLandingConfig = {
     toolset: 'releases',
     gate: 'read',
     title: 'Get a release landing-page config',
-    description: 'Retrieve the smart-link landing-page configuration for a release: whether the links page is enabled, its style/mode, custom copy, the action list and any pre-order links. Pair with manage_release_links (action update_landing_config) to change it.',
+    description: "Retrieve a release's smart-link landing-page configuration: enabled state, style/mode, custom copy, action list, pre-order links. Change it via manage_release_links (action update_landing_config).",
     inputShape: { release_id: releaseId },
     annotations: { readOnlyHint: true },
     handler: (args, { client }) => client.get(`/releases/${args.release_id}/landing-config`),
@@ -80,7 +78,7 @@ const listTrackLicenses = {
     toolset: 'releases',
     gate: 'read',
     title: 'List track licenses',
-    description: 'List the licenses attached to a track (e.g. cover/mechanical or sample clearances), paginated. Pass `license_id` to retrieve one license by its id instead.',
+    description: "List a track's licenses (e.g. cover/mechanical or sample clearances), paginated. Pass `license_id` to retrieve one license instead.",
     inputShape: {
         track_id: z.number().int().positive().describe('The track id.'),
         license_id: z
@@ -109,8 +107,8 @@ const runReleaseChecks = {
     gate: 'safe_write',
     title: 'Run release checks',
     description: 'Run an automated check on a release. Pick ONE with `check`: ' +
-        '`validate` returns any problems that would block distribution, as a human-readable `errors` list and a machine-readable `errors_structured` list — it changes nothing and is safe to repeat; run it before distributing. ' +
-        '`refresh_quality_report` re-runs the Preflight QC checks and refreshes the quality report (read it with get_release_review view quality_report); the server applies an hourly refresh budget, so frequent calls may be rate-limited. Preflight QC is an optional add-on.',
+        '`validate` returns problems that would block distribution (human-readable `errors` + machine-readable `errors_structured`); it changes nothing and is safe to repeat — run it before distributing. ' +
+        '`refresh_quality_report` re-runs the Preflight QC checks (read the report with get_release_review view quality_report); an hourly refresh budget may rate-limit frequent calls. Preflight QC is an optional add-on.',
     inputShape: {
         release_id: releaseId,
         check: z.enum(['validate', 'refresh_quality_report']).describe('Which check to run.'),
@@ -126,8 +124,8 @@ const manageReleaseLinks = {
     gate: 'safe_write',
     title: 'Manage a release smart link',
     description: "Manage a release's smart-link landing page. Pick ONE action with `action`: " +
-        '`update_landing_config` replaces the landing-page configuration with `config` (required for this action) — `config.actions` uses the current (v2) action-list contract (one entry per call-to-action); other keys: links_page_enabled, config_mode, page_style, custom_cta_text, custom_description, pre_order_links. ' +
-        "`create_short_url` creates (or returns the existing) short URL for the release's smart-link landing page — safe to repeat.",
+        '`update_landing_config` replaces the configuration with `config` (required for this action) — `config.actions` uses the v2 action-list contract (one entry per call-to-action); other keys: links_page_enabled, config_mode, page_style, custom_cta_text, custom_description, pre_order_links. ' +
+        '`create_short_url` creates (or returns the existing) short URL for the landing page — safe to repeat.',
     inputShape: {
         release_id: releaseId,
         action: z.enum(['update_landing_config', 'create_short_url']).describe('Which action.'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@labelgrid/mcp",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "mcpName": "io.github.labelgrid/labelgrid-mcp",
   "description": "Official LabelGrid MCP server — connect your AI client to your LabelGrid account",
   "type": "module",
@@ -27,7 +27,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@labelgrid/core": "0.1.0",
+    "@labelgrid/core": "0.2.0",
     "@modelcontextprotocol/sdk": "^1.12.0",
     "zod": "^3.24.0"
   }

package/server.json

@@ -2,7 +2,7 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.labelgrid/labelgrid-mcp",
   "description": "Official LabelGrid MCP server — manage your music catalog, releases, analytics and distribution.",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "websiteUrl": "https://labelgrid.com",
   "repository": {
     "url": "https://github.com/labelgrid/labelgrid-mcp",
@@ -12,7 +12,7 @@
     {
       "registryType": "npm",
       "identifier": "@labelgrid/mcp",
-      "version": "0.3.1",
+      "version": "0.4.0",
       "transport": {
         "type": "stdio"
       },