@withpica/mcp-server-directory 1.0.0 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@withpica/mcp-server-directory",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "MCP Server for PICA Public Directory — enables AI assistants to search verified works and creators",
   "type": "module",
   "main": "dist/index.js",
@@ -13,7 +13,8 @@
     "start": "node dist/index.js",
     "test": "NODE_OPTIONS=--experimental-vm-modules jest",
     "test:watch": "NODE_OPTIONS=--experimental-vm-modules jest --watch",
-    "test:coverage": "NODE_OPTIONS=--experimental-vm-modules jest --coverage"
+    "test:coverage": "NODE_OPTIONS=--experimental-vm-modules jest --coverage",
+    "prepublishOnly": "npm run build"
   },
   "author": "PICA Platform",
   "license": "MIT",

package/src/__tests__/prompts/index.test.ts

@@ -0,0 +1,128 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+
+/**
+ * Directory Prompt Registry Tests
+ */
+
+import { describe, it, expect, beforeAll } from "@jest/globals";
+import { PromptRegistry } from "../../prompts/index";
+
+describe("Directory Prompt Registry", () => {
+  const registry = new PromptRegistry();
+
+  describe("listPrompts", () => {
+    it("returns 3 prompts", () => {
+      const prompts = registry.listPrompts();
+      expect(prompts).toHaveLength(3);
+    });
+
+    it("includes all expected prompts", () => {
+      const names = registry.listPrompts().map((p) => p.name);
+      expect(names).toContain("find-music");
+      expect(names).toContain("research-creator");
+      expect(names).toContain("directory-autopilot");
+    });
+
+    it("prompt names are unique and kebab-case", () => {
+      const prompts = registry.listPrompts();
+      const names = prompts.map((p) => p.name);
+      expect(new Set(names).size).toBe(names.length);
+      for (const name of names) {
+        expect(name).toMatch(/^[a-z][a-z0-9-]*$/);
+      }
+    });
+  });
+
+  describe("getPrompt", () => {
+    it("resolves all prompts without error", async () => {
+      const prompts = registry.listPrompts();
+      for (const prompt of prompts) {
+        const result = await registry.getPrompt(prompt.name);
+        expect(result.messages).toBeInstanceOf(Array);
+        expect(result.messages.length).toBeGreaterThan(0);
+        expect(result.messages[0].content.type).toBe("text");
+        expect(result.messages[0].content.text).toBeTruthy();
+      }
+    });
+
+    it("throws on unknown prompt", async () => {
+      await expect(registry.getPrompt("nonexistent")).rejects.toThrow(
+        "Prompt not found",
+      );
+    });
+  });
+
+  describe("directory-autopilot routing", () => {
+    let text: string;
+
+    beforeAll(async () => {
+      const result = await registry.getPrompt("directory-autopilot");
+      text = result.messages[0].content.text;
+    });
+
+    it("reads the primer first", () => {
+      expect(text).toContain("llms://primer");
+    });
+
+    it("routes sync searches to find-music workflow", () => {
+      expect(text).toMatch(/sync|playlist|project/i);
+      expect(text).toContain("find-music");
+    });
+
+    it("routes creator research to lookup tools", () => {
+      expect(text).toContain("directory_lookup_person");
+    });
+
+    it("routes identifier resolution to specific tools", () => {
+      expect(text).toContain("directory_lookup_isrc");
+      expect(text).toContain("directory_lookup_work");
+    });
+
+    it("handles browsing requests", () => {
+      expect(text).toContain("directory_search");
+      expect(text).toContain("directory_list_works");
+    });
+  });
+
+  describe("find-music workflow", () => {
+    it("references audio search tool", async () => {
+      const result = await registry.getPrompt("find-music");
+      const text = result.messages[0].content.text;
+      expect(text).toContain("directory_search_recordings");
+      expect(text).toContain("directory_lookup_work");
+    });
+
+    it("includes mood-to-parameter translation guide", async () => {
+      const result = await registry.getPrompt("find-music");
+      const text = result.messages[0].content.text;
+      expect(text).toMatch(/upbeat|dark|chill/i);
+      expect(text).toContain("energy");
+      expect(text).toContain("BPM");
+    });
+
+    it("accepts optional brief argument", async () => {
+      const result = await registry.getPrompt("find-music", {
+        brief: "dark moody piano",
+      });
+      const text = result.messages[0].content.text;
+      expect(text).toContain("dark moody piano");
+    });
+  });
+
+  describe("research-creator workflow", () => {
+    it("references person lookup tools", async () => {
+      const result = await registry.getPrompt("research-creator");
+      const text = result.messages[0].content.text;
+      expect(text).toContain("directory_lookup_person");
+      expect(text).toContain("directory_lookup_work");
+    });
+
+    it("accepts optional name argument", async () => {
+      const result = await registry.getPrompt("research-creator", {
+        name_or_id: "Max Martin",
+      });
+      const text = result.messages[0].content.text;
+      expect(text).toContain("Max Martin");
+    });
+  });
+});

package/src/__tests__/prompts/prompt-eval-harness.test.ts

@@ -0,0 +1,282 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+
+/**
+ * Directory Prompt Eval Harness — ADR-140 Phase 3
+ *
+ * Deterministic test suite that validates directory prompt text produces
+ * correct workflow routing. Parses prompt text for tool references,
+ * ordering, and routing conditions.
+ */
+
+import { describe, it, expect, beforeAll } from "@jest/globals";
+import { PromptRegistry } from "../../prompts/index";
+
+const registry = new PromptRegistry();
+
+/** Extract all directory_* tool references from text in order of appearance */
+function extractToolRefs(text: string): string[] {
+  return [...text.matchAll(/directory_\w+/g)].map((m) => m[0]);
+}
+
+/** Check if tool A appears before tool B in the text */
+function appearsBeforeInText(
+  text: string,
+  toolA: string,
+  toolB: string,
+): boolean {
+  const indexA = text.indexOf(toolA);
+  const indexB = text.indexOf(toolB);
+  return indexA !== -1 && indexB !== -1 && indexA < indexB;
+}
+
+describe("Prompt Eval Harness — Directory MCP", () => {
+  describe("Scenario 1: directory-autopilot routes sync searches to find-music", () => {
+    let text: string;
+
+    beforeAll(async () => {
+      const result = await registry.getPrompt("directory-autopilot");
+      text = result.messages[0].content.text;
+    });
+
+    it("reads llms://primer first for orientation", () => {
+      expect(text).toContain("llms://primer");
+      const primerIdx = text.indexOf("llms://primer");
+      const firstRouteIdx = text.search(/if i'm looking for/i);
+      expect(primerIdx).toBeLessThan(firstRouteIdx);
+    });
+
+    it("routes music/sync/playlist requests to find-music workflow", () => {
+      // Find the sync search routing block
+      const syncBlock = text.slice(
+        text.search(/music for a project|sync|playlist/i),
+        text.search(/music for a project|sync|playlist/i) + 300,
+      );
+      expect(syncBlock.toLowerCase()).toContain("find-music");
+    });
+
+    it("mentions sync brief, playlist, and mood as triggers for find-music", () => {
+      expect(text).toMatch(/sync/i);
+      expect(text).toMatch(/playlist/i);
+      expect(text).toMatch(/mood/i);
+    });
+  });
+
+  describe("Scenario 2: directory-autopilot routes creator research to person lookup", () => {
+    let text: string;
+
+    beforeAll(async () => {
+      const result = await registry.getPrompt("directory-autopilot");
+      text = result.messages[0].content.text;
+    });
+
+    it("routes creator/songwriter/performer requests to research-creator", () => {
+      expect(text).toMatch(/songwriter|composer|performer|creator/i);
+      expect(text).toContain("research-creator");
+    });
+
+    it("references directory_lookup_person as the primary lookup tool", () => {
+      expect(text).toContain("directory_lookup_person");
+    });
+  });
+
+  describe("Scenario 3: directory-autopilot routes identifier resolution to correct tools", () => {
+    let text: string;
+
+    beforeAll(async () => {
+      const result = await registry.getPrompt("directory-autopilot");
+      text = result.messages[0].content.text;
+    });
+
+    it("routes ISRC to directory_lookup_isrc", () => {
+      expect(text).toMatch(/isrc/i);
+      expect(text).toContain("directory_lookup_isrc");
+    });
+
+    it("chains ISRC lookup to directory_lookup_work", () => {
+      // After ISRC lookup, should chain to work details
+      const isrcBlock = text.slice(
+        text.search(/isrc/i),
+        text.search(/isrc/i) + 200,
+      );
+      expect(isrcBlock).toContain("directory_lookup_work");
+    });
+
+    it("routes IPI/ISNI to directory_lookup_person", () => {
+      expect(text).toMatch(/ipi|isni/i);
+      expect(text).toContain("directory_lookup_person");
+    });
+
+    it("routes ISWC to directory_lookup_work", () => {
+      expect(text).toMatch(/iswc/i);
+      expect(text).toContain("directory_lookup_work");
+    });
+
+    it("handles MusicBrainz IDs", () => {
+      expect(text).toMatch(/musicbrainz/i);
+    });
+  });
+
+  describe("Scenario 4: find-music references search then lookup workflow", () => {
+    let text: string;
+    let tools: string[];
+
+    beforeAll(async () => {
+      const result = await registry.getPrompt("find-music");
+      text = result.messages[0].content.text;
+      tools = extractToolRefs(text);
+    });
+
+    it("uses directory_search_recordings as the primary search tool", () => {
+      expect(tools).toContain("directory_search_recordings");
+    });
+
+    it("chains to directory_lookup_work for detailed results", () => {
+      expect(tools).toContain("directory_lookup_work");
+    });
+
+    it("search comes before lookup (correct order)", () => {
+      expect(
+        appearsBeforeInText(
+          text,
+          "directory_search_recordings",
+          "directory_lookup_work",
+        ),
+      ).toBe(true);
+    });
+
+    it("includes mood-to-parameter translation guide", () => {
+      // The prompt should help agents translate natural language to search params
+      expect(text).toMatch(/energy/i);
+      expect(text).toMatch(/bpm/i);
+      expect(text).toMatch(/danceability/i);
+    });
+
+    it("covers all key audio search dimensions", () => {
+      const dimensions = [/energy/i, /bpm/i, /key/i, /mood/i, /duration/i];
+      for (const dim of dimensions) {
+        expect(text).toMatch(dim);
+      }
+    });
+
+    it("includes result presentation format with credits", () => {
+      expect(text).toMatch(/credits|who to contact/i);
+    });
+
+    it("handles no-results case with broadening suggestions", () => {
+      expect(text).toMatch(/no results|broaden/i);
+    });
+  });
+
+  describe("Scenario 5: research-creator references person then work lookup", () => {
+    let text: string;
+    let tools: string[];
+
+    beforeAll(async () => {
+      const result = await registry.getPrompt("research-creator");
+      text = result.messages[0].content.text;
+      tools = extractToolRefs(text);
+    });
+
+    it("starts with directory_lookup_person", () => {
+      expect(tools[0]).toBe("directory_lookup_person");
+    });
+
+    it("chains to directory_lookup_work for notable works", () => {
+      expect(tools).toContain("directory_lookup_work");
+    });
+
+    it("person lookup comes before work lookup", () => {
+      expect(
+        appearsBeforeInText(
+          text,
+          "directory_lookup_person",
+          "directory_lookup_work",
+        ),
+      ).toBe(true);
+    });
+
+    it("checks identifiers (IPI, ISNI, MusicBrainz)", () => {
+      expect(text).toMatch(/ipi/i);
+      expect(text).toMatch(/isni/i);
+      expect(text).toMatch(/musicbrainz/i);
+    });
+
+    it("examines collaborator network", () => {
+      expect(text).toMatch(/collaborator/i);
+    });
+
+    it("includes use cases for the research output", () => {
+      expect(text).toMatch(
+        /rights research|due diligence|licensing|publisher|acquisition/i,
+      );
+    });
+
+    it("accepts name_or_id argument and includes it in search", async () => {
+      const result = await registry.getPrompt("research-creator", {
+        name_or_id: "Diane Warren",
+      });
+      const argText = result.messages[0].content.text;
+      expect(argText).toContain("Diane Warren");
+    });
+  });
+
+  describe("Cross-prompt routing integrity", () => {
+    it("directory-autopilot references both sub-workflow prompts", async () => {
+      const result = await registry.getPrompt("directory-autopilot");
+      const text = result.messages[0].content.text;
+      expect(text).toContain("find-music");
+      expect(text).toContain("research-creator");
+    });
+
+    it("every sub-workflow referenced by autopilot exists as a prompt", () => {
+      const promptNames = registry.listPrompts().map((p) => p.name);
+      expect(promptNames).toContain("find-music");
+      expect(promptNames).toContain("research-creator");
+      expect(promptNames).toContain("directory-autopilot");
+    });
+
+    it("autopilot has at least 3 routing conditions", async () => {
+      const result = await registry.getPrompt("directory-autopilot");
+      const text = result.messages[0].content.text;
+
+      const conditions = [
+        /music for a project/i,
+        /information about a creator/i,
+        /specific identifier/i,
+      ];
+
+      for (const cond of conditions) {
+        expect(text).toMatch(cond);
+      }
+    });
+
+    it("autopilot explains routing decision", async () => {
+      const result = await registry.getPrompt("directory-autopilot");
+      const text = result.messages[0].content.text;
+      expect(text).toMatch(/tell me which|explain|why/i);
+    });
+
+    it("all prompts reference at least one directory_ tool", async () => {
+      const prompts = registry.listPrompts();
+      const noTools: string[] = [];
+
+      for (const prompt of prompts) {
+        const result = await registry.getPrompt(prompt.name);
+        const text = result.messages[0].content.text;
+        const tools = extractToolRefs(text);
+
+        if (tools.length === 0) {
+          noTools.push(prompt.name);
+        }
+      }
+
+      expect(noTools).toEqual([]);
+    });
+
+    it("directory-autopilot is read-only (no create/modify language)", async () => {
+      const result = await registry.getPrompt("directory-autopilot");
+      const text = result.messages[0].content.text;
+      expect(text).toMatch(/read-only/i);
+    });
+  });
+});

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

@@ -0,0 +1,122 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+
+import {
+  jest,
+  describe,
+  it,
+  expect,
+  beforeEach,
+  afterEach,
+} from "@jest/globals";
+import { DirectoryChainTools } from "../../tools/chain";
+import { DirectoryClient } from "../../client";
+
+describe("DirectoryChainTools", () => {
+  let chainTools: DirectoryChainTools;
+  let mockClient: jest.Mocked<DirectoryClient>;
+
+  beforeEach(() => {
+    mockClient = { request: jest.fn() } as any;
+    chainTools = new DirectoryChainTools(mockClient);
+  });
+
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it("registers 1 tool", () => {
+    const tools = chainTools.getTools();
+    expect(tools).toHaveLength(1);
+    expect(tools[0].definition.name).toBe("directory_chain");
+  });
+
+  describe("directory_chain", () => {
+    it("passes free-text query to /chain", async () => {
+      mockClient.request.mockResolvedValue({
+        success: true,
+        results: [{ match_type: "work", work: { title: "Test" } }],
+        total: 1,
+      });
+
+      const tool = chainTools
+        .getTools()
+        .find((t) => t.definition.name === "directory_chain")!;
+      const result = await tool.executor({ q: "test query" });
+
+      expect(mockClient.request).toHaveBeenCalledWith("/chain", {
+        q: "test query",
+      });
+      expect(result.structuredContent.results).toHaveLength(1);
+      expect(result.structuredContent.total).toBe(1);
+    });
+
+    it("passes identifier for direct ISWC/ISRC lookup", async () => {
+      mockClient.request.mockResolvedValue({
+        success: true,
+        results: [],
+        total: 0,
+      });
+
+      const tool = chainTools
+        .getTools()
+        .find((t) => t.definition.name === "directory_chain")!;
+      await tool.executor({ identifier: "T-123.456.789-0" });
+
+      expect(mockClient.request).toHaveBeenCalledWith("/chain", {
+        identifier: "T-123.456.789-0",
+      });
+    });
+
+    it("forwards audio filters", async () => {
+      mockClient.request.mockResolvedValue({
+        success: true,
+        results: [],
+        total: 0,
+      });
+
+      const tool = chainTools
+        .getTools()
+        .find((t) => t.definition.name === "directory_chain")!;
+      await tool.executor({
+        min_bpm: 100,
+        max_bpm: 140,
+        key: "C",
+        key_mode: "minor",
+        mood: "dark",
+        limit: 15,
+      });
+
+      expect(mockClient.request).toHaveBeenCalledWith("/chain", {
+        min_bpm: "100",
+        max_bpm: "140",
+        key: "C",
+        key_mode: "minor",
+        mood: "dark",
+        limit: "15",
+      });
+    });
+
+    it("returns a human summary when no results", async () => {
+      mockClient.request.mockResolvedValue({
+        success: true,
+        results: [],
+        total: 0,
+      });
+
+      const tool = chainTools
+        .getTools()
+        .find((t) => t.definition.name === "directory_chain")!;
+      const result = await tool.executor({ q: "no-match" });
+
+      expect(result.content[0].text).toContain("No chain results");
+    });
+
+    it("throws on API failure", async () => {
+      mockClient.request.mockRejectedValue(new Error("Network error"));
+      const tool = chainTools
+        .getTools()
+        .find((t) => t.definition.name === "directory_chain")!;
+      await expect(tool.executor({ q: "x" })).rejects.toThrow("Network error");
+    });
+  });
+});

package/src/__tests__/tools/composability-chains.test.ts

@@ -0,0 +1,100 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+
+/**
+ * Directory MCP — Composability Chain Tests
+ * Verifies "→ then:" chains point to valid tools
+ */
+
+import { describe, it, expect, beforeAll } from "@jest/globals";
+import { DirectoryWorksTools } from "../../tools/works";
+import { DirectoryPeopleTools } from "../../tools/people";
+import { DirectorySearchTools } from "../../tools/search";
+import { DirectoryRecordingsTools } from "../../tools/recordings";
+import { DirectoryChainTools } from "../../tools/chain";
+
+const nullClient = null as any;
+
+function getAllTools() {
+  const classes = [
+    new DirectoryWorksTools(nullClient),
+    new DirectoryPeopleTools(nullClient),
+    new DirectorySearchTools(nullClient),
+    new DirectoryRecordingsTools(nullClient),
+    new DirectoryChainTools(nullClient),
+  ];
+
+  const tools: Array<{ name: string; description: string }> = [];
+  for (const cls of classes) {
+    for (const tool of cls.getTools()) {
+      tools.push({
+        name: tool.definition.name,
+        description: tool.definition.description,
+      });
+    }
+  }
+  return tools;
+}
+
+function parseChains(description: string): string[] {
+  const match = description.match(/→ then: (.+)$/);
+  if (!match) return [];
+  return [...match[1].matchAll(/directory_\w+/g)].map((m) => m[0]);
+}
+
+describe("Directory Composability Chains", () => {
+  let allTools: Array<{ name: string; description: string }>;
+  let allNames: Set<string>;
+
+  beforeAll(() => {
+    allTools = getAllTools();
+    allNames = new Set(allTools.map((t) => t.name));
+  });
+
+  it("all 8 tools are registered", () => {
+    expect(allTools).toHaveLength(8);
+  });
+
+  it("all tools have composability chains", () => {
+    const missing = allTools.filter((t) => !t.description.includes("→ then:"));
+    expect(missing.map((t) => t.name)).toEqual([]);
+  });
+
+  it("all chain references point to existing tools", () => {
+    const broken: string[] = [];
+    for (const tool of allTools) {
+      const refs = parseChains(tool.description);
+      for (const ref of refs) {
+        if (!allNames.has(ref)) {
+          broken.push(`${tool.name} → ${ref} (not found)`);
+        }
+      }
+    }
+    expect(broken).toEqual([]);
+  });
+
+  it("no tool chains reference itself", () => {
+    const selfRefs = allTools.filter((t) =>
+      parseChains(t.description).includes(t.name),
+    );
+    expect(selfRefs.map((t) => t.name)).toEqual([]);
+  });
+
+  it("every chain includes a reason hint", () => {
+    const missingReasons: string[] = [];
+    for (const tool of allTools) {
+      if (!tool.description.includes("→ then:")) continue;
+      const chainPart = tool.description.split("→ then:")[1];
+      const refs = [...chainPart.matchAll(/directory_\w+/g)];
+      for (const ref of refs) {
+        const afterRef = chainPart.slice(
+          (ref.index ?? 0) + ref[0].length,
+          (ref.index ?? 0) + ref[0].length + 50,
+        );
+        if (!afterRef.match(/^\s*\(/)) {
+          missingReasons.push(`${tool.name} → ${ref[0]} missing reason`);
+        }
+      }
+    }
+    expect(missingReasons).toEqual([]);
+  });
+});