@withpica/mcp-server-directory 1.4.1 → 1.5.0

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.
@@ -563,4 +563,19 @@ export const PUBLIC_ATLAS: AtlasEntry[] = [
     ],
     resolves_to: { kind: "tool", name: "directory_release_notes" },
   },
+
+  // ─────────────────────────────────────────────────────────────────
+  // Reaching an owner — the directory's one write
+  // ─────────────────────────────────────────────────────────────────
+  {
+    question: "can I license this song?",
+    synonyms: [
+      "ask the owner if I can use this",
+      "send a licensing enquiry",
+      "contact the rights holder",
+      "who do I ask to license this?",
+      "I want to use this track in my project",
+    ],
+    resolves_to: { kind: "tool", name: "directory_send_licensing_enquiry" },
+  },
 ];

package/src/resources/llms-primer.ts

@@ -1,8 +1,10 @@
-// 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
 
-Read-only access to published music catalog data. No authentication required.
+Read access to published music catalog data, plus one write: sending a
+licensing enquiry to a work's owner when the user asks. No authentication
+required.
 Works and people are only visible if the owning organisation has opted into
 the directory.
 
@@ -17,9 +19,11 @@ research, or identifier lookup.
 - Search people by name, ISNI, IPI
 - Look up works by recording ISRC (directory_lookup_isrc)
 - Search recordings by audio characteristics (BPM, key, mood, energy)
+- Send a licensing enquiry to a work's owner (directory_send_licensing_enquiry),
+  only when the user asks and gives their own name, email and project
 
 ## What You Cannot Do
-- Create, update, or delete anything (read-only)
+- Create, update, or delete catalogue data (the catalogue is read-only)
 - Access unpublished works or private catalog data
 - See financial data, agreements, or internal metadata
 

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.
@@ -79,7 +79,7 @@ Be honest if the directory is small for a specific style — PICA's directory gr
 
 ## What not to do
 
-- Don't claim to license tracks — this skill returns a shortlist, not a license. The user contacts the rights holder via the credits summary.
+- Don't claim to license tracks — this skill returns a shortlist, not a license. When the user wants to approach an owner, offer `directory_send_licensing_enquiry`, and send it only once they say yes and give their own name, email and project description. Never invent those details.
 - Don't speculate about pricing — sync fees are negotiated per-placement
 - Don't return results from outside the directory (no general web search, no Spotify metadata directly) — the directory is the source of truth for this skill
 - Don't return tracks with no attested credits without flagging them as "rights chain unverified"

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.
@@ -26,7 +26,7 @@ export const SKILLS: Record<string, Skill> = {
     audience: "sync supervisor / music library / ad agency / film & TV music team",
     tools_required: ["directory_search_recordings","directory_lookup_work","directory_lookup_person"],
     output: "A rights-aware shortlist — each result with title, artist, audio characteristics (BPM, key, energy), credits summary for licensing contact, and any flags (unattested credits, low registration score, missing ISRC).",
-    body: "# find-music-for-sync-brief\n\nHelp the user find music in PICA's public directory for a sync brief. Translate their description (mood, vibe, scene, era, vocal style) into search parameters, run the search, and return a shortlist that includes the information they need to license — not just the track.\n\nThis is a public skill — any AI agent connected to the directory MCP can use it. The directory only contains works from organisations that have opted in.\n\n## Step 1 — Translate the brief\n\nMost sync briefs are described in natural language. Translate before searching:\n\n| User says | Search parameters |\n|---|---|\n| upbeat / uplifting / driving | `min_energy: 0.6`, `min_danceability: 0.5` |\n| dark / moody / brooding | `max_energy: 0.4`, `key_mode: minor` |\n| chill / ambient / background | `max_energy: 0.4`, `max_bpm: 100` |\n| epic / cinematic | `min_energy: 0.7`, often longer durations |\n| specific BPM (\"around 120bpm\") | `min_bpm: 115`, `max_bpm: 125` |\n| acoustic / sparse | typically lower `danceability` and `energy` |\n| vocal / instrumental | filter on `has_vocals` if available |\n\nIf the user gives an artist or song reference (\"something like X\"), look up that reference first via `directory_lookup_work` or `directory_search_recordings` by title — then mimic its audio profile in the new search.\n\n## Step 2 — Search\n\nCall `directory_search_recordings` with the parameters from step 1. Default limit is fine for an initial scan.\n\nIf the brief is vague, do two searches with slightly different parameters and compare. If too many results, narrow on BPM or key. If too few, widen the BPM range first, then drop key_mode.\n\n## Step 3 — Lookup full details\n\nFor the top 5-10 promising results, call `directory_lookup_work` to get:\n\n- **Who wrote it** — credits with IPI numbers (essential for the licensing contact path)\n- **Whether credits are attested** — an unattested credit means the ownership claim hasn't been verified; flag this\n- **DSP links** (Spotify, Apple Music) — the user wants to listen before shortlisting\n- **Registration score** — higher score = cleaner rights chain = easier to license\n\nFor high-value matches where the user wants to know more about the creator, call `directory_lookup_person` with the IPI to see the writer's broader catalog and collaborator network.\n\n## Step 4 — Present the shortlist\n\nPresent each shortlisted track with:\n\n- **Title, artist** — what the user listens for\n- **Audio profile** — BPM, key, energy (one line, the supervisor's quick filter)\n- **Credits summary** — writers with IPI, publisher if known (this is the licensing path)\n- **DSP links** — so the user can listen\n- **Flags** — unattested credits, low registration score, missing ISRC, multiple writers (= multi-party clearance needed)\n\nIf a track has all green flags (attested credits, high registration score, ISRC present, single or low-count writers), call it out as \"clean to clear.\"\n\n## Step 5 — If no results\n\nIf the search returns nothing, walk the user back through the brief:\n- Widen the BPM range first (most supervisors don't actually mind ±10 BPM)\n- Drop the key filter (key matching matters less than mood for most placements)\n- Drop the energy bounds and search by genre/mood text only\n- Suggest the user expand to adjacent moods (\"uplifting\" → also try \"warm\" or \"hopeful\")\n\nBe honest if the directory is small for a specific style — PICA's directory grows with org opt-ins; some niches are sparse.\n\n## What not to do\n\n- Don't claim to license tracks — this skill returns a shortlist, not a license. The user contacts the rights holder via the credits summary.\n- Don't speculate about pricing — sync fees are negotiated per-placement\n- Don't return results from outside the directory (no general web search, no Spotify metadata directly) — the directory is the source of truth for this skill\n- Don't return tracks with no attested credits without flagging them as \"rights chain unverified\"\n\n## Follow-on skills\n\n- `due-diligence-on-creator` (Stage 2 candidate) — for deeper research on a specific writer before reaching out\n",
+    body: "# find-music-for-sync-brief\n\nHelp the user find music in PICA's public directory for a sync brief. Translate their description (mood, vibe, scene, era, vocal style) into search parameters, run the search, and return a shortlist that includes the information they need to license — not just the track.\n\nThis is a public skill — any AI agent connected to the directory MCP can use it. The directory only contains works from organisations that have opted in.\n\n## Step 1 — Translate the brief\n\nMost sync briefs are described in natural language. Translate before searching:\n\n| User says | Search parameters |\n|---|---|\n| upbeat / uplifting / driving | `min_energy: 0.6`, `min_danceability: 0.5` |\n| dark / moody / brooding | `max_energy: 0.4`, `key_mode: minor` |\n| chill / ambient / background | `max_energy: 0.4`, `max_bpm: 100` |\n| epic / cinematic | `min_energy: 0.7`, often longer durations |\n| specific BPM (\"around 120bpm\") | `min_bpm: 115`, `max_bpm: 125` |\n| acoustic / sparse | typically lower `danceability` and `energy` |\n| vocal / instrumental | filter on `has_vocals` if available |\n\nIf the user gives an artist or song reference (\"something like X\"), look up that reference first via `directory_lookup_work` or `directory_search_recordings` by title — then mimic its audio profile in the new search.\n\n## Step 2 — Search\n\nCall `directory_search_recordings` with the parameters from step 1. Default limit is fine for an initial scan.\n\nIf the brief is vague, do two searches with slightly different parameters and compare. If too many results, narrow on BPM or key. If too few, widen the BPM range first, then drop key_mode.\n\n## Step 3 — Lookup full details\n\nFor the top 5-10 promising results, call `directory_lookup_work` to get:\n\n- **Who wrote it** — credits with IPI numbers (essential for the licensing contact path)\n- **Whether credits are attested** — an unattested credit means the ownership claim hasn't been verified; flag this\n- **DSP links** (Spotify, Apple Music) — the user wants to listen before shortlisting\n- **Registration score** — higher score = cleaner rights chain = easier to license\n\nFor high-value matches where the user wants to know more about the creator, call `directory_lookup_person` with the IPI to see the writer's broader catalog and collaborator network.\n\n## Step 4 — Present the shortlist\n\nPresent each shortlisted track with:\n\n- **Title, artist** — what the user listens for\n- **Audio profile** — BPM, key, energy (one line, the supervisor's quick filter)\n- **Credits summary** — writers with IPI, publisher if known (this is the licensing path)\n- **DSP links** — so the user can listen\n- **Flags** — unattested credits, low registration score, missing ISRC, multiple writers (= multi-party clearance needed)\n\nIf a track has all green flags (attested credits, high registration score, ISRC present, single or low-count writers), call it out as \"clean to clear.\"\n\n## Step 5 — If no results\n\nIf the search returns nothing, walk the user back through the brief:\n- Widen the BPM range first (most supervisors don't actually mind ±10 BPM)\n- Drop the key filter (key matching matters less than mood for most placements)\n- Drop the energy bounds and search by genre/mood text only\n- Suggest the user expand to adjacent moods (\"uplifting\" → also try \"warm\" or \"hopeful\")\n\nBe honest if the directory is small for a specific style — PICA's directory grows with org opt-ins; some niches are sparse.\n\n## What not to do\n\n- Don't claim to license tracks — this skill returns a shortlist, not a license. When the user wants to approach an owner, offer `directory_send_licensing_enquiry`, and send it only once they say yes and give their own name, email and project description. Never invent those details.\n- Don't speculate about pricing — sync fees are negotiated per-placement\n- Don't return results from outside the directory (no general web search, no Spotify metadata directly) — the directory is the source of truth for this skill\n- Don't return tracks with no attested credits without flagging them as \"rights chain unverified\"\n\n## Follow-on skills\n\n- `due-diligence-on-creator` (Stage 2 candidate) — for deeper research on a specific writer before reaching out\n",
   },
 };
 

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/enquiries.ts

@@ -0,0 +1,210 @@
+// Copyright (c) 2025-2026 Withpica Ltd. All rights reserved.
+
+import { DirectoryClient } from "../client.js";
+import { ToolDefinition, ToolExecutor, ToolResult } from "./index.js";
+
+const PROJECT_TYPES = [
+  "film",
+  "tv series",
+  "commercial",
+  "trailer",
+  "video game",
+  "podcast",
+  "social media",
+  "other",
+];
+
+/** The enquiry route answers `{ error: "…" }` or `{ error: { message } }`. */
+function errorMessage(json: any): string | null {
+  const e = json?.error;
+  if (typeof e === "string") return e;
+  if (e && typeof e.message === "string") return e.message;
+  return null;
+}
+
+/**
+ * The route stores the enquiry and THEN sends the emails, so a 5xx or a lost
+ * answer can come after it was stored. Saying "not sent" there would invite a
+ * resend, and a second enquiry and email to the owner.
+ */
+function outcomeUnknown(detail: string): ToolResult {
+  const reason =
+    "Outcome unknown: the enquiry may already have reached the owner. " +
+    "Do not resend without checking with the user first.";
+  return {
+    content: [{ type: "text", text: `${reason} (${detail})` }],
+    structuredContent: { sent: null, outcome: "unknown", reason, detail },
+    isError: true,
+  };
+}
+
+/**
+ * The directory's only non-read tool: send a licensing enquiry to the owner
+ * of a work listed in the public directory. It goes through the same public
+ * route as the directory's web form (POST /api/shop/license-enquiries), so
+ * the same rules apply: the work must be listed, the owner must not have
+ * switched enquiries off, and a budget is optional.
+ */
+export class DirectoryEnquiryTools {
+  private client: DirectoryClient;
+
+  constructor(client: DirectoryClient) {
+    this.client = client;
+  }
+
+  getTools(): Array<{ definition: ToolDefinition; executor: ToolExecutor }> {
+    return [
+      {
+        definition: {
+          name: "directory_send_licensing_enquiry",
+          tier: "write",
+          description:
+            "Use when the user asks: 'ask the owner if I can license this', " +
+            "'send a licensing enquiry for X', 'contact the rights holder about using this song'. " +
+            "Sends a licensing enquiry to the owner of a work listed in the public directory. " +
+            "The enquiry is passed to the owner, who can reply to the user by email (the user's address is " +
+            "shared with them); a confirmation email to the user is usually sent but not guaranteed. " +
+            "Nothing is agreed or priced: it only opens the conversation. " +
+            "ONLY call after the user has explicitly asked to send it and has given their own name, " +
+            "email and a description of the project. Never invent these, and never send on their behalf " +
+            "without asking. Get work_id from directory_lookup_work, directory_list_works or directory_chain. " +
+            "A 403 means the owner is not taking enquiries; a 404 means the work is not publicly listed; " +
+            "an unknown outcome means it may already have been sent, so never resend without asking. " +
+            "NOT FOR: looking up who owns a song (use directory_lookup_work). " +
+            "→ then: directory_lookup_work (the work page and credits, to share with the user)",
+          inputSchema: {
+            type: "object",
+            properties: {
+              work_id: {
+                type: "string",
+                description: "The work's UUID from the directory.",
+              },
+              contact_name: {
+                type: "string",
+                description: "The user's own name, as they gave it.",
+              },
+              contact_email: {
+                type: "string",
+                description:
+                  "The user's own email address. The owner will reply to it.",
+              },
+              company_name: {
+                type: "string",
+                description: "The user's company or production (optional).",
+              },
+              project_type: {
+                type: "string",
+                enum: PROJECT_TYPES,
+                description: "The kind of project.",
+              },
+              project_description: {
+                type: "string",
+                description:
+                  "How the music would be used, in the user's words.",
+              },
+              territory: {
+                type: "string",
+                description:
+                  "Where it would be used (optional; omit if the user didn't say).",
+              },
+              term: {
+                type: "string",
+                description:
+                  "For how long (optional; omit if the user didn't say).",
+              },
+              budget_amount: {
+                type: "number",
+                description:
+                  "Proposed fee, only if the user named one (optional).",
+              },
+              budget_currency: {
+                type: "string",
+                description: "Three-letter currency code (default GBP).",
+              },
+              budget_notes: {
+                type: "string",
+                description:
+                  "Anything the user said about budget that isn't a single amount, e.g. a range.",
+              },
+            },
+            required: [
+              "work_id",
+              "contact_name",
+              "contact_email",
+              "project_type",
+              "project_description",
+            ],
+            additionalProperties: false,
+          },
+        },
+        executor: this.sendEnquiry.bind(this),
+      },
+    ];
+  }
+
+  private async sendEnquiry(args: Record<string, any>): Promise<ToolResult> {
+    const workId = String(args.work_id ?? "");
+    let answer: { status: number; json: any };
+    try {
+      answer = await this.client.sendLicensingEnquiry({
+        workId,
+        contactName: args.contact_name,
+        contactEmail: args.contact_email,
+        companyName: args.company_name,
+        projectType: args.project_type,
+        projectDescription: args.project_description,
+        // Not specified is said plainly, never guessed.
+        territory: args.territory || "not specified",
+        duration: args.term || "not specified",
+        proposedBudgetAmount:
+          typeof args.budget_amount === "number" ? args.budget_amount : null,
+        proposedBudgetCurrency: args.budget_currency || "GBP",
+        budgetNotes: args.budget_notes,
+      });
+    } catch (err) {
+      // No answer at all (timeout, network): the route may still have stored it.
+      return outcomeUnknown((err as Error).message);
+    }
+    const { status, json } = answer;
+    const page = this.client.workPageUrl(workId);
+
+    if (status >= 200 && status < 300 && json?.data?.id) {
+      return {
+        content: [
+          {
+            type: "text",
+            text:
+              `Enquiry passed to the owner (reference ${json.data.id}). ` +
+              `They can reply to ${args.contact_email} if they want to take it further; ` +
+              `nothing has been agreed. Work page: ${page}`,
+          },
+        ],
+        structuredContent: {
+          sent: true,
+          enquiry_id: json.data.id,
+          status: json.data.status,
+          work_page_url: page,
+        },
+      };
+    }
+
+    // A 5xx, or a 2xx without the reference, may have stored the enquiry.
+    if (status >= 500 || (status >= 200 && status < 300))
+      return outcomeUnknown(`HTTP ${status}`);
+
+    const reason =
+      status === 403
+        ? "The owner is not taking licensing enquiries for this work."
+        : status === 404
+          ? "That work is not listed in the public directory."
+          : status === 429
+            ? "Too many enquiries were sent recently. Try again later."
+            : (errorMessage(json) ??
+              `The enquiry was not sent (HTTP ${status}).`);
+    return {
+      content: [{ type: "text", text: `Not sent. ${reason}` }],
+      structuredContent: { sent: false, http_status: status, reason },
+      isError: true,
+    };
+  }
+}

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";
@@ -8,13 +8,15 @@ import { DirectoryRecordingsTools } from "./recordings.js";
 import { DirectoryChainTools } from "./chain.js";
 import { DirectorySkillsTools } from "./skills.js";
 import { DirectoryReleaseNotesTools } from "./release-notes.js";
+import { DirectoryEnquiryTools } from "./enquiries.js";
 import { formatError, logError, ToolExecutionError } from "../utils/errors.js";
 
 /**
  * ADR-230 — authority tier on every directory_* tool. Sister of the
- * creator + team MCP's `Tier` declaration. Every directory tool is
- * `read` (public catalogue lookup with no mutation surface), but the
- * field is required for cross-surface uniformity and lint enforcement.
+ * creator + team MCP's `Tier` declaration. Every directory tool is `read`
+ * (public catalogue lookup) except directory_send_licensing_enquiry
+ * (`write`, tools/enquiries.ts), which sends an enquiry through the same
+ * public route as the directory's web form.
  */
 export type Tier = "read" | "draft" | "write" | "destructive";
 
@@ -56,6 +58,7 @@ export class ToolRegistry {
       new DirectoryChainTools(client),
       new DirectorySkillsTools(),
       new DirectoryReleaseNotesTools(client),
+      new DirectoryEnquiryTools(client),
     ];
 
     for (const group of groups) {

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";
@@ -243,11 +243,29 @@ export class DirectoryWorksTools {
       lines.push("");
     }
 
+    // How to reach the owner. Enquiries are opt-out (only an explicit false
+    // closes them), the same test the enquiry route applies.
+    const workId: string | undefined = data.work_id || data.id;
+    const pageUrl = workId ? this.client.workPageUrl(workId) : undefined;
+    const enquiriesOpen = data.contact_enabled !== false;
+    lines.push("### Licensing");
+    if (pageUrl) lines.push(`- Work page: ${pageUrl}`);
+    lines.push(
+      enquiriesOpen && workId
+        ? `- Enquiries open: with the user's go-ahead, send one via directory_send_licensing_enquiry (work_id ${workId}).`
+        : "- The owner is not taking licensing enquiries for this work.",
+    );
+    lines.push("");
+
     const markdown = lines.join("\n");
 
     return {
       content: [{ type: "text", text: markdown }],
-      structuredContent: data as Record<string, unknown>,
+      structuredContent: {
+        ...(data as Record<string, unknown>),
+        work_page_url: pageUrl ?? null,
+        enquiries_open: enquiriesOpen && Boolean(workId),
+      },
     };
   }
 

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"
+  ]
+}

package/dist/tools/__tests__/release-notes.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=release-notes.test.d.ts.map

package/dist/tools/__tests__/release-notes.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"release-notes.test.d.ts","sourceRoot":"","sources":["../../../src/tools/__tests__/release-notes.test.ts"],"names":[],"mappings":""}