@labelgrid/mcp 0.2.2 → 0.3.0

package/dist/tools/distribution.js

@@ -0,0 +1,266 @@
+/**
+ * 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 { z } from 'zod';
+import { assertAllowedExtension } from '../api/content-types.js';
+import { uploadViaPresignedUrl } from '../api/upload.js';
+/** 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[];

package/dist/tools/finance.js

@@ -0,0 +1,311 @@
+/**
+ * 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 { realpathSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute } from 'node:path';
+import { z } from 'zod';
+import { applyProjection } from '../projection.js';
+import { VERSION } from '../version.js';
+const INLINE_CSV_LIMIT = 100 * 1024;
+/**
+ * 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.
+ */
+function validateSavePath(p) {
+    if (!isAbsolute(p)) {
+        return {
+            code: 'INVALID_PATH',
+            message: `save_to_path must be an absolute path (received: ${p}).`,
+            status: 0,
+        };
+    }
+    const dir = dirname(p);
+    let realDir;
+    try {
+        realDir = realpathSync(dir);
+    }
+    catch {
+        return {
+            code: 'INVALID_PATH',
+            message: `The parent directory of save_to_path does not exist: ${dir}.`,
+            status: 0,
+        };
+    }
+    let isDir = false;
+    try {
+        isDir = statSync(realDir).isDirectory();
+    }
+    catch {
+        isDir = false;
+    }
+    if (!isDir) {
+        return {
+            code: 'INVALID_PATH',
+            message: `The parent directory of save_to_path is not a directory: ${dir}.`,
+            status: 0,
+        };
+    }
+    return null;
+}
+/**
+ * Writes a file with exclusive creation ('wx'): an existing path is NEVER
+ * overwritten. Returns FILE_EXISTS on collision, or a structured write error,
+ * or null on success.
+ */
+function writeNewFile(path, data) {
+    try {
+        writeFileSync(path, data, { flag: 'wx' });
+        return null;
+    }
+    catch (err) {
+        if (err.code === 'EEXIST') {
+            return {
+                code: 'FILE_EXISTS',
+                message: `A file already exists at ${path}. This tool never overwrites — choose a new path.`,
+                status: 0,
+            };
+        }
+        return {
+            code: 'WRITE_FAILED',
+            message: `Could not write to ${path}: ${err instanceof Error ? err.message : 'unknown error'}.`,
+            status: 0,
+        };
+    }
+}
+/** 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';
+}
+/** 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;
+    try {
+        res = await ctx.client.raw(`${base}${path}`, {
+            method: 'GET',
+            headers: {
+                Authorization: `Bearer ${ctx.config.token}`,
+                Accept: 'application/json',
+                'User-Agent': `labelgrid-mcp/${VERSION}`,
+            },
+        });
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: {
+                code: 'NETWORK_ERROR',
+                message: err instanceof Error ? err.message : 'Network request failed.',
+                status: 0,
+            },
+        };
+    }
+    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;
+                }
+            }
+        }
+        catch {
+            // keep the default message
+        }
+        return { ok: false, error: { code: statusToCode(res.status), message, status: res.status } };
+    }
+    return { ok: true, res };
+}
+const queryFinancials = {
+    name: 'query_financials',
+    toolset: 'finance',
+    gate: 'read',
+    title: 'Query financial data',
+    description: 'Query your financial data. Pick ONE view with `view`: ' +
+        '`statements` lists your royalty statements, paginated — `filters`: label_id, release_id, isrc, upc, start_date/end_date; group_by="release" rolls totals up per release. ' +
+        '`statement_detail` retrieves one statement by `invoice_number` (required). ' +
+        '`transactions` lists account transactions, paginated — same `filters`; sort with `sort`; group_by="release" rolls up per release. ' +
+        '`royalty_breakdown` returns a cursor-paginated royalty breakdown — `group_by` is REQUIRED for this view: a comma-separated, ordered subset of: track, dsp, release, territory, period (e.g. "release,dsp"); same `filters`; pass `cursor` to page. ' +
+        "Use download_statement for statement line items (CSV) or the invoice PDF. response_format:'detailed' returns the verbatim API response.",
+    inputShape: {
+        view: z
+            .enum(['statements', 'statement_detail', 'transactions', 'royalty_breakdown'])
+            .describe('Which financial read.'),
+        invoice_number: z.string().optional().describe('Required for view statement_detail.'),
+        group_by: z
+            .string()
+            .optional()
+            .describe('REQUIRED for royalty_breakdown (ordered subset: track, dsp, release, territory, period); "release" rolls statements/transactions up per release.'),
+        sort: z.string().optional().describe('Sort expression (view transactions).'),
+        filters: z
+            .record(z.string(), z.unknown())
+            .optional()
+            .describe('label_id, release_id, isrc, upc, start_date, end_date — passed through verbatim.'),
+        cursor: z.string().optional().describe('Pagination cursor (view royalty_breakdown).'),
+        page: z.number().int().positive().optional().describe('1-based page number.'),
+        per_page: z.number().int().positive().optional().describe('Items per page.'),
+        response_format: z
+            .enum(['concise', 'detailed'])
+            .optional()
+            .describe("'concise' (default) keeps only the high-signal fields (ids always kept); 'detailed' returns the verbatim API response."),
+    },
+    annotations: { readOnlyHint: true },
+    handler: async (args, { client }) => {
+        const view = args.view;
+        let result;
+        if (view === 'statements') {
+            result = await client.get('/statements', {
+                group_by: args.group_by,
+                page: args.page,
+                per_page: args.per_page,
+                filter: args.filters,
+            });
+        }
+        else if (view === 'statement_detail') {
+            if (args.invoice_number === undefined) {
+                return {
+                    error: {
+                        code: 'INVALID_SELECTOR',
+                        message: "view 'statement_detail' requires `invoice_number` — the statement invoice number.",
+                        status: 0,
+                    },
+                };
+            }
+            result = await client.get(`/statements/${encodeURIComponent(String(args.invoice_number))}`);
+        }
+        else if (view === 'transactions') {
+            result = await client.get('/transactions', {
+                group_by: args.group_by,
+                page: args.page,
+                per_page: args.per_page,
+                sort: args.sort,
+                filter: args.filters,
+            });
+        }
+        else {
+            result = await client.get('/royalties/breakdown', {
+                group_by: args.group_by,
+                per_page: args.per_page,
+                cursor: args.cursor,
+                filter: args.filters,
+            });
+        }
+        return applyProjection(result, 'query_financials', args.response_format);
+    },
+};
+const downloadStatement = {
+    name: 'download_statement',
+    toolset: 'finance',
+    gate: 'read',
+    title: 'Download a statement file',
+    description: "Download statement files. `format: 'csv'` downloads statement line items — pass invoice_number for one statement, OR a start_date/end_date range to export across statements; with save_to_path (an absolute path whose parent directory exists) the CSV is written there and the byte count returned; otherwise it is returned inline, truncated at 100KB (truncated: true) — use save_to_path for large exports. `format: 'invoice_pdf'` downloads the invoice PDF — invoice_number and save_to_path are both REQUIRED (the PDF is binary). An existing file is never overwritten (returns FILE_EXISTS).",
+    inputShape: {
+        format: z
+            .enum(['csv', 'invoice_pdf'])
+            .describe('Which file: csv (line items) or invoice_pdf (the invoice PDF).'),
+        invoice_number: z
+            .string()
+            .optional()
+            .describe('Single-statement invoice number. Required for format invoice_pdf.'),
+        start_date: z.string().optional().describe('CSV export range start, YYYY-MM-DD.'),
+        end_date: z.string().optional().describe('CSV export range end, YYYY-MM-DD.'),
+        save_to_path: z
+            .string()
+            .optional()
+            .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) => {
+        const invoice = args.invoice_number;
+        const savePath = args.save_to_path;
+        if (args.format === 'invoice_pdf') {
+            if (invoice === undefined || invoice === '') {
+                return {
+                    error: {
+                        code: 'INVALID_SELECTOR',
+                        message: "format 'invoice_pdf' requires `invoice_number` — the statement invoice number.",
+                        status: 0,
+                    },
+                };
+            }
+            if (savePath === undefined) {
+                return {
+                    error: {
+                        code: 'INVALID_SELECTOR',
+                        message: "format 'invoice_pdf' requires `save_to_path` — an absolute path to write the binary PDF to.",
+                        status: 0,
+                    },
+                };
+            }
+            const err = validateSavePath(savePath);
+            if (err)
+                return { error: err };
+            const result = await authedGet(ctx, `/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 } };
+        }
+        // format === 'csv'
+        if (savePath !== undefined) {
+            const err = validateSavePath(savePath);
+            if (err)
+                return { error: err };
+        }
+        let path;
+        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('&')}` : ''}`;
+        }
+        const result = await authedGet(ctx, path);
+        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 } };
+        }
+        const truncated = text.length > INLINE_CSV_LIMIT;
+        const content = truncated ? text.slice(0, INLINE_CSV_LIMIT) : text;
+        return { data: { content, truncated, bytes: totalBytes } };
+    },
+};
+export const financeTools = [queryFinancials, downloadStatement];

package/dist/tools/insights.d.ts

@@ -0,0 +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.
+ */
+import type { ToolDef } from './types.js';
+export declare const insightsTools: ToolDef[];