@labelgrid/mcp 0.1.0

package/dist/coverage.js

@@ -0,0 +1,150 @@
+/**
+ * The endpoint-coverage manifest, consumed by the API-coverage drift check.
+ *
+ * `COVERAGE` maps every public endpoint (method + path) this server exposes as a
+ * tool to that tool's name. `EXCLUDED` lists public endpoints deliberately not
+ * exposed in v1, each with a short customer-appropriate reason. `PENDING_DOCS`
+ * lists tool endpoints whose reference documentation is still being generated
+ * (the drift check tolerates their absence from the API document snapshot).
+ *
+ * The drift check fails when the live API document contains a path+method that
+ * is neither covered nor excluded — the signal to add a tool (or an exclusion)
+ * in the same cycle the API grows.
+ *
+ * Keys use the API document's exact path templates (e.g. `{release}`) and an
+ * uppercase method followed by a single space.
+ */
+export const COVERAGE = {
+    // identity
+    'GET /me': 'get_me',
+    'DELETE /tokens/current': 'revoke_api_token',
+    'DELETE /tokens/{tokenId}': 'revoke_api_token',
+    // reference
+    'GET /genres': 'list_reference_data',
+    'GET /genre-categories': 'list_reference_data',
+    'GET /languages': 'list_reference_data',
+    'GET /contributor-roles': 'list_reference_data',
+    'GET /instruments': 'list_reference_data',
+    'GET /distro-outlets': 'list_reference_data',
+    'GET /territories': 'list_reference_data',
+    // analytics
+    'GET /analytics/summary': 'get_analytics',
+    // catalog reads
+    'GET /labels': 'list_labels',
+    'GET /labels/{label}': 'get_label',
+    'GET /artists': 'list_artists',
+    'GET /artists/{artist}': 'get_artist',
+    'GET /writers': 'list_writers',
+    'GET /writers/{writer}': 'get_writer',
+    'GET /publishers': 'list_publishers',
+    'GET /publishers/{publisher}': 'get_publisher',
+    'GET /releases': 'list_releases',
+    'GET /releases/{release}': 'get_release',
+    'GET /tracks': 'list_tracks',
+    'GET /tracks/{track}': 'get_track',
+    // files reads
+    'GET /tracks/{track}/files/{fileType}': 'get_track_file',
+    'GET /tracks/{track}/licenses': 'list_track_licenses',
+    'GET /tracks/{track}/licenses/{trackLicense}': 'get_track_license',
+    'GET /releases/{release}/files/{assetType}': 'get_release_file',
+    // review reads
+    'GET /review-issues': 'list_review_issues',
+    'GET /issue-definitions': 'list_issue_definitions',
+    'GET /releases/{release}/quality-report': 'get_quality_report',
+    'GET /stream-radar/flags': 'list_stream_radar_flags',
+    'GET /stream-radar/flags/{streamRadarFlag}': 'get_stream_radar_flag',
+    // delivery
+    'GET /queues/distro': 'get_delivery_queue',
+    'GET /releases/{release}/landing-config': 'get_landing_config',
+    // accounting
+    'GET /statements': 'list_statements',
+    'GET /statements/{invoiceNumber}': 'get_statement',
+    'GET /statements/{invoiceNumber}/csv': 'download_statement_csv',
+    'GET /statements/export/csv': 'download_statement_csv',
+    'GET /statements/{invoiceNumber}/invoice': 'download_statement_invoice',
+    'GET /transactions': 'list_transactions',
+    'GET /royalties/breakdown': 'get_royalties_breakdown',
+    'GET /royalties/artificial-streams': 'list_artificial_streams',
+    'GET /artificial-streaming-fee/{period}': 'get_artificial_fee_breakdown',
+    // webhooks
+    'GET /webhooks': 'list_webhooks',
+    'POST /webhooks': 'create_webhook',
+    'GET /webhooks/event-types': 'list_webhook_event_types',
+    'GET /webhooks/{webhook}': 'get_webhook',
+    'PATCH /webhooks/{webhook}': 'update_webhook',
+    'DELETE /webhooks/{webhook}': 'delete_webhook',
+    'GET /webhooks/{webhook}/logs': 'get_webhook_logs',
+    'POST /webhooks/{webhook}/regenerate-secret': 'rotate_webhook_secret',
+    'POST /webhooks/{webhook}/test': 'test_webhook',
+    // catalog writes
+    'POST /labels': 'create_label',
+    'PATCH /labels/{label}': 'update_label',
+    'DELETE /labels/{label}': 'delete_label',
+    'POST /labels/{label}/images/{imageType}': 'upload_label_image',
+    'POST /artists': 'create_artist',
+    'PATCH /artists/{artist}': 'update_artist',
+    'DELETE /artists/{artist}': 'delete_artist',
+    'POST /artists/{artist}/photo': 'upload_artist_photo',
+    'POST /writers': 'create_writer',
+    'PATCH /writers/{writer}': 'update_writer',
+    'DELETE /writers/{writer}': 'delete_writer',
+    'POST /publishers': 'create_publisher',
+    'PATCH /publishers/{publisher}': 'update_publisher',
+    'DELETE /publishers/{publisher}': 'delete_publisher',
+    // release/track draft writes
+    'POST /releases': 'create_release',
+    'PATCH /releases/{release}': 'update_release',
+    'DELETE /releases/{release}': 'delete_release',
+    'POST /tracks': 'create_track',
+    'PATCH /tracks/{track}': 'update_track',
+    'DELETE /tracks/{track}': 'delete_track',
+    'POST /releases/{release}/validate': 'validate_release',
+    'POST /releases/{release}/quality-report/refresh': 'refresh_quality_report',
+    'PUT /releases/{release}/landing-config': 'update_landing_config',
+    'POST /releases/short-url': 'create_release_short_url',
+    'POST /review-issues/{reviewReleaseIssue}/notes': 'add_review_issue_note',
+    // full writes (distribution)
+    'POST /tracks/{track}/files/{fileType}/upload-url': 'upload_track_audio',
+    'PUT /tracks/{track}/files/{fileType}': 'upload_track_audio',
+    'DELETE /tracks/{track}/files/{fileType}': 'delete_track_audio',
+    'POST /releases/{release}/files/{assetType}/upload-url': 'upload_release_asset',
+    'PUT /releases/{release}/files/{assetType}': 'upload_release_asset',
+    'DELETE /releases/{release}/files/{assetType}': 'delete_release_asset',
+    'POST /tracks/{track}/licenses': 'upload_track_license',
+    'POST /tracks/{track}/licenses/{trackLicense}': 'update_track_license',
+    'DELETE /tracks/{track}/licenses/{trackLicense}': 'delete_track_license',
+    'POST /releases/{release}/photo': 'upload_release_artwork',
+    'POST /releases/{release}/distribute': 'distribute_release',
+    'POST /releases/{release}/takedown-all': 'takedown_release',
+    'POST /releases/{release}/confirm-review': 'confirm_review',
+    'POST /labels/{label}/enable-beatport': 'enable_beatport',
+};
+export const EXCLUDED = {
+    // The per-metric analytics endpoints are all served by get_analytics.
+    'GET /analytics/streams': 'served by get_analytics (summary)',
+    'GET /analytics/listeners': 'served by get_analytics (summary)',
+    'GET /analytics/saves': 'served by get_analytics (summary)',
+    'GET /analytics/skips': 'served by get_analytics (summary)',
+    'GET /analytics/shares': 'served by get_analytics (summary)',
+    'GET /analytics/completion-rate': 'served by get_analytics (summary)',
+    'GET /analytics/lyrics-view-rate': 'served by get_analytics (summary)',
+    'GET /analytics/canvas-view-rate': 'served by get_analytics (summary)',
+    'GET /analytics/device-split': 'served by get_analytics (summary)',
+    'GET /analytics/source-split': 'served by get_analytics (summary)',
+    'GET /analytics/saves-by-tier': 'served by get_analytics (summary)',
+    'GET /analytics/streams-by-country': 'served by get_analytics (summary)',
+    'GET /analytics/streams-by-gender': 'served by get_analytics (summary)',
+    'GET /analytics/streams-by-age': 'served by get_analytics (summary)',
+    'GET /analytics/shares-by-country': 'served by get_analytics (summary)',
+    // Alternate/adjacent surfaces intentionally not exposed in v1.
+    'POST /releases/{release}/withdraw-review': 'withdraw-review flow — not exposed in v1',
+    'GET /resolve/label/{labelSlug}': 'label-website resolution — not exposed in v1',
+    'GET /site-settings/{label}': 'label-website settings — not exposed in v1',
+    'GET /site-settings/links/{label}': 'label-website settings — not exposed in v1',
+    'GET /tracks/{track}/licenses/{trackLicense}/download': 'license file download — not exposed in v1',
+    'GET /transactions/csv': 'transaction CSV export — not exposed in v1',
+};
+export const PENDING_DOCS = {
+    'GET /account': 'get_account_summary',
+    'GET /tracks/{track}/files/{assetType}/download-url': 'get_track_audio_download_url',
+};

package/dist/gating.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Fail-closed tool gating.
+ *
+ * A tool is enabled only when its toolset is selected AND its gate's write
+ * class is armed. Anything the matrix cannot positively resolve — including an
+ * unrecognized gate — is disabled.
+ */
+import type { Config } from './config.js';
+export type Gate = 'read' | 'safe_write' | 'full_write';
+export declare function isToolEnabled(t: {
+    gate: Gate;
+    toolset: string;
+}, c: Config): boolean;

package/dist/gating.js

@@ -0,0 +1,22 @@
+/**
+ * Fail-closed tool gating.
+ *
+ * A tool is enabled only when its toolset is selected AND its gate's write
+ * class is armed. Anything the matrix cannot positively resolve — including an
+ * unrecognized gate — is disabled.
+ */
+export function isToolEnabled(t, c) {
+    const toolsetSelected = c.toolsets === null || c.toolsets.has(t.toolset);
+    if (!toolsetSelected)
+        return false;
+    switch (t.gate) {
+        case 'read':
+            return true;
+        case 'safe_write':
+            return c.writes;
+        case 'full_write':
+            return c.fullWrites;
+        default:
+            return false;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * Entrypoint: env → config → client → server → stdio.
+ *
+ * A configuration problem (missing token, etc.) prints an actionable message
+ * to stderr and exits 1. Otherwise the server connects over the stdio
+ * transport; stdout carries the MCP protocol only, all logging goes to stderr.
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+/**
+ * Entrypoint: env → config → client → server → stdio.
+ *
+ * A configuration problem (missing token, etc.) prints an actionable message
+ * to stderr and exits 1. Otherwise the server connects over the stdio
+ * transport; stdout carries the MCP protocol only, all logging goes to stderr.
+ */
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { LabelGridClient } from './api/http.js';
+import { ConfigError, loadConfig } from './config.js';
+import { isToolEnabled } from './gating.js';
+import { FULL_WRITES_NOTICE, LEGAL_SUMMARY } from './legal.js';
+import { log } from './log.js';
+import { buildServer } from './server.js';
+import { accountingTools } from './tools/accounting.js';
+import { analyticsTools } from './tools/analytics.js';
+import { catalogReadTools } from './tools/catalog-read.js';
+import { catalogWriteTools } from './tools/catalog-write.js';
+import { deliveryTools } from './tools/delivery.js';
+import { filesReadTools } from './tools/files-read.js';
+import { fullWriteTools } from './tools/full-writes.js';
+import { identityTools } from './tools/identity.js';
+import { referenceTools } from './tools/reference.js';
+import { releaseWriteTools } from './tools/release-write.js';
+import { reviewReadTools } from './tools/review-read.js';
+import { webhookTools } from './tools/webhooks.js';
+import { VERSION } from './version.js';
+function allTools() {
+    return [
+        ...identityTools,
+        ...referenceTools,
+        ...analyticsTools,
+        ...catalogReadTools,
+        ...filesReadTools,
+        ...reviewReadTools,
+        ...deliveryTools,
+        ...accountingTools,
+        ...webhookTools,
+        ...catalogWriteTools,
+        ...releaseWriteTools,
+        ...fullWriteTools,
+    ];
+}
+async function main() {
+    let config;
+    try {
+        config = loadConfig(process.env);
+    }
+    catch (err) {
+        if (err instanceof ConfigError) {
+            log('error', err.message);
+            process.exit(1);
+        }
+        throw err;
+    }
+    // In setup mode the token is null and never used; the placeholder keeps the
+    // client type intact while no API calls are possible.
+    const client = new LabelGridClient({
+        baseUrl: config.baseUrl,
+        token: config.token ?? '',
+        version: VERSION,
+    });
+    if (config.setupMode) {
+        const server = buildServer(config, client, []);
+        log('info', `labelgrid-mcp v${VERSION} — setup mode (no API token configured); call the "setup" tool for guided setup`);
+        log('info', LEGAL_SUMMARY);
+        await server.connect(new StdioServerTransport());
+        return;
+    }
+    const tools = allTools();
+    const server = buildServer(config, client, tools);
+    const enabled = tools.filter((t) => isToolEnabled(t, config)).length;
+    log('info', `labelgrid-mcp v${VERSION} — ${enabled} tools enabled (writes: ${config.writes ? 'on' : 'off'}, full-writes: ${config.fullWrites ? 'on' : 'off'})`);
+    log('info', LEGAL_SUMMARY);
+    if (config.fullWrites) {
+        log('warn', FULL_WRITES_NOTICE);
+    }
+    await server.connect(new StdioServerTransport());
+}
+main().catch((err) => {
+    log('error', 'fatal error starting labelgrid-mcp', {
+        message: err instanceof Error ? err.message : String(err),
+    });
+    process.exit(1);
+});

package/dist/legal.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The legal / acceptable-use disclosure strings, surfaced at runtime in two
+ * places: the MCP `instructions` field (shown by clients on initialize) and
+ * stderr at startup. README.md "Legal notices" carries the same text for
+ * readers who never launch the server.
+ */
+/** The one-paragraph AS-IS summary shown to every session. */
+export declare const LEGAL_SUMMARY = "This software is provided AS-IS, without warranty of any kind, express or implied. By using it you accept sole responsibility for your use of the LabelGrid API and for every action taken by any AI client or agent you connect to this server, including write operations against your LabelGrid account. Your use of the API through this server is governed by the LabelGrid API Terms of Service and Acceptable Use Policy. This server does not bypass server-side protections such as rate limits, plan entitlements, or terms enforcement.";
+/** Shown only when full writes are armed. */
+export declare const FULL_WRITES_NOTICE = "Full writes are enabled. Distribution submissions, takedowns, and immutable file uploads initiated by an AI agent have real, potentially irreversible consequences for your releases on streaming platforms and stores. By setting the LABELGRID_FULL_WRITES_ACK acknowledgment variable you accepted that all such actions are your sole responsibility.";
+/** The data-handling disclosure. */
+export declare const DATA_HANDLING_NOTE = "This server transmits your LabelGrid catalogue and account data to the AI client you configure. Choosing that client, and disclosing that data flow where required, is your responsibility.";

package/dist/legal.js

@@ -0,0 +1,13 @@
+// README.md "Legal notices" mirrors these strings — keep them in sync when editing.
+/**
+ * The legal / acceptable-use disclosure strings, surfaced at runtime in two
+ * places: the MCP `instructions` field (shown by clients on initialize) and
+ * stderr at startup. README.md "Legal notices" carries the same text for
+ * readers who never launch the server.
+ */
+/** The one-paragraph AS-IS summary shown to every session. */
+export const LEGAL_SUMMARY = 'This software is provided AS-IS, without warranty of any kind, express or implied. By using it you accept sole responsibility for your use of the LabelGrid API and for every action taken by any AI client or agent you connect to this server, including write operations against your LabelGrid account. Your use of the API through this server is governed by the LabelGrid API Terms of Service and Acceptable Use Policy. This server does not bypass server-side protections such as rate limits, plan entitlements, or terms enforcement.';
+/** Shown only when full writes are armed. */
+export const FULL_WRITES_NOTICE = 'Full writes are enabled. Distribution submissions, takedowns, and immutable file uploads initiated by an AI agent have real, potentially irreversible consequences for your releases on streaming platforms and stores. By setting the LABELGRID_FULL_WRITES_ACK acknowledgment variable you accepted that all such actions are your sole responsibility.';
+/** The data-handling disclosure. */
+export const DATA_HANDLING_NOTE = 'This server transmits your LabelGrid catalogue and account data to the AI client you configure. Choosing that client, and disclosing that data flow where required, is your responsibility.';

package/dist/log.d.ts

@@ -0,0 +1,16 @@
+/**
+ * stderr-only structured logging with secret redaction.
+ *
+ * stdout is reserved for the MCP protocol stream, so every log line goes to
+ * stderr. Any structured metadata is passed through {@link redactSecrets}
+ * first so tokens, passwords and signed URLs never reach the log.
+ */
+/**
+ * Deep-clones a value, replacing the value of any object key whose name looks
+ * like a secret with a fixed mask. Non-secret values, arrays and primitives are
+ * preserved (arrays and nested objects are walked recursively).
+ */
+export declare function redactSecrets(v: unknown): unknown;
+export type LogLevel = 'info' | 'warn' | 'error';
+/** Writes a single redacted log line to stderr (never stdout). */
+export declare function log(level: LogLevel, msg: string, meta?: unknown): void;

package/dist/log.js

@@ -0,0 +1,35 @@
+/**
+ * stderr-only structured logging with secret redaction.
+ *
+ * stdout is reserved for the MCP protocol stream, so every log line goes to
+ * stderr. Any structured metadata is passed through {@link redactSecrets}
+ * first so tokens, passwords and signed URLs never reach the log.
+ */
+const SECRET_KEY = /token|password|secret|nonce|authorization|key/i;
+const MASK = '***REDACTED***';
+/**
+ * Deep-clones a value, replacing the value of any object key whose name looks
+ * like a secret with a fixed mask. Non-secret values, arrays and primitives are
+ * preserved (arrays and nested objects are walked recursively).
+ */
+export function redactSecrets(v) {
+    if (Array.isArray(v)) {
+        return v.map((item) => redactSecrets(item));
+    }
+    if (v !== null && typeof v === 'object') {
+        const out = {};
+        for (const [key, value] of Object.entries(v)) {
+            out[key] = SECRET_KEY.test(key) ? MASK : redactSecrets(value);
+        }
+        return out;
+    }
+    return v;
+}
+/** Writes a single redacted log line to stderr (never stdout). */
+export function log(level, msg, meta) {
+    let line = `[${level}] ${msg}`;
+    if (meta !== undefined) {
+        line += ` ${JSON.stringify(redactSecrets(meta))}`;
+    }
+    process.stderr.write(`${line}\n`);
+}

package/dist/server.d.ts

@@ -0,0 +1,15 @@
+/**
+ * MCP server construction and gated tool registration.
+ *
+ * Only tools that pass {@link isToolEnabled} are registered. Each handler is
+ * wrapped so it: (1) re-checks its gate at call time (defense in depth — the
+ * registration filter is the first line), (2) runs the one-call handler, (3)
+ * logs the tool name, redacted args and duration to stderr, and (4) shapes the
+ * result via {@link toToolResult} (API errors become isError results, never
+ * protocol errors).
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { LabelGridClient } from './api/http.js';
+import type { Config } from './config.js';
+import { type ToolDef } from './tools/types.js';
+export declare function buildServer(config: Config, client: LabelGridClient, tools: ToolDef[]): McpServer;

package/dist/server.js

@@ -0,0 +1,83 @@
+/**
+ * MCP server construction and gated tool registration.
+ *
+ * Only tools that pass {@link isToolEnabled} are registered. Each handler is
+ * wrapped so it: (1) re-checks its gate at call time (defense in depth — the
+ * registration filter is the first line), (2) runs the one-call handler, (3)
+ * logs the tool name, redacted args and duration to stderr, and (4) shapes the
+ * result via {@link toToolResult} (API errors become isError results, never
+ * protocol errors).
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { isToolEnabled } from './gating.js';
+import { DATA_HANDLING_NOTE, FULL_WRITES_NOTICE, LEGAL_SUMMARY } from './legal.js';
+import { log } from './log.js';
+import { setupTools } from './tools/setup.js';
+import { toToolResult } from './tools/types.js';
+import { VERSION } from './version.js';
+/**
+ * The MCP-native disclosure channel: a concise usage + legal text delivered in
+ * the initialize result's `instructions` field, which clients surface to users.
+ * In setup mode it points the client at the `setup` tool instead.
+ */
+function buildInstructions(config) {
+    if (config.setupMode) {
+        return [
+            'No LabelGrid API token is configured, so the account is not connected yet. ' +
+                'Call the `setup` tool for step-by-step instructions to connect. No account ' +
+                'data can be accessed in this state.',
+            LEGAL_SUMMARY,
+        ].join('\n\n');
+    }
+    const parts = [
+        'Official LabelGrid MCP server — your AI client can read and manage this LabelGrid ' +
+            'account via the public API.',
+        LEGAL_SUMMARY,
+        DATA_HANDLING_NOTE,
+    ];
+    if (config.fullWrites)
+        parts.push(FULL_WRITES_NOTICE);
+    return parts.join('\n\n');
+}
+export function buildServer(config, client, tools) {
+    const server = new McpServer({ name: 'labelgrid-mcp', version: VERSION }, { instructions: buildInstructions(config) });
+    // In setup mode ONLY the setup helper is registered — the account is not
+    // connected, so none of the API-backed tools are exposed.
+    const registered = config.setupMode ? setupTools : tools;
+    for (const tool of registered) {
+        if (!isToolEnabled(tool, config))
+            continue;
+        server.registerTool(tool.name, {
+            title: tool.title,
+            description: tool.description,
+            inputSchema: tool.inputShape,
+            annotations: { title: tool.title, ...tool.annotations },
+        }, async (args) => {
+            // Defense in depth: even a registered tool re-verifies its gate.
+            if (!isToolEnabled(tool, config)) {
+                return toToolResult({
+                    error: {
+                        code: 'TOOL_DISABLED',
+                        message: `Tool "${tool.name}" is not enabled in the current configuration.`,
+                        status: 0,
+                    },
+                });
+            }
+            const startedAt = Date.now();
+            let result;
+            try {
+                result = await tool.handler(args ?? {}, { client, config });
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : 'An unexpected error occurred.';
+                log('error', `tool ${tool.name} threw`, { message });
+                return toToolResult({
+                    error: { code: 'UNEXPECTED_ERROR', message, status: 0 },
+                });
+            }
+            log('info', `tool ${tool.name}`, { args: args ?? {}, duration_ms: Date.now() - startedAt });
+            return toToolResult(result);
+        });
+    }
+    return server;
+}

package/dist/tools/accounting.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Accounting toolset: statements, transactions, royalty breakdowns,
+ * artificial-streaming records, and the account summary. All read-only.
+ *
+ * Two tools (`download_statement_csv`, `download_statement_invoice`) fetch a
+ * file body. They validate the caller-supplied `save_to_path` and write ONLY
+ * there; a CSV without a save path is returned inline, truncated at 100KB.
+ * These 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 accountingTools: ToolDef[];