@withpica/mcp-server-directory 1.4.2 → 1.5.0

package/src/skills/skills.generated.ts

@@ -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/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

@@ -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/works.ts

@@ -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),
+      },
     };
   }