@withpica/mcp-server-directory 1.0.0 → 1.1.0

package/src/tools/people.ts

@@ -0,0 +1,215 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+
+import { DirectoryClient } from "../client.js";
+import { ToolDefinition, ToolExecutor } from "./index.js";
+import { formatAsText, formatStructuredList } from "../utils/formatting.js";
+
+export class DirectoryPeopleTools {
+  private client: DirectoryClient;
+
+  constructor(client: DirectoryClient) {
+    this.client = client;
+  }
+
+  getTools(): Array<{ definition: ToolDefinition; executor: ToolExecutor }> {
+    return [
+      {
+        definition: {
+          name: "directory_list_people",
+          description:
+            "Browse and filter creators in the PICA public directory. " +
+            "Search by name, ISNI, or IPI number. Returns paginated results. " +
+            "→ then: directory_lookup_person_full (full profile with works and identifiers)",
+          inputSchema: {
+            type: "object",
+            properties: {
+              q: {
+                type: "string",
+                description: "Text search across creator names",
+              },
+              isni: {
+                type: "string",
+                description: "Filter by ISNI identifier",
+              },
+              ipi: {
+                type: "string",
+                description: "Filter by IPI number",
+              },
+              page: {
+                type: "number",
+                description: "Page number (default: 1, 20 results per page)",
+              },
+            },
+          },
+        },
+        executor: this.listPeople.bind(this),
+      },
+      {
+        definition: {
+          name: "directory_lookup_person",
+          description:
+            "Get full details of a single creator by their global creator ID, ISNI, IPI, or MusicBrainz ID. " +
+            "Returns roles, works, identifiers, and profile information. " +
+            "→ then: directory_lookup_person_full (agent-optimised markdown), directory_lookup_work_full (inspect a credited work)",
+          inputSchema: {
+            type: "object",
+            properties: {
+              id: {
+                type: "string",
+                description:
+                  "Global creator ID (UUID), ISNI, IPI number, or MusicBrainz ID",
+              },
+            },
+            required: ["id"],
+          },
+        },
+        executor: this.lookupPerson.bind(this),
+      },
+      {
+        definition: {
+          name: "directory_lookup_person_full",
+          description:
+            "Get complete details about a person in the public directory — identifiers (IPI, ISNI), " +
+            "credited works with roles, collaborator network, and verification score. " +
+            "Returns a structured markdown summary. " +
+            "→ then: directory_lookup_work_full (inspect a specific work), directory_search_recordings (find their recordings by audio)",
+          inputSchema: {
+            type: "object",
+            properties: {
+              id: {
+                type: "string",
+                description:
+                  "Global creator ID (UUID), ISNI, IPI number, or MusicBrainz ID",
+              },
+            },
+            required: ["id"],
+          },
+        },
+        executor: this.lookupPersonFull.bind(this),
+      },
+    ];
+  }
+
+  private async listPeople(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.isni) params.isni = args.isni;
+    if (args.ipi) params.ipi = args.ipi;
+
+    const response: any = await this.client.request("/people", params);
+
+    return formatStructuredList(response.data || [], "creator", {
+      page,
+      total: response.pagination?.total || 0,
+      total_pages: Math.ceil((response.pagination?.total || 0) / limit),
+    });
+  }
+
+  private async lookupPerson(args: Record<string, any>): Promise<any> {
+    const response: any = await this.client.request(
+      `/people/${encodeURIComponent(args.id)}`,
+    );
+
+    return formatAsText(response.data);
+  }
+
+  private async lookupPersonFull(args: Record<string, any>): Promise<any> {
+    const response: any = await this.client.request(
+      `/people/${encodeURIComponent(args.id)}`,
+    );
+
+    const data = response.data;
+    if (!data) {
+      return {
+        content: [{ type: "text", text: "Person not found." }],
+        structuredContent: {},
+      };
+    }
+
+    const lines: string[] = [];
+
+    // Name heading
+    const name = data.name || data.full_name || data.display_name || "Unknown";
+    lines.push(`## ${name}`);
+    lines.push("");
+
+    // Score / verification
+    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("");
+    }
+
+    // Identifiers
+    const identifiers: Array<{ type: string; value: string }> = [];
+    if (data.ipi || data.ipi_number)
+      identifiers.push({ type: "IPI", value: data.ipi || data.ipi_number });
+    if (data.isni) identifiers.push({ type: "ISNI", value: data.isni });
+    if (data.musicbrainz_id)
+      identifiers.push({ type: "MusicBrainz", value: data.musicbrainz_id });
+    if (data.ipn) identifiers.push({ type: "IPN", value: data.ipn });
+
+    lines.push("### Identifiers");
+    if (identifiers.length > 0) {
+      lines.push("| Type | Value |");
+      lines.push("| --- | --- |");
+      for (const id of identifiers) {
+        lines.push(`| ${id.type} | ${id.value} |`);
+      }
+    } else {
+      lines.push("_No identifiers recorded._");
+    }
+    lines.push("");
+
+    // Works
+    const works: any[] = data.works || data.credited_works || [];
+    lines.push(`### Works (${works.length})`);
+    if (works.length > 0) {
+      lines.push("| Title | Role |");
+      lines.push("| --- | --- |");
+      for (const w of works) {
+        const title = w.title || "—";
+        const role = w.role || w.credit_role || "—";
+        lines.push(`| ${title} | ${role} |`);
+      }
+    } else {
+      lines.push("_No works recorded._");
+    }
+    lines.push("");
+
+    // Collaborators
+    const collaborators: any[] = data.collaborators || [];
+    lines.push(`### Collaborators (${collaborators.length})`);
+    if (collaborators.length > 0) {
+      lines.push("| Name |");
+      lines.push("| --- |");
+      for (const c of collaborators) {
+        const colName = c.name || c.full_name || c.display_name || "—";
+        lines.push(`| ${colName} |`);
+      }
+    } else {
+      lines.push("_No collaborators recorded._");
+    }
+    lines.push("");
+
+    const markdown = lines.join("\n");
+
+    return {
+      content: [{ type: "text", text: markdown }],
+      structuredContent: data as Record<string, unknown>,
+    };
+  }
+}

package/src/tools/recordings.ts

@@ -0,0 +1,145 @@
+// 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 DirectoryRecordingsTools {
+  private client: DirectoryClient;
+
+  constructor(client: DirectoryClient) {
+    this.client = client;
+  }
+
+  getTools(): Array<{ definition: ToolDefinition; executor: ToolExecutor }> {
+    return [
+      {
+        definition: {
+          name: "directory_search_recordings",
+          description:
+            "Search recordings across the PICA directory by audio characteristics. " +
+            "Find tracks by BPM, key, energy, danceability, duration, and more. " +
+            "Only returns recordings from organisations that have opted into the directory. " +
+            "Use this for sync licensing searches like 'find upbeat tracks around 120 BPM in a minor key'. " +
+            "→ then: directory_lookup_work_full (credits and licensing details for a matched track)",
+          inputSchema: {
+            type: "object",
+            properties: {
+              min_bpm: {
+                type: "number",
+                description: "Minimum BPM (e.g. 100)",
+              },
+              max_bpm: {
+                type: "number",
+                description: "Maximum BPM (e.g. 140)",
+              },
+              key: {
+                type: "string",
+                description:
+                  "Musical key (e.g. 'C', 'F#', 'Bb'). Matches the detected key.",
+              },
+              key_mode: {
+                type: "string",
+                enum: ["major", "minor"],
+                description: "Key mode — major or minor",
+              },
+              min_energy: {
+                type: "number",
+                description: "Minimum energy (0-1). Higher = more energetic.",
+              },
+              max_energy: {
+                type: "number",
+                description: "Maximum energy (0-1).",
+              },
+              min_danceability: {
+                type: "number",
+                description:
+                  "Minimum danceability (0-1). Higher = more danceable.",
+              },
+              max_danceability: {
+                type: "number",
+                description: "Maximum danceability (0-1).",
+              },
+              min_duration: {
+                type: "number",
+                description: "Minimum duration in seconds.",
+              },
+              max_duration: {
+                type: "number",
+                description: "Maximum duration in seconds.",
+              },
+              vocals_only: {
+                type: "boolean",
+                description: "Only return tracks with vocals.",
+              },
+              instrumental_only: {
+                type: "boolean",
+                description: "Only return instrumental tracks.",
+              },
+              mood: {
+                type: "string",
+                description: "Filter by mood (exact match).",
+              },
+              limit: {
+                type: "number",
+                description: "Max results to return (default: 20, max: 100).",
+              },
+            },
+          },
+        },
+        executor: this.searchRecordings.bind(this),
+      },
+    ];
+  }
+
+  private async searchRecordings(args: Record<string, any>): Promise<any> {
+    const params: Record<string, string> = {};
+
+    // Map all filters to query params
+    const numericKeys = [
+      "min_bpm",
+      "max_bpm",
+      "min_energy",
+      "max_energy",
+      "min_danceability",
+      "max_danceability",
+      "min_duration",
+      "max_duration",
+      "limit",
+    ];
+    for (const k of numericKeys) {
+      if (args[k] != null) params[k] = String(args[k]);
+    }
+
+    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.vocals_only) params.vocals_only = "true";
+    if (args.instrumental_only) params.instrumental_only = "true";
+
+    const response: any = await this.client.request("/recordings", params);
+
+    const recordings = response.data || [];
+
+    // Format each recording for readability
+    const formatted = recordings.map((r: any) => {
+      const parts: string[] = [`${r.title} (${r.isrc})`];
+      if (r.artist_name) parts.push(`Artist: ${r.artist_name}`);
+      if (r.bpm) parts.push(`BPM: ${Math.round(r.bpm)}`);
+      if (r.key)
+        parts.push(`Key: ${r.key}${r.key_mode ? ` ${r.key_mode}` : ""}`);
+      if (r.energy != null) parts.push(`Energy: ${r.energy}`);
+      if (r.duration_seconds)
+        parts.push(`Duration: ${Math.round(r.duration_seconds)}s`);
+      if (r.has_vocals != null)
+        parts.push(r.has_vocals ? "Vocals: yes" : "Instrumental");
+      if (r.owner_org_name) parts.push(`Owner: ${r.owner_org_name}`);
+      if (r.work_title) parts.push(`Work: ${r.work_title}`);
+      return { ...r, _summary: parts.join(" | ") };
+    });
+
+    return formatStructuredList(formatted, "recording", {
+      filters: args,
+    });
+  }
+}

package/src/tools/search.ts

@@ -0,0 +1,63 @@
+// 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",
+          description:
+            "Search across all verified works and creators in the PICA public directory. " +
+            "Returns mixed results sorted by relevance. Use this for broad searches; " +
+            "use list_works or list_people for filtered browsing. " +
+            "→ then: directory_lookup_work_full (work details), directory_lookup_person_full (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,273 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+
+import { DirectoryClient } from "../client.js";
+import { ToolDefinition, ToolExecutor } from "./index.js";
+import { formatAsText, 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",
+          description:
+            "Browse and filter verified musical works in the PICA public directory. " +
+            "Search by title, ISWC, publisher, or label. Returns paginated results. " +
+            "→ then: directory_lookup_work_full (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)",
+              },
+              publisher: {
+                type: "string",
+                description: "Filter by publisher name (partial match)",
+              },
+              label: {
+                type: "string",
+                description: "Filter by record label (partial match)",
+              },
+              page: {
+                type: "number",
+                description: "Page number (default: 1, 20 results per page)",
+              },
+            },
+          },
+        },
+        executor: this.listWorks.bind(this),
+      },
+      {
+        definition: {
+          name: "directory_lookup_work",
+          description:
+            "Get full details of a single work by ISWC or work ID. " +
+            "Returns credits, recordings, attestation status, provenance, DSP links, and carbon badge. " +
+            "→ then: directory_lookup_work_full (agent-optimised markdown), directory_lookup_person_full (inspect a credited writer)",
+          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_work_full",
+          description:
+            "Get complete details about a work in the public directory — 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. Returns a structured markdown summary optimised for agent reasoning. " +
+            "→ then: directory_lookup_person_full (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.lookupWorkFull.bind(this),
+      },
+      {
+        definition: {
+          name: "directory_lookup_isrc",
+          description:
+            "Find musical work(s) associated with an ISRC code. " +
+            "ISRC identifies a specific recording; this returns the underlying work(s). " +
+            "→ then: directory_lookup_work_full (full details on 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.publisher) params.publisher = args.publisher;
+    if (args.label) params.label = args.label;
+
+    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)}`,
+    );
+
+    return formatAsText(response.data);
+  }
+
+  private async lookupWorkFull(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[] = [];
+
+    // Title + artist
+    const artistName = data.artist_name || data.primary_artist || "";
+    lines.push(`## ${data.title}${artistName ? ` by ${artistName}` : ""}`);
+    lines.push("");
+
+    // Key metadata line
+    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(" | "));
+
+    // Score
+    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("");
+
+    // Credits
+    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("");
+
+    // Recordings
+    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("");
+
+    // Audio analysis
+    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("");
+    }
+
+    // DSP links
+    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}`);
+      // catch any other keys
+      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,
+    });
+  }
+}