@withpica/mcp-server-directory 1.4.0 → 1.4.2

package/scripts/build-skills.ts

@@ -1,4 +1,4 @@
-// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+// Copyright (c) 2025-2026 Withpica Ltd. All rights reserved.
 
 /**
  * ADR-140 Phase 2b — generator for `skills.generated.ts` (directory MCP).
@@ -91,7 +91,9 @@ function parseFrontmatter(src: string, sourceFile: string): ParsedSkill {
   ];
   for (const field of required) {
     if (!(field in fm)) {
-      throw new Error(`${sourceFile}: missing required frontmatter field "${field}"`);
+      throw new Error(
+        `${sourceFile}: missing required frontmatter field "${field}"`,
+      );
     }
   }
   if (!Array.isArray(fm.triggers) || fm.triggers.length === 0) {
@@ -136,7 +138,7 @@ function discoverSkills(): ParsedSkill[] {
 }
 
 function emit(skills: ParsedSkill[]): string {
-  const header = `// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+  const header = `// Copyright (c) 2025-2026 Withpica Ltd. All rights reserved.
 
 /**
  * GENERATED FILE — DO NOT EDIT BY HAND.
@@ -156,7 +158,10 @@ export interface Skill {
 }
 
 `;
-  const lines: string[] = [header, "export const SKILLS: Record<string, Skill> = {"];
+  const lines: string[] = [
+    header,
+    "export const SKILLS: Record<string, Skill> = {",
+  ];
   for (const skill of skills) {
     lines.push(`  ${JSON.stringify(skill.name)}: {`);
     lines.push(`    name: ${JSON.stringify(skill.name)},`);

package/src/__tests__/prompts/index.test.ts

@@ -1,4 +1,4 @@
-// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+// Copyright (c) 2025-2026 Withpica Ltd. All rights reserved.
 
 /**
  * Directory Prompt Registry Tests

package/src/__tests__/prompts/prompt-eval-harness.test.ts

@@ -1,4 +1,4 @@
-// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+// Copyright (c) 2025-2026 Withpica Ltd. All rights reserved.
 
 /**
  * Directory Prompt Eval Harness — ADR-140 Phase 3

package/src/__tests__/skills/skills-registry.test.ts

@@ -1,4 +1,4 @@
-// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+// Copyright (c) 2025-2026 Withpica Ltd. All rights reserved.
 
 /**
  * Directory SkillsRegistry test suite — ADR-140 Phase 2b
@@ -9,10 +9,7 @@
  */
 
 import { describe, it, expect } from "@jest/globals";
-import {
-  SkillsRegistry,
-  SkillNotFoundError,
-} from "../../skills/index.js";
+import { SkillsRegistry, SkillNotFoundError } from "../../skills/index.js";
 
 describe("Directory SkillsRegistry", () => {
   const registry = new SkillsRegistry();

package/src/__tests__/skills/skills-tools.test.ts

@@ -1,4 +1,4 @@
-// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+// Copyright (c) 2025-2026 Withpica Ltd. All rights reserved.
 
 /**
  * Directory skills tools test suite — ADR-140 Phase 2b
@@ -38,15 +38,11 @@ describe("DirectorySkillsTools", () => {
     const summaries = result.structuredContent!.skills as Array<{
       name: string;
     }>;
-    expect(summaries.map((s) => s.name)).toContain(
-      "find-music-for-sync-brief",
-    );
+    expect(summaries.map((s) => s.name)).toContain("find-music-for-sync-brief");
   });
 
   it("directory_skill_get returns the methodology body", async () => {
-    const get = tools.find(
-      (t) => t.definition.name === "directory_skill_get",
-    )!;
+    const get = tools.find((t) => t.definition.name === "directory_skill_get")!;
     const result = await get.executor({ name: "find-music-for-sync-brief" });
     expect(result.isError).toBeFalsy();
     const textBlock = result.content.find((c: any) => c.type === "text") as
@@ -57,17 +53,13 @@ describe("DirectorySkillsTools", () => {
   });
 
   it("directory_skill_get returns isError for unknown skill", async () => {
-    const get = tools.find(
-      (t) => t.definition.name === "directory_skill_get",
-    )!;
+    const get = tools.find((t) => t.definition.name === "directory_skill_get")!;
     const result = await get.executor({ name: "not-a-real-skill" });
     expect(result.isError).toBe(true);
   });
 
   it("directory_skill_get returns isError when name is missing", async () => {
-    const get = tools.find(
-      (t) => t.definition.name === "directory_skill_get",
-    )!;
+    const get = tools.find((t) => t.definition.name === "directory_skill_get")!;
     const result = await get.executor({});
     expect(result.isError).toBe(true);
   });

package/src/__tests__/tools/chain.test.ts

@@ -1,4 +1,4 @@
-// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+// Copyright (c) 2025-2026 Withpica Ltd. All rights reserved.
 
 import {
   jest,

package/src/__tests__/tools/composability-chains.test.ts

@@ -1,4 +1,4 @@
-// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+// Copyright (c) 2025-2026 Withpica Ltd. All rights reserved.
 
 /**
  * Directory MCP — Composability Chain Tests
@@ -6,33 +6,22 @@
  */
 
 import { describe, it, expect, beforeAll } from "@jest/globals";
-import { DirectoryWorksTools } from "../../tools/works";
-import { DirectoryPeopleTools } from "../../tools/people";
-import { DirectorySearchTools } from "../../tools/search";
-import { DirectoryRecordingsTools } from "../../tools/recordings";
-import { DirectoryChainTools } from "../../tools/chain";
+import { ToolRegistry } from "../../tools/index";
 
 const nullClient = null as any;
 
+/**
+ * 2026-08-24 — derived from the REAL registry, not a local class list. The
+ * previous fixed five-class list here missed DirectorySkillsTools and
+ * DirectoryReleaseNotesTools, so "all 8 tools are registered" passed while
+ * the server advertised 11 — a fixed list cannot see the class nobody
+ * listed (same failure family as the shows-trust-floor guard).
+ */
 function getAllTools() {
-  const classes = [
-    new DirectoryWorksTools(nullClient),
-    new DirectoryPeopleTools(nullClient),
-    new DirectorySearchTools(nullClient),
-    new DirectoryRecordingsTools(nullClient),
-    new DirectoryChainTools(nullClient),
-  ];
-
-  const tools: Array<{ name: string; description: string }> = [];
-  for (const cls of classes) {
-    for (const tool of cls.getTools()) {
-      tools.push({
-        name: tool.definition.name,
-        description: tool.definition.description,
-      });
-    }
-  }
-  return tools;
+  return new ToolRegistry(nullClient).listTools().map((definition) => ({
+    name: definition.name,
+    description: definition.description,
+  }));
 }
 
 function parseChains(description: string): string[] {
@@ -50,8 +39,8 @@ describe("Directory Composability Chains", () => {
     allNames = new Set(allTools.map((t) => t.name));
   });
 
-  it("all 8 tools are registered", () => {
-    expect(allTools).toHaveLength(8);
+  it("all 11 tools are registered (parity with lib/constants/mcp-surface.ts is enforced by tool-count-parity.test.ts)", () => {
+    expect(allTools).toHaveLength(11);
   });
 
   it("all tools have composability chains", () => {

package/src/__tests__/tools/people.test.ts

@@ -1,4 +1,4 @@
-// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+// Copyright (c) 2025-2026 Withpica Ltd. All rights reserved.
 
 import {
   jest,

package/src/__tests__/tools/search.test.ts

@@ -1,4 +1,4 @@
-// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+// Copyright (c) 2025-2026 Withpica Ltd. All rights reserved.
 
 import {
   jest,

package/src/__tests__/tools/tool-count-parity.test.ts

@@ -0,0 +1,63 @@
+// Copyright (c) 2025-2026 Withpica Ltd. All rights reserved.
+
+/**
+ * Directory tool-count parity tripwire — sister of
+ * mcp-server/src/__tests__/tools/tool-count-parity.test.ts.
+ *
+ * MCP_DIRECTORY_TOOL_COUNT in `lib/constants/mcp-surface.ts` is published
+ * live at /.well-known/mcp.json and /.well-known/mcp/server-card.json. It
+ * was documented as "small, hand-verified" and drifted exactly as
+ * hand-verified numbers do: it read 9 while this registry served 11
+ * (directory_search_recordings and directory_release_notes landed without a
+ * bump). This test builds the REAL registry and fails when the constant
+ * drifts — update the constant in the same PR as any directory tool
+ * addition, removal, or retirement.
+ *
+ * The constant is read from the file as text (not imported) — the app and
+ * this package are deliberately isolated builds; a source-text read keeps
+ * the tripwire without coupling them.
+ */
+
+import { describe, it, expect } from "@jest/globals";
+import { readFileSync, existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { ToolRegistry } from "../../tools/index";
+
+function readDeclaredCount(): { count: number; source: string } {
+  // jest runs with cwd = mcp-server-directory (package script) but tolerate
+  // a repo-root cwd too.
+  const candidates = [
+    resolve(process.cwd(), "..", "lib", "constants", "mcp-surface.ts"),
+    resolve(process.cwd(), "lib", "constants", "mcp-surface.ts"),
+  ];
+  const source = candidates.find((p) => existsSync(p));
+  if (!source) {
+    throw new Error(
+      `lib/constants/mcp-surface.ts not found from cwd=${process.cwd()} — the app-side directory tool-count constant is missing`,
+    );
+  }
+  const text = readFileSync(source, "utf8");
+  const match = text.match(/MCP_DIRECTORY_TOOL_COUNT\s*=\s*(\d+)/);
+  if (!match) {
+    throw new Error(`MCP_DIRECTORY_TOOL_COUNT not declared in ${source}`);
+  }
+  return { count: Number(match[1]), source };
+}
+
+describe("directory tool-count parity — app constant vs real registry", () => {
+  it("MCP_DIRECTORY_TOOL_COUNT equals the registry's advertised surface", () => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const registry = new ToolRegistry(null as any);
+    const advertised = registry.listTools().length;
+    const declared = readDeclaredCount();
+
+    if (advertised !== declared.count) {
+      throw new Error(
+        `Directory tool count drifted: registry advertises ${advertised} tools, ` +
+          `but MCP_DIRECTORY_TOOL_COUNT in ${declared.source} declares ${declared.count}. ` +
+          `Update the constant in the same PR as the tool change.`,
+      );
+    }
+    expect(advertised).toBe(declared.count);
+  });
+});

package/src/__tests__/tools/works.test.ts

@@ -1,4 +1,4 @@
-// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+// Copyright (c) 2025-2026 Withpica Ltd. All rights reserved.
 
 import {
   jest,

package/src/__tests__/utils/errors.test.ts

@@ -0,0 +1,68 @@
+// Copyright (c) 2025-2026 Withpica Ltd. All rights reserved.
+
+import { describe, it, expect } from "@jest/globals";
+import { formatError, McpServerError } from "../../utils/errors.js";
+
+describe("directory-mcp formatError structured-body decode", () => {
+  it("keeps McpServerError code + message", () => {
+    const result = formatError(
+      new McpServerError("Tool blew up", "TOOL_EXECUTION_ERROR"),
+    );
+    const parsed = JSON.parse(result.text);
+    expect(parsed.error).toBe("TOOL_EXECUTION_ERROR");
+    expect(parsed.message).toBe("Tool blew up");
+  });
+
+  // PICA's api-response.ts errorResponse() emits a nested body where `error`
+  // is an OBJECT: { success: false, error: { code, message, details } }. The
+  // mcp-sdk wraps it as `ApiError("API request failed: <status> <body>")`.
+  // Without decoding, the whole thing collapsed to UNKNOWN_ERROR.
+  it("surfaces code+message from a wrapped nested { error: { code, message } } body", () => {
+    const error = {
+      status: 404,
+      message:
+        "API 404 not found: " +
+        JSON.stringify({
+          success: false,
+          error: {
+            code: "WORK_NOT_FOUND",
+            message: "no work matches that ISWC",
+          },
+        }),
+    };
+    const result = formatError(error);
+    const parsed = JSON.parse(result.text);
+    expect(parsed.error).toBe("WORK_NOT_FOUND");
+    expect(parsed.message).toBe("no work matches that ISWC");
+  });
+
+  it("surfaces code+message from the flat { code, error } convention", () => {
+    const error = {
+      message: JSON.stringify({ code: "BAD_INPUT", error: "nope" }),
+    };
+    const result = formatError(error);
+    const parsed = JSON.parse(result.text);
+    expect(parsed.error).toBe("BAD_INPUT");
+    expect(parsed.message).toBe("nope");
+  });
+
+  it("recovers the real message from a coded-less body (no UNKNOWN noise)", () => {
+    const error = {
+      message: JSON.stringify({
+        success: false,
+        error: { message: "name required" },
+      }),
+    };
+    const result = formatError(error);
+    const parsed = JSON.parse(result.text);
+    expect(parsed.error).toBe("UNKNOWN_ERROR");
+    expect(parsed.message).toBe("name required");
+  });
+
+  it("falls through to UNKNOWN_ERROR for a plain non-JSON error", () => {
+    const result = formatError(new Error("some weird thing"));
+    const parsed = JSON.parse(result.text);
+    expect(parsed.error).toBe("UNKNOWN_ERROR");
+    expect(parsed.message).toBe("some weird thing");
+  });
+});

package/src/client.ts

@@ -1,4 +1,4 @@
-// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+// Copyright (c) 2025-2026 Withpica Ltd. All rights reserved.
 
 const DEFAULT_TIMEOUT_MS = 15_000;
 const MAX_RETRIES = 2;

package/src/config.ts

@@ -1,4 +1,4 @@
-// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+// Copyright (c) 2025-2026 Withpica Ltd. All rights reserved.
 
 export interface ServerConfig {
   directoryUrl: string;

package/src/index.ts

@@ -1,6 +1,5 @@
 #!/usr/bin/env node
-// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
-
+// Copyright (c) 2025-2026 Withpica Ltd. All rights reserved.
 
 import { loadConfig, validateConfig } from "./config.js";
 import { DirectoryMcpServer } from "./server.js";

package/src/lib/changelog.ts

@@ -1,4 +1,4 @@
-// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+// Copyright (c) 2025-2026 Withpica Ltd. All rights reserved.
 
 /**
  * Runtime CHANGELOG parser. Mirrors scripts/parse-changelog.ts but takes

package/src/prompts/index.ts

@@ -1,4 +1,4 @@
-// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+// Copyright (c) 2025-2026 Withpica Ltd. All rights reserved.
 
 /**
  * Prompt Registry for Directory MCP Server

package/src/prompts/public-question-atlas.ts

@@ -1,4 +1,4 @@
-// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+// Copyright (c) 2025-2026 Withpica Ltd. All rights reserved.
 
 /**
  * Public Question Atlas — ADR-229 Decision 1.

package/src/resources/llms-primer.ts

@@ -1,4 +1,4 @@
-// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+// Copyright (c) 2025-2026 Withpica Ltd. All rights reserved.
 
 export const DIRECTORY_PRIMER = `# PICA Directory — Public Music Catalog Search
 

package/src/server.ts

@@ -1,4 +1,4 @@
-// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+// Copyright (c) 2025-2026 Withpica Ltd. All rights reserved.
 
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

package/src/skills/find-music-for-sync-brief/SKILL.md

@@ -1,4 +1,4 @@
-<!-- Copyright (c) 2024-2026 Withpica Ltd. All rights reserved. -->
+<!-- Copyright (c) 2025-2026 Withpica Ltd. All rights reserved. -->
 ---
 name: find-music-for-sync-brief
 description: Find music in the PICA public directory for a sync brief — translate a mood/vibe/scene description into audio search parameters, run the search, and return a rights-aware shortlist with credit details for licensing.

package/src/skills/index.ts

@@ -1,4 +1,4 @@
-// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+// Copyright (c) 2025-2026 Withpica Ltd. All rights reserved.
 
 /**
  * Skills Registry — directory MCP, ADR-140 Phase 2b

package/src/skills/skills.generated.ts

@@ -1,4 +1,4 @@
-// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+// Copyright (c) 2025-2026 Withpica Ltd. All rights reserved.
 
 /**
  * GENERATED FILE — DO NOT EDIT BY HAND.

package/src/tools/__tests__/release-notes.test.ts

@@ -1,4 +1,4 @@
-// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+// Copyright (c) 2025-2026 Withpica Ltd. All rights reserved.
 
 import { DirectoryReleaseNotesTools } from "../release-notes.js";
 import type { DirectoryClient } from "../../client.js";

package/src/tools/chain.ts

@@ -1,4 +1,4 @@
-// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+// Copyright (c) 2025-2026 Withpica Ltd. All rights reserved.
 
 import { DirectoryClient } from "../client.js";
 import { ToolDefinition, ToolExecutor } from "./index.js";

package/src/tools/index.ts

@@ -1,4 +1,4 @@
-// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+// Copyright (c) 2025-2026 Withpica Ltd. All rights reserved.
 
 import { DirectoryClient } from "../client.js";
 import { DirectoryWorksTools } from "./works.js";

package/src/tools/people.ts

@@ -1,4 +1,4 @@
-// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+// Copyright (c) 2025-2026 Withpica Ltd. All rights reserved.
 
 import { DirectoryClient } from "../client.js";
 import { ToolDefinition, ToolExecutor } from "./index.js";

package/src/tools/recordings.ts

@@ -1,4 +1,4 @@
-// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+// Copyright (c) 2025-2026 Withpica Ltd. All rights reserved.
 
 import { DirectoryClient } from "../client.js";
 import { ToolDefinition, ToolExecutor } from "./index.js";

package/src/tools/release-notes.ts

@@ -1,4 +1,4 @@
-// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+// Copyright (c) 2025-2026 Withpica Ltd. All rights reserved.
 
 /* eslint-disable @typescript-eslint/no-explicit-any -- ToolExecutor signature uses Record<string, any> */
 
@@ -58,7 +58,8 @@ export class DirectoryReleaseNotesTools {
             "directory_list_works / directory_chain for those). " +
             "Returns { package, current_version, releases: [{ version, date, sections, markdown }], resource_uri }. " +
             "Defaults to the last 3 releases; use `since_version` to bound the output " +
-            "or `sections` to filter to Added/Fixed/etc.",
+            "or `sections` to filter to Added/Fixed/etc. " +
+            "→ then: directory_search (explore anything a release note mentions)",
           inputSchema: {
             type: "object",
             properties: {

package/src/tools/search.ts

@@ -1,4 +1,4 @@
-// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+// Copyright (c) 2025-2026 Withpica Ltd. All rights reserved.
 
 import { DirectoryClient } from "../client.js";
 import { ToolDefinition, ToolExecutor } from "./index.js";

package/src/tools/skills.ts

@@ -1,4 +1,4 @@
-// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+// Copyright (c) 2025-2026 Withpica Ltd. All rights reserved.
 
 /**
  * Directory MCP skill tools — ADR-140 Phase 2b
@@ -27,7 +27,8 @@ export class DirectorySkillsTools {
           description:
             "Use when the user asks: 'what skills do you have?', 'what can you do?', 'show me your methodologies', 'how do I find music here?'. " +
             "Returns the list of downloadable directory skill methodologies — name, description, trigger phrases. " +
-            "Cheap to call. Use directory_skill_get(name) to load a specific skill's full methodology body.",
+            "Cheap to call. " +
+            "→ then: directory_skill_get (load a specific skill's full methodology body)",
           inputSchema: {
             type: "object",
             properties: {},
@@ -43,7 +44,8 @@ export class DirectorySkillsTools {
           description:
             "Use when the user asks: 'what skills do you have?', 'what can you do?', 'show me your methodologies'. " +
             "Returns the full methodology body for one directory skill — markdown with step-by-step instructions and tool chains. " +
-            "Call directory_skill_list first to see available skill names, then directory_skill_get to load one. Read once at the start of the workflow; do not re-fetch on every step.",
+            "Call directory_skill_list first to see available skill names, then directory_skill_get to load one. Read once at the start of the workflow; do not re-fetch on every step. " +
+            "→ then: directory_search (run the loaded methodology against the catalogue)",
           inputSchema: {
             type: "object",
             properties: {

package/src/tools/works.ts

@@ -1,4 +1,4 @@
-// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+// Copyright (c) 2025-2026 Withpica Ltd. All rights reserved.
 
 import { DirectoryClient } from "../client.js";
 import { ToolDefinition, ToolExecutor } from "./index.js";

package/src/utils/errors.ts

@@ -1,4 +1,4 @@
-// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+// Copyright (c) 2025-2026 Withpica Ltd. All rights reserved.
 
 export class McpServerError extends Error {
   constructor(
@@ -31,11 +31,47 @@ export function formatError(error: any): { type: string; text: string } {
     };
   }
 
-  if (error instanceof Error) {
+  // Recover a structured error body so a real domain code surfaces instead of
+  // collapsing every route failure to UNKNOWN_ERROR. The mcp-sdk wraps the
+  // body inside `ApiError("API request failed: <status> <body>")`, so the JSON
+  // is not at the start of the string. PICA's api-response.ts errorResponse()
+  // emits { success: false, error: { code, message, details } } — `error` is a
+  // nested OBJECT; a few routes emit the flat { code, error } / { error_code,
+  // message } conventions. Decode all of them.
+  const rawMessage =
+    error instanceof Error
+      ? error.message
+      : (error as any)?.message || String(error);
+  const structuredBody = extractEmbeddedJson(rawMessage);
+  const nestedError =
+    structuredBody?.error && typeof structuredBody.error === "object"
+      ? (structuredBody.error as {
+          code?: string;
+          message?: string;
+          details?: unknown;
+        })
+      : null;
+  const bodyCode =
+    structuredBody?.error_code ?? structuredBody?.code ?? nestedError?.code;
+  const bodyMessage =
+    structuredBody?.message ??
+    nestedError?.message ??
+    (typeof structuredBody?.error === "string"
+      ? structuredBody.error
+      : undefined);
+  const bodyDetails = structuredBody?.details ?? nestedError?.details;
+
+  // Structured error body from the route — propagate the domain-specific code
+  // and message rather than the "API request failed: …" wrapper noise.
+  if (bodyCode) {
     return {
       type: "text",
       text: JSON.stringify(
-        { error: "UNKNOWN_ERROR", message: error.message },
+        {
+          error: bodyCode,
+          message: bodyMessage || rawMessage,
+          details: bodyDetails,
+        },
         null,
         2,
       ),
@@ -45,13 +81,45 @@ export function formatError(error: any): { type: string; text: string } {
   return {
     type: "text",
     text: JSON.stringify(
-      { error: "UNKNOWN_ERROR", message: String(error) },
+      {
+        error: "UNKNOWN_ERROR",
+        // A body without a code still carries the real message — surface it.
+        message: bodyMessage || rawMessage,
+      },
       null,
       2,
     ),
   };
 }
 
+/**
+ * Extract a JSON error body from an error message. The body may be the whole
+ * string, or — as the mcp-sdk wraps it — embedded after a prefix
+ * ("API request failed: 400 {…}"). Slices from the first `{` to the last `}`
+ * so a wrapped body is still recovered. Returns null when there is no
+ * parseable object.
+ */
+function extractEmbeddedJson(raw: unknown): {
+  error_code?: string;
+  code?: string;
+  message?: string;
+  // `error` is a string for { code, error: "<message>" }, an object for PICA's
+  // nested { error: { code, message, details } } shape.
+  error?: string | { code?: string; message?: string; details?: unknown };
+  details?: unknown;
+} | null {
+  if (typeof raw !== "string") return null;
+  const first = raw.indexOf("{");
+  const last = raw.lastIndexOf("}");
+  if (first === -1 || last <= first) return null;
+  try {
+    const parsed = JSON.parse(raw.slice(first, last + 1));
+    return parsed && typeof parsed === "object" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
 export function logError(context: string, error: any): void {
   const entry: Record<string, unknown> = {
     level: "error",

package/src/utils/formatting.ts

@@ -1,4 +1,4 @@
-// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+// Copyright (c) 2025-2026 Withpica Ltd. All rights reserved.
 
 export interface FormattedResult {
   content: Array<{ type: string; text: string }>;
@@ -6,9 +6,15 @@ export interface FormattedResult {
 }
 
 export function formatAsText(data: any): FormattedResult {
+  // MCP requires structuredContent to be a RECORD — bare arrays are rejected
+  // by the SDK server with -32602. Wrap them in the standard list envelope
+  // (mirrors @withpica/mcp-utils formatAsText).
+  const envelope = Array.isArray(data)
+    ? { items: data, count: data.length }
+    : data;
   return {
-    content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
-    structuredContent: data as Record<string, unknown>,
+    content: [{ type: "text", text: JSON.stringify(envelope, null, 2) }],
+    structuredContent: envelope as Record<string, unknown>,
   };
 }
 

package/tsconfig.build.json

@@ -0,0 +1,10 @@
+{
+  "extends": "./tsconfig.json",
+  "exclude": [
+    "node_modules",
+    "dist",
+    "**/__tests__/**",
+    "**/*.test.ts",
+    "**/*.spec.ts"
+  ]
+}