@withpica/mcp-server-directory 1.4.2 → 1.6.0

package/dist/utils/errors.d.ts

@@ -6,6 +6,16 @@ export declare class McpServerError extends Error {
 export declare class ToolExecutionError extends McpServerError {
     constructor(message: string, details?: any);
 }
+/**
+ * Status → code for a route refusal that carried no code of its own.
+ *
+ * ⚠️ A port of `STATUS_REFUSAL_CODES` in
+ * `mcp-server-shared/mcp-utils/src/errors.ts`. This package does not depend on
+ * `@withpica/mcp-utils` (it publishes on its own), so it cannot import the
+ * shared formatter; `scripts/__tests__/format-error-status-parity.test.ts`
+ * fails if the two tables disagree.
+ */
+export declare const STATUS_REFUSAL_CODES: Record<number, string>;
 export declare function formatError(error: any): {
     type: string;
     text: string;

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

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"AAEA,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,kBAAmB,SAAQ,cAAc;gBACxC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG;CAI3C;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,GAAG,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAuEtE;AA8BD,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,IAAI,CAS1D"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"AAEA,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,kBAAmB,SAAQ,cAAc;gBACxC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG;CAI3C;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAOvD,CAAC;AAEF,wBAAgB,WAAW,CAAC,KAAK,EAAE,GAAG,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CA6FtE;AA8BD,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,IAAI,CAS1D"}

package/dist/utils/errors.js

@@ -16,6 +16,23 @@ export class ToolExecutionError extends McpServerError {
         this.name = "ToolExecutionError";
     }
 }
+/**
+ * Status → code for a route refusal that carried no code of its own.
+ *
+ * ⚠️ A port of `STATUS_REFUSAL_CODES` in
+ * `mcp-server-shared/mcp-utils/src/errors.ts`. This package does not depend on
+ * `@withpica/mcp-utils` (it publishes on its own), so it cannot import the
+ * shared formatter; `scripts/__tests__/format-error-status-parity.test.ts`
+ * fails if the two tables disagree.
+ */
+export const STATUS_REFUSAL_CODES = {
+    400: "VALIDATION_ERROR",
+    404: "NOT_FOUND",
+    409: "CONFLICT",
+    413: "PAYLOAD_TOO_LARGE",
+    415: "UNSUPPORTED_MEDIA_TYPE",
+    422: "VALIDATION_ERROR",
+};
 export function formatError(error) {
     if (error instanceof McpServerError) {
         return {
@@ -56,6 +73,22 @@ export function formatError(error) {
             }, null, 2),
         };
     }
+    // A code-less 4xx is still a refusal; its status names the kind. Without
+    // this it read as UNKNOWN_ERROR, the bucket for an unclassified crash (ops
+    // issue 55510879 — the same defect in the shared formatter).
+    const status = error?.status;
+    const statusCode = typeof status === "number" ? STATUS_REFUSAL_CODES[status] : undefined;
+    if (statusCode) {
+        return {
+            type: "text",
+            text: JSON.stringify({
+                error: statusCode,
+                message: bodyMessage || rawMessage,
+                status,
+                ...(bodyDetails !== undefined ? { details: bodyDetails } : {}),
+            }, null, 2),
+        };
+    }
     return {
         type: "text",
         text: JSON.stringify({

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@withpica/mcp-server-directory",
-  "version": "1.4.2",
+  "version": "1.6.0",
   "description": "MCP Server for the withPICA Public Directory — enables AI assistants to search verified works and creators",
   "homepage": "https://withpica.com/connect",
   "bugs": {
@@ -9,7 +9,7 @@
   "type": "module",
   "main": "dist/index.js",
   "bin": {
-    "pica-directory-mcp": "./dist/index.js"
+    "pica-directory-mcp": "dist/index.js"
   },
   "scripts": {
     "prebuild": "tsx scripts/build-changelog.ts && tsx scripts/build-skills.ts",

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

@@ -273,10 +273,11 @@ describe("Prompt Eval Harness — Directory MCP", () => {
       expect(noTools).toEqual([]);
     });
 
-    it("directory-autopilot is read-only (no create/modify language)", async () => {
+    it("directory-autopilot says the catalogue is read-only and the one write needs the user's say-so", async () => {
       const result = await registry.getPrompt("directory-autopilot");
       const text = result.messages[0].content.text;
-      expect(text).toMatch(/read-only/i);
+      expect(text).toMatch(/catalogue is read-only/i);
+      expect(text).toMatch(/only if you ask/i);
     });
   });
 });

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

@@ -96,6 +96,40 @@ describe("DirectoryChainTools", () => {
       });
     });
 
+    it("forwards the ADR-321 rights filters only when true", async () => {
+      mockClient.request.mockResolvedValue({
+        success: true,
+        results: [],
+        total: 0,
+      });
+      const tool = chainTools
+        .getTools()
+        .find((t) => t.definition.name === "directory_chain")!;
+
+      await tool.executor({ programmable_only: true, ready_to_license: true });
+      expect(mockClient.request).toHaveBeenLastCalledWith("/chain", {
+        programmable_only: "true",
+        ready_to_license: "true",
+      });
+
+      // control: false (or a truthy non-boolean) is not forwarded
+      await tool.executor({
+        q: "song",
+        programmable_only: false,
+        ready_to_license: "yes",
+      });
+      expect(mockClient.request).toHaveBeenLastCalledWith("/chain", {
+        q: "song",
+      });
+    });
+
+    it("declares both rights filters as booleans in the schema", () => {
+      const props = chainTools.getTools()[0].definition.inputSchema
+        .properties as Record<string, { type: string }>;
+      expect(props.programmable_only.type).toBe("boolean");
+      expect(props.ready_to_license.type).toBe("boolean");
+    });
+
     it("returns a human summary when no results", async () => {
       mockClient.request.mockResolvedValue({
         success: true,

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

@@ -39,8 +39,8 @@ describe("Directory Composability Chains", () => {
     allNames = new Set(allTools.map((t) => t.name));
   });
 
-  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 12 tools are registered (parity with lib/constants/mcp-surface.ts is enforced by tool-count-parity.test.ts)", () => {
+    expect(allTools).toHaveLength(12);
   });
 
   it("all tools have composability chains", () => {

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

@@ -0,0 +1,135 @@
+// Copyright (c) 2025-2026 Withpica Ltd. All rights reserved.
+
+/**
+ * directory_send_licensing_enquiry — agents browsing the public directory had
+ * no way to reach an owner; the sync skill told them to "contact the rights
+ * holder via the credits summary" (brief 2026-09-25).
+ */
+
+import { jest, describe, it, expect, beforeEach } from "@jest/globals";
+import { DirectoryEnquiryTools } from "../../tools/enquiries";
+import { DirectoryClient } from "../../client";
+
+const WORK = "11111111-2222-4333-8444-555555555555";
+
+describe("directory_send_licensing_enquiry", () => {
+  let client: jest.Mocked<DirectoryClient>;
+  let tool: ReturnType<DirectoryEnquiryTools["getTools"]>[number];
+
+  beforeEach(() => {
+    client = {
+      sendLicensingEnquiry: jest.fn(),
+      workPageUrl: jest.fn(
+        (id: string) => `https://withpica.com/directory/works/${id}`,
+      ),
+    } as any;
+    tool = new DirectoryEnquiryTools(client).getTools()[0];
+  });
+
+  const args = {
+    work_id: WORK,
+    contact_name: "Jane Doe",
+    contact_email: "jane@films.test",
+    project_type: "film",
+    project_description: "opening titles",
+  };
+
+  it("is the one write-tier directory tool and requires the user's own details", () => {
+    expect(tool.definition.tier).toBe("write");
+    expect(tool.definition.inputSchema.required).toEqual([
+      "work_id",
+      "contact_name",
+      "contact_email",
+      "project_type",
+      "project_description",
+    ]);
+    expect(tool.definition.inputSchema.required).not.toContain("budget_amount");
+    expect(tool.definition.description).toMatch(/ONLY call after the user/);
+  });
+
+  it("maps to the public enquiry body, says 'not specified' for what the user didn't give, and returns the work page", async () => {
+    client.sendLicensingEnquiry.mockResolvedValue({
+      status: 200,
+      json: { success: true, data: { id: "enq-1", status: "pending" } },
+    });
+
+    const result = await tool.executor(args);
+
+    expect(client.sendLicensingEnquiry).toHaveBeenCalledWith(
+      expect.objectContaining({
+        workId: WORK,
+        contactName: "Jane Doe",
+        contactEmail: "jane@films.test",
+        territory: "not specified",
+        duration: "not specified",
+        proposedBudgetAmount: null,
+        proposedBudgetCurrency: "GBP",
+      }),
+    );
+    expect(result.isError).toBeUndefined();
+    expect(result.structuredContent).toEqual({
+      sent: true,
+      enquiry_id: "enq-1",
+      status: "pending",
+      work_page_url: `https://withpica.com/directory/works/${WORK}`,
+    });
+    expect(result.content[0].text).toContain("nothing has been agreed");
+  });
+
+  it.each([
+    [403, /not taking licensing enquiries/],
+    [404, /not listed in the public directory/],
+    [429, /Too many enquiries/],
+  ])("reports HTTP %i as not sent, with the reason", async (status, text) => {
+    client.sendLicensingEnquiry.mockResolvedValue({
+      status,
+      json: { success: false, error: { code: "X", message: "x" } },
+    });
+    const result = await tool.executor(args);
+    expect(result.isError).toBe(true);
+    expect(result.structuredContent).toMatchObject({
+      sent: false,
+      http_status: status,
+    });
+    expect(result.content[0].text).toMatch(text);
+  });
+
+  // Review finding: the route stores, THEN emails. A 5xx or a lost answer can
+  // follow a stored enquiry, so "not sent" would invite a duplicate.
+  it.each([500, 502])(
+    "reports HTTP %i as an unknown outcome, not 'not sent'",
+    async (status) => {
+      client.sendLicensingEnquiry.mockResolvedValue({ status, json: null });
+      const result = await tool.executor(args);
+      expect(result.structuredContent).toMatchObject({
+        sent: null,
+        outcome: "unknown",
+      });
+      expect(result.content[0].text).toMatch(/Do not resend/);
+      expect(result.content[0].text).not.toMatch(/^Not sent/);
+    },
+  );
+
+  it("reports a timeout as an unknown outcome", async () => {
+    client.sendLicensingEnquiry.mockRejectedValue(
+      new Error("Request timed out after 15000ms: POST x"),
+    );
+    const result = await tool.executor(args);
+    expect(result.structuredContent).toMatchObject({ outcome: "unknown" });
+  });
+
+  it("passes a 400's own message through", async () => {
+    client.sendLicensingEnquiry.mockResolvedValue({
+      status: 400,
+      json: {
+        success: false,
+        error: {
+          code: "ENQUIRY_EMAIL_INVALID",
+          message: "Invalid email format",
+        },
+      },
+    });
+    const result = await tool.executor(args);
+    expect(result.content[0].text).toContain("Invalid email format");
+  });
+});

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

@@ -18,6 +18,9 @@ describe("DirectoryWorksTools", () => {
   beforeEach(() => {
     mockClient = {
       request: jest.fn(),
+      workPageUrl: jest.fn(
+        (id: string) => `https://withpica.com/directory/works/${id}`,
+      ),
     } as any;
 
     worksTools = new DirectoryWorksTools(mockClient);

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

@@ -46,6 +46,19 @@ describe("directory-mcp formatError structured-body decode", () => {
     expect(parsed.message).toBe("nope");
   });
 
+  // Ops issue 55510879: a code-less 4xx is a refusal; its status names it.
+  it("classifies a code-less 400 as VALIDATION_ERROR by status", () => {
+    const error = {
+      status: 400,
+      message:
+        "API request failed: 400 " +
+        JSON.stringify({ success: false, error: "name required" }),
+    };
+    const parsed = JSON.parse(formatError(error).text);
+    expect(parsed.error).toBe("VALIDATION_ERROR");
+    expect(parsed.message).toBe("name required");
+  });
+
   it("recovers the real message from a coded-less body (no UNKNOWN noise)", () => {
     const error = {
       message: JSON.stringify({

package/src/client.ts

@@ -17,7 +17,22 @@ export interface DirectoryClientConfig {
   debug?: boolean;
 }
 
-export class DirectoryClient {
+/**
+ * What the directory tools need from the API. `DirectoryClient` below talks to
+ * the public API over HTTP (the npm/stdio server). The hosted endpoint
+ * (app/api/mcp/directory in the pica app) supplies its own implementation that
+ * calls the same route handlers in-process, so the caller's IP still reaches
+ * every rate limit.
+ */
+export interface DirectoryApi {
+  request<T>(path: string, params?: Record<string, string>): Promise<T>;
+  workPageUrl(workId: string): string;
+  sendLicensingEnquiry(
+    body: Record<string, unknown>,
+  ): Promise<{ status: number; json: any }>;
+}
+
+export class DirectoryClient implements DirectoryApi {
   private baseUrl: string;
   private debug: boolean;
 
@@ -37,7 +52,9 @@ export class DirectoryClient {
       return await fetch(url, { ...init, signal: controller.signal });
     } catch (err: any) {
       if (err.name === "AbortError") {
-        throw new Error(`Request timed out after ${timeoutMs}ms: GET ${url}`);
+        throw new Error(
+          `Request timed out after ${timeoutMs}ms: ${init.method ?? "GET"} ${url}`,
+        );
       }
       throw err;
     } finally {
@@ -45,6 +62,40 @@ export class DirectoryClient {
     }
   }
 
+  /** The public page for a directory work, for a human to open. */
+  workPageUrl(workId: string): string {
+    return `${this.baseUrl}/directory/works/${encodeURIComponent(workId)}`;
+  }
+
+  /**
+   * Send a licensing enquiry through the public enquiry route (the same one
+   * the directory's web form uses). ONE attempt, never retried: a retry after
+   * a timeout or a 5xx could store the enquiry twice and email the owner
+   * twice. Resolves with the status and parsed body for every HTTP answer,
+   * so the caller can tell a refusal (400/403/404/429) from a failure;
+   * throws only when no answer arrived.
+   */
+  async sendLicensingEnquiry(
+    body: Record<string, unknown>,
+  ): Promise<{ status: number; json: any }> {
+    const url = `${this.baseUrl}/api/shop/license-enquiries`;
+    if (this.debug) console.error(`[Directory MCP] POST ${url}`);
+    const response = await this.fetchWithTimeout(
+      url,
+      {
+        method: "POST",
+        headers: {
+          Accept: "application/json",
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify(body),
+      },
+      DEFAULT_TIMEOUT_MS,
+    );
+    const json: any = await response.json().catch(() => null);
+    return { status: response.status, json };
+  }
+
   async request<T>(path: string, params?: Record<string, string>): Promise<T> {
     const url = new URL(`${this.baseUrl}/api/public/directory${path}`);
     if (params) {

package/src/config.ts

@@ -1,5 +1,16 @@
 // Copyright (c) 2025-2026 Withpica Ltd. All rights reserved.
 
+import { createRequire } from "node:module";
+
+/**
+ * The package's own version, read from package.json (src/ and dist/ both sit
+ * one level below it). It was hardcoded "1.0.0", so serverInfo never said
+ * which release an agent was talking to.
+ */
+export const PACKAGE_VERSION: string = createRequire(import.meta.url)(
+  "../package.json",
+).version;
+
 export interface ServerConfig {
   directoryUrl: string;
   serverName: string;
@@ -11,7 +22,7 @@ export function loadConfig(): ServerConfig {
   return {
     directoryUrl: process.env.PICA_DIRECTORY_URL || "https://withpica.com",
     serverName: "pica-directory-mcp-server",
-    version: "1.0.0",
+    version: PACKAGE_VERSION,
     debug: process.env.DEBUG === "true" || process.env.DEBUG === "1",
   };
 }

package/src/prompts/index.ts

@@ -197,7 +197,7 @@ If I want to BROWSE what's in the directory:
 
 Tell me which workflow you chose and why, in one sentence. Offer alternatives.
 
-Important: This is a read-only public directory. I can search and look up, but I can't create or modify anything. Only works from organisations that opted into the directory are visible.`,
+Important: The directory's catalogue is read-only: I can search and look up, but I can't create or modify anything in it. The one thing I can send, and only if you ask, is a licensing enquiry to a work's owner, with your own name and email. Only works from organisations that opted into the directory are visible.`,
           },
         },
       ],

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

@@ -563,4 +563,22 @@ 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",
+      "ask the owner if I can license this",
+      "send a licensing enquiry for X",
+      "contact the rights holder about using this song",
+    ],
+    resolves_to: { kind: "tool", name: "directory_send_licensing_enquiry" },
+  },
 ];

package/src/resources/llms-primer.ts

@@ -2,7 +2,9 @@
 
 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

@@ -2,6 +2,7 @@
 
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
 import {
   CallToolRequestSchema,
   ListToolsRequestSchema,
@@ -10,7 +11,7 @@ import {
   ListPromptsRequestSchema,
   GetPromptRequestSchema,
 } from "@modelcontextprotocol/sdk/types.js";
-import { DirectoryClient } from "./client.js";
+import { DirectoryClient, type DirectoryApi } from "./client.js";
 import { ServerConfig } from "./config.js";
 import { ToolRegistry } from "./tools/index.js";
 import { PromptRegistry } from "./prompts/index.js";
@@ -21,7 +22,7 @@ import { SkillsRegistry } from "./skills/index.js";
 
 export class DirectoryMcpServer {
   private server: Server;
-  private client: DirectoryClient;
+  private client: DirectoryApi;
   private toolRegistry: ToolRegistry;
   private promptRegistry: PromptRegistry;
   private skillsRegistry: SkillsRegistry;
@@ -32,13 +33,19 @@ export class DirectoryMcpServer {
   // pipeline today; this is provenance-only.
   private clientAttributionLogged = false;
 
-  constructor(config: ServerConfig) {
+  /**
+   * `client` defaults to the HTTP client for the public API (the npm/stdio
+   * server). The hosted endpoint passes an in-process one.
+   */
+  constructor(config: ServerConfig, client?: DirectoryApi) {
     this.config = config;
 
-    this.client = new DirectoryClient({
-      baseUrl: config.directoryUrl,
-      debug: config.debug,
-    });
+    this.client =
+      client ??
+      new DirectoryClient({
+        baseUrl: config.directoryUrl,
+        debug: config.debug,
+      });
 
     this.server = new Server(
       {
@@ -248,6 +255,11 @@ export class DirectoryMcpServer {
     };
   }
 
+  /** Serve over any MCP transport (the hosted endpoint uses Streamable HTTP). */
+  async connect(transport: Transport): Promise<void> {
+    await this.server.connect(transport);
+  }
+
   async start(): Promise<void> {
     const transport = new StdioServerTransport();
     await this.server.connect(transport);

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

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

@@ -1,12 +1,12 @@
 // Copyright (c) 2025-2026 Withpica Ltd. All rights reserved.
 
-import { DirectoryClient } from "../client.js";
+import type { DirectoryApi } from "../client.js";
 import { ToolDefinition, ToolExecutor } from "./index.js";
 
 export class DirectoryChainTools {
-  private client: DirectoryClient;
+  private client: DirectoryApi;
 
-  constructor(client: DirectoryClient) {
+  constructor(client: DirectoryApi) {
     this.client = client;
   }
 
@@ -26,6 +26,9 @@ export class DirectoryChainTools {
             "Prefer over stitching list_works + lookup_work + lookup_person when you want the whole graph " +
             "around a track in a single round-trip. " +
             "Supports audio-only queries (min_bpm, key, mood, etc.) when you don't have a text query. " +
+            "Work results carry programmable_since (every owner confirmed a locked split) and " +
+            "ready_to_license (composition and a master confirmed, with audio, ISRC and ISWC); " +
+            "filter to either with programmable_only / ready_to_license. " +
             "→ then: directory_lookup_work (deeper work detail), directory_lookup_person (research a named writer)",
           inputSchema: {
             type: "object",
@@ -62,6 +65,16 @@ export class DirectoryChainTools {
                 type: "string",
                 description: "Mood filter (exact match)",
               },
+              programmable_only: {
+                type: "boolean",
+                description:
+                  "Only programmable songs — every owner confirmed a locked split, so a licence fee is paid to each without chasing sign-off. Drops people from text results.",
+              },
+              ready_to_license: {
+                type: "boolean",
+                description:
+                  "Only songs ready to license — composition and a master confirmed by every owner, that recording has audio and an ISRC, and the song has an ISWC. Audio results are the ready recordings themselves. Drops people from text results.",
+              },
               limit: {
                 type: "number",
                 description: "Max results (default 10, max 20)",
@@ -94,6 +107,8 @@ export class DirectoryChainTools {
     if (args.key) params.key = args.key;
     if (args.key_mode) params.key_mode = args.key_mode;
     if (args.mood) params.mood = args.mood;
+    if (args.programmable_only === true) params.programmable_only = "true";
+    if (args.ready_to_license === true) params.ready_to_license = "true";
 
     const response: any = await this.client.request("/chain", params);