@withpica/mcp-server 2.5.1 → 2.5.4

package/dist/utils/confirmation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"confirmation.js","sourceRoot":"","sources":["../../src/utils/confirmation.ts"],"names":[],"mappings":"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"}

package/dist/utils/credentials.d.ts

@@ -0,0 +1,11 @@
+export interface StoredCredentials {
+    api_key: string;
+    email: string;
+    org_name: string;
+    authenticated_at: string;
+}
+export declare function getDefaultCredentialsPath(): string;
+export declare function readCredentials(filePath?: string): StoredCredentials | null;
+export declare function writeCredentials(filePath: string | undefined, credentials: StoredCredentials): void;
+export declare function clearCredentials(filePath?: string): void;
+//# sourceMappingURL=credentials.d.ts.map

package/dist/utils/credentials.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentials.d.ts","sourceRoot":"","sources":["../../src/utils/credentials.ts"],"names":[],"mappings":"AAYA,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAQD,wBAAgB,yBAAyB,IAAI,MAAM,CAElD;AAED,wBAAgB,eAAe,CAC7B,QAAQ,GAAE,MAAiC,GAC1C,iBAAiB,GAAG,IAAI,CAqB1B;AAED,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,YAA2B,EAC3C,WAAW,EAAE,iBAAiB,GAC7B,IAAI,CAQN;AAED,wBAAgB,gBAAgB,CAC9B,QAAQ,GAAE,MAAiC,GAC1C,IAAI,CAMN"}

package/dist/utils/credentials.js

@@ -0,0 +1,47 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+import { readFileSync, writeFileSync, unlinkSync, mkdirSync, chmodSync, } from "fs";
+import { dirname, join } from "path";
+import { homedir } from "os";
+const DEFAULT_CREDENTIALS_PATH = join(homedir(), ".withpica", "credentials.json");
+export function getDefaultCredentialsPath() {
+    return DEFAULT_CREDENTIALS_PATH;
+}
+export function readCredentials(filePath = DEFAULT_CREDENTIALS_PATH) {
+    try {
+        const raw = readFileSync(filePath, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (!parsed.api_key || typeof parsed.api_key !== "string") {
+            return null;
+        }
+        if (!parsed.api_key.startsWith("withpica_live_")) {
+            return null;
+        }
+        return {
+            api_key: parsed.api_key,
+            email: parsed.email || "",
+            org_name: parsed.org_name || "",
+            authenticated_at: parsed.authenticated_at || new Date().toISOString(),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export function writeCredentials(filePath = DEFAULT_CREDENTIALS_PATH, credentials) {
+    const dir = dirname(filePath);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(filePath, JSON.stringify(credentials, null, 2), {
+        mode: 0o600,
+    });
+    // Ensure permissions even if file existed
+    chmodSync(filePath, 0o600);
+}
+export function clearCredentials(filePath = DEFAULT_CREDENTIALS_PATH) {
+    try {
+        unlinkSync(filePath);
+    }
+    catch {
+        // File doesn't exist — that's fine
+    }
+}
+//# sourceMappingURL=credentials.js.map

package/dist/utils/credentials.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentials.js","sourceRoot":"","sources":["../../src/utils/credentials.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAE7D,OAAO,EACL,YAAY,EACZ,aAAa,EACb,UAAU,EACV,SAAS,EACT,SAAS,GACV,MAAM,IAAI,CAAC;AACZ,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,IAAI,CAAC;AAS7B,MAAM,wBAAwB,GAAG,IAAI,CACnC,OAAO,EAAE,EACT,WAAW,EACX,kBAAkB,CACnB,CAAC;AAEF,MAAM,UAAU,yBAAyB;IACvC,OAAO,wBAAwB,CAAC;AAClC,CAAC;AAED,MAAM,UAAU,eAAe,CAC7B,WAAmB,wBAAwB;IAE3C,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAC5C,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAE/B,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;YAC1D,OAAO,IAAI,CAAC;QACd,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,gBAAgB,CAAC,EAAE,CAAC;YACjD,OAAO,IAAI,CAAC;QACd,CAAC;QAED,OAAO;YACL,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,EAAE;YACzB,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,EAAE;YAC/B,gBAAgB,EAAE,MAAM,CAAC,gBAAgB,IAAI,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACtE,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,UAAU,gBAAgB,CAC9B,WAAmB,wBAAwB,EAC3C,WAA8B;IAE9B,MAAM,GAAG,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC9B,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACpC,aAAa,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE;QAC5D,IAAI,EAAE,KAAK;KACZ,CAAC,CAAC;IACH,0CAA0C;IAC1C,SAAS,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,gBAAgB,CAC9B,WAAmB,wBAAwB;IAE3C,IAAI,CAAC;QACH,UAAU,CAAC,QAAQ,CAAC,CAAC;IACvB,CAAC;IAAC,MAAM,CAAC;QACP,mCAAmC;IACrC,CAAC;AACH,CAAC"}

package/dist/utils/enrichment-format.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Shared enrichment result formatting utilities
+ *
+ * Detects whether an enrichment call actually found data and formats
+ * the response accordingly — matched / partial / no_match.
+ * Prevents tools from returning unconditional success messages when
+ * the API returned nothing. (ADR-149 Phase 2)
+ */
+import { ToolResult } from "../tools/index.js";
+export type ResultQuality = "matched" | "partial" | "no_match";
+/**
+ * Inspect the raw enrichment result and determine data quality.
+ *
+ * Resolution order:
+ * 1. If the API already set `result_quality`, trust it.
+ * 2. If `fieldsUpdated` is present, use count to decide.
+ * 3. If `writers`/`publishers` arrays are present (MLC shape), check emptiness.
+ * 4. If a non-empty `data` object is present, treat as matched.
+ * 5. Default to `partial` — better than falsely claiming "no match".
+ */
+export declare function detectResultQuality(result: unknown): ResultQuality;
+/**
+ * Build a ToolResult for an enrichment call with quality signalling.
+ *
+ * @param entityType  "work" | "person"
+ * @param entityId    The ID that was enriched
+ * @param source      Display name of the source ("MLC", "MusicBrainz", "general", …)
+ * @param result      Raw API response
+ */
+export declare function formatEnrichmentResult(entityType: string, entityId: string, source: string, result: unknown): ToolResult;
+//# sourceMappingURL=enrichment-format.d.ts.map

package/dist/utils/enrichment-format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enrichment-format.d.ts","sourceRoot":"","sources":["../../src/utils/enrichment-format.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE/C,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,SAAS,GAAG,UAAU,CAAC;AAE/D;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,OAAO,GAAG,aAAa,CA+BlE;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,OAAO,GACd,UAAU,CA0BZ"}

package/dist/utils/enrichment-format.js

@@ -0,0 +1,69 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+/**
+ * Inspect the raw enrichment result and determine data quality.
+ *
+ * Resolution order:
+ * 1. If the API already set `result_quality`, trust it.
+ * 2. If `fieldsUpdated` is present, use count to decide.
+ * 3. If `writers`/`publishers` arrays are present (MLC shape), check emptiness.
+ * 4. If a non-empty `data` object is present, treat as matched.
+ * 5. Default to `partial` — better than falsely claiming "no match".
+ */
+export function detectResultQuality(result) {
+    if (!result || typeof result !== "object")
+        return "no_match";
+    const r = result;
+    if (r.result_quality === "matched" || r.result_quality === "partial" || r.result_quality === "no_match") {
+        return r.result_quality;
+    }
+    if (typeof r.fieldsUpdated === "number") {
+        return r.fieldsUpdated > 0 ? "matched" : "no_match";
+    }
+    const hasWriters = Array.isArray(r.writers);
+    const hasPublishers = Array.isArray(r.publishers);
+    if (hasWriters || hasPublishers) {
+        const writersEmpty = hasWriters && r.writers.length === 0;
+        const publishersEmpty = hasPublishers && r.publishers.length === 0;
+        if ((hasWriters ? writersEmpty : true) &&
+            (hasPublishers ? publishersEmpty : true)) {
+            return "no_match";
+        }
+        return "matched";
+    }
+    if (r.data && typeof r.data === "object" && Object.keys(r.data).length > 0) {
+        return "matched";
+    }
+    return "partial";
+}
+/**
+ * Build a ToolResult for an enrichment call with quality signalling.
+ *
+ * @param entityType  "work" | "person"
+ * @param entityId    The ID that was enriched
+ * @param source      Display name of the source ("MLC", "MusicBrainz", "general", …)
+ * @param result      Raw API response
+ */
+export function formatEnrichmentResult(entityType, entityId, source, result) {
+    const quality = detectResultQuality(result);
+    const messages = {
+        matched: `${source} enrichment complete for ${entityType} ${entityId} — data found and applied`,
+        partial: `${source} enrichment complete for ${entityType} ${entityId} — some data found`,
+        no_match: `no ${source} match found for ${entityType} ${entityId}`,
+    };
+    const response = {
+        success: true,
+        message: messages[quality],
+        result_quality: quality,
+        data: result,
+    };
+    if (quality === "no_match") {
+        response.suggestion =
+            "try a different enrichment source for additional metadata";
+    }
+    const jsonText = JSON.stringify(response, null, 2);
+    return {
+        content: [{ type: "text", text: `${response.message}\n\n${jsonText}` }],
+        structuredContent: response,
+    };
+}
+//# sourceMappingURL=enrichment-format.js.map

package/dist/utils/enrichment-format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"enrichment-format.js","sourceRoot":"","sources":["../../src/utils/enrichment-format.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAe7D;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAAe;IACjD,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ;QAAE,OAAO,UAAU,CAAC;IAC7D,MAAM,CAAC,GAAG,MAAiC,CAAC;IAE5C,IAAI,CAAC,CAAC,cAAc,KAAK,SAAS,IAAI,CAAC,CAAC,cAAc,KAAK,SAAS,IAAI,CAAC,CAAC,cAAc,KAAK,UAAU,EAAE,CAAC;QACxG,OAAO,CAAC,CAAC,cAA+B,CAAC;IAC3C,CAAC;IAED,IAAI,OAAO,CAAC,CAAC,aAAa,KAAK,QAAQ,EAAE,CAAC;QACxC,OAAO,CAAC,CAAC,aAAa,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC;IACtD,CAAC;IAED,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;IAC5C,MAAM,aAAa,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;IAClD,IAAI,UAAU,IAAI,aAAa,EAAE,CAAC;QAChC,MAAM,YAAY,GAAG,UAAU,IAAK,CAAC,CAAC,OAAqB,CAAC,MAAM,KAAK,CAAC,CAAC;QACzE,MAAM,eAAe,GAAG,aAAa,IAAK,CAAC,CAAC,UAAwB,CAAC,MAAM,KAAK,CAAC,CAAC;QAClF,IACE,CAAC,UAAU,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC;YAClC,CAAC,aAAa,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,IAAI,CAAC,EACxC,CAAC;YACD,OAAO,UAAU,CAAC;QACpB,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,IAAI,CAAC,CAAC,IAAI,IAAI,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3E,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,sBAAsB,CACpC,UAAkB,EAClB,QAAgB,EAChB,MAAc,EACd,MAAe;IAEf,MAAM,OAAO,GAAG,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAE5C,MAAM,QAAQ,GAAkC;QAC9C,OAAO,EAAE,GAAG,MAAM,4BAA4B,UAAU,IAAI,QAAQ,2BAA2B;QAC/F,OAAO,EAAE,GAAG,MAAM,4BAA4B,UAAU,IAAI,QAAQ,oBAAoB;QACxF,QAAQ,EAAE,MAAM,MAAM,oBAAoB,UAAU,IAAI,QAAQ,EAAE;KACnE,CAAC;IAEF,MAAM,QAAQ,GAA4B;QACxC,OAAO,EAAE,IAAI;QACb,OAAO,EAAE,QAAQ,CAAC,OAAO,CAAC;QAC1B,cAAc,EAAE,OAAO;QACvB,IAAI,EAAE,MAAM;KACb,CAAC;IAEF,IAAI,OAAO,KAAK,UAAU,EAAE,CAAC;QAC3B,QAAQ,CAAC,UAAU;YACjB,2DAA2D,CAAC;IAChE,CAAC;IAED,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IACnD,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,QAAQ,CAAC,OAAO,OAAO,QAAQ,EAAE,EAAE,CAAC;QACvE,iBAAiB,EAAE,QAAQ;KAC5B,CAAC;AACJ,CAAC"}

package/dist/utils/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"AAEA;;GAEG;AAEH,qBAAa,cAAe,SAAQ,KAAK;IAG9B,IAAI,EAAE,MAAM;IACZ,OAAO,CAAC,EAAE,GAAG;gBAFpB,OAAO,EAAE,MAAM,EACR,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,GAAG,YAAA;CAMvB;AAED,qBAAa,mBAAoB,SAAQ,cAAc;gBACzC,OAAO,GAAE,MAAgC,EAAE,OAAO,CAAC,EAAE,GAAG;CAIrE;AAED,qBAAa,kBAAmB,SAAQ,cAAc;gBACxC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG;CAI3C;AAED,qBAAa,aAAc,SAAQ,cAAc;gBACnC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG;CAI3C;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,GAAG,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CA6FtE;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,IAAI,CAc1D"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"AAEA;;GAEG;AAEH,qBAAa,cAAe,SAAQ,KAAK;IAG9B,IAAI,EAAE,MAAM;IACZ,OAAO,CAAC,EAAE,GAAG;gBAFpB,OAAO,EAAE,MAAM,EACR,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,GAAG,YAAA;CAMvB;AAED,qBAAa,mBAAoB,SAAQ,cAAc;gBACzC,OAAO,GAAE,MAAgC,EAAE,OAAO,CAAC,EAAE,GAAG;CAIrE;AAED,qBAAa,kBAAmB,SAAQ,cAAc;gBACxC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG;CAI3C;AAED,qBAAa,aAAc,SAAQ,cAAc;gBACnC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG;CAI3C;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,GAAG,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAwHtE;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,IAAI,CAc1D"}

package/dist/utils/errors.js

@@ -35,6 +35,18 @@ export class ResourceError extends McpServerError {
  * Format error for MCP response
  */
 export function formatError(error) {
+    const status = error?.status;
+    const rawMessage = error instanceof Error ? error.message : error?.message || String(error);
+    // Attempt to parse structured error body from API responses
+    let structuredBody = null;
+    try {
+        if (typeof rawMessage === "string" && rawMessage.startsWith("{")) {
+            structuredBody = JSON.parse(rawMessage);
+        }
+    }
+    catch {
+        // Not JSON — use raw message
+    }
     if (error instanceof McpServerError) {
         return {
             type: "text",
@@ -42,11 +54,11 @@ export function formatError(error) {
                 error: error.code,
                 message: error.message,
                 details: error.details,
+                retry_safe: false,
             }, null, 2),
         };
     }
     // Classify ApiError from SDK layer
-    const status = error?.status;
     if (status === 0 ||
         (error instanceof Error && error.message?.includes("timed out"))) {
         return {
@@ -54,6 +66,8 @@ export function formatError(error) {
             text: JSON.stringify({
                 error: "REQUEST_TIMEOUT",
                 message: "API request timed out after retries. The server may be slow or unreachable.",
+                retry_safe: true,
+                suggestion: "wait a moment and try again",
             }, null, 2),
         };
     }
@@ -64,6 +78,8 @@ export function formatError(error) {
                 error: "AUTHENTICATION_ERROR",
                 message: "API authentication failed. Check your PICA_API_KEY is valid.",
                 status,
+                retry_safe: false,
+                suggestion: "your API key may be invalid or expired — check your PICA settings",
             }, null, 2),
         };
     }
@@ -74,23 +90,31 @@ export function formatError(error) {
                 error: "RATE_LIMITED",
                 message: "API rate limit exceeded after retries. Try again in a moment.",
                 status,
+                retry_safe: true,
+                suggestion: "wait a moment and try again",
             }, null, 2),
         };
     }
-    if (error instanceof Error) {
+    // Structured error body from API — propagate domain-specific codes
+    if (structuredBody?.error_code) {
         return {
             type: "text",
             text: JSON.stringify({
-                error: "UNKNOWN_ERROR",
-                message: error.message,
+                error: structuredBody.error_code,
+                message: structuredBody.message || rawMessage,
+                details: structuredBody.details,
+                retry_safe: false,
             }, null, 2),
         };
     }
+    // Generic fallback
+    const message = error instanceof Error ? error.message : String(error);
     return {
         type: "text",
         text: JSON.stringify({
             error: "UNKNOWN_ERROR",
-            message: String(error),
+            message,
+            retry_safe: false,
         }, null, 2),
     };
 }

package/dist/utils/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"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"}

package/dist/utils/formatting.d.ts

@@ -60,4 +60,5 @@ export declare function formatStructured(data: any, summary?: string): Formatted
  * Format a list with both human summary and structured JSON
  */
 export declare function formatStructuredList<T>(items: T[], entityName: string, metadata?: Record<string, any>): FormattedResult;
+export declare function guardResponseSize(text: string, toolName: string): string;
 //# sourceMappingURL=formatting.d.ts.map

package/dist/utils/formatting.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"formatting.d.ts","sourceRoot":"","sources":["../../src/utils/formatting.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AAEH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC7C;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,GAAG,GAAG,eAAe,CAKvD;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,UAAU,GAAG,WAAW,GAAG,cAAc,CAAC;CACtD;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,GAAG,EACV,eAAe,CAAC,EAAE,cAAc,EAAE,GACjC,eAAe,CA0BjB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,GAAG,EAAE,EACX,KAAK,GAAE,MAAU,GAChB,cAAc,EAAE,CAOlB;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAC1B,KAAK,EAAE,CAAC,EAAE,EACV,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC7B,eAAe,CAsBjB;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,GAAE,MAAa,GAAG,MAAM,CAKvE;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC7B,eAAe,CAWjB;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,eAAe,CAW7E;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EACpC,KAAK,EAAE,CAAC,EAAE,EACV,UAAU,EAAE,MAAM,EAClB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC7B,eAAe,CAOjB"}
+{"version":3,"file":"formatting.d.ts","sourceRoot":"","sources":["../../src/utils/formatting.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AAEH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC7C;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,GAAG,GAAG,eAAe,CAQvD;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,UAAU,GAAG,WAAW,GAAG,cAAc,CAAC;CACtD;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,GAAG,EACV,eAAe,CAAC,EAAE,cAAc,EAAE,GACjC,eAAe,CA0BjB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,GAAG,EAAE,EACX,KAAK,GAAE,MAAU,GAChB,cAAc,EAAE,CAOlB;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAC1B,KAAK,EAAE,CAAC,EAAE,EACV,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC7B,eAAe,CAsBjB;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,GAAE,MAAa,GAAG,MAAM,CAKvE;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC7B,eAAe,CAWjB;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,eAAe,CAW7E;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EACpC,KAAK,EAAE,CAAC,EAAE,EACV,UAAU,EAAE,MAAM,EAClB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAC7B,eAAe,CAOjB;AAWD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAkBxE"}

package/dist/utils/formatting.js

@@ -3,9 +3,12 @@
  * Format data as JSON text for MCP response
  */
 export function formatAsText(data) {
+    // Round-trip through JSON to ensure structuredContent is a plain object
+    // (raw API responses may contain class instances or Date objects that fail MCP validation)
+    const serialized = JSON.stringify(data, null, 2);
     return {
-        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
-        structuredContent: data,
+        content: [{ type: "text", text: serialized }],
+        structuredContent: JSON.parse(serialized),
     };
 }
 /**
@@ -122,4 +125,29 @@ export function formatStructuredList(items, entityName, metadata) {
     const summary = `Found ${count} ${entityName}${count !== 1 ? "s" : ""}${metadata?.query ? ` matching "${metadata.query}"` : ""}.`;
     return formatStructured({ count, items, ...metadata }, summary);
 }
+/**
+ * Guard against oversized tool responses that would blow the agent's context window.
+ * Block playbook: "Check byte size before returning text."
+ * Lowin: "Respect the token budget."
+ *
+ * Threshold: 100KB (~25K tokens). Truncates with recovery instructions.
+ */
+const MAX_RESPONSE_BYTES = 100_000;
+export function guardResponseSize(text, toolName) {
+    const byteSize = Buffer.byteLength(text, "utf8");
+    if (byteSize <= MAX_RESPONSE_BYTES) {
+        return text;
+    }
+    // Truncate by chars (conservative — multi-byte chars mean fewer chars than bytes)
+    const truncated = text.substring(0, MAX_RESPONSE_BYTES);
+    const recovery = [
+        "\n\n---",
+        `TRUNCATED: Response from ${toolName} exceeded 100KB (was ${Math.round(byteSize / 1024)}KB).`,
+        "To get complete results, narrow your query:",
+        "- Use a smaller 'limit' parameter (e.g. limit=10)",
+        "- Add search/filter parameters to reduce results",
+        '- Use a more specific tool (e.g. pica_works_inspect with sections: ["basic"] instead of pica_works_query)',
+    ].join("\n");
+    return truncated + recovery;
+}
 //# sourceMappingURL=formatting.js.map

package/dist/utils/formatting.js.map

@@ -1 +1 @@
-{"version":3,"file":"formatting.js","sourceRoot":"","sources":["../../src/utils/formatting.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"formatting.js","sourceRoot":"","sources":["../../src/utils/formatting.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@withpica/mcp-server",
   "mcpName": "io.github.withpica/pica",
-  "version": "2.5.1",
+  "version": "2.5.4",
   "description": "MCP Server for PICA Platform - enables AI assistants to interact with PICA",
   "type": "module",
   "main": "dist/index.js",
@@ -9,6 +9,7 @@
     "pica-mcp": "./dist/index.js"
   },
   "scripts": {
+    "prebuild": "tsx scripts/bundle-apps.ts",
     "build": "tsc",
     "dev": "tsx src/index.ts",
     "start": "node dist/index.js",
@@ -32,6 +33,7 @@
     "mppx": "^0.5.0"
   },
   "devDependencies": {
+    "@modelcontextprotocol/ext-apps": "^1.5.0",
     "@types/jest": "^29.5.14",
     "@types/node": "^20.10.0",
     "jest": "^29.7.0",

package/scripts/bundle-apps.ts

@@ -0,0 +1,61 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+
+/**
+ * Build script: reads font files + ext-apps browser bridge,
+ * writes src/apps/generated/shared-bundle.ts with const string exports.
+ * Run via: npm run prebuild (before tsc)
+ */
+
+import { readFileSync, writeFileSync, mkdirSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { createRequire } from "module";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const root = join(__dirname, "..");
+
+// Read fonts as base64
+const fontsDir = join(root, "assets/fonts");
+const instrumentSerifRegular = readFileSync(
+  join(fontsDir, "InstrumentSerif-Regular.woff2"),
+).toString("base64");
+const instrumentSerifItalic = readFileSync(
+  join(fontsDir, "InstrumentSerif-Italic.woff2"),
+).toString("base64");
+const geistSansLight = readFileSync(
+  join(fontsDir, "GeistSans-Light.woff2"),
+).toString("base64");
+
+// Read ext-apps browser bridge bundle (devDependency — may not be installed in CI)
+const require = createRequire(import.meta.url);
+let appBridgeJs: string;
+try {
+  const appBridgePath =
+    require.resolve("@modelcontextprotocol/ext-apps/app-with-deps");
+  appBridgeJs = readFileSync(appBridgePath, "utf-8");
+} catch {
+  console.warn(
+    "[bundle-apps] @modelcontextprotocol/ext-apps not installed — writing stub (MCP Apps will not render)",
+  );
+  appBridgeJs = "/* ext-apps bridge not available */";
+}
+
+// Write generated file
+const outDir = join(root, "src/apps/generated");
+mkdirSync(outDir, { recursive: true });
+
+const output = `// Auto-generated by scripts/bundle-apps.ts — do not edit
+// Re-run: npm run prebuild
+
+export const INSTRUMENT_SERIF_REGULAR_BASE64 = "${instrumentSerifRegular}";
+export const INSTRUMENT_SERIF_ITALIC_BASE64 = "${instrumentSerifItalic}";
+export const GEIST_SANS_LIGHT_BASE64 = "${geistSansLight}";
+export const APP_BRIDGE_JS = ${JSON.stringify(appBridgeJs)};
+`;
+
+writeFileSync(join(outDir, "shared-bundle.ts"), output, "utf-8");
+
+console.log(
+  `[bundle-apps] Generated shared-bundle.ts (${Math.round(output.length / 1024)}KB)`,
+);