@labelgrid/mcp 0.2.2 → 0.3.1

package/dist/tools/account.js

@@ -0,0 +1,32 @@
+/** Account toolset: read the authenticated account, revoke API tokens. */
+import { z } from 'zod';
+const getAccount = {
+    name: 'get_account',
+    toolset: 'account',
+    gate: 'read',
+    title: 'Get account',
+    description: 'Read the authenticated LabelGrid account. Pick ONE view with `view`: ' +
+        '`profile` returns the account profile — including the release submission limit/quota and terms-acceptance status — use it to confirm which account your API token belongs to before making other calls; ' +
+        '`balance` returns your accounting summary — current balance and related account-level financial totals.',
+    inputShape: {
+        view: z.enum(['profile', 'balance']).describe('Which account read.'),
+    },
+    annotations: { readOnlyHint: true },
+    handler: (args, { client }) => client.get(args.view === 'balance' ? '/account' : '/me'),
+};
+const revokeApiToken = {
+    name: 'revoke_api_token',
+    toolset: 'account',
+    gate: 'safe_write',
+    title: 'Revoke an API token',
+    description: 'Revoke a LabelGrid API token. Pass token_id to revoke a specific token; omit it to revoke the token currently in use. WARNING: revoking the current token immediately ends this session — the server loses access and stops working until you configure a new token.',
+    inputShape: { token_id: z.number().int().positive().optional() },
+    annotations: { destructiveHint: true, idempotentHint: true },
+    handler: (args, { client }) => {
+        const tokenId = args.token_id;
+        return tokenId === undefined
+            ? client.delete('/tokens/current')
+            : client.delete(`/tokens/${tokenId}`);
+    },
+};
+export const accountTools = [getAccount, revokeApiToken];

package/dist/tools/all.js

@@ -1,29 +1,21 @@
 /** The complete tool catalog, in registration order. */
-import { accountingTools } from './accounting.js';
-import { analyticsTools } from './analytics.js';
-import { catalogReadTools } from './catalog-read.js';
-import { catalogWriteTools } from './catalog-write.js';
-import { deliveryTools } from './delivery.js';
-import { filesReadTools } from './files-read.js';
-import { fullWriteTools } from './full-writes.js';
-import { identityTools } from './identity.js';
+import { accountTools } from './account.js';
+import { catalogTools } from './catalog.js';
+import { distributionTools } from './distribution.js';
+import { financeTools } from './finance.js';
+import { insightsTools } from './insights.js';
 import { referenceTools } from './reference.js';
-import { releaseWriteTools } from './release-write.js';
-import { reviewReadTools } from './review-read.js';
+import { releaseTools } from './releases.js';
 import { webhookTools } from './webhooks.js';
 export function allTools() {
     return [
-        ...identityTools,
+        ...accountTools,
         ...referenceTools,
-        ...analyticsTools,
-        ...catalogReadTools,
-        ...filesReadTools,
-        ...reviewReadTools,
-        ...deliveryTools,
-        ...accountingTools,
+        ...catalogTools,
+        ...releaseTools,
+        ...insightsTools,
+        ...financeTools,
         ...webhookTools,
-        ...catalogWriteTools,
-        ...releaseWriteTools,
-        ...fullWriteTools,
+        ...distributionTools,
     ];
 }

package/dist/tools/catalog.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Catalog toolset: the consolidated entity CRUD (search/get/create/update/
+ * delete across labels, artists, writers, publishers, releases and tracks),
+ * image uploads, and the asset read (`get_asset`).
+ *
+ * Every tool selects its entity via the entity registry in `@labelgrid/core`.
+ * Create/update forward a permissive `fields` object straight to the API,
+ * which owns all validation — this keeps each tool a thin wrapper and lets the
+ * full documented field set through without re-declaring it here. The two
+ * reads are [proj] tools: concise-mode projection by default, with
+ * `response_format: 'detailed'` returning the verbatim API response.
+ */
+import type { ToolDef } from './types.js';
+export declare const catalogTools: ToolDef[];

package/dist/tools/catalog.js

@@ -0,0 +1,266 @@
+/**
+ * Catalog toolset: the consolidated entity CRUD (search/get/create/update/
+ * delete across labels, artists, writers, publishers, releases and tracks),
+ * image uploads, and the asset read (`get_asset`).
+ *
+ * Every tool selects its entity via the entity registry in `@labelgrid/core`.
+ * Create/update forward a permissive `fields` object straight to the API,
+ * which owns all validation — this keeps each tool a thin wrapper and lets the
+ * full documented field set through without re-declaring it here. The two
+ * reads are [proj] tools: concise-mode projection by default, with
+ * `response_format: 'detailed'` returning the verbatim API response.
+ */
+import { statSync } from 'node:fs';
+import { ENTITIES, ENTITY_NAMES, assertAllowedExtension, } from '@labelgrid/core';
+import { z } from 'zod';
+import { applyProjection } from '../projection.js';
+/** Accepted image extensions for the catalog image uploads. */
+const IMAGE_EXTS = ['.jpg', '.jpeg', '.png', '.webp', '.tif', '.tiff'];
+const entityArg = z.enum(ENTITY_NAMES).describe('The catalog entity kind.');
+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.");
+/** A permissive body of API fields, forwarded verbatim to the endpoint. */
+function fieldsBody(desc) {
+    return z.record(z.string(), z.unknown()).describe(desc);
+}
+/** Optional caller-supplied idempotency key, plumbed to the Idempotency-Key header. */
+const idempotencyKey = z
+    .string()
+    .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.');
+/** Rejects a path that is not an existing regular file, before any HTTP call. */
+function fileError(p) {
+    let isFile = false;
+    try {
+        isFile = statSync(p).isFile();
+    }
+    catch {
+        isFile = false;
+    }
+    return isFile
+        ? null
+        : { code: 'FILE_NOT_FOUND', message: `No readable file at ${p}.`, status: 0 };
+}
+function entityDoc(pick) {
+    return ENTITY_NAMES.map((name) => pick(ENTITIES[name])).join(' ');
+}
+const searchCatalog = {
+    name: 'search_catalog',
+    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.`,
+    inputShape: {
+        entity: entityArg,
+        filters: z
+            .record(z.string(), z.unknown())
+            .optional()
+            .describe('Filter names → values, passed through verbatim.'),
+        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,
+    },
+    annotations: { readOnlyHint: true },
+    handler: async (args, { client }) => {
+        const spec = ENTITIES[args.entity];
+        const result = await client.get(spec.path, {
+            page: args.page,
+            per_page: args.per_page,
+            filter: args.filters,
+        });
+        return applyProjection(result, 'search_catalog', args.response_format);
+    },
+};
+const getCatalogItem = {
+    name: 'get_catalog_item',
+    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.",
+    inputShape: {
+        entity: entityArg,
+        id: idArg,
+        response_format: responseFormat,
+    },
+    annotations: { readOnlyHint: true },
+    handler: async (args, { client }) => {
+        const spec = ENTITIES[args.entity];
+        const result = await client.get(`${spec.path}/${args.id}`);
+        return applyProjection(result, 'get_catalog_item', args.response_format);
+    },
+};
+const createCatalogItem = {
+    name: 'create_catalog_item',
+    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.`,
+    inputShape: {
+        entity: entityArg,
+        fields: fieldsBody('The entity attributes, forwarded verbatim.'),
+        idempotency_key: idempotencyKey,
+    },
+    annotations: {},
+    handler: (args, { client }) => {
+        const entity = args.entity;
+        const spec = ENTITIES[entity];
+        // Only the release and track POST endpoints support idempotency keys — the
+        // header is never sent for the other entities (their endpoints lack it).
+        if (entity === 'release' || entity === 'track') {
+            return client.post(spec.path, args.fields, {
+                idempotency: true,
+                idempotencyKey: args.idempotency_key,
+            });
+        }
+        return client.post(spec.path, args.fields);
+    },
+};
+const updateCatalogItem = {
+    name: 'update_catalog_item',
+    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.',
+    inputShape: {
+        entity: entityArg,
+        id: idArg,
+        fields: fieldsBody('The fields to change, forwarded verbatim.'),
+    },
+    annotations: { idempotentHint: true },
+    handler: (args, { client }) => {
+        const spec = ENTITIES[args.entity];
+        return client.patch(`${spec.path}/${args.id}`, args.fields);
+    },
+};
+const deleteCatalogItem = {
+    name: 'delete_catalog_item',
+    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)}`,
+    inputShape: { entity: entityArg, id: idArg },
+    annotations: { destructiveHint: true },
+    handler: (args, { client }) => {
+        const spec = ENTITIES[args.entity];
+        return client.delete(`${spec.path}/${args.id}`);
+    },
+};
+/** Maps the label image targets to the API's imageType path segment. */
+const LABEL_IMAGE_TYPES = {
+    label_logo: 'logo',
+    label_logo_dark: 'logo-dark',
+    label_background: 'background',
+};
+const uploadImage = {
+    name: 'upload_image',
+    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.',
+    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.'),
+    },
+    annotations: {},
+    handler: async (args, { client }) => {
+        const err = fileError(args.file_path);
+        if (err)
+            return { error: err };
+        const ext = assertAllowedExtension(args.file_path, IMAGE_EXTS);
+        if ('error' in ext)
+            return { error: ext.error };
+        const target = args.target;
+        if (target === 'artist_photo') {
+            return client.postMultipart(`/artists/${args.id}/photo`, ext.realPath, 'file');
+        }
+        return client.postMultipart(`/labels/${args.id}/images/${LABEL_IMAGE_TYPES[target]}`, ext.realPath, 'file');
+    },
+};
+/** The (mode, parent) → allowed-assets matrix — the only combinations with an endpoint. */
+const INFO_TRACK_ASSETS = new Set(['stereo', 'dolby', 'lyrics']);
+const INFO_RELEASE_ASSETS = new Set(['square', 'tall']);
+const DOWNLOAD_TRACK_ASSETS = new Set([
+    'audio_16',
+    'audio_24',
+    'audio_32',
+    'audio_preview_full',
+    'audio_preview_clip',
+]);
+const GET_ASSET_VALID_COMBINATIONS = 'Valid combinations: mode=info + parent=track + asset stereo|dolby|lyrics (file metadata and processing state); ' +
+    'mode=info + parent=release + asset square|tall (animated cover / motion artwork video metadata); ' +
+    'mode=download_url + parent=track + asset audio_16|audio_24|audio_32|audio_preview_full|audio_preview_clip (a signed download URL).';
+const getAsset = {
+    name: 'get_asset',
+    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.',
+    inputShape: {
+        parent: z.enum(['track', 'release']).describe('Whose asset.'),
+        id: z.number().int().positive().describe('The track id or release id, per `parent`.'),
+        asset: z
+            .enum([
+            'stereo',
+            'dolby',
+            'lyrics',
+            'square',
+            'tall',
+            'audio_16',
+            'audio_24',
+            'audio_32',
+            'audio_preview_full',
+            'audio_preview_clip',
+        ])
+            .describe('Which asset — see the description for the valid parent/mode pairings.'),
+        mode: z
+            .enum(['info', 'download_url'])
+            .optional()
+            .describe('info (default) returns file metadata; download_url returns a signed URL.'),
+    },
+    annotations: { readOnlyHint: true },
+    handler: (args, { client }) => {
+        const mode = args.mode ?? 'info';
+        const parent = args.parent;
+        const asset = args.asset;
+        if (mode === 'info' && parent === 'track' && INFO_TRACK_ASSETS.has(asset)) {
+            return client.get(`/tracks/${args.id}/files/${asset}`);
+        }
+        if (mode === 'info' && parent === 'release' && INFO_RELEASE_ASSETS.has(asset)) {
+            return client.get(`/releases/${args.id}/files/${asset}`);
+        }
+        if (mode === 'download_url' && parent === 'track' && DOWNLOAD_TRACK_ASSETS.has(asset)) {
+            return client.get(`/tracks/${args.id}/files/${asset}/download-url`);
+        }
+        // No endpoint exists for this combination — there is nothing to send it to.
+        return Promise.resolve({
+            error: {
+                code: 'INVALID_SELECTOR',
+                message: `No endpoint exists for mode=${mode}, parent=${parent}, asset=${asset}. ${GET_ASSET_VALID_COMBINATIONS}`,
+                status: 0,
+            },
+        });
+    },
+};
+export const catalogTools = [
+    searchCatalog,
+    getCatalogItem,
+    createCatalogItem,
+    updateCatalogItem,
+    deleteCatalogItem,
+    uploadImage,
+    getAsset,
+];

package/dist/tools/distribution.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Distribution toolset (full writes): the consequential actions that put a
+ * release into the world or change immutable assets. Every tool here is gated
+ * `full_write`, so it is neither registered nor callable unless the operator
+ * has explicitly armed full writes (the flag AND the acknowledgment sentence).
+ *
+ * These wrap: finalized audio/artwork/motion-artwork uploads (via the
+ * presigned-URL flow or multipart), license file management, the FINAL
+ * distribute/takedown actions, the Preflight-QC confirm-review step, and
+ * one-time Beatport onboarding.
+ */
+import type { ToolDef } from './types.js';
+export declare const distributionTools: ToolDef[];

package/dist/tools/distribution.js

@@ -0,0 +1,265 @@
+/**
+ * Distribution toolset (full writes): the consequential actions that put a
+ * release into the world or change immutable assets. Every tool here is gated
+ * `full_write`, so it is neither registered nor callable unless the operator
+ * has explicitly armed full writes (the flag AND the acknowledgment sentence).
+ *
+ * These wrap: finalized audio/artwork/motion-artwork uploads (via the
+ * presigned-URL flow or multipart), license file management, the FINAL
+ * distribute/takedown actions, the Preflight-QC confirm-review step, and
+ * one-time Beatport onboarding.
+ */
+import { assertAllowedExtension, uploadViaPresignedUrl } from '@labelgrid/core';
+import { z } from 'zod';
+/** Per-target upload extension allow-lists: an upload tool never reads an arbitrary file. */
+const TRACK_UPLOAD_EXTS = {
+    track_stereo: ['.wav', '.flac', '.aif', '.aiff'],
+    track_dolby: ['.wav'],
+    track_lyrics: ['.lrc', '.txt'],
+};
+const MOTION_EXTS = ['.mp4', '.mov'];
+const IMAGE_EXTS = ['.jpg', '.jpeg', '.png', '.webp', '.tif', '.tiff'];
+const LICENSE_EXTS = ['.pdf', '.jpg', '.jpeg', '.png'];
+/** target → the API's track fileType path segment. */
+const TRACK_FILE_TYPES = {
+    track_stereo: 'stereo',
+    track_dolby: 'dolby',
+    track_lyrics: 'lyrics',
+};
+/** target → the API's release motion-artwork assetType path segment. */
+const MOTION_ASSET_TYPES = {
+    release_motion_square: 'square',
+    release_motion_tall: 'tall',
+};
+const releaseId = z.number().int().positive().describe('The release id.');
+/** Optional caller-supplied idempotency key, plumbed to the Idempotency-Key header. */
+const idempotencyKey = z
+    .string()
+    .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.');
+/** 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.'),
+    license_provider: z
+        .enum(['licensing_agency', 'direct_from_publisher'])
+        .optional()
+        .describe('Where the license came from.'),
+    license_provider_name: z.string().optional().describe('The name of the license provider.'),
+    original_track_link: z.string().optional().describe('URL to the original/source track.'),
+};
+/** Collects the defined license metadata fields into a string map for multipart. */
+function licenseExtra(args) {
+    const out = {};
+    for (const key of [
+        'type',
+        'license_id',
+        'license_provider',
+        'license_provider_name',
+        'original_track_link',
+    ]) {
+        const v = args[key];
+        if (v !== undefined && v !== null)
+            out[key] = String(v);
+    }
+    return out;
+}
+const uploadAsset = {
+    name: 'upload_asset',
+    toolset: 'distribution',
+    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.',
+    inputShape: {
+        target: z
+            .enum([
+            'track_stereo',
+            'track_dolby',
+            'track_lyrics',
+            'release_cover_art',
+            'release_motion_square',
+            'release_motion_tall',
+        ])
+            .describe('Which asset to upload.'),
+        id: z.number().int().positive().describe('The track id (track_*) or release id (release_*).'),
+        file_path: z.string().describe('Local path to the file to upload.'),
+    },
+    annotations: {},
+    handler: async (args, { client }) => {
+        const target = args.target;
+        const filePath = args.file_path;
+        if (target in TRACK_FILE_TYPES) {
+            const ext = assertAllowedExtension(filePath, TRACK_UPLOAD_EXTS[target]);
+            if ('error' in ext)
+                return { error: ext.error };
+            const fileType = TRACK_FILE_TYPES[target];
+            return uploadViaPresignedUrl(client, {
+                uploadUrlPath: `/tracks/${args.id}/files/${fileType}/upload-url`,
+                commitPath: `/tracks/${args.id}/files/${fileType}`,
+                filePath: ext.realPath,
+            });
+        }
+        if (target === 'release_cover_art') {
+            const ext = assertAllowedExtension(filePath, IMAGE_EXTS);
+            if ('error' in ext)
+                return { error: ext.error };
+            return client.postMultipart(`/releases/${args.id}/photo`, ext.realPath, 'file');
+        }
+        const ext = assertAllowedExtension(filePath, MOTION_EXTS);
+        if ('error' in ext)
+            return { error: ext.error };
+        const assetType = MOTION_ASSET_TYPES[target];
+        return uploadViaPresignedUrl(client, {
+            uploadUrlPath: `/releases/${args.id}/files/${assetType}/upload-url`,
+            commitPath: `/releases/${args.id}/files/${assetType}`,
+            filePath: ext.realPath,
+        });
+    },
+};
+const deleteAsset = {
+    name: 'delete_asset',
+    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.',
+    inputShape: {
+        target: z
+            .enum([
+            'track_stereo',
+            'track_dolby',
+            'track_lyrics',
+            'release_motion_square',
+            'release_motion_tall',
+        ])
+            .describe('Which asset to delete.'),
+        id: z
+            .number()
+            .int()
+            .positive()
+            .describe('The track id (track_*) or release id (release_motion_*).'),
+    },
+    annotations: { destructiveHint: true },
+    handler: (args, { client }) => {
+        const target = args.target;
+        if (target in TRACK_FILE_TYPES) {
+            return client.delete(`/tracks/${args.id}/files/${TRACK_FILE_TYPES[target]}`);
+        }
+        return client.delete(`/releases/${args.id}/files/${MOTION_ASSET_TYPES[target]}`);
+    },
+};
+const manageTrackLicense = {
+    name: 'manage_track_license',
+    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.',
+    inputShape: {
+        action: z.enum(['upload', 'update', 'delete']).describe('Which license action.'),
+        track_id: z.number().int().positive().describe('The track id.'),
+        track_license_id: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe('From list_track_licenses. Required for update/delete.'),
+        file_path: z
+            .string()
+            .optional()
+            .describe('Local path to the license file. Required for upload/update.'),
+        type: z.enum(['cover', 'sample']).optional().describe('Kind of license (upload).'),
+        ...licenseMeta,
+    },
+    annotations: { destructiveHint: true },
+    handler: async (args, { client }) => {
+        const action = args.action;
+        if ((action === 'update' || action === 'delete') && args.track_license_id === undefined) {
+            return {
+                error: {
+                    code: 'INVALID_SELECTOR',
+                    message: `action '${action}' requires \`track_license_id\` — the license to act on (from list_track_licenses).`,
+                    status: 0,
+                },
+            };
+        }
+        if (action === 'delete') {
+            return client.delete(`/tracks/${args.track_id}/licenses/${args.track_license_id}`);
+        }
+        if (args.file_path === undefined) {
+            return {
+                error: {
+                    code: 'INVALID_SELECTOR',
+                    message: `action '${action}' requires \`file_path\` — the local license file to submit.`,
+                    status: 0,
+                },
+            };
+        }
+        const ext = assertAllowedExtension(args.file_path, LICENSE_EXTS);
+        if ('error' in ext)
+            return { error: ext.error };
+        const path = action === 'upload'
+            ? `/tracks/${args.track_id}/licenses`
+            : `/tracks/${args.track_id}/licenses/${args.track_license_id}`;
+        return client.postMultipart(path, ext.realPath, 'file', licenseExtra(args));
+    },
+};
+const distributeRelease = {
+    name: 'distribute_release',
+    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.',
+    inputShape: { release_id: releaseId, idempotency_key: idempotencyKey },
+    annotations: { destructiveHint: true },
+    handler: (args, { client }) => client.post(`/releases/${args.release_id}/distribute`, undefined, {
+        idempotency: true,
+        idempotencyKey: args.idempotency_key,
+    }),
+};
+const takedownRelease = {
+    name: 'takedown_release',
+    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.',
+    inputShape: { release_id: releaseId },
+    annotations: { destructiveHint: true },
+    handler: (args, { client }) => client.post(`/releases/${args.release_id}/takedown-all`),
+};
+const confirmReview = {
+    name: 'confirm_review',
+    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.',
+    inputShape: { release_id: releaseId },
+    annotations: { destructiveHint: true, idempotentHint: true },
+    handler: (args, { client }) => client.post(`/releases/${args.release_id}/confirm-review`),
+};
+const enableBeatport = {
+    name: 'enable_beatport',
+    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.',
+    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`),
+};
+export const distributionTools = [
+    uploadAsset,
+    deleteAsset,
+    manageTrackLicense,
+    distributeRelease,
+    takedownRelease,
+    confirmReview,
+    enableBeatport,
+];

package/dist/tools/finance.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Finance toolset: the consolidated financial query (statements, transactions,
+ * royalty breakdowns) and statement downloads. All read-only.
+ *
+ * `download_statement` fetches a file body. It validates the caller-supplied
+ * `save_to_path` and writes ONLY there; a CSV without a save path is returned
+ * inline, truncated at 100KB. Downloads use an authenticated raw GET (the
+ * shared client's JSON path would corrupt binary PDFs), with the same auth
+ * headers the client sends.
+ */
+import type { ToolDef } from './types.js';
+export declare const financeTools: ToolDef[];