@withpica/mcp-server-directory 1.1.0 → 1.2.0

package/src/tools/people.ts

@@ -2,7 +2,7 @@
 
 import { DirectoryClient } from "../client.js";
 import { ToolDefinition, ToolExecutor } from "./index.js";
-import { formatAsText, formatStructuredList } from "../utils/formatting.js";
+import { formatStructuredList } from "../utils/formatting.js";
 
 export class DirectoryPeopleTools {
   private client: DirectoryClient;
@@ -16,10 +16,14 @@ export class DirectoryPeopleTools {
       {
         definition: {
           name: "directory_list_people",
+          tier: "read",
           description:
+            "Use when the user asks: 'list creators in PICA', 'people starting with B', " +
+            "'browse the people directory'. " +
             "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)",
+            "Filter by free-text (q), ISNI, IPI, or starting letter (A–Z, or '#' for numeric). " +
+            "Returns paginated results. " +
+            "→ then: directory_lookup_person (full profile with works and identifiers)",
           inputSchema: {
             type: "object",
             properties: {
@@ -35,6 +39,11 @@ export class DirectoryPeopleTools {
                 type: "string",
                 description: "Filter by IPI number",
               },
+              letter: {
+                type: "string",
+                description:
+                  "Filter by last name starting letter (A–Z), or '#' for numeric",
+              },
               page: {
                 type: "number",
                 description: "Page number (default: 1, 20 results per page)",
@@ -47,10 +56,16 @@ export class DirectoryPeopleTools {
       {
         definition: {
           name: "directory_lookup_person",
+          tier: "read",
           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)",
+            "Use when the user asks: 'lookup IPI 12345', 'who is creator X?', " +
+            "'tell me about creator X', 'lookup ISNI X'. " +
+            "Also call this BEFORE directory_list_works when the input person name is ambiguous " +
+            "(e.g. 'Bowie', 'Sade', 'Madonna') to surface candidate persons for disambiguation. " +
+            "Get full details of a creator by global creator ID (UUID), ISNI, IPI number, or MusicBrainz ID. " +
+            "Returns identifiers, credited works with roles, collaborator network, and verification score " +
+            "as a structured markdown summary. " +
+            "→ then: directory_lookup_work (inspect a credited work), directory_search_recordings (find their recordings by audio)",
           inputSchema: {
             type: "object",
             properties: {
@@ -65,28 +80,6 @@ export class DirectoryPeopleTools {
         },
         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),
-      },
     ];
   }
 
@@ -103,6 +96,7 @@ export class DirectoryPeopleTools {
     if (args.q) params.q = args.q;
     if (args.isni) params.isni = args.isni;
     if (args.ipi) params.ipi = args.ipi;
+    if (args.letter) params.letter = args.letter;
 
     const response: any = await this.client.request("/people", params);
 
@@ -118,14 +112,6 @@ export class DirectoryPeopleTools {
       `/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 {
@@ -136,12 +122,10 @@ export class DirectoryPeopleTools {
 
     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
@@ -153,7 +137,6 @@ export class DirectoryPeopleTools {
       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 });
@@ -174,7 +157,6 @@ export class DirectoryPeopleTools {
     }
     lines.push("");
 
-    // Works
     const works: any[] = data.works || data.credited_works || [];
     lines.push(`### Works (${works.length})`);
     if (works.length > 0) {
@@ -190,7 +172,6 @@ export class DirectoryPeopleTools {
     }
     lines.push("");
 
-    // Collaborators
     const collaborators: any[] = data.collaborators || [];
     lines.push(`### Collaborators (${collaborators.length})`);
     if (collaborators.length > 0) {

package/src/tools/recordings.ts

@@ -16,12 +16,16 @@ export class DirectoryRecordingsTools {
       {
         definition: {
           name: "directory_search_recordings",
+          tier: "read",
           description:
-            "Search recordings across the PICA directory by audio characteristics. " +
+            "Use when the user asks: 'find upbeat tracks around 120 BPM', " +
+            "'find instrumental tracks in C minor', 'find energetic music for sync', " +
+            "'tracks at X BPM in [key]'. " +
+            "AUDIO-FEATURE search only — for name- or title-shaped queries use directory_lookup_work, " +
+            "directory_lookup_isrc, or directory_lookup_person, NOT this tool. " +
             "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)",
+            "→ then: directory_lookup_work (credits and licensing details for a matched track)",
           inputSchema: {
             type: "object",
             properties: {

package/src/tools/search.ts

@@ -16,11 +16,14 @@ export class DirectorySearchTools {
       {
         definition: {
           name: "directory_search",
+          tier: "read",
           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)",
+            "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: {

package/src/tools/works.ts

@@ -2,7 +2,7 @@
 
 import { DirectoryClient } from "../client.js";
 import { ToolDefinition, ToolExecutor } from "./index.js";
-import { formatAsText, formatStructuredList } from "../utils/formatting.js";
+import { formatStructuredList } from "../utils/formatting.js";
 
 export class DirectoryWorksTools {
   private client: DirectoryClient;
@@ -16,10 +16,14 @@ export class DirectoryWorksTools {
       {
         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. " +
-            "Search by title, ISWC, publisher, or label. Returns paginated results. " +
-            "→ then: directory_lookup_work_full (full details with credits and audio)",
+            "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: {
@@ -31,6 +35,11 @@ export class DirectoryWorksTools {
                 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)",
@@ -39,6 +48,16 @@ export class DirectoryWorksTools {
                 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)",
@@ -51,10 +70,15 @@ export class DirectoryWorksTools {
       {
         definition: {
           name: "directory_lookup_work",
+          tier: "read",
           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)",
+            "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: {
@@ -68,34 +92,16 @@ export class DirectoryWorksTools {
         },
         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",
+          tier: "read",
           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)",
+            "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: {
@@ -124,8 +130,11 @@ export class DirectoryWorksTools {
 
     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);
 
@@ -141,14 +150,6 @@ export class DirectoryWorksTools {
       `/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 {
@@ -159,19 +160,16 @@ export class DirectoryWorksTools {
 
     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
@@ -184,7 +182,6 @@ export class DirectoryWorksTools {
 
     lines.push("");
 
-    // Credits
     const credits: any[] = data.credits || [];
     lines.push(`### Credits (${credits.length})`);
     if (credits.length > 0) {
@@ -202,7 +199,6 @@ export class DirectoryWorksTools {
     }
     lines.push("");
 
-    // Recordings
     const recordings: any[] = data.recordings || [];
     lines.push(`### Recordings (${recordings.length})`);
     if (recordings.length > 0) {
@@ -218,7 +214,6 @@ export class DirectoryWorksTools {
     }
     lines.push("");
 
-    // Audio analysis
     const audio = data.audio_analysis || data.audio || null;
     if (audio) {
       lines.push("### Audio");
@@ -234,14 +229,12 @@ export class DirectoryWorksTools {
       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}`);