@withpica/mcp-server-directory 1.1.0 → 1.3.0

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

@@ -1,10 +1,10 @@
 // Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
 
 /**
- * Directory Skill Eval Harness — ADR-140 Phase 3 + ADR-171 Skills
+ * Directory Prompt Eval Harness — ADR-140 Phase 3
  *
- * Deterministic test suite that validates directory skill text produces
- * correct workflow routing. Parses skill text for tool references,
+ * Deterministic test suite that validates directory prompt text produces
+ * correct workflow routing. Parses prompt text for tool references,
  * ordering, and routing conditions.
  */
 
@@ -29,27 +29,109 @@ function appearsBeforeInText(
   return indexA !== -1 && indexB !== -1 && indexA < indexB;
 }
 
-describe("Skill Eval Harness — Directory MCP", () => {
-  describe("Scenario 1: discover-music search then lookup workflow", () => {
+describe("Prompt Eval Harness — Directory MCP", () => {
+  describe("Scenario 1: directory-autopilot routes sync searches to find-music", () => {
     let text: string;
-    let tools: string[];
 
     beforeAll(async () => {
-      const result = await registry.getPrompt("discover-music");
+      const result = await registry.getPrompt("directory-autopilot");
       text = result.messages[0].content.text;
-      tools = extractToolRefs(text);
     });
 
-    it("reads llms://primer in the shared preamble", () => {
+    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_full for detailed results", () => {
-      expect(tools).toContain("directory_lookup_work_full");
+    it("chains to directory_lookup_work for detailed results", () => {
+      expect(tools).toContain("directory_lookup_work");
     });
 
     it("search comes before lookup (correct order)", () => {
@@ -57,12 +139,13 @@ describe("Skill Eval Harness — Directory MCP", () => {
         appearsBeforeInText(
           text,
           "directory_search_recordings",
-          "directory_lookup_work_full",
+          "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);
@@ -82,30 +165,9 @@ describe("Skill Eval Harness — Directory MCP", () => {
     it("handles no-results case with broadening suggestions", () => {
       expect(text).toMatch(/no results|broaden/i);
     });
-
-    it("emphasises equal discovery principle", () => {
-      expect(text).toMatch(/equal discovery/i);
-      expect(text).toMatch(/not.*popularity|not.*fame/i);
-    });
-
-    it("includes reference track search path", () => {
-      expect(text).toMatch(/reference track/i);
-    });
-
-    it("includes similarity exploration path", () => {
-      expect(text).toMatch(/similar/i);
-    });
-
-    it("mentions sync brief and playlist as use cases", () => {
-      expect(text).toMatch(/sync/i);
-    });
-
-    it("includes rights check path", () => {
-      expect(text).toMatch(/rights/i);
-    });
   });
 
-  describe("Scenario 2: research-creator references person then work lookup", () => {
+  describe("Scenario 5: research-creator references person then work lookup", () => {
     let text: string;
     let tools: string[];
 
@@ -115,23 +177,20 @@ describe("Skill Eval Harness — Directory MCP", () => {
       tools = extractToolRefs(text);
     });
 
-    it("references directory_lookup_person_full as primary lookup", () => {
-      expect(tools).toContain("directory_lookup_person_full");
+    it("starts with directory_lookup_person", () => {
+      expect(tools[0]).toBe("directory_lookup_person");
     });
 
-    it("chains to directory_lookup_work_full for notable works", () => {
-      expect(tools).toContain("directory_lookup_work_full");
+    it("chains to directory_lookup_work for notable works", () => {
+      expect(tools).toContain("directory_lookup_work");
     });
 
-    it("person lookup comes before work lookup in the main flow", () => {
-      // After the routing section, lookup_person_full should appear before lookup_work_full
-      const mainFlowStart = text.indexOf("Lookup by name");
-      const subText = text.slice(mainFlowStart);
+    it("person lookup comes before work lookup", () => {
       expect(
         appearsBeforeInText(
-          subText,
-          "directory_lookup_person_full",
-          "directory_lookup_work_full",
+          text,
+          "directory_lookup_person",
+          "directory_lookup_work",
         ),
       ).toBe(true);
     });
@@ -143,7 +202,7 @@ describe("Skill Eval Harness — Directory MCP", () => {
     });
 
     it("examines collaborator network", () => {
-      expect(text).toMatch(/collaborator.*network/i);
+      expect(text).toMatch(/collaborator/i);
     });
 
     it("includes use cases for the research output", () => {
@@ -161,50 +220,43 @@ describe("Skill Eval Harness — Directory MCP", () => {
     });
   });
 
-  describe("Scenario 3: research-creator handles identifier routing (from old directory-autopilot)", () => {
-    let text: string;
-
-    beforeAll(async () => {
-      const result = await registry.getPrompt("research-creator");
-      text = result.messages[0].content.text;
-    });
-
-    it("routes ISRC to directory_lookup_isrc", () => {
-      expect(text).toMatch(/isrc/i);
-      expect(text).toContain("directory_lookup_isrc");
+  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("chains ISRC lookup to directory_lookup_work_full", () => {
-      const isrcBlock = text.slice(
-        text.search(/ISRC/),
-        text.search(/ISRC/) + 200,
-      );
-      expect(isrcBlock).toContain("directory_lookup_work_full");
+    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("routes IPI/ISNI to directory_lookup_person_full", () => {
-      expect(text).toMatch(/ipi|isni/i);
-      expect(text).toContain("directory_lookup_person_full");
-    });
+    it("autopilot has at least 3 routing conditions", async () => {
+      const result = await registry.getPrompt("directory-autopilot");
+      const text = result.messages[0].content.text;
 
-    it("routes ISWC to directory_lookup_work_full", () => {
-      expect(text).toMatch(/iswc/i);
-      expect(text).toContain("directory_lookup_work_full");
-    });
+      const conditions = [
+        /music for a project/i,
+        /information about a creator/i,
+        /specific identifier/i,
+      ];
 
-    it("handles MusicBrainz IDs", () => {
-      expect(text).toMatch(/musicbrainz/i);
+      for (const cond of conditions) {
+        expect(text).toMatch(cond);
+      }
     });
 
-    it("supports browsing via directory_search and list tools", () => {
-      expect(text).toContain("directory_search");
-      expect(text).toContain("directory_list_works");
-      expect(text).toContain("directory_list_people");
+    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);
     });
-  });
 
-  describe("Cross-skill integrity", () => {
-    it("all skills reference at least one directory_ tool", async () => {
+    it("all prompts reference at least one directory_ tool", async () => {
       const prompts = registry.listPrompts();
       const noTools: string[] = [];
 
@@ -221,31 +273,10 @@ describe("Skill Eval Harness — Directory MCP", () => {
       expect(noTools).toEqual([]);
     });
 
-    it("all skills include the shared preamble with discovery principle", async () => {
-      const prompts = registry.listPrompts();
-
-      for (const prompt of prompts) {
-        const result = await registry.getPrompt(prompt.name);
-        const text = result.messages[0].content.text;
-        expect(text).toContain("Discovery principle");
-        expect(text).toContain("llms://primer");
-      }
-    });
-
-    it("all skills are read-only (no create/modify tools)", async () => {
-      const prompts = registry.listPrompts();
-
-      for (const prompt of prompts) {
-        const result = await registry.getPrompt(prompt.name);
-        const text = result.messages[0].content.text;
-        expect(text).toMatch(/read-only/i);
-      }
-    });
-
-    it("discover-music includes similarity path to research-creator", async () => {
-      const result = await registry.getPrompt("discover-music");
+    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).toContain("research-creator");
+      expect(text).toMatch(/read-only/i);
     });
   });
 });

package/src/__tests__/skills/skills-registry.test.ts

@@ -0,0 +1,63 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+
+/**
+ * Directory SkillsRegistry test suite — ADR-140 Phase 2b
+ *
+ * Sister of mcp-server's skills-registry.test.ts. Scoped to the directory
+ * MCP's single Stage 1 skill (find-music-for-sync-brief) and its public-skill
+ * IP-exposure profile (lower bar — methodology body must be IP-safe).
+ */
+
+import { describe, it, expect } from "@jest/globals";
+import {
+  SkillsRegistry,
+  SkillNotFoundError,
+} from "../../skills/index.js";
+
+describe("Directory SkillsRegistry", () => {
+  const registry = new SkillsRegistry();
+
+  it("registers the Stage 1 directory skill", () => {
+    expect(registry.has("find-music-for-sync-brief")).toBe(true);
+  });
+
+  it("listSkills returns metadata-only summaries", () => {
+    for (const summary of registry.listSkills()) {
+      expect(summary).toHaveProperty("triggers");
+      expect(summary).not.toHaveProperty("body");
+    }
+  });
+
+  it("getSkill returns the methodology body", () => {
+    const skill = registry.getSkill("find-music-for-sync-brief");
+    expect(skill.body.length).toBeGreaterThan(100);
+    expect(skill.body).toContain("# find-music-for-sync-brief");
+    expect(skill.tools_required).toContain("directory_search_recordings");
+  });
+
+  it("getSkill throws SkillNotFoundError for unknown name", () => {
+    expect(() => registry.getSkill("not-a-real-skill")).toThrow(
+      SkillNotFoundError,
+    );
+  });
+
+  it("body contains no trade-secret path fragments (directory MCP is public)", () => {
+    const FORBIDDEN = [
+      "lib/services/chain",
+      "lib/services/enrichment",
+      "lib/services/pica-export",
+      "lib/services/global-identity",
+      "lib/services/identity-inheritance",
+      "lib/services/machine-payments",
+      "lib/services/credit-gating",
+      "lib/services/mlc-import",
+      "lib/integrations/",
+    ];
+    for (const summary of registry.listSkills()) {
+      const skill = registry.getSkill(summary.name);
+      for (const fragment of FORBIDDEN) {
+        expect(skill.body).not.toContain(fragment);
+      }
+    }
+  });
+});

package/src/__tests__/skills/skills-tools.test.ts

@@ -0,0 +1,74 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+
+/**
+ * Directory skills tools test suite — ADR-140 Phase 2b
+ *
+ * Covers directory_skill_list + directory_skill_get on the public directory
+ * MCP. Same meta-tool shape as the creator MCP, but tools_required names
+ * follow the `directory_*` prefix convention.
+ */
+
+import { describe, it, expect } from "@jest/globals";
+import { DirectorySkillsTools } from "../../tools/skills.js";
+
+describe("DirectorySkillsTools", () => {
+  const skillsTools = new DirectorySkillsTools();
+  const tools = skillsTools.getTools();
+
+  it("registers exactly 2 meta-tools", () => {
+    expect(tools.length).toBe(2);
+    expect(tools.map((t) => t.definition.name).sort()).toEqual([
+      "directory_skill_get",
+      "directory_skill_list",
+    ]);
+  });
+
+  it("both tools are tier:read", () => {
+    for (const tool of tools) {
+      expect(tool.definition.tier).toBe("read");
+    }
+  });
+
+  it("directory_skill_list returns the Stage 1 skill", async () => {
+    const list = tools.find(
+      (t) => t.definition.name === "directory_skill_list",
+    )!;
+    const result = await list.executor({});
+    expect(result.isError).toBeFalsy();
+    const summaries = result.structuredContent!.skills as Array<{
+      name: string;
+    }>;
+    expect(summaries.map((s) => s.name)).toContain(
+      "find-music-for-sync-brief",
+    );
+  });
+
+  it("directory_skill_get returns the methodology body", async () => {
+    const get = tools.find(
+      (t) => t.definition.name === "directory_skill_get",
+    )!;
+    const result = await get.executor({ name: "find-music-for-sync-brief" });
+    expect(result.isError).toBeFalsy();
+    const textBlock = result.content.find((c: any) => c.type === "text") as
+      | { type: "text"; text: string }
+      | undefined;
+    expect(textBlock?.text).toContain("# find-music-for-sync-brief");
+    expect(textBlock?.text).toContain("directory_search_recordings");
+  });
+
+  it("directory_skill_get returns isError for unknown skill", async () => {
+    const get = tools.find(
+      (t) => t.definition.name === "directory_skill_get",
+    )!;
+    const result = await get.executor({ name: "not-a-real-skill" });
+    expect(result.isError).toBe(true);
+  });
+
+  it("directory_skill_get returns isError when name is missing", async () => {
+    const get = tools.find(
+      (t) => t.definition.name === "directory_skill_get",
+    )!;
+    const result = await get.executor({});
+    expect(result.isError).toBe(true);
+  });
+});

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

@@ -10,6 +10,7 @@ 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;
 
@@ -19,6 +20,7 @@ function getAllTools() {
     new DirectoryPeopleTools(nullClient),
     new DirectorySearchTools(nullClient),
     new DirectoryRecordingsTools(nullClient),
+    new DirectoryChainTools(nullClient),
   ];
 
   const tools: Array<{ name: string; description: string }> = [];
@@ -48,8 +50,8 @@ describe("Directory Composability Chains", () => {
     allNames = new Set(allTools.map((t) => t.name));
   });
 
-  it("all 9 tools are registered", () => {
-    expect(allTools).toHaveLength(9);
+  it("all 8 tools are registered", () => {
+    expect(allTools).toHaveLength(8);
   });
 
   it("all tools have composability chains", () => {

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", () => {