@withpica/mcp-server-directory 1.1.0 → 1.2.0

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

@@ -24,13 +24,19 @@ describe("DirectoryPeopleTools", () => {
     jest.clearAllMocks();
   });
 
-  it("registers 3 tools", () => {
+  it("registers 2 tools", () => {
     const tools = peopleTools.getTools();
-    expect(tools).toHaveLength(3);
+    expect(tools).toHaveLength(2);
     const names = tools.map((t) => t.definition.name);
     expect(names).toContain("directory_list_people");
     expect(names).toContain("directory_lookup_person");
-    expect(names).toContain("directory_lookup_person_full");
+  });
+
+  it("exposes the letter filter on list_people", () => {
+    const tool = peopleTools
+      .getTools()
+      .find((t) => t.definition.name === "directory_list_people")!;
+    expect(tool.definition.inputSchema.properties.letter).toBeDefined();
   });
 
   describe("directory_list_people", () => {

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

@@ -27,16 +27,45 @@ describe("DirectoryWorksTools", () => {
     jest.clearAllMocks();
   });
 
-  it("registers 4 tools", () => {
+  it("registers 3 tools", () => {
     const tools = worksTools.getTools();
-    expect(tools).toHaveLength(4);
+    expect(tools).toHaveLength(3);
     const names = tools.map((t) => t.definition.name);
     expect(names).toContain("directory_list_works");
     expect(names).toContain("directory_lookup_work");
-    expect(names).toContain("directory_lookup_work_full");
     expect(names).toContain("directory_lookup_isrc");
   });
 
+  it("exposes letter, sort, and isrc filters on list_works", () => {
+    const tool = worksTools
+      .getTools()
+      .find((t) => t.definition.name === "directory_list_works")!;
+    expect(tool.definition.inputSchema.properties.letter).toBeDefined();
+    expect(tool.definition.inputSchema.properties.sort).toBeDefined();
+    expect(tool.definition.inputSchema.properties.isrc).toBeDefined();
+  });
+
+  it("list_works forwards letter, sort, and isrc to /works", async () => {
+    mockClient.request.mockResolvedValue({
+      success: true,
+      data: [],
+      pagination: { limit: 20, offset: 0, total: 0 },
+    });
+
+    const tool = worksTools
+      .getTools()
+      .find((t) => t.definition.name === "directory_list_works")!;
+    await tool.executor({ letter: "B", sort: "recent", isrc: "USABC1234567" });
+
+    expect(mockClient.request).toHaveBeenCalledWith("/works", {
+      letter: "B",
+      sort: "recent",
+      isrc: "USABC1234567",
+      limit: "20",
+      offset: "0",
+    });
+  });
+
   describe("directory_list_works", () => {
     it("calls /works with query params", async () => {
       mockClient.request.mockResolvedValue({

package/src/prompts/index.ts

@@ -1,10 +1,8 @@
 // Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
 
 /**
- * Skill Registry for Directory MCP Server
- * Workflow-level skills for music discovery and creator research.
- * Deployed as upgraded prompts; will convert to MCP skills format
- * when the spec extension ships (ADR-171).
+ * Prompt Registry for Directory MCP Server
+ * Guided workflows for music discovery, sync licensing, and rights research
  */
 
 export interface PromptDefinition {
@@ -30,29 +28,13 @@ export interface PromptResult {
   [key: string]: unknown;
 }
 
-const SHARED_PREAMBLE = `You are guiding a music seeker through the PICA public directory — a discovery layer over verified music catalogs.
-
-Tone: knowledgeable friend. You know what's available and how to find it. Straightforward, never salesy.
-
-Discovery principle: every creator's work has equal discoverability. Catalog quality determines visibility, not fame or follower count. Results are sorted by musical fit, not popularity. An unknown songwriter with analysed audio ranks the same as a major artist.
-
-Before starting this workflow:
-1. Read the llms://primer resource to understand what's available in the directory
-2. This is a read-only public directory — you can search and look up, but you can't create or modify anything
-3. Only works from organisations that opted into the directory are visible
-
-After completing this workflow:
-- Summarise what you found in one short paragraph
-- Suggest the natural next step
-- If they say no, that's fine. Don't ask twice.`;
-
 export class PromptRegistry {
   listPrompts(): PromptDefinition[] {
     return [
       {
-        name: "discover-music",
+        name: "find-music",
         description:
-          "Find music for a sync brief, playlist, or project — search by mood, BPM, key, energy, or description. Equal discovery: results sorted by musical fit, not popularity",
+          "Find music for a sync brief, playlist, or project — search by mood, BPM, key, energy, or description",
         arguments: [
           {
             name: "brief",
@@ -65,7 +47,7 @@ export class PromptRegistry {
       {
         name: "research-creator",
         description:
-          "Research a songwriter, composer, or performer — full catalog, identifiers, collaborator network, rights landscape, and similarity search",
+          "Research a songwriter, composer, or performer — see their works, identifiers, collaborators, and verification status",
         arguments: [
           {
             name: "name_or_id",
@@ -74,6 +56,12 @@ export class PromptRegistry {
           },
         ],
       },
+      {
+        name: "directory-autopilot",
+        description:
+          "Not sure where to start? Describe what you need and get routed to the right workflow — sync search, rights research, or identifier lookup",
+        arguments: [],
+      },
     ];
   }
 
@@ -82,19 +70,21 @@ export class PromptRegistry {
     args?: Record<string, any>,
   ): Promise<PromptResult> {
     switch (name) {
-      case "discover-music":
-        return this.getDiscoverMusicSkill(args?.brief);
+      case "find-music":
+        return this.getFindMusicPrompt(args?.brief);
       case "research-creator":
-        return this.getResearchCreatorSkill(args?.name_or_id);
+        return this.getResearchCreatorPrompt(args?.name_or_id);
+      case "directory-autopilot":
+        return this.getDirectoryAutopilotPrompt();
       default:
         throw new Error(`Prompt not found: ${name}`);
     }
   }
 
-  private getDiscoverMusicSkill(brief?: string): PromptResult {
+  private getFindMusicPrompt(brief?: string): PromptResult {
     const briefInstruction = brief
       ? `The user is looking for: "${brief}". Translate this into audio search parameters.`
-      : `Ask what they're looking for — a mood, a scene, a vibe, or specific audio characteristics (BPM, key, energy).`;
+      : `Ask me what I'm looking for — a mood, a scene, a vibe, or specific audio characteristics (BPM, key, energy).`;
 
     return {
       messages: [
@@ -102,80 +92,44 @@ export class PromptRegistry {
           role: "user",
           content: {
             type: "text",
-            text: `${SHARED_PREAMBLE}
-
---- SKILL: discover-music ---
-
-Help find music by what it sounds like, not who made it. Equal discovery — every well-catalogued work has the same chance.
+            text: `Help me find music in the PICA public directory for a sync brief or project.
 
 ${briefInstruction}
 
-Sync brief / mood-based search:
-  → Extract parameters from natural language:
-    mood, BPM range, key, energy, instrumentation, vocal/instrumental, duration constraints
-  → Translate mood descriptions to search parameters for directory_search_recordings:
-    - "Upbeat" → min_energy: 0.6, min_danceability: 0.5
-    - "Dark/moody" → max_energy: 0.4, key_mode: minor
-    - "Chill" → max_energy: 0.4, max_bpm: 100
-    - Specific requests → use BPM, key, duration filters directly
-  → Run directory_search_recordings with the parameters
-  → Present results by musical fit, not popularity:
-    "here are [N] tracks that match. sorted by how closely they fit your brief, not by who made them."
-  → Per result: title, creator, BPM, key, mood tags, duration.
-     No follower counts. No stream numbers.
-
-For each promising result, use directory_lookup_work_full to get:
-  - Who wrote it (credits with IPI numbers)
-  - Whether credits are attested (verified ownership)
-  - DSP links (Spotify, Apple Music — so the user can listen)
-  - Registration score (higher = cleaner rights chain)
-
-Present as a shortlist with:
-  - Title, artist, BPM, key, energy
-  - Credits summary (who to contact for licensing)
-  - Any flags (unattested credits, low registration score, missing ISRC)
-
-Reference track search:
-  → "got a reference track? tell me what you like about it."
-  → Parse what they value: tempo, mood, instrumentation, vocal style
-  → Search by those parameters
-
-Similarity exploration:
-  → "want to find music similar to [track] by someone you've never heard of?"
-  → Search by the sound, not the name — this is where the discovery principle lives
-
-If they like one:
-  → "want to hear more from this creator, or find similar tracks?"
-  → Similar → search with same parameters
-  → More from creator → pivot to research-creator skill
-
-Rights check:
-  → For any track: "want to check the rights situation?"
-  → Show ownership, publisher, contact path via directory_lookup_work_full
-  → If enquiry → guide through submission
+Workflow:
+1. Translate the brief into search parameters for directory_search_recordings:
+   - Mood descriptions → energy, danceability, key_mode, mood filters
+   - "Upbeat" → min_energy: 0.6, min_danceability: 0.5
+   - "Dark/moody" → max_energy: 0.4, key_mode: minor
+   - "Chill" → max_energy: 0.4, max_bpm: 100
+   - Specific requests → use BPM, key, duration filters directly
 
-If no results match, suggest broadening the search (wider BPM range, drop key filter, etc.).
+2. Run directory_search_recordings with the parameters.
+
+3. For each promising result, use directory_lookup_work to get:
+   - Who wrote it (credits with IPI numbers)
+   - Whether credits are attested (verified ownership)
+   - DSP links (Spotify, Apple Music — so the user can listen)
+   - Registration score (higher = cleaner rights chain)
 
-If the catalog is small, say so: "the directory currently has [N] works — it's growing. here's what matches from what's available."
+4. Present results as a shortlist with:
+   - Title, artist, BPM, key, energy
+   - Credits summary (who to contact for licensing)
+   - Any flags (unattested credits, low registration score, missing ISRC)
 
-Domain knowledge:
-- Results sorted by audio-parameter match, not streams or followers
-- Reference track searching works by extracting musical qualities, not artist similarity
-- Rights information is always available — the directory doesn't hide who owns what
-- Sync supervisors think in briefs (mood + tempo + energy + duration), not artist names
-- Similarity search by audio surfaces genuinely similar music the seeker might never have found
+If no results match, suggest broadening the search (wider BPM range, drop key filter, etc.).
 
-Tools: directory_search_recordings, directory_search, directory_lookup_work, directory_lookup_work_full, directory_lookup_person, directory_lookup_person_full`,
+Important: This is a public directory — only works from organisations that opted in are visible. If the catalog is small, say so.`,
           },
         },
       ],
     };
   }
 
-  private getResearchCreatorSkill(nameOrId?: string): PromptResult {
+  private getResearchCreatorPrompt(nameOrId?: string): PromptResult {
     const searchInstruction = nameOrId
-      ? `Look up: "${nameOrId}". Try directory_lookup_person_full first (it accepts name, IPI, ISNI, or MusicBrainz ID). If that doesn't match, use directory_list_people with a text search.`
-      : `Ask for the creator's name, IPI number, ISNI, or MusicBrainz ID.`;
+      ? `Look up: "${nameOrId}". Try directory_lookup_person first (it accepts name, IPI, ISNI, or MusicBrainz ID). If that doesn't match, use directory_list_people with a text search.`
+      : `Ask me for the creator's name, IPI number, ISNI, or MusicBrainz ID.`;
 
     return {
       messages: [
@@ -183,65 +137,67 @@ Tools: directory_search_recordings, directory_search, directory_lookup_work, dir
           role: "user",
           content: {
             type: "text",
-            text: `${SHARED_PREAMBLE}
+            text: `Help me research a music creator in the PICA public directory.
 
---- SKILL: research-creator ---
+${searchInstruction}
 
-Deep-dive on a specific creator. Full catalog, identifiers, collaborator network, rights landscape.
+Once you find the person, use directory_lookup_person to get their complete profile:
+- Identifiers (IPI, ISNI, MusicBrainz) — essential for rights verification
+- All credited works with roles (writer, composer, performer, producer)
+- Collaborator network — who they work with
+- Verification score — how complete their profile is
+
+Then for their most notable works (up to 5), use directory_lookup_work to get:
+- Full credits and splits (are they the sole writer or one of many?)
+- Recordings with ISRCs
+- Audio analysis (BPM, key, energy)
+- DSP links and registration status
+
+Present a summary:
+- Creator profile (name, identifiers, role patterns)
+- Catalog overview (how many works, typical roles, common collaborators)
+- Notable works with credit details
+- Any gaps (missing identifiers, unattested credits, low scores)
+
+This is useful for: rights research, due diligence before licensing, publisher evaluation, or understanding a catalog before acquisition.`,
+          },
+        },
+      ],
+    };
+  }
 
-Also handles routing that was previously in directory-autopilot:
-- If the user has a specific identifier to resolve (ISRC, ISWC, IPI, ISNI):
-  → ISRC (e.g. USABC1234567) → directory_lookup_isrc → then directory_lookup_work_full
-  → ISWC (e.g. T-123.456.789-0) → directory_lookup_work_full
-  → IPI or ISNI → directory_lookup_person_full
-  → MusicBrainz ID → directory_lookup_person_full
-- If the user wants to browse → use directory_search with a broad query, or directory_list_works / directory_list_people
+  private getDirectoryAutopilotPrompt(): PromptResult {
+    return {
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `You've connected to the PICA public music directory. Help me find what I need.
 
-"who do you want to learn about?"
+First, read the llms://primer resource to understand what's available.
 
-${searchInstruction}
+Then ask me what I'm looking for. Based on my answer, route to the right workflow:
+
+If I'm looking for MUSIC FOR A PROJECT (sync brief, playlist, mood search):
+→ Use the find-music workflow. Translate my description into audio search parameters and search recordings by BPM, key, energy, mood. Then look up full details on promising matches.
+
+If I'm looking for INFORMATION ABOUT A CREATOR (songwriter, composer, performer):
+→ Use the research-creator workflow. Look up their profile, works, identifiers, and collaborators.
+
+If I have a SPECIFIC IDENTIFIER to resolve (ISRC, ISWC, IPI, ISNI):
+→ Route directly to the right lookup tool:
+  - ISRC (e.g. USABC1234567) → directory_lookup_isrc → then directory_lookup_work
+  - ISWC (e.g. T-123.456.789-0) → directory_lookup_work
+  - IPI or ISNI → directory_lookup_person
+  - MusicBrainz ID → directory_lookup_person
+
+If I want to BROWSE what's in the directory:
+→ Use directory_search with a broad query, or directory_list_works / directory_list_people to paginate.
+
+Tell me which workflow you chose and why, in one sentence. Offer alternatives.
 
-Lookup by name, IPI, ISNI, or ISRC:
-  → Find the person using directory_lookup_person_full
-  → If multiple matches: present with distinguishing works/roles
-
-Creator profile:
-  → Full catalog: all works, roles, co-writers
-  → Identifiers: IPI, ISNI, MusicBrainz, IPN
-  → Collaborator network: "frequently works with [names]"
-  → Genre/mood footprint: based on analysed audio across catalog
-
-For their most notable works (up to 5), use directory_lookup_work_full to get:
-  - Full credits and splits (are they the sole writer or one of many?)
-  - Recordings with ISRCs
-  - Audio analysis (BPM, key, energy)
-  - DSP links and registration status
-
-Cross-reference:
-  → "want to verify their identifiers against ISNI or MusicBrainz?"
-  → Flag discrepancies
-
-Similarity exploration:
-  → "want to find other creators with a similar sound?"
-  → Use directory_search_recordings by audio characteristics of their catalog
-  → Equal discovery: results by sound, not fame
-
-Rights landscape:
-  → "want to know who controls their catalog?"
-  → Publishers, agreements, licensing paths
-
-After research:
-  → Summary: creator profile, catalog overview, notable works, gaps
-  → "want to submit a licensing enquiry, or explore more creators?"
-
-Domain knowledge:
-- Creator research often starts from one work and expands via collaborator network — adjacent talent discovery
-- Identifier verification across sources catches discrepancies that matter for rights
-- Similarity search by audio surfaces genuinely similar music through non-traditional channels
-- The collaborator network is how you discover creators no algorithm would surface
-- This is useful for: rights research, due diligence before licensing, publisher evaluation, or catalog acquisition
-
-Tools: directory_lookup_person_full, directory_lookup_work_full, directory_search_recordings, directory_search, directory_lookup_isrc, directory_list_works, directory_list_people`,
+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.`,
           },
         },
       ],