@withpica/mcp-server-directory 1.0.0 → 1.2.0

package/src/tools/search.ts

@@ -0,0 +1,66 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+
+import { DirectoryClient } from "../client.js";
+import { ToolDefinition, ToolExecutor } from "./index.js";
+import { formatStructuredList } from "../utils/formatting.js";
+
+export class DirectorySearchTools {
+  private client: DirectoryClient;
+
+  constructor(client: DirectoryClient) {
+    this.client = client;
+  }
+
+  getTools(): Array<{ definition: ToolDefinition; executor: ToolExecutor }> {
+    return [
+      {
+        definition: {
+          name: "directory_search",
+          tier: "read",
+          description:
+            "Use when the user asks: 'find me X', 'who or what is X?', " +
+            "'find any record of X'. " +
+            "Use when the entity type is not yet known. " +
+            "Convenience fan-out across works and creators — runs list_works and list_people with the same query and returns the union. " +
+            "No cross-type ranking; prefer list_works or list_people when the entity type is known. " +
+            "→ then: directory_lookup_work (work details), directory_lookup_person (creator details)",
+          inputSchema: {
+            type: "object",
+            properties: {
+              query: {
+                type: "string",
+                description:
+                  "Search query — matches work titles, ISWCs, creator names, ISNIs",
+              },
+              type: {
+                type: "string",
+                enum: ["works", "people"],
+                description: "Limit results to a specific entity type",
+              },
+            },
+            required: ["query"],
+          },
+        },
+        executor: this.search.bind(this),
+      },
+    ];
+  }
+
+  private async search(args: Record<string, any>): Promise<any> {
+    const params: Record<string, string> = {
+      q: args.query,
+      limit: "20",
+      offset: "0",
+    };
+
+    if (args.type) params.type = args.type;
+
+    const response: any = await this.client.request("/search", params);
+
+    return formatStructuredList(response.data || [], "result", {
+      query: args.query,
+      type: args.type || "all",
+      total: response.pagination?.total || 0,
+    });
+  }
+}

package/src/tools/works.ts

@@ -0,0 +1,266 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+
+import { DirectoryClient } from "../client.js";
+import { ToolDefinition, ToolExecutor } from "./index.js";
+import { formatStructuredList } from "../utils/formatting.js";
+
+export class DirectoryWorksTools {
+  private client: DirectoryClient;
+
+  constructor(client: DirectoryClient) {
+    this.client = client;
+  }
+
+  getTools(): Array<{ definition: ToolDefinition; executor: ToolExecutor }> {
+    return [
+      {
+        definition: {
+          name: "directory_list_works",
+          tier: "read",
+          description:
+            "Use when the user asks: 'list works in PICA', 'works starting with B', " +
+            "'find works by publisher X', 'browse the catalog'. " +
+            "Browse and filter verified musical works in the PICA public directory. " +
+            "Filter by free-text (q), ISWC, ISRC, publisher, label, or starting letter (A–Z, or '#' for numeric). " +
+            "Sort by title (default) or recent. Returns paginated results. " +
+            "→ then: directory_lookup_work (full details with credits and audio)",
+          inputSchema: {
+            type: "object",
+            properties: {
+              q: {
+                type: "string",
+                description: "Text search across work titles and identifiers",
+              },
+              iswc: {
+                type: "string",
+                description: "Filter by ISWC (e.g. T-123.456.789-0)",
+              },
+              isrc: {
+                type: "string",
+                description:
+                  "Filter by ISRC (exact match, cross-table recording lookup)",
+              },
+              publisher: {
+                type: "string",
+                description: "Filter by publisher name (partial match)",
+              },
+              label: {
+                type: "string",
+                description: "Filter by record label (partial match)",
+              },
+              letter: {
+                type: "string",
+                description:
+                  "Filter by title starting letter (A–Z), or '#' for numeric",
+              },
+              sort: {
+                type: "string",
+                enum: ["title", "recent"],
+                description: "Sort order (default: title)",
+              },
+              page: {
+                type: "number",
+                description: "Page number (default: 1, 20 results per page)",
+              },
+            },
+          },
+        },
+        executor: this.listWorks.bind(this),
+      },
+      {
+        definition: {
+          name: "directory_lookup_work",
+          tier: "read",
+          description:
+            "Use when the user asks: 'what's the ISWC for X?', 'who wrote X?', " +
+            "'tell me about song X', 'is this song registered?'. " +
+            "Get full details of a single work by ISWC or work UUID. " +
+            "Returns credits with IPI numbers and attestation status, recordings with ISRCs, " +
+            "audio analysis (BPM, key, energy), DSP links (Spotify, Apple Music), " +
+            "AI provenance, and registration score as a structured markdown summary. " +
+            "→ then: directory_lookup_person (research a credited writer), directory_search_recordings (find similar tracks by audio)",
+          inputSchema: {
+            type: "object",
+            properties: {
+              identifier: {
+                type: "string",
+                description: "ISWC (e.g. T-123.456.789-0) or work UUID",
+              },
+            },
+            required: ["identifier"],
+          },
+        },
+        executor: this.lookupWork.bind(this),
+      },
+      {
+        definition: {
+          name: "directory_lookup_isrc",
+          tier: "read",
+          description:
+            "Use when the user asks: 'lookup ISRC X', 'what's the work for ISRC X?', " +
+            "'find the work for this recording'. " +
+            "Shortcut: look up the work(s) associated with a recording identifier (ISRC). " +
+            "Equivalent to directory_list_works with an isrc filter, pinned for recording-first discovery. " +
+            "→ then: directory_lookup_work (full details on the matched work)",
+          inputSchema: {
+            type: "object",
+            properties: {
+              isrc: {
+                type: "string",
+                description: "ISRC code (e.g. USABC1234567)",
+              },
+            },
+            required: ["isrc"],
+          },
+        },
+        executor: this.lookupIsrc.bind(this),
+      },
+    ];
+  }
+
+  private async listWorks(args: Record<string, any>): Promise<any> {
+    const page = Math.max(args.page || 1, 1);
+    const limit = 20;
+    const offset = (page - 1) * limit;
+
+    const params: Record<string, string> = {
+      limit: String(limit),
+      offset: String(offset),
+    };
+
+    if (args.q) params.q = args.q;
+    if (args.iswc) params.iswc = args.iswc;
+    if (args.isrc) params.isrc = args.isrc;
+    if (args.publisher) params.publisher = args.publisher;
+    if (args.label) params.label = args.label;
+    if (args.letter) params.letter = args.letter;
+    if (args.sort) params.sort = args.sort;
+
+    const response: any = await this.client.request("/works", params);
+
+    return formatStructuredList(response.data || [], "work", {
+      page,
+      total: response.pagination?.total || 0,
+      total_pages: Math.ceil((response.pagination?.total || 0) / limit),
+    });
+  }
+
+  private async lookupWork(args: Record<string, any>): Promise<any> {
+    const response: any = await this.client.request(
+      `/works/${encodeURIComponent(args.identifier)}`,
+    );
+
+    const data = response.data;
+    if (!data) {
+      return {
+        content: [{ type: "text", text: "Work not found." }],
+        structuredContent: {},
+      };
+    }
+
+    const lines: string[] = [];
+
+    const artistName = data.artist_name || data.primary_artist || "";
+    lines.push(`## ${data.title}${artistName ? ` by ${artistName}` : ""}`);
+    lines.push("");
+
+    const metaParts: string[] = [];
+    if (data.iswc) metaParts.push(`**ISWC:** ${data.iswc}`);
+    if (data.organisation_name)
+      metaParts.push(`**Organisation:** ${data.organisation_name}`);
+    if (metaParts.length > 0) lines.push(metaParts.join(" | "));
+
+    if (data.score !== undefined && data.score !== null) {
+      const tier =
+        data.score >= 80
+          ? "verified"
+          : data.score >= 50
+            ? "partial"
+            : "incomplete";
+      lines.push(`- **Score:** ${data.score}/100 (${tier})`);
+    }
+
+    lines.push("");
+
+    const credits: any[] = data.credits || [];
+    lines.push(`### Credits (${credits.length})`);
+    if (credits.length > 0) {
+      lines.push("| Role | Name | IPI | Attestation |");
+      lines.push("| --- | --- | --- | --- |");
+      for (const c of credits) {
+        const role = c.role || c.credit_role || "—";
+        const name = c.name || c.person_name || "—";
+        const ipi = c.ipi || c.ipi_number || "—";
+        const attestation = c.attestation_status || c.attestation || "—";
+        lines.push(`| ${role} | ${name} | ${ipi} | ${attestation} |`);
+      }
+    } else {
+      lines.push("_No credits recorded._");
+    }
+    lines.push("");
+
+    const recordings: any[] = data.recordings || [];
+    lines.push(`### Recordings (${recordings.length})`);
+    if (recordings.length > 0) {
+      lines.push("| ISRC | Type |");
+      lines.push("| --- | --- |");
+      for (const r of recordings) {
+        const isrc = r.isrc || "—";
+        const type = r.recording_type || r.type || "—";
+        lines.push(`| ${isrc} | ${type} |`);
+      }
+    } else {
+      lines.push("_No recordings linked._");
+    }
+    lines.push("");
+
+    const audio = data.audio_analysis || data.audio || null;
+    if (audio) {
+      lines.push("### Audio");
+      const audioParts: string[] = [];
+      if (audio.bpm !== undefined && audio.bpm !== null)
+        audioParts.push(`**BPM:** ${audio.bpm}`);
+      if (audio.key) audioParts.push(`**Key:** ${audio.key}`);
+      if (audio.energy !== undefined && audio.energy !== null)
+        audioParts.push(`**Energy:** ${audio.energy}`);
+      if (audioParts.length > 0) {
+        lines.push(`- ${audioParts.join(" | ")}`);
+      }
+      lines.push("");
+    }
+
+    const dsp = data.dsp_links || data.streaming_links || null;
+    if (dsp && typeof dsp === "object" && Object.keys(dsp).length > 0) {
+      lines.push("### DSP Links");
+      if (dsp.spotify) lines.push(`- Spotify: ${dsp.spotify}`);
+      if (dsp.apple_music) lines.push(`- Apple Music: ${dsp.apple_music}`);
+      if (dsp.youtube) lines.push(`- YouTube: ${dsp.youtube}`);
+      for (const [key, val] of Object.entries(dsp)) {
+        if (!["spotify", "apple_music", "youtube"].includes(key) && val) {
+          lines.push(`- ${key}: ${val}`);
+        }
+      }
+      lines.push("");
+    }
+
+    const markdown = lines.join("\n");
+
+    return {
+      content: [{ type: "text", text: markdown }],
+      structuredContent: data as Record<string, unknown>,
+    };
+  }
+
+  private async lookupIsrc(args: Record<string, any>): Promise<any> {
+    const response: any = await this.client.request("/works", {
+      isrc: args.isrc,
+      limit: "100",
+      offset: "0",
+    });
+
+    return formatStructuredList(response.data || [], "work", {
+      isrc: args.isrc,
+      total: response.pagination?.total || 0,
+    });
+  }
+}

package/src/utils/errors.ts

@@ -0,0 +1,64 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+
+export class McpServerError extends Error {
+  constructor(
+    message: string,
+    public code: string,
+    public details?: any,
+  ) {
+    super(message);
+    this.name = "McpServerError";
+    Object.setPrototypeOf(this, McpServerError.prototype);
+  }
+}
+
+export class ToolExecutionError extends McpServerError {
+  constructor(message: string, details?: any) {
+    super(message, "TOOL_EXECUTION_ERROR", details);
+    this.name = "ToolExecutionError";
+  }
+}
+
+export function formatError(error: any): { type: string; text: string } {
+  if (error instanceof McpServerError) {
+    return {
+      type: "text",
+      text: JSON.stringify(
+        { error: error.code, message: error.message, details: error.details },
+        null,
+        2,
+      ),
+    };
+  }
+
+  if (error instanceof Error) {
+    return {
+      type: "text",
+      text: JSON.stringify(
+        { error: "UNKNOWN_ERROR", message: error.message },
+        null,
+        2,
+      ),
+    };
+  }
+
+  return {
+    type: "text",
+    text: JSON.stringify(
+      { error: "UNKNOWN_ERROR", message: String(error) },
+      null,
+      2,
+    ),
+  };
+}
+
+export function logError(context: string, error: any): void {
+  const entry: Record<string, unknown> = {
+    level: "error",
+    context,
+    message: error instanceof Error ? error.message : String(error),
+    timestamp: new Date().toISOString(),
+  };
+  if (error instanceof Error && error.stack) entry.stack = error.stack;
+  console.error(JSON.stringify(entry));
+}

package/src/utils/formatting.ts

@@ -0,0 +1,28 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+
+export interface FormattedResult {
+  content: Array<{ type: string; text: string }>;
+  structuredContent?: Record<string, unknown>;
+}
+
+export function formatAsText(data: any): FormattedResult {
+  return {
+    content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+    structuredContent: data as Record<string, unknown>,
+  };
+}
+
+export function formatStructuredList<T>(
+  items: T[],
+  entityName: string,
+  metadata?: Record<string, any>,
+): FormattedResult {
+  const count = items.length;
+  const summary = `Found ${count} ${entityName}${count !== 1 ? "s" : ""}${
+    metadata?.query ? ` matching "${metadata.query}"` : ""
+  }.`;
+  return {
+    content: [{ type: "text", text: summary }],
+    structuredContent: { count, items, ...metadata } as Record<string, unknown>,
+  };
+}

package/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "isolatedModules": true,
+    "types": ["node", "jest"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "src/__tests__"]
+}