@withpica/mcp-server-directory 1.4.2 → 1.6.0

package/src/tools/enquiries.ts

@@ -0,0 +1,210 @@
+// Copyright (c) 2025-2026 Withpica Ltd. All rights reserved.
+
+import type { DirectoryApi } 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: DirectoryApi;
+
+  constructor(client: DirectoryApi) {
+    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,6 +1,6 @@
 // Copyright (c) 2025-2026 Withpica Ltd. All rights reserved.
 
-import { DirectoryClient } from "../client.js";
+import type { DirectoryApi } from "../client.js";
 import { DirectoryWorksTools } from "./works.js";
 import { DirectoryPeopleTools } from "./people.js";
 import { DirectorySearchTools } from "./search.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";
 
@@ -45,7 +47,7 @@ export class ToolRegistry {
     { definition: ToolDefinition; executor: ToolExecutor }
   >;
 
-  constructor(client: DirectoryClient) {
+  constructor(client: DirectoryApi) {
     this.tools = new Map();
 
     const groups = [
@@ -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,13 +1,13 @@
 // 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";
 import { formatStructuredList } from "../utils/formatting.js";
 
 export class DirectoryPeopleTools {
-  private client: DirectoryClient;
+  private client: DirectoryApi;
 
-  constructor(client: DirectoryClient) {
+  constructor(client: DirectoryApi) {
     this.client = client;
   }
 

package/src/tools/recordings.ts

@@ -1,13 +1,13 @@
 // 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";
 import { formatStructuredList } from "../utils/formatting.js";
 
 export class DirectoryRecordingsTools {
-  private client: DirectoryClient;
+  private client: DirectoryApi;
 
-  constructor(client: DirectoryClient) {
+  constructor(client: DirectoryApi) {
     this.client = client;
   }
 

package/src/tools/release-notes.ts

@@ -13,7 +13,7 @@
  * shipped in the npm tarball, already vetted as public.
  */
 
-import { DirectoryClient } from "../client.js";
+import type { DirectoryApi } from "../client.js";
 import { ToolDefinition, ToolExecutor, ToolResult } from "./index.js";
 import {
   parseChangelogText,
@@ -40,7 +40,7 @@ function compareSemver(a: string, b: string): number {
 }
 
 export class DirectoryReleaseNotesTools {
-  constructor(private client: DirectoryClient) {}
+  constructor(private client: DirectoryApi) {}
 
   getTools(): Array<{ definition: ToolDefinition; executor: ToolExecutor }> {
     return [

package/src/tools/search.ts

@@ -1,13 +1,13 @@
 // 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";
 import { formatStructuredList } from "../utils/formatting.js";
 
 export class DirectorySearchTools {
-  private client: DirectoryClient;
+  private client: DirectoryApi;
 
-  constructor(client: DirectoryClient) {
+  constructor(client: DirectoryApi) {
     this.client = client;
   }
 

package/src/tools/works.ts

@@ -1,13 +1,13 @@
 // 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";
 import { formatStructuredList } from "../utils/formatting.js";
 
 export class DirectoryWorksTools {
-  private client: DirectoryClient;
+  private client: DirectoryApi;
 
-  constructor(client: DirectoryClient) {
+  constructor(client: DirectoryApi) {
     this.client = client;
   }
 
@@ -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

@@ -19,6 +19,24 @@ export class ToolExecutionError extends McpServerError {
   }
 }
 
+/**
+ * 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: Record<number, string> = {
+  400: "VALIDATION_ERROR",
+  404: "NOT_FOUND",
+  409: "CONFLICT",
+  413: "PAYLOAD_TOO_LARGE",
+  415: "UNSUPPORTED_MEDIA_TYPE",
+  422: "VALIDATION_ERROR",
+};
+
 export function formatError(error: any): { type: string; text: string } {
   if (error instanceof McpServerError) {
     return {
@@ -78,6 +96,28 @@ export function formatError(error: any): { type: string; text: string } {
     };
   }
 
+  // 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 as { status?: unknown })?.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(