@withpica/mcp-server-directory 1.0.0 → 1.2.0

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/chain.ts

@@ -0,0 +1,118 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+
+import { DirectoryClient } from "../client.js";
+import { ToolDefinition, ToolExecutor } from "./index.js";
+
+export class DirectoryChainTools {
+  private client: DirectoryClient;
+
+  constructor(client: DirectoryClient) {
+    this.client = client;
+  }
+
+  getTools(): Array<{ definition: ToolDefinition; executor: ToolExecutor }> {
+    return [
+      {
+        definition: {
+          name: "directory_chain",
+          tier: "read",
+          description:
+            "Use when the user asks: 'show me the rights chain for X', " +
+            "'give me everything on this song', 'what's the full picture for X?', " +
+            "'trace the chain from this writer to that work'. " +
+            "Graph lookup — resolves a query, ISWC, or ISRC to its full rights chain in one call. " +
+            "Each result bundles the work, its writers and publishers (names + roles, no IPIs or splits), " +
+            "the linked recording (ISRC, DSP presence, duration), and audio characteristics (BPM, key, energy). " +
+            "Prefer over stitching list_works + lookup_work + lookup_person when you want the whole graph " +
+            "around a track in a single round-trip. " +
+            "Supports audio-only queries (min_bpm, key, mood, etc.) when you don't have a text query. " +
+            "→ then: directory_lookup_work (deeper work detail), directory_lookup_person (research a named writer)",
+          inputSchema: {
+            type: "object",
+            properties: {
+              q: {
+                type: "string",
+                description:
+                  "Free-text query (work title, creator name, etc.). Minimum 2 characters.",
+              },
+              identifier: {
+                type: "string",
+                description: "ISWC or ISRC — direct identifier lookup",
+              },
+              min_bpm: { type: "number", description: "Minimum BPM" },
+              max_bpm: { type: "number", description: "Maximum BPM" },
+              key: {
+                type: "string",
+                description: "Musical key (e.g. 'C', 'F#', 'Bb')",
+              },
+              key_mode: {
+                type: "string",
+                enum: ["major", "minor"],
+                description: "Key mode",
+              },
+              min_energy: {
+                type: "number",
+                description: "Minimum energy (0–1)",
+              },
+              max_energy: {
+                type: "number",
+                description: "Maximum energy (0–1)",
+              },
+              mood: {
+                type: "string",
+                description: "Mood filter (exact match)",
+              },
+              limit: {
+                type: "number",
+                description: "Max results (default 10, max 20)",
+              },
+            },
+          },
+        },
+        executor: this.chainLookup.bind(this),
+      },
+    ];
+  }
+
+  private async chainLookup(args: Record<string, any>): Promise<any> {
+    const params: Record<string, string> = {};
+
+    if (args.q) params.q = String(args.q);
+    if (args.identifier) params.identifier = String(args.identifier);
+
+    const numericKeys = [
+      "min_bpm",
+      "max_bpm",
+      "min_energy",
+      "max_energy",
+      "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;
+
+    const response: any = await this.client.request("/chain", params);
+
+    const results: any[] = response.results || [];
+
+    return {
+      content: [
+        {
+          type: "text",
+          text:
+            results.length === 0
+              ? "No chain results."
+              : `Found ${results.length} chain result(s). See structuredContent for the full graph.`,
+        },
+      ],
+      structuredContent: {
+        total: response.total ?? results.length,
+        results,
+      },
+    };
+  }
+}

package/src/tools/index.ts

@@ -0,0 +1,83 @@
+// 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 { DirectoryChainTools } from "./chain.js";
+import { formatError, logError, ToolExecutionError } from "../utils/errors.js";
+
+/**
+ * ADR-230 — authority tier on every directory_* tool. Sister of the
+ * creator + team MCP's `Tier` declaration. Every directory tool is
+ * `read` (public catalogue lookup with no mutation surface), but the
+ * field is required for cross-surface uniformity and lint enforcement.
+ */
+export type Tier = "read" | "draft" | "write" | "destructive";
+
+export interface ToolDefinition {
+  name: string;
+  /** ADR-230 — see {@link Tier}. Required on every directory tool. */
+  tier: Tier;
+  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),
+      new DirectoryChainTools(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,
+      };
+    }
+  }
+}

package/src/tools/people.ts

@@ -0,0 +1,196 @@
+// 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 DirectoryPeopleTools {
+  private client: DirectoryClient;
+
+  constructor(client: DirectoryClient) {
+    this.client = client;
+  }
+
+  getTools(): Array<{ definition: ToolDefinition; executor: ToolExecutor }> {
+    return [
+      {
+        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. " +
+            "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: {
+              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",
+              },
+              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)",
+              },
+            },
+          },
+        },
+        executor: this.listPeople.bind(this),
+      },
+      {
+        definition: {
+          name: "directory_lookup_person",
+          tier: "read",
+          description:
+            "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: {
+              id: {
+                type: "string",
+                description:
+                  "Global creator ID (UUID), ISNI, IPI number, or MusicBrainz ID",
+              },
+            },
+            required: ["id"],
+          },
+        },
+        executor: this.lookupPerson.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;
+    if (args.letter) params.letter = args.letter;
+
+    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)}`,
+    );
+
+    const data = response.data;
+    if (!data) {
+      return {
+        content: [{ type: "text", text: "Person not found." }],
+        structuredContent: {},
+      };
+    }
+
+    const lines: string[] = [];
+
+    const name = data.name || data.full_name || data.display_name || "Unknown";
+    lines.push(`## ${name}`);
+    lines.push("");
+
+    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("");
+    }
+
+    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("");
+
+    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("");
+
+    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,149 @@
+// 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",
+          tier: "read",
+          description:
+            "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. " +
+            "→ then: directory_lookup_work (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,
+    });
+  }
+}