@labelgrid/mcp 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -5,6 +5,26 @@ All notable changes to `@labelgrid/mcp` are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.2] - 2026-07-16
+
+### Changed
+
+- API requests time out after 60 seconds (structured `TIMEOUT` error) and raw
+  transfers after 10 minutes — a hung call can no longer hang a tool.
+- CI and publish workflows install dependencies with `--ignore-scripts`.
+
+## [0.2.1] - 2026-07-15
+
+### Added
+
+- Dockerfile (the server runs containerized; boots into setup mode without credentials).
+- `glama.json` metadata and score badges.
+
+### Changed
+
+- Setup mode now lists the full tool catalog for introspection; every catalog
+  tool returns setup guidance (`NOT_CONNECTED`) until a token is configured.
+
 ## [0.2.0] - 2026-07-15
 
 ### Added

package/README.md

@@ -1,5 +1,7 @@
 # LabelGrid MCP Server
 
+[![npm version](https://img.shields.io/npm/v/%40labelgrid%2Fmcp)](https://www.npmjs.com/package/@labelgrid/mcp) [![CI](https://github.com/labelgrid/labelgrid-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/labelgrid/labelgrid-mcp/actions/workflows/ci.yml) [![LabelGrid MCP server](https://glama.ai/mcp/servers/@labelgrid/labelgrid-mcp/badges/score.svg)](https://glama.ai/mcp/servers/@labelgrid/labelgrid-mcp)
+
 `@labelgrid/mcp` — the official [Model Context Protocol](https://modelcontextprotocol.io) server for [LabelGrid](https://labelgrid.com), the music distribution platform. Point Claude Desktop, Claude Code, Cursor, or any MCP client at your own LabelGrid account and manage your music catalog, releases, files, analytics, royalty accounting, webhooks, and distribution in natural language — it is a thin, typed wrapper over the LabelGrid public API, so every rule and validation stays on the server.
 
 ## Quickstart
@@ -62,7 +64,7 @@ Add this to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per project):
 
 ### First run / setup mode
 
-If you start the server without `LABELGRID_API_TOKEN`, it does not fail — it launches in **setup mode** and exposes a single `setup` helper. Just ask your AI client to "set up LabelGrid" and it will walk you through creating a token and adding it to your config. Once the token is set, restart your client and the full toolset loads automatically.
+If you start the server without `LABELGRID_API_TOKEN`, it does not fail — it launches in **setup mode**: the full tool catalog stays listed so you can see what the server offers, and a `setup` helper leads the way. Nothing can run in this state — every catalog tool returns setup guidance instead. Just ask your AI client to "set up LabelGrid" and it will walk you through creating a token and adding it to your config. Once the token is set, restart your client and the tools go live.
 
 ## Getting a token
 

package/dist/api/http.d.ts

@@ -28,14 +28,26 @@ export declare class LabelGridClient {
     private readonly token;
     private readonly fetchFn;
     private readonly version;
+    private readonly timeoutMs;
+    private readonly rawTimeoutMs;
     constructor(opts: {
         baseUrl: string;
         token: string;
         fetchFn?: typeof fetch;
         version: string;
+        /** API request timeout (default 60s) — a hung call must never hang a tool. */
+        timeoutMs?: number;
+        /** Timeout for raw transfers like presigned uploads (default 10min). */
+        rawTimeoutMs?: number;
     });
     private authHeaders;
     private send;
+    /**
+     * Reads a response body with the byte ceiling enforced mid-stream. Returns
+     * the decoded text, or the supplied too-large error result when the ceiling
+     * is crossed. Abort/timeout rejections propagate to the caller for mapping.
+     */
+    private readBody;
     get<T>(path: string, query?: Record<string, unknown>): Promise<ApiResult<T>>;
     post<T>(path: string, body?: unknown, opts?: {
         idempotency?: boolean;

package/dist/api/http.js

@@ -166,11 +166,15 @@ export class LabelGridClient {
     token;
     fetchFn;
     version;
+    timeoutMs;
+    rawTimeoutMs;
     constructor(opts) {
         this.baseUrl = opts.baseUrl.replace(/\/+$/, '');
         this.token = opts.token;
         this.fetchFn = opts.fetchFn ?? fetch;
         this.version = opts.version;
+        this.timeoutMs = opts.timeoutMs ?? 60_000;
+        this.rawTimeoutMs = opts.rawTimeoutMs ?? 600_000;
     }
     authHeaders() {
         return {
@@ -187,7 +191,7 @@ export class LabelGridClient {
             // across separate tool calls); otherwise a fresh UUID is generated.
             headers['Idempotency-Key'] = opts.idempotencyKey ?? randomUUID();
         }
-        const init = { method, headers };
+        const init = { method, headers, signal: AbortSignal.timeout(this.timeoutMs) };
         if (opts.rawBody !== undefined) {
             init.body = opts.rawBody;
         }
@@ -200,6 +204,16 @@ export class LabelGridClient {
             res = await this.fetchFn(url, init);
         }
         catch (err) {
+            if (err instanceof DOMException &&
+                (err.name === 'TimeoutError' || err.name === 'AbortError')) {
+                return {
+                    error: {
+                        code: 'TIMEOUT',
+                        message: `The request timed out after ${Math.round(this.timeoutMs / 1000)} seconds. Try again, or narrow the request.`,
+                        status: 0,
+                    },
+                };
+            }
             return {
                 error: {
                     code: 'NETWORK_ERROR',
@@ -229,7 +243,54 @@ export class LabelGridClient {
         // 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.
+        // The request timeout keeps running while the body streams, so a read can
+        // also abort here — map that to the same structured TIMEOUT.
         let text;
+        try {
+            text = await this.readBody(res, tooLarge);
+        }
+        catch (err) {
+            if (err instanceof DOMException &&
+                (err.name === 'TimeoutError' || err.name === 'AbortError')) {
+                return {
+                    error: {
+                        code: 'TIMEOUT',
+                        message: `The request timed out after ${Math.round(this.timeoutMs / 1000)} seconds while reading the response. Try again, or narrow the request.`,
+                        status: 0,
+                    },
+                };
+            }
+            return {
+                error: {
+                    code: 'NETWORK_ERROR',
+                    message: err instanceof Error ? err.message : 'Reading the response failed.',
+                    status: 0,
+                },
+            };
+        }
+        if (typeof text !== 'string') {
+            return text; // the bounded reader returned the too-large error result
+        }
+        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) };
+    }
+    /**
+     * Reads a response body with the byte ceiling enforced mid-stream. Returns
+     * the decoded text, or the supplied too-large error result when the ceiling
+     * is crossed. Abort/timeout rejections propagate to the caller for mapping.
+     */
+    async readBody(res, tooLarge) {
         if (res.body) {
             const reader = res.body.getReader();
             const chunks = [];
@@ -260,29 +321,15 @@ export class LabelGridClient {
                 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;
-            }
+            return new TextDecoder('utf-8').decode(merged);
         }
-        if (res.ok) {
-            return { data: body };
+        // 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).
+        const text = await res.text();
+        if (Buffer.byteLength(text, 'utf8') > MAX_RESPONSE_BYTES) {
+            return tooLarge;
         }
-        return { error: normalizeError(res, body) };
+        return text;
     }
     get(path, query) {
         return this.send('GET', path, { query });
@@ -340,6 +387,6 @@ export class LabelGridClient {
      * Bearer token would break the signature.
      */
     raw(url, init) {
-        return this.fetchFn(url, init);
+        return this.fetchFn(url, { signal: AbortSignal.timeout(this.rawTimeoutMs), ...init });
     }
 }

package/dist/index.js

@@ -13,35 +13,8 @@ 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 { allTools } from './tools/all.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 {
@@ -62,7 +35,7 @@ async function main() {
         version: VERSION,
     });
     if (config.setupMode) {
-        const server = buildServer(config, client, []);
+        const server = buildServer(config, client, allTools());
         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());

package/dist/server.js

@@ -24,8 +24,10 @@ 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.',
+                'Call the `setup` tool for step-by-step instructions to connect. The full ' +
+                'tool catalog is listed so you can see what the server offers, but no ' +
+                'account data can be accessed in this state — every tool returns setup ' +
+                'guidance until a token is configured.',
             LEGAL_SUMMARY,
         ].join('\n\n');
     }
@@ -41,11 +43,20 @@ function buildInstructions(config) {
 }
 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;
+    // In setup mode the setup helper leads, and the full catalog stays LISTED so
+    // introspection shows what the server offers — but every catalog tool is
+    // inert: without a token no API call is possible, so invoking one returns
+    // setup guidance instead of executing.
+    const registered = config.setupMode ? [...setupTools, ...tools] : tools;
     for (const tool of registered) {
-        if (!isToolEnabled(tool, config))
+        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.
+        const listable = config.setupMode
+            ? config.toolsets === null || config.toolsets.has(tool.toolset)
+            : isToolEnabled(tool, config);
+        if (!isSetupHelper && !listable)
             continue;
         server.registerTool(tool.name, {
             title: tool.title,
@@ -53,8 +64,19 @@ export function buildServer(config, client, tools) {
             inputSchema: tool.inputShape,
             annotations: { title: tool.title, ...tool.annotations },
         }, async (args) => {
+            // Not connected: every catalog tool refuses with setup guidance.
+            if (config.setupMode && !isSetupHelper) {
+                return toToolResult({
+                    error: {
+                        code: 'NOT_CONNECTED',
+                        message: 'No LabelGrid API token is configured, so this tool cannot run yet. ' +
+                            'Call the `setup` tool for step-by-step instructions to connect your account.',
+                        status: 0,
+                    },
+                });
+            }
             // Defense in depth: even a registered tool re-verifies its gate.
-            if (!isToolEnabled(tool, config)) {
+            if (!isSetupHelper && !isToolEnabled(tool, config)) {
                 return toToolResult({
                     error: {
                         code: 'TOOL_DISABLED',

package/dist/tools/all.d.ts

@@ -0,0 +1,3 @@
+/** The complete tool catalog, in registration order. */
+import type { ToolDef } from './types.js';
+export declare function allTools(): ToolDef[];

package/dist/tools/all.js

@@ -0,0 +1,29 @@
+/** 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 { referenceTools } from './reference.js';
+import { releaseWriteTools } from './release-write.js';
+import { reviewReadTools } from './review-read.js';
+import { webhookTools } from './webhooks.js';
+export function allTools() {
+    return [
+        ...identityTools,
+        ...referenceTools,
+        ...analyticsTools,
+        ...catalogReadTools,
+        ...filesReadTools,
+        ...reviewReadTools,
+        ...deliveryTools,
+        ...accountingTools,
+        ...webhookTools,
+        ...catalogWriteTools,
+        ...releaseWriteTools,
+        ...fullWriteTools,
+    ];
+}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@labelgrid/mcp",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "mcpName": "io.github.labelgrid/labelgrid-mcp",
-  "description": "Official LabelGrid MCP server \u2014 connect your AI client to your LabelGrid account",
+  "description": "Official LabelGrid MCP server — connect your AI client to your LabelGrid account",
   "type": "module",
   "keywords": ["mcp", "model-context-protocol", "labelgrid", "music-distribution", "ai", "claude"],
   "main": "dist/index.js",

package/server.json

@@ -2,7 +2,7 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.labelgrid/labelgrid-mcp",
   "description": "Official LabelGrid MCP server — manage your music catalog, releases, analytics and distribution.",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "websiteUrl": "https://labelgrid.com",
   "repository": {
     "url": "https://github.com/labelgrid/labelgrid-mcp",
@@ -12,7 +12,7 @@
     {
       "registryType": "npm",
       "identifier": "@labelgrid/mcp",
-      "version": "0.2.0",
+      "version": "0.2.2",
       "transport": {
         "type": "stdio"
       },