@labelgrid/mcp 0.1.0

package/dist/api/http.js

@@ -0,0 +1,345 @@
+/**
+ * The single typed HTTP client for the LabelGrid public API.
+ *
+ * Every tool goes through this client. It owns transport, header injection,
+ * query serialization, optional idempotency keys and — critically — error
+ * normalization: HTTP failures are turned into a structured {@link ApiError}
+ * and returned, never thrown. Business rules live server-side; this file is
+ * transport only (no retries, no queues).
+ */
+import { randomUUID } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { contentType } from './content-types.js';
+/** Hard ceiling on a single response body, in bytes/characters. */
+const MAX_RESPONSE_BYTES = 10_000_000;
+const TOKEN_SUGGESTION = 'Check LABELGRID_API_TOKEN — create a new token in your dashboard under Profile → API Tokens.';
+/**
+ * Serializes a query object into a URL search string, supporting nested
+ * `filter[label_id]=5` objects and repeated `metrics[]=a&metrics[]=b` arrays.
+ * Null/undefined values are skipped. Bracket structure is kept literal; only
+ * key names and values are percent-encoded.
+ */
+function buildQuery(query) {
+    if (!query)
+        return '';
+    const parts = [];
+    const push = (rawKey, value) => {
+        if (value === undefined || value === null)
+            return;
+        parts.push(`${rawKey}=${encodeURIComponent(String(value))}`);
+    };
+    for (const [key, value] of Object.entries(query)) {
+        if (value === undefined || value === null)
+            continue;
+        const ek = encodeURIComponent(key);
+        if (Array.isArray(value)) {
+            for (const item of value)
+                push(`${ek}[]`, item);
+        }
+        else if (typeof value === 'object') {
+            for (const [subKey, subValue] of Object.entries(value)) {
+                const esk = encodeURIComponent(subKey);
+                if (Array.isArray(subValue)) {
+                    for (const item of subValue)
+                        push(`${ek}[${esk}][]`, item);
+                }
+                else {
+                    push(`${ek}[${esk}]`, subValue);
+                }
+            }
+        }
+        else {
+            push(ek, value);
+        }
+    }
+    return parts.length > 0 ? `?${parts.join('&')}` : '';
+}
+/**
+ * Extracts a code/message/errors triple from any of the four backend error body
+ * shapes: `{message}`, `{error: string}`, `{errors}`, `{error: {code, message}}`.
+ */
+function extractServerError(body) {
+    if (typeof body === 'string') {
+        return { message: body };
+    }
+    if (body === null || typeof body !== 'object') {
+        return {};
+    }
+    const record = body;
+    const errors = record.errors;
+    const errorsStructured = record.errors_structured;
+    // Shape: { error: { code, message } }
+    if (record.error !== null && typeof record.error === 'object') {
+        const nested = record.error;
+        return {
+            code: typeof nested.code === 'string' ? nested.code : undefined,
+            message: typeof nested.message === 'string'
+                ? nested.message
+                : typeof nested.error === 'string'
+                    ? nested.error
+                    : undefined,
+            errors,
+            errors_structured: errorsStructured,
+        };
+    }
+    // Shape: { error: 'string' }
+    if (typeof record.error === 'string') {
+        return {
+            code: typeof record.code === 'string' ? record.code : undefined,
+            message: record.error,
+            errors,
+            errors_structured: errorsStructured,
+        };
+    }
+    // Shapes: { message } and/or { errors } and/or top-level { code }
+    const parts = {
+        code: typeof record.code === 'string' ? record.code : undefined,
+        message: typeof record.message === 'string' ? record.message : undefined,
+        field: typeof record.field === 'string' ? record.field : undefined,
+        errors,
+        errors_structured: errorsStructured,
+    };
+    // Derive a message from the first validation error when none was given.
+    if (parts.message === undefined && errors !== null && typeof errors === 'object') {
+        const first = Object.values(errors)[0];
+        if (Array.isArray(first) && typeof first[0] === 'string') {
+            parts.message = first[0];
+        }
+        else if (typeof first === 'string') {
+            parts.message = first;
+        }
+    }
+    return parts;
+}
+function parseRetryAfter(res) {
+    const raw = res.headers.get('Retry-After');
+    if (raw === null)
+        return undefined;
+    const seconds = Number.parseInt(raw, 10);
+    return Number.isNaN(seconds) ? undefined : seconds;
+}
+/** Normalizes a non-2xx HTTP response into a structured {@link ApiError}. */
+function normalizeError(res, body) {
+    const server = extractServerError(body);
+    const status = res.status;
+    const withCommon = (code, message, extra = {}) => ({
+        code,
+        message,
+        status,
+        ...(server.field !== undefined ? { field: server.field } : {}),
+        ...(server.errors !== undefined ? { errors: server.errors } : {}),
+        ...extra,
+    });
+    switch (status) {
+        case 401:
+            return withCommon('TOKEN_INVALID', server.message ?? 'Your API token was rejected.', {
+                suggestion: TOKEN_SUGGESTION,
+            });
+        case 403:
+            return withCommon(server.code ?? 'FORBIDDEN', server.message ?? 'Forbidden.');
+        case 404:
+            return withCommon('NOT_FOUND', server.message ?? 'The requested resource was not found.');
+        case 409:
+            return withCommon(server.code ?? 'CONFLICT', server.message ?? 'The request conflicts with the current state.');
+        case 422:
+            return withCommon('VALIDATION_FAILED', server.message ?? 'The submitted data was invalid.', {
+                ...(server.errors_structured !== undefined
+                    ? { errors_structured: server.errors_structured }
+                    : {}),
+            });
+        case 429: {
+            const retryAfter = parseRetryAfter(res);
+            return withCommon('RATE_LIMITED', server.message ?? 'Rate limit exceeded.', {
+                ...(retryAfter !== undefined ? { retry_after_seconds: retryAfter } : {}),
+            });
+        }
+        default:
+            if (status >= 500) {
+                return withCommon('SERVER_ERROR', server.message ?? 'The server encountered an error.');
+            }
+            return withCommon(server.code ?? 'ERROR', server.message ?? `Request failed with status ${status}.`);
+    }
+}
+export class LabelGridClient {
+    baseUrl;
+    token;
+    fetchFn;
+    version;
+    constructor(opts) {
+        this.baseUrl = opts.baseUrl.replace(/\/+$/, '');
+        this.token = opts.token;
+        this.fetchFn = opts.fetchFn ?? fetch;
+        this.version = opts.version;
+    }
+    authHeaders() {
+        return {
+            Authorization: `Bearer ${this.token}`,
+            Accept: 'application/json',
+            'User-Agent': `labelgrid-mcp/${this.version}`,
+        };
+    }
+    async send(method, path, opts = {}) {
+        const url = `${this.baseUrl}${path}${buildQuery(opts.query)}`;
+        const headers = { ...this.authHeaders(), ...opts.headers };
+        if (opts.idempotency) {
+            // A caller-supplied key is used verbatim (so a caller can dedupe a retry
+            // across separate tool calls); otherwise a fresh UUID is generated.
+            headers['Idempotency-Key'] = opts.idempotencyKey ?? randomUUID();
+        }
+        const init = { method, headers };
+        if (opts.rawBody !== undefined) {
+            init.body = opts.rawBody;
+        }
+        else if (opts.body !== undefined) {
+            headers['Content-Type'] = 'application/json';
+            init.body = JSON.stringify(opts.body);
+        }
+        let res;
+        try {
+            res = await this.fetchFn(url, init);
+        }
+        catch (err) {
+            return {
+                error: {
+                    code: 'NETWORK_ERROR',
+                    message: err instanceof Error ? err.message : 'Network request failed.',
+                    status: 0,
+                },
+            };
+        }
+        // Cheap pre-check: bound the response before reading when the length is known.
+        const declaredLength = Number.parseInt(res.headers.get('Content-Length') ?? '', 10);
+        if (!Number.isNaN(declaredLength) && declaredLength > MAX_RESPONSE_BYTES) {
+            return {
+                error: {
+                    code: 'RESPONSE_TOO_LARGE',
+                    message: `The response is ${declaredLength} bytes, over the ${MAX_RESPONSE_BYTES}-byte limit. Narrow the request with pagination or filters.`,
+                    status: res.status,
+                },
+            };
+        }
+        const tooLarge = {
+            error: {
+                code: 'RESPONSE_TOO_LARGE',
+                message: `The response body exceeds the ${MAX_RESPONSE_BYTES}-byte limit. Narrow the request with pagination or filters.`,
+                status: res.status,
+            },
+        };
+        // A chunked/streamed response carries no Content-Length, so bound it AS we
+        // read: accumulate chunks with a running byte counter and abort the moment
+        // the counter crosses the ceiling — never buffering the whole oversized body.
+        let text;
+        if (res.body) {
+            const reader = res.body.getReader();
+            const chunks = [];
+            let total = 0;
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                if (value) {
+                    total += value.byteLength;
+                    if (total > MAX_RESPONSE_BYTES) {
+                        // cancel() can reject (e.g. an already-errored stream); swallow it so
+                        // an oversized response ALWAYS returns RESPONSE_TOO_LARGE.
+                        try {
+                            await reader.cancel();
+                        }
+                        catch {
+                            // best-effort cleanup — the size bound is what matters here.
+                        }
+                        return tooLarge;
+                    }
+                    chunks.push(value);
+                }
+            }
+            const merged = new Uint8Array(total);
+            let offset = 0;
+            for (const chunk of chunks) {
+                merged.set(chunk, offset);
+                offset += chunk.byteLength;
+            }
+            text = new TextDecoder('utf-8').decode(merged);
+        }
+        else {
+            // No readable stream (some test stubs) — fall back to text() and measure
+            // the true byte length as a backstop (multi-byte chars exceed char count).
+            text = await res.text();
+            if (Buffer.byteLength(text, 'utf8') > MAX_RESPONSE_BYTES) {
+                return tooLarge;
+            }
+        }
+        let body = null;
+        if (text.length > 0) {
+            try {
+                body = JSON.parse(text);
+            }
+            catch {
+                body = text;
+            }
+        }
+        if (res.ok) {
+            return { data: body };
+        }
+        return { error: normalizeError(res, body) };
+    }
+    get(path, query) {
+        return this.send('GET', path, { query });
+    }
+    post(path, body, opts) {
+        return this.send('POST', path, {
+            body,
+            idempotency: opts?.idempotency,
+            idempotencyKey: opts?.idempotencyKey,
+        });
+    }
+    patch(path, body) {
+        return this.send('PATCH', path, { body });
+    }
+    put(path, body, opts) {
+        return this.send('PUT', path, {
+            body,
+            idempotency: opts?.idempotency,
+            idempotencyKey: opts?.idempotencyKey,
+        });
+    }
+    delete(path) {
+        return this.send('DELETE', path);
+    }
+    /**
+     * Sends a multipart/form-data POST with a single file field plus optional
+     * extra string fields. A missing/unreadable file yields a FILE_NOT_FOUND
+     * error result rather than throwing.
+     */
+    async postMultipart(path, filePath, fieldName, extra) {
+        let bytes;
+        try {
+            bytes = await readFile(filePath);
+        }
+        catch (err) {
+            return {
+                error: {
+                    code: 'FILE_NOT_FOUND',
+                    message: `Could not read file at ${filePath}: ${err instanceof Error ? err.message : 'unknown error'}`,
+                    status: 0,
+                },
+            };
+        }
+        const form = new FormData();
+        form.append(fieldName, new Blob([new Uint8Array(bytes)], { type: contentType(filePath) }), basename(filePath));
+        for (const [key, value] of Object.entries(extra ?? {})) {
+            form.append(key, value);
+        }
+        // Let fetch set the multipart Content-Type boundary; do not override it.
+        return this.send('POST', path, { rawBody: form });
+    }
+    /**
+     * Performs a raw request with NO Authorization header — used for presigned
+     * upload PUTs, where the signed URL is already the credential and an extra
+     * Bearer token would break the signature.
+     */
+    raw(url, init) {
+        return this.fetchFn(url, init);
+    }
+}

package/dist/api/upload.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Presigned-URL upload helper.
+ *
+ * A large binary asset is never streamed through the LabelGrid API. Instead the
+ * flow is three steps:
+ *   1. POST the upload-url endpoint (with the filename) to mint a short-lived
+ *      presigned storage URL and its object key.
+ *   2. PUT the file bytes straight to that presigned URL. This request carries
+ *      NO Authorization header — the signature in the URL is the credential, and
+ *      an extra Bearer token would break it.
+ *   3. PUT the commit endpoint with the returned object key (with an idempotency
+ *      key) so the API records the finalized file.
+ *
+ * A failure at step 2 aborts before the commit, so a half-uploaded object is
+ * never finalized. Business rules (format checks, transcoding) stay server-side.
+ */
+import type { ApiResult, LabelGridClient } from './http.js';
+export type UploadOptions = {
+    /** The endpoint that mints the presigned URL, e.g. /tracks/42/files/stereo/upload-url. */
+    uploadUrlPath: string;
+    /** The endpoint that records the finalized file, e.g. /tracks/42/files/stereo. */
+    commitPath: string;
+    /** Absolute or relative local path to the file to upload. */
+    filePath: string;
+};
+export declare function uploadViaPresignedUrl(client: LabelGridClient, opts: UploadOptions): Promise<ApiResult<unknown>>;

package/dist/api/upload.js

@@ -0,0 +1,104 @@
+/**
+ * Presigned-URL upload helper.
+ *
+ * A large binary asset is never streamed through the LabelGrid API. Instead the
+ * flow is three steps:
+ *   1. POST the upload-url endpoint (with the filename) to mint a short-lived
+ *      presigned storage URL and its object key.
+ *   2. PUT the file bytes straight to that presigned URL. This request carries
+ *      NO Authorization header — the signature in the URL is the credential, and
+ *      an extra Bearer token would break it.
+ *   3. PUT the commit endpoint with the returned object key (with an idempotency
+ *      key) so the API records the finalized file.
+ *
+ * A failure at step 2 aborts before the commit, so a half-uploaded object is
+ * never finalized. Business rules (format checks, transcoding) stay server-side.
+ */
+import { statSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { log } from '../log.js';
+import { contentType } from './content-types.js';
+/** True only for an existing regular file. */
+function isReadableFile(p) {
+    try {
+        return statSync(p).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+export async function uploadViaPresignedUrl(client, opts) {
+    // Fail fast and locally: never touch the network for a file we cannot read.
+    if (!isReadableFile(opts.filePath)) {
+        const error = {
+            code: 'FILE_NOT_FOUND',
+            message: `No readable file at ${opts.filePath}.`,
+            status: 0,
+        };
+        return { error };
+    }
+    // Step 1: mint the presigned URL.
+    const minted = await client.post(opts.uploadUrlPath, {
+        filename: basename(opts.filePath),
+    });
+    if ('error' in minted)
+        return minted;
+    const uploadUrl = minted.data?.upload_url;
+    const key = minted.data?.key;
+    if (typeof uploadUrl !== 'string' || typeof key !== 'string') {
+        const error = {
+            code: 'UPLOAD_URL_INVALID',
+            message: 'The upload-url response did not contain a usable upload_url and key.',
+            status: 0,
+        };
+        return { error };
+    }
+    // Step 2: PUT the bytes directly to storage — NO auth header (the URL is signed).
+    // The file passed isReadableFile above, but it can vanish before this read
+    // (a TOCTOU race); a structured FILE_NOT_FOUND is the contract, not a throw.
+    let bytes;
+    try {
+        bytes = await readFile(opts.filePath);
+    }
+    catch {
+        const error = {
+            code: 'FILE_NOT_FOUND',
+            message: `The file at ${opts.filePath} could not be read.`,
+            status: 0,
+        };
+        return { error };
+    }
+    let putRes;
+    try {
+        putRes = await client.raw(uploadUrl, {
+            method: 'PUT',
+            headers: { 'Content-Type': contentType(opts.filePath) },
+            body: new Uint8Array(bytes),
+        });
+    }
+    catch (err) {
+        // Never surface err.message raw to the log — it can embed the signed URL,
+        // and `reason` is not a redacted key. Strip any URL before logging.
+        log('error', 'presigned upload PUT failed', {
+            reason: err instanceof Error ? err.message.replace(/https?:\/\/\S+/gi, '[url]') : 'network error',
+        });
+        const error = {
+            code: 'UPLOAD_FAILED',
+            message: 'Uploading the file to storage failed.',
+            status: 0,
+        };
+        return { error };
+    }
+    if (!putRes.ok) {
+        // Abort BEFORE the commit — a half-uploaded object is never finalized.
+        const error = {
+            code: 'UPLOAD_FAILED',
+            message: `Uploading the file to storage failed with status ${putRes.status}.`,
+            status: putRes.status,
+        };
+        return { error };
+    }
+    // Step 3: commit the object key (idempotent — a retried commit will not duplicate).
+    return client.put(opts.commitPath, { s3_key: key }, { idempotency: true });
+}

package/dist/config.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Environment parsing into a validated {@link Config}.
+ *
+ * When the token is absent the server does not fail: it enters setup mode
+ * ({@link Config.setupMode}), which exposes only the `setup` helper tool. When a
+ * token is present, write access is opt-out (safe writes on by default) and
+ * full-write access is doubly opt-in (flag + an exact acknowledgment sentence).
+ * A read-only override wins over everything.
+ */
+export type Config = {
+    baseUrl: string;
+    /** The API token, or null when the server is running in setup mode. */
+    token: string | null;
+    /** True when no token is configured: only the `setup` tool is registered. */
+    setupMode: boolean;
+    writes: boolean;
+    fullWrites: boolean;
+    toolsets: Set<string> | null;
+};
+export declare const DEFAULT_BASE_URL = "https://api.labelgrid.com/api/public";
+/** The exact sentence a user must set in LABELGRID_FULL_WRITES_ACK to arm full writes. */
+export declare const FULL_WRITES_ACK = "I accept responsibility for AI-driven distribution actions";
+/** The valid toolset names; unknown names in LABELGRID_TOOLSETS warn and are ignored. */
+export declare const KNOWN_TOOLSETS: ReadonlySet<string>;
+/** Thrown when the environment cannot produce a usable config. */
+export declare class ConfigError extends Error {
+    constructor(message: string);
+}
+export declare function loadConfig(env: NodeJS.ProcessEnv): Config;

package/dist/config.js

@@ -0,0 +1,82 @@
+/**
+ * Environment parsing into a validated {@link Config}.
+ *
+ * When the token is absent the server does not fail: it enters setup mode
+ * ({@link Config.setupMode}), which exposes only the `setup` helper tool. When a
+ * token is present, write access is opt-out (safe writes on by default) and
+ * full-write access is doubly opt-in (flag + an exact acknowledgment sentence).
+ * A read-only override wins over everything.
+ */
+import { log } from './log.js';
+export const DEFAULT_BASE_URL = 'https://api.labelgrid.com/api/public';
+/** The exact sentence a user must set in LABELGRID_FULL_WRITES_ACK to arm full writes. */
+export const FULL_WRITES_ACK = 'I accept responsibility for AI-driven distribution actions';
+/** The valid toolset names; unknown names in LABELGRID_TOOLSETS warn and are ignored. */
+export const KNOWN_TOOLSETS = new Set([
+    'identity',
+    'reference',
+    'catalog',
+    'releases',
+    'review',
+    'analytics',
+    'accounting',
+    'delivery',
+    'webhooks',
+    'distribution',
+]);
+/** Thrown when the environment cannot produce a usable config. */
+export class ConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ConfigError';
+    }
+}
+function isTruthy(value) {
+    if (value === undefined)
+        return false;
+    return /^(1|true|yes|on)$/i.test(value.trim());
+}
+export function loadConfig(env) {
+    const baseUrl = env.LABELGRID_API_URL?.trim() || DEFAULT_BASE_URL;
+    const token = env.LABELGRID_API_TOKEN?.trim();
+    if (!token) {
+        // No token: start in setup mode instead of failing. The server registers
+        // only the `setup` tool, which guides the user through creating a token. No
+        // API calls are possible until a token is configured, so writes are off.
+        return {
+            baseUrl,
+            token: null,
+            setupMode: true,
+            writes: false,
+            fullWrites: false,
+            toolsets: null,
+        };
+    }
+    const readOnly = isTruthy(env.LABELGRID_READ_ONLY);
+    let writes = env.LABELGRID_ENABLE_WRITES === undefined ? true : isTruthy(env.LABELGRID_ENABLE_WRITES);
+    const fullWritesFlag = isTruthy(env.LABELGRID_ENABLE_FULL_WRITES);
+    const ackOk = env.LABELGRID_FULL_WRITES_ACK === FULL_WRITES_ACK;
+    let fullWrites = fullWritesFlag && ackOk;
+    if (fullWritesFlag && !ackOk) {
+        log('warn', `LABELGRID_ENABLE_FULL_WRITES is set but full writes stay OFF: set LABELGRID_FULL_WRITES_ACK to exactly "${FULL_WRITES_ACK}" to enable them.`);
+    }
+    if (readOnly) {
+        writes = false;
+        fullWrites = false;
+    }
+    let toolsets = null;
+    const rawToolsets = env.LABELGRID_TOOLSETS;
+    if (rawToolsets !== undefined && rawToolsets.trim() !== '') {
+        toolsets = new Set();
+        for (const name of rawToolsets
+            .split(',')
+            .map((s) => s.trim())
+            .filter((s) => s.length > 0)) {
+            if (!KNOWN_TOOLSETS.has(name)) {
+                log('warn', `Unknown toolset in LABELGRID_TOOLSETS: "${name}" (ignored).`);
+            }
+            toolsets.add(name);
+        }
+    }
+    return { baseUrl, token, setupMode: false, writes, fullWrites, toolsets };
+}

package/dist/coverage.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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 declare const COVERAGE: Record<string, string>;
+export declare const EXCLUDED: Record<string, string>;
+export declare const PENDING_DOCS: Record<string, string>;