@withpica/mcp-server-directory 1.0.0 → 1.1.0

package/src/prompts/index.ts

@@ -0,0 +1,250 @@
+// 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).
+ */
+
+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;
+}
+
+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",
+        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",
+        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 — full catalog, identifiers, collaborator network, rights landscape, and similarity search",
+        arguments: [
+          {
+            name: "name_or_id",
+            description: "Creator name, IPI number, ISNI, or MusicBrainz ID",
+            required: false,
+          },
+        ],
+      },
+    ];
+  }
+
+  async getPrompt(
+    name: string,
+    args?: Record<string, any>,
+  ): Promise<PromptResult> {
+    switch (name) {
+      case "discover-music":
+        return this.getDiscoverMusicSkill(args?.brief);
+      case "research-creator":
+        return this.getResearchCreatorSkill(args?.name_or_id);
+      default:
+        throw new Error(`Prompt not found: ${name}`);
+    }
+  }
+
+  private getDiscoverMusicSkill(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).`;
+
+    return {
+      messages: [
+        {
+          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.
+
+${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
+
+If no results match, suggest broadening the search (wider BPM range, drop key filter, etc.).
+
+If the catalog is small, say so: "the directory currently has [N] works — it's growing. here's what matches from what's available."
+
+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
+
+Tools: directory_search_recordings, directory_search, directory_lookup_work, directory_lookup_work_full, directory_lookup_person, directory_lookup_person_full`,
+          },
+        },
+      ],
+    };
+  }
+
+  private getResearchCreatorSkill(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.`;
+
+    return {
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `${SHARED_PREAMBLE}
+
+--- SKILL: research-creator ---
+
+Deep-dive on a specific creator. Full catalog, identifiers, collaborator network, rights landscape.
+
+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
+
+"who do you want to learn about?"
+
+${searchInstruction}
+
+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`,
+          },
+        },
+      ],
+    };
+  }
+}

package/src/resources/llms-primer.ts

@@ -0,0 +1,35 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+
+export const DIRECTORY_PRIMER = `# PICA Directory — Public Music Catalog Search
+
+Read-only access to published music catalog data. No authentication required.
+Works and people are only visible if the owning organisation has opted into
+the directory.
+
+## First Connection
+
+If you're not sure where to start, invoke the **directory-autopilot** prompt.
+It asks what you need and routes to the right workflow: sync search, rights
+research, or identifier lookup.
+
+## What You Can Do
+- Search works by title, ISWC, publisher, label
+- Search people by name, ISNI, IPI
+- Look up works by recording ISRC (directory_lookup_isrc)
+- Search recordings by audio characteristics (BPM, key, mood, energy)
+
+## What You Cannot Do
+- Create, update, or delete anything (read-only)
+- Access unpublished works or private catalog data
+- See financial data, agreements, or internal metadata
+
+## Entity Model
+- **Work**: composition with title, ISWC, credits, recordings
+- **Person**: writer/composer/performer with IPI, ISNI identifiers
+- **Recording**: audio capture with ISRC, linked to one work
+
+## Recommended Flow
+1. directory_search (broad text search across works + people)
+2. directory_lookup_work or directory_lookup_person (detailed view)
+3. directory_search_recordings (audio characteristic search for sync)
+`;

package/src/server.ts

@@ -0,0 +1,134 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  ListResourcesRequestSchema,
+  ReadResourceRequestSchema,
+  ListPromptsRequestSchema,
+  GetPromptRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import { DirectoryClient } from "./client.js";
+import { ServerConfig } from "./config.js";
+import { ToolRegistry } from "./tools/index.js";
+import { PromptRegistry } from "./prompts/index.js";
+import { logError } from "./utils/errors.js";
+import { DIRECTORY_PRIMER } from "./resources/llms-primer.js";
+
+export class DirectoryMcpServer {
+  private server: Server;
+  private client: DirectoryClient;
+  private toolRegistry: ToolRegistry;
+  private promptRegistry: PromptRegistry;
+  private config: ServerConfig;
+
+  constructor(config: ServerConfig) {
+    this.config = config;
+
+    this.client = new DirectoryClient({
+      baseUrl: config.directoryUrl,
+      debug: config.debug,
+    });
+
+    this.server = new Server(
+      {
+        name: config.serverName,
+        version: config.version,
+      },
+      {
+        capabilities: {
+          tools: {},
+          resources: {},
+          prompts: {},
+        },
+      },
+    );
+
+    this.toolRegistry = new ToolRegistry(this.client);
+    this.promptRegistry = new PromptRegistry();
+    this.setupHandlers();
+  }
+
+  private setupHandlers(): void {
+    this.server.setRequestHandler(ListToolsRequestSchema, async () => {
+      if (this.config.debug) {
+        console.error("[Directory MCP] Listing tools");
+      }
+      return { tools: this.toolRegistry.listTools() };
+    });
+
+    this.server.setRequestHandler(ListResourcesRequestSchema, async () => {
+      return {
+        resources: [
+          {
+            uri: "llms://primer",
+            name: "PICA Domain Primer",
+            description:
+              "Plain-language description of PICA's domain model, entity relationships, and recommended agent workflows. Read this first.",
+            mimeType: "text/markdown",
+          },
+        ],
+      };
+    });
+
+    this.server.setRequestHandler(
+      ReadResourceRequestSchema,
+      async (request) => {
+        const { uri } = request.params;
+        if (uri === "llms://primer") {
+          return {
+            contents: [
+              {
+                uri: "llms://primer",
+                mimeType: "text/markdown",
+                text: DIRECTORY_PRIMER,
+              },
+            ],
+          };
+        }
+        throw new Error(`Resource not found: ${uri}`);
+      },
+    );
+
+    this.server.setRequestHandler(ListPromptsRequestSchema, async () => {
+      return { prompts: this.promptRegistry.listPrompts() };
+    });
+
+    this.server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+      const { name, arguments: args } = request.params;
+      return await this.promptRegistry.getPrompt(name, args);
+    });
+
+    this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+      const { name, arguments: args } = request.params;
+
+      if (this.config.debug) {
+        console.error(`[Directory MCP] Executing tool: ${name}`, args);
+      }
+
+      try {
+        return await this.toolRegistry.executeTool(name, args || {});
+      } catch (error) {
+        logError(`Tool execution: ${name}`, error);
+        throw error;
+      }
+    });
+  }
+
+  async start(): Promise<void> {
+    const transport = new StdioServerTransport();
+    await this.server.connect(transport);
+
+    console.error("[Directory MCP] PICA Directory MCP Server started");
+    console.error(`[Directory MCP] Version: ${this.config.version}`);
+    console.error(`[Directory MCP] API URL: ${this.config.directoryUrl}`);
+    console.error("[Directory MCP] Ready to accept connections");
+  }
+
+  async stop(): Promise<void> {
+    await this.server.close();
+    console.error("[Directory MCP] Server stopped");
+  }
+}

package/src/tools/index.ts

@@ -0,0 +1,71 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+
+import { DirectoryClient } from "../client.js";
+import { DirectoryWorksTools } from "./works.js";
+import { DirectoryPeopleTools } from "./people.js";
+import { DirectorySearchTools } from "./search.js";
+import { DirectoryRecordingsTools } from "./recordings.js";
+import { formatError, logError, ToolExecutionError } from "../utils/errors.js";
+
+export interface ToolDefinition {
+  name: string;
+  description: string;
+  inputSchema: {
+    type: string;
+    properties: Record<string, any>;
+    required?: string[];
+  };
+}
+
+export interface ToolResult {
+  content: Array<{ type: string; text: string }>;
+  structuredContent?: Record<string, unknown>;
+  isError?: boolean;
+}
+
+export type ToolExecutor = (args: Record<string, any>) => Promise<any>;
+
+export class ToolRegistry {
+  private tools: Map<
+    string,
+    { definition: ToolDefinition; executor: ToolExecutor }
+  >;
+
+  constructor(client: DirectoryClient) {
+    this.tools = new Map();
+
+    const groups = [
+      new DirectoryWorksTools(client),
+      new DirectoryPeopleTools(client),
+      new DirectorySearchTools(client),
+      new DirectoryRecordingsTools(client),
+    ];
+
+    for (const group of groups) {
+      for (const tool of group.getTools()) {
+        this.tools.set(tool.definition.name, tool);
+      }
+    }
+  }
+
+  listTools(): ToolDefinition[] {
+    return Array.from(this.tools.values()).map((t) => t.definition);
+  }
+
+  async executeTool(name: string, args: Record<string, any>): Promise<any> {
+    const tool = this.tools.get(name);
+    if (!tool) {
+      throw new ToolExecutionError(`Tool not found: ${name}`);
+    }
+
+    try {
+      return await tool.executor(args);
+    } catch (error) {
+      logError(`Tool execution: ${name}`, error);
+      return {
+        content: [formatError(error)],
+        isError: true,
+      };
+    }
+  }
+}