@labelgrid/mcp 0.2.2 → 0.3.0

package/dist/server.js

@@ -9,9 +9,11 @@
  * protocol errors).
  */
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { defaultExcludedToolsets } from './config.js';
 import { isToolEnabled } from './gating.js';
 import { DATA_HANDLING_NOTE, FULL_WRITES_NOTICE, LEGAL_SUMMARY } from './legal.js';
 import { log } from './log.js';
+import { registerReferenceResources } from './resources.js';
 import { setupTools } from './tools/setup.js';
 import { toToolResult } from './tools/types.js';
 import { VERSION } from './version.js';
@@ -51,10 +53,14 @@ export function buildServer(config, client, tools) {
     for (const tool of registered) {
         const isSetupHelper = tool.toolset === 'setup';
         // Listing rule: connected mode applies the full gate matrix; setup mode
-        // lists the whole catalog (only honoring an explicit toolset narrowing),
-        // because nothing can execute without a token anyway.
+        // lists the whole catalog (honoring an explicit toolset narrowing, and
+        // otherwise the same default exclusion the connected surface applies — so
+        // the advertised surface matches reality), because nothing can execute
+        // without a token anyway.
         const listable = config.setupMode
-            ? config.toolsets === null || config.toolsets.has(tool.toolset)
+            ? config.toolsets === null
+                ? !defaultExcludedToolsets.has(tool.toolset)
+                : config.toolsets.has(tool.toolset)
             : isToolEnabled(tool, config);
         if (!isSetupHelper && !listable)
             continue;
@@ -101,5 +107,19 @@ export function buildServer(config, client, tools) {
             return toToolResult(result);
         });
     }
+    // The nine labelgrid://reference/{type} resources follow the SAME listing
+    // rule as the reference tools: they are registered only when the `reference`
+    // toolset is enabled. Reference is not default-excluded, so an unset
+    // LABELGRID_TOOLSETS (or one naming `reference`) registers them; an explicit
+    // selection omitting `reference` disables them. Setup mode keeps them
+    // registered-but-inert under the same rule (reads return NOT_CONNECTED).
+    const referenceEnabled = config.setupMode
+        ? config.toolsets === null
+            ? !defaultExcludedToolsets.has('reference')
+            : config.toolsets.has('reference')
+        : isToolEnabled({ gate: 'read', toolset: 'reference' }, config);
+    if (referenceEnabled) {
+        registerReferenceResources(server, config, client);
+    }
     return server;
 }

package/dist/tools/account.d.ts

@@ -0,0 +1,3 @@
+/** Account toolset: read the authenticated account, revoke API tokens. */
+import type { ToolDef } from './types.js';
+export declare const accountTools: ToolDef[];

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 registry in `src/entities.ts`.
+ * 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,267 @@
+/**
+ * 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 registry in `src/entities.ts`.
+ * 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 { z } from 'zod';
+import { assertAllowedExtension } from '../api/content-types.js';
+import { ENTITIES, ENTITY_NAMES } from '../entities.js';
+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[];