@withpica/mcp-server-directory 1.0.0 → 1.2.0

package/src/prompts/index.ts

@@ -0,0 +1,206 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+
+/**
+ * Prompt Registry for Directory MCP Server
+ * Guided workflows for music discovery, sync licensing, and rights research
+ */
+
+export interface PromptDefinition {
+  name: string;
+  description: string;
+  arguments?: Array<{
+    name: string;
+    description: string;
+    required?: boolean;
+  }>;
+}
+
+export interface PromptMessage {
+  role: "user" | "assistant";
+  content: {
+    type: string;
+    text: string;
+  };
+}
+
+export interface PromptResult {
+  messages: PromptMessage[];
+  [key: string]: unknown;
+}
+
+export class PromptRegistry {
+  listPrompts(): PromptDefinition[] {
+    return [
+      {
+        name: "find-music",
+        description:
+          "Find music for a sync brief, playlist, or project — search by mood, BPM, key, energy, or description",
+        arguments: [
+          {
+            name: "brief",
+            description:
+              "What you're looking for — a mood, scene description, or audio characteristics",
+            required: false,
+          },
+        ],
+      },
+      {
+        name: "research-creator",
+        description:
+          "Research a songwriter, composer, or performer — see their works, identifiers, collaborators, and verification status",
+        arguments: [
+          {
+            name: "name_or_id",
+            description: "Creator name, IPI number, ISNI, or MusicBrainz ID",
+            required: false,
+          },
+        ],
+      },
+      {
+        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: [],
+      },
+    ];
+  }
+
+  async getPrompt(
+    name: string,
+    args?: Record<string, any>,
+  ): Promise<PromptResult> {
+    switch (name) {
+      case "find-music":
+        return this.getFindMusicPrompt(args?.brief);
+      case "research-creator":
+        return this.getResearchCreatorPrompt(args?.name_or_id);
+      case "directory-autopilot":
+        return this.getDirectoryAutopilotPrompt();
+      default:
+        throw new Error(`Prompt not found: ${name}`);
+    }
+  }
+
+  private getFindMusicPrompt(brief?: string): PromptResult {
+    const briefInstruction = brief
+      ? `The user is looking for: "${brief}". Translate this into audio search parameters.`
+      : `Ask me what I'm looking for — a mood, a scene, a vibe, or specific audio characteristics (BPM, key, energy).`;
+
+    return {
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `Help me find music in the PICA public directory for a sync brief or project.
+
+${briefInstruction}
+
+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
+
+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)
+
+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)
+
+If no results match, suggest broadening the search (wider BPM range, drop key filter, etc.).
+
+Important: This is a public directory — only works from organisations that opted in are visible. If the catalog is small, say so.`,
+          },
+        },
+      ],
+    };
+  }
+
+  private getResearchCreatorPrompt(nameOrId?: string): PromptResult {
+    const searchInstruction = nameOrId
+      ? `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: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `Help me research a music creator in the PICA public directory.
+
+${searchInstruction}
+
+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.`,
+          },
+        },
+      ],
+    };
+  }
+
+  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.
+
+First, read the llms://primer resource to understand what's available.
+
+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.
+
+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.`,
+          },
+        },
+      ],
+    };
+  }
+}