@labelgrid/mcp 0.2.2 → 0.3.1

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[];

package/dist/tools/insights.js

@@ -0,0 +1,139 @@
+/**
+ * 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 { z } from 'zod';
+import { applyProjection } from '../projection.js';
+/** The 15 metric sections the summary endpoint can return. */
+const METRICS = [
+    'streams',
+    'listeners',
+    'saves',
+    'skips',
+    'shares',
+    'completion-rate',
+    'lyrics-view-rate',
+    'canvas-view-rate',
+    'device-split',
+    'source-split',
+    'saves-by-tier',
+    'streams-by-country',
+    'streams-by-gender',
+    'streams-by-age',
+    'shares-by-country',
+];
+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.',
+    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).'),
+        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(),
+        release_id: z.number().int().positive().optional(),
+        isrc: z.string().optional(),
+        upc: z.string().optional(),
+        artist_names: z.array(z.string()).optional().describe('Filter to one or more artist names.'),
+        limit: z.number().int().positive().optional(),
+    },
+    annotations: { readOnlyHint: true },
+    handler: (args, { client }) => client.get('/analytics/summary', {
+        filter: {
+            start_date: args.start_date,
+            end_date: args.end_date,
+            platform: args.platform,
+            release_id: args.release_id,
+            isrc: args.isrc,
+            upc: args.upc,
+            artist_names: args.artist_names,
+        },
+        metrics: args.metrics,
+        limit: args.limit,
+    }),
+};
+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. ' +
+        "response_format:'detailed' returns the verbatim API response.",
+    inputShape: {
+        view: z
+            .enum(['flags', 'flag_detail', 'records', 'fee_breakdown'])
+            .describe('Which artificial-streaming read.'),
+        flag_id: z.number().int().positive().optional().describe('Required for view flag_detail.'),
+        period: z.string().optional().describe('YYYY-MM. Required for view fee_breakdown.'),
+        filters: z
+            .record(z.string(), z.unknown())
+            .optional()
+            .describe('Filter names → values, passed through verbatim.'),
+        cursor: z.string().optional().describe('Pagination cursor (view records).'),
+        page: z.number().int().positive().optional().describe('1-based page number (view flags).'),
+        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;
+        if (view === 'flag_detail' && args.flag_id === undefined) {
+            return {
+                error: {
+                    code: 'INVALID_SELECTOR',
+                    message: "view 'flag_detail' requires `flag_id` — the flag to retrieve.",
+                    status: 0,
+                },
+            };
+        }
+        if (view === 'fee_breakdown' && args.period === undefined) {
+            return {
+                error: {
+                    code: 'INVALID_SELECTOR',
+                    message: "view 'fee_breakdown' requires `period` — the billing month, YYYY-MM.",
+                    status: 0,
+                },
+            };
+        }
+        let result;
+        if (view === 'flags') {
+            result = await client.get('/stream-radar/flags', {
+                page: args.page,
+                per_page: args.per_page,
+                filter: args.filters,
+            });
+        }
+        else if (view === 'flag_detail') {
+            result = await client.get(`/stream-radar/flags/${args.flag_id}`);
+        }
+        else if (view === 'records') {
+            // The records endpoint takes its filters as top-level query params.
+            result = await client.get('/royalties/artificial-streams', {
+                ...(args.filters ?? {}),
+                cursor: args.cursor,
+                per_page: args.per_page,
+            });
+        }
+        else {
+            result = await client.get(`/artificial-streaming-fee/${encodeURIComponent(String(args.period))}`);
+        }
+        return applyProjection(result, 'query_artificial_streaming', args.response_format);
+    },
+};
+export const insightsTools = [getAnalytics, queryArtificialStreaming];

package/dist/tools/reference.js

@@ -1,36 +1,21 @@
 /** Reference toolset: one tool serving all read-only lookup datasets. */
 import { z } from 'zod';
-/** Maps the public `type` selector to its reference endpoint. */
-const REFERENCE_PATHS = {
-    genres: '/genres',
-    genre_categories: '/genre-categories',
-    languages: '/languages',
-    contributor_roles: '/contributor-roles',
-    instruments: '/instruments',
-    distro_outlets: '/distro-outlets',
-    territories: '/territories',
-};
+import { REFERENCE_DATASETS, REFERENCE_TYPES } from '../resources.js';
 const listReferenceData = {
     name: 'list_reference_data',
     toolset: 'reference',
     gate: 'read',
     title: 'List reference data',
-    description: 'Fetch a LabelGrid reference dataset used to resolve the IDs and codes that catalog and release tools expect. Pick ONE dataset with `type`: ' +
-        '`genres` and `genre_categories` (values for primary/secondary/tertiary genre IDs), `languages` (audio and metadata language codes), ' +
-        '`contributor_roles` (valid role names for track contributors), `instruments`, `distro_outlets` (the distribution outlets/stores available to your account), ' +
-        'or `territories` (country/territory codes). Call this before creating or updating a release or track when you need a valid ID or code.',
+    description: 'Fetch a LabelGrid reference dataset used to resolve the IDs and codes the catalog and release tools expect. Pick ONE dataset with `type`: ' +
+        '`genres` and `genre_categories` (genre IDs), `languages` (audio/metadata language codes), `contributor_roles`, `instruments`, `distro_outlets` (the outlets/stores available to your account), ' +
+        '`territories` (country codes), `issue_definitions` (each review issue code’s title, description, severity and whether it blocks distribution; codes are string slugs), ' +
+        'or `webhook_event_types` (every webhook event type with its payload schema). ' +
+        'Call this when you need a valid ID or code. ' +
+        'The same datasets are exposed as MCP resources at labelgrid://reference/{type}; this tool is the fallback for clients that don’t surface resources.',
     inputShape: {
-        type: z.enum([
-            'genres',
-            'genre_categories',
-            'languages',
-            'contributor_roles',
-            'instruments',
-            'distro_outlets',
-            'territories',
-        ]),
+        type: z.enum(REFERENCE_TYPES),
     },
     annotations: { readOnlyHint: true },
-    handler: (args, { client }) => client.get(REFERENCE_PATHS[args.type]),
+    handler: (args, { client }) => client.get(REFERENCE_DATASETS[args.type].path),
 };
 export const referenceTools = [listReferenceData];

package/dist/tools/releases.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Releases toolset: release-level reads (review results, the delivery queue,
+ * the smart-link landing config, track licenses) plus the safe-write release
+ * checks, landing-page management and review-issue notes.
+ *
+ * The two [proj] reads (`get_release_review`, `get_delivery_queue`) default to
+ * concise-mode projection; `response_format: 'detailed'` returns the verbatim
+ * API response.
+ */
+import type { ToolDef } from './types.js';
+export declare const releaseTools: ToolDef[];