@labelgrid/mcp 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -5,6 +5,37 @@ 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.7.0] - 2026-08-20
+
+### Added
+
+- `delete_catalog_item` accepts `replace_with` for writers and publishers. The
+  replacement receives every credit before the original is deleted. Other
+  entity types reject the parameter without sending a delete request.
+- `query_financials` concise responses include `credit_amount`, preserving
+  positive, zero and explicit null values from the API.
+
+### Changed
+
+- Writer and publisher deletion guidance now names all references that can
+  block deletion and documents the `REPLACEMENT_UNAVAILABLE` response.
+
+## [0.6.1] - 2026-08-05
+
+### Changed
+
+- `get_analytics` states how the summary aggregates: every section aggregates
+  over the resolved filter scope, so a `upc` filter returns release totals
+  rather than a row per track. Per-track output comes from the `track-*-daily`
+  sections (which need a `release_id`, `isrc` or `upc` scope) or from
+  `get_analytics_rankings`.
+- `get_analytics_rankings` is described as the per-entity breakdown of a scope
+  as well as a leaderboard — `type: 'tracks'` with a `upc` or `release_id`
+  filter ranks the tracks on that release.
+- Descriptions on the `metrics`, `view` and `type` parameters were removed where
+  they restated the parameter's own enum or its tool description. No parameter,
+  enum value or validation rule changed.
+
 ## [0.6.0] - 2026-08-05
 
 ### Added

package/README.md

@@ -129,7 +129,7 @@ tool definitions by `npm run gen-docs` — do not edit it by hand._
 | `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). 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: refused once the release is no longer an editable draft. |
+| `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 or artists, unless replace_with reassigns those credits. publisher: refused while still referenced by tracks or label default publishers, unless replace_with reassigns those credits. release: only a never-submitted draft can be deleted. track: refused once the release is no longer an editable draft. `replace_with` — writer and publisher only — is the id inheriting those credits; a 422 REPLACEMENT_UNAVAILABLE means nothing was deleted. |
 | `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 is refused. |
 
@@ -149,9 +149,9 @@ tool definitions by `npm run gen-docs` — do not edit it by hand._
 
 | Tool | Gate | Description |
 | --- | --- | --- |
-| `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. The `social-*` / `soundcloud-engagement` sections cover social and UGC usage instead of streaming: their `platform` is a UGC platform; a use, view and play are distinct quantities, never summed with each other or with streams; `ugc_platform` narrows them. Selecting any adds `meta.social_availability` (which UGC platforms report each signal) — the streaming matrix excludes them. The `track-*-daily` sections need a `release_id`, `isrc` or `upc` scope. `track-listeners-daily` sums per-entry daily counts: not distinct people, not summable across dates. 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` | read | Streaming analytics summary. Window capped at 400 days; `metrics` takes 1-12 section keys per request (split larger selections; responses cached). KUGOU/KUWO/QQMUSIC report weekly: one point carries the whole week — never average per day. `meta` carries `platform_cadence`, `section_granularity`, `sections_as_of` and `sections_complete_through` (later dates still filling in). See get_analytics_availability for per-platform support. Sections aggregate over the resolved filter scope: a `upc` filter gives release totals, not per-track rows. For those use `track-*-daily` (needs a `release_id`, `isrc` or `upc` scope) or get_analytics_rankings. `track-listeners-daily` sums per-entry daily counts: not distinct people, not summable across dates. `social-*` / `soundcloud-engagement` cover social/UGC usage, not streaming: `platform` is a UGC platform, `ugc_platform` narrows them; use, view and play are distinct quantities never summed together or with streams. Selecting any adds `meta.social_availability` (which UGC platforms report each signal); the streaming matrix omits them. Rate-limited ~60/min; windows over 90 days draw a separate ~30/min budget — prefer short 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. |
-| `get_analytics_rankings` | read | Top-N rankings for a window, ordered by summed streams. Pick ONE `view`: `leaderboards` — your top artists, tracks or albums (`type` required; `all` returns all three in one request). `placements` — the playlists and radio containers driving streams, summed across storefronts. Same scope filters as get_analytics; `limit` 1-50 (default 10). Under a `platform` filter, an `availability` of `not_available_for_platform` means that platform reports no ranking and `data` is empty. |
+| `get_analytics_rankings` | read | Top-N rankings for a window, ordered by summed streams — the per-entity breakdown of a scope: `type` tracks with a `upc`/`release_id` filter ranks the tracks on that release. Pick ONE `view`: `leaderboards` — your top artists, tracks or albums (`type` required; `all` returns all three in one call). `placements` — playlists and radio containers driving streams, summed across storefronts. Same scope filters as get_analytics; `limit` 1-50 (default 10). Under a `platform` filter, `availability: not_available_for_platform` means no ranking there and `data` is empty. |
 | `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`

package/dist/coverage.js

@@ -145,6 +145,7 @@ export const EXCLUDED = {
     'GET /resolve/label/{labelSlug}': 'label-website resolution — not exposed in v1',
     'GET /site-settings/{label}': 'label-website settings — not exposed in v1',
     'GET /site-settings/links/{label}': 'label-website settings — not exposed in v1',
+    'GET /tracks/{track}/file-upload-attempts/{uploadAttempt}': 'per-upload audio processing status — not exposed in v1',
     'GET /tracks/{track}/licenses/{trackLicense}/download': 'license file download — not exposed in v1',
     'GET /transactions/csv': 'transaction CSV export — not exposed in v1',
 };

package/dist/projection.js

@@ -72,6 +72,7 @@ export const CONCISE_ALLOWLISTS = {
         'status',
         'currency',
         'gross_usd',
+        'credit_amount',
         'labelgrid_fee',
         'platform_fee_usd',
         'ugc_fee_usd',

package/dist/tools/catalog.js

@@ -11,7 +11,7 @@
  * `response_format: 'detailed'` returning the verbatim API response.
  */
 import { statSync } from 'node:fs';
-import { ENTITIES, ENTITY_NAMES, assertAllowedExtension, } from '@labelgrid/core';
+import { ENTITIES, ENTITY_NAMES, REPLACEMENT_ENTITIES, assertAllowedExtension, } from '@labelgrid/core';
 import { z } from 'zod';
 import { applyProjection } from '../projection.js';
 /** Accepted image extensions for the catalog image uploads. */
@@ -135,17 +135,47 @@ const updateCatalogItem = {
         return client.patch(`${spec.path}/${args.id}`, args.fields);
     },
 };
+/** 'writer and publisher' — read off the registry, never spelled out by hand. */
+const REPLACEMENT_ENTITY_LIST = REPLACEMENT_ENTITIES.join(' and ');
 const deleteCatalogItem = {
     name: 'delete_catalog_item',
     toolset: 'catalog',
     gate: 'safe_write',
     title: 'Delete a catalog item',
-    description: `Delete a catalog entity. The API refuses deletes that would orphan data — ${entityDoc((s) => s.deleteNote)}`,
-    inputShape: { entity: entityArg, id: idArg },
+    description: `Delete a catalog entity. The API refuses deletes that would orphan data — ${entityDoc((s) => s.deleteNote)}` +
+        ` \`replace_with\` — ${REPLACEMENT_ENTITY_LIST} only — is the id inheriting those credits; a 422 REPLACEMENT_UNAVAILABLE means nothing was deleted.`,
+    inputShape: {
+        entity: entityArg,
+        id: idArg,
+        replace_with: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe(`${REPLACEMENT_ENTITY_LIST} only: the id that takes over every credit held by the one being deleted.`),
+    },
     annotations: { destructiveHint: true },
     handler: (args, { client }) => {
-        const spec = ENTITIES[args.entity];
-        return client.delete(`${spec.path}/${args.id}`);
+        const entity = args.entity;
+        const spec = ENTITIES[entity];
+        const path = `${spec.path}/${args.id}`;
+        const replaceWith = args.replace_with;
+        if (replaceWith === undefined) {
+            return client.delete(path);
+        }
+        // Only two endpoints take the parameter. Dropping it for the others would
+        // delete on the caller's behalf while silently ignoring the reassignment
+        // they asked for, so the call is refused before anything is sent.
+        if (!spec.acceptsDeleteReplacement) {
+            return Promise.resolve({
+                error: {
+                    code: 'INVALID_SELECTOR',
+                    message: `The ${entity} delete does not accept replace_with — only ${REPLACEMENT_ENTITY_LIST} deletes do. Delete without it, or clear the references first.`,
+                    status: 0,
+                },
+            });
+        }
+        return client.delete(path, { replace_with: replaceWith });
     },
 };
 /** Maps the label image targets to the API's imageType path segment. */

package/dist/tools/insights.js

@@ -7,9 +7,11 @@
 import { z } from 'zod';
 import { applyProjection } from '../projection.js';
 /**
- * The 47 metric sections the summary endpoint can return, in the server's
- * canonical order: the streaming sections first, then the social and UGC
- * family, then the per-track daily series.
+ * The 47 metric sections the summary endpoint can return. The server's canonical
+ * order — the order it projects sections into the response — is the streaming
+ * sections, then the per-track daily series, then the social and UGC family.
+ * This list groups the social and UGC family last instead; only membership
+ * matters here, since the enum validates which keys are legal, not their order.
  */
 const METRICS = [
     'streams',
@@ -96,25 +98,18 @@ const getAnalytics = {
     toolset: 'insights',
     gate: 'read',
     title: 'Get streaming and social analytics',
-    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. ' +
-        'The `social-*` / `soundcloud-engagement` sections cover social and UGC usage instead of streaming: their `platform` is a UGC platform; a use, view and play are distinct quantities, never summed with each other or with streams; `ugc_platform` narrows them. Selecting any adds `meta.social_availability` (which UGC platforms report each signal) — the streaming matrix excludes them. ' +
-        'The `track-*-daily` sections need a `release_id`, `isrc` or `upc` scope. `track-listeners-daily` sums per-entry daily counts: not distinct people, not summable across dates. ' +
-        '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.',
+    description: 'Streaming analytics summary. Window capped at 400 days; `metrics` takes 1-12 section keys per request (split larger selections; responses cached). ' +
+        'KUGOU/KUWO/QQMUSIC report weekly: one point carries the whole week — never average per day. `meta` carries `platform_cadence`, `section_granularity`, `sections_as_of` and `sections_complete_through` (later dates still filling in). ' +
+        'See get_analytics_availability for per-platform support. ' +
+        'Sections aggregate over the resolved filter scope: a `upc` filter gives release totals, not per-track rows. For those use `track-*-daily` (needs a `release_id`, `isrc` or `upc` scope) or get_analytics_rankings. `track-listeners-daily` sums per-entry daily counts: not distinct people, not summable across dates. ' +
+        '`social-*` / `soundcloud-engagement` cover social/UGC usage, not streaming: `platform` is a UGC platform, `ugc_platform` narrows them; use, view and play are distinct quantities never summed together or with streams. Selecting any adds `meta.social_availability` (which UGC platforms report each signal); the streaming matrix omits them. ' +
+        'Rate-limited ~60/min; windows over 90 days draw a separate ~30/min budget — prefer short windows for polling. A 429 carries retry_after_seconds.',
     inputShape: {
         start_date: z.string().describe('Window start, YYYY-MM-DD.'),
         end_date: z.string().describe('Window end, YYYY-MM-DD.'),
-        metrics: z
-            .array(z.enum(METRICS))
-            .min(1)
-            .max(MAX_METRICS_PER_REQUEST)
-            .describe('Section keys, 1-12 per request.'),
+        metrics: z.array(z.enum(METRICS)).min(1).max(MAX_METRICS_PER_REQUEST),
         platform: z.enum(PLATFORMS).optional(),
-        ugc_platform: z
-            .enum(UGC_PLATFORMS)
-            .optional()
-            .describe('Narrows the social/UGC sections only.'),
+        ugc_platform: z.enum(UGC_PLATFORMS).optional().describe('Social/UGC sections only.'),
         release_id: z.number().int().positive().optional(),
         isrc: z.string().optional(),
         upc: z.string().optional(),
@@ -158,15 +153,15 @@ const getAnalyticsRankings = {
     toolset: 'insights',
     gate: 'read',
     title: 'Get analytics rankings',
-    description: 'Top-N rankings for a window, ordered by summed streams. Pick ONE `view`: ' +
-        '`leaderboards` — your top artists, tracks or albums (`type` required; `all` returns all three in one request). ' +
-        '`placements` — the playlists and radio containers driving streams, summed across storefronts. ' +
-        'Same scope filters as get_analytics; `limit` 1-50 (default 10). Under a `platform` filter, an `availability` of `not_available_for_platform` means that platform reports no ranking and `data` is empty.',
+    description: 'Top-N rankings for a window, ordered by summed streams — the per-entity breakdown of a scope: `type` tracks with a `upc`/`release_id` filter ranks the tracks on that release. Pick ONE `view`: ' +
+        '`leaderboards` — your top artists, tracks or albums (`type` required; `all` returns all three in one call). ' +
+        '`placements` — playlists and radio containers driving streams, summed across storefronts. ' +
+        'Same scope filters as get_analytics; `limit` 1-50 (default 10). Under a `platform` filter, `availability: not_available_for_platform` means no ranking there and `data` is empty.',
     inputShape: {
-        view: z.enum(RANKING_VIEWS).describe('Which ranking read.'),
+        view: z.enum(RANKING_VIEWS),
         start_date: z.string().describe('Window start, YYYY-MM-DD.'),
         end_date: z.string().describe('Window end, YYYY-MM-DD.'),
-        type: z.enum(LEADERBOARD_TYPES).optional().describe('Required for view leaderboards.'),
+        type: z.enum(LEADERBOARD_TYPES).optional(),
         platform: z.enum(PLATFORMS).optional(),
         ugc_platform: z.enum(UGC_PLATFORMS).optional(),
         release_id: z.number().int().positive().optional(),
@@ -178,7 +173,7 @@ const getAnalyticsRankings = {
             .int()
             .positive()
             .optional()
-            .describe('Narrow to one of your own labels; it can never widen scope.'),
+            .describe('Narrow to one of your own labels; never widens scope.'),
         limit: z.number().int().positive().max(MAX_RANKING_LIMIT).optional(),
     },
     annotations: { readOnlyHint: true },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@labelgrid/mcp",
-  "version": "0.6.0",
+  "version": "0.7.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.2.1",
+    "@labelgrid/core": "0.2.2",
     "@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.6.0",
+  "version": "0.7.0",
   "websiteUrl": "https://labelgrid.com",
   "repository": {
     "url": "https://github.com/labelgrid/labelgrid-mcp",
@@ -12,7 +12,7 @@
     {
       "registryType": "npm",
       "identifier": "@labelgrid/mcp",
-      "version": "0.6.0",
+      "version": "0.7.0",
       "transport": {
         "type": "stdio"
       },