@withpica/mcp-server-directory 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -1,39 +1,56 @@
 # Changelog
 
-All notable changes to `@withpica/mcp-server-directory` will be documented in this file.
+All notable changes to `@withpica/mcp-server-directory` are documented here.
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-> **Rule of the road:** every version bump to this package MUST land with a
-> matching entry here in the same commit. See the project's "npm publish
-> discipline" memory entry for the enforcement rationale.
+The format is loosely based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to semantic versioning where the major number is incremented
+for breaking tool-surface changes.
 
 ## [Unreleased]
 
-## [1.1.0] — 2026-04-13
+## [1.1.0] - 2026-04-21
 
-### Changed
+Shipped as minor rather than major despite the `*_full` tool removal:
+the removed names had near-zero external adoption (they shipped recently
+and weren't advertised externally), and staying on the 1.x line keeps
+`^1.0.0` consumers on the upgrade path rather than stranding them on
+the broken cascade. Clients that cached the `*_full` names will see a
+tool-not-found error and need to refresh their tool list.
 
-- **ADR-171: Prompts replaced with workflow-level skills.**
-  3 prompts → 2 skills, each with decision trees, domain knowledge,
-  and the shared preamble (tone, discovery principle, read-only note).
+### Breaking
 
-  New skills: `discover-music`, `research-creator`.
+- **Removed `directory_lookup_person_full` and `directory_lookup_work_full`.**
+  Both tools hit the same upstream endpoints as their non-`_full` counterparts
+  with only a formatting difference — there was no capability delta. The
+  `_full` variants are now the canonical names (`directory_lookup_person`
+  and `directory_lookup_work`); the thin variants have been deleted. Clients
+  that cached the `_full` names need to update their tool list; the
+  replacements return a superset of the prior data, so no output is lost.
 
-  Retired prompts: `find-music`, `directory-autopilot`.
-  `find-music` → `discover-music` (adds equal discovery principle,
-  reference track search, similarity exploration).
-  `directory-autopilot` routing folded into `research-creator`
-  (identifier resolution, browsing, creator lookup all in one skill).
-  `research-creator` gains collaborator network, similarity search,
-  rights landscape, and identifier routing from the old autopilot.
+### Added
 
-## [1.0.0] — 2026-04-06
+- **`directory_chain` tool** — one-call rights-chain lookup. Accepts a
+  free-text query, a direct ISWC/ISRC `identifier`, or audio-only filters
+  (BPM / key / energy / mood). Returns the already-public `ChainResult`
+  shape: work + writers + publishers (names + roles only, no IPIs or
+  splits) + linked recording + audio characteristics. Wraps the existing
+  public `/api/public/directory/chain` endpoint — no new backing API work.
+- `directory_list_people` now accepts `letter` (A–Z, `#`) for alphabetical
+  browsing. The backend has supported this for months; only the MCP tool
+  was missing the parameter.
+- `directory_list_works` now accepts `letter`, `sort` (`title` | `recent`),
+  and `isrc` — all previously backend-only.
 
-### Added
+### Changed
 
-- Initial release of the PICA Public Directory MCP Server
-- 12 read-only tools for searching works, recordings, people, and identifiers
-- 3 prompts: `find-music`, `research-creator`, `directory-autopilot`
-- Deterministic eval harness for prompt routing validation
+- **`directory_lookup_person` now matches its description.** Previously the
+  tool advertised ISNI / IPI / MusicBrainz ID support but the backing query
+  only matched `global_creator_id` — any non-UUID identifier silently 404'd.
+  The query now cascades through `global_creator_id` → `isni` →
+  `cae_ipi_number` → `musicbrainz_id`, first hit wins.
+- `directory_search` description rewritten to drop the false "ranked" claim.
+  The backing endpoint is a fan-out (`listWorks` + `listPeople`,
+  half-limit each), not cross-type ranking. Callers should prefer typed
+  list tools when they know the entity type.
+- `directory_lookup_isrc` description rewritten to frame it honestly as a
+  pinned filter preset on `list_works` rather than a distinct lookup.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@withpica/mcp-server-directory",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "MCP Server for PICA Public Directory — enables AI assistants to search verified works and creators",
   "type": "module",
   "main": "dist/index.js",
@@ -8,12 +8,14 @@
     "pica-directory-mcp": "./dist/index.js"
   },
   "scripts": {
+    "prebuild": "tsx scripts/build-skills.ts",
     "build": "tsc",
     "dev": "tsx src/index.ts",
     "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/scripts/build-skills.ts

@@ -0,0 +1,192 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+
+/**
+ * ADR-140 Phase 2b — generator for `skills.generated.ts` (directory MCP).
+ *
+ * Sister of mcp-server/scripts/build-skills.ts. Same shape, scoped to the
+ * directory MCP. Public/anonymous surface — every skill body must pass the
+ * IP-protection lint (scripts/lint-mcp-tools.ts Rule 14) before publishing.
+ */
+
+import { readFileSync, readdirSync, writeFileSync, existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const ROOT = join(__dirname, "..");
+const SKILLS_ROOT = join(ROOT, "src/skills");
+const OUTPUT_PATH = join(SKILLS_ROOT, "skills.generated.ts");
+
+interface SkillFrontmatter {
+  name: string;
+  description: string;
+  triggers: string[];
+  audience: string;
+  tools_required: string[];
+  output: string;
+}
+
+interface ParsedSkill extends SkillFrontmatter {
+  body: string;
+}
+
+function parseFrontmatter(src: string, sourceFile: string): ParsedSkill {
+  let i = 0;
+  if (src.startsWith("<!--")) {
+    const end = src.indexOf("-->");
+    if (end === -1) {
+      throw new Error(`${sourceFile}: unterminated HTML comment header`);
+    }
+    i = end + 3;
+    while (i < src.length && /\s/.test(src[i])) i++;
+  }
+  if (src.slice(i, i + 3) !== "---") {
+    throw new Error(`${sourceFile}: missing --- frontmatter opener`);
+  }
+  i += 3;
+  while (i < src.length && src[i] !== "\n") i++;
+  i++;
+  const closeIdx = src.indexOf("\n---", i);
+  if (closeIdx === -1) {
+    throw new Error(`${sourceFile}: missing --- frontmatter closer`);
+  }
+  const frontmatterText = src.slice(i, closeIdx);
+  const bodyStart = closeIdx + 4;
+  const body = src.slice(bodyStart).replace(/^\n+/, "").trimEnd() + "\n";
+
+  const fm: Record<string, string | string[]> = {};
+  const lines = frontmatterText.split("\n");
+  let currentListKey: string | null = null;
+  for (const line of lines) {
+    if (line.trim() === "") {
+      currentListKey = null;
+      continue;
+    }
+    const listItemMatch = line.match(/^\s+-\s+(.+)$/);
+    if (listItemMatch && currentListKey) {
+      (fm[currentListKey] as string[]).push(listItemMatch[1].trim());
+      continue;
+    }
+    const kvMatch = line.match(/^([a-z_][a-z0-9_]*)\s*:\s*(.*)$/i);
+    if (!kvMatch) continue;
+    const key = kvMatch[1];
+    const value = kvMatch[2].trim();
+    if (value === "") {
+      fm[key] = [];
+      currentListKey = key;
+    } else {
+      fm[key] = value;
+      currentListKey = null;
+    }
+  }
+
+  const required = [
+    "name",
+    "description",
+    "triggers",
+    "audience",
+    "tools_required",
+    "output",
+  ];
+  for (const field of required) {
+    if (!(field in fm)) {
+      throw new Error(`${sourceFile}: missing required frontmatter field "${field}"`);
+    }
+  }
+  if (!Array.isArray(fm.triggers) || fm.triggers.length === 0) {
+    throw new Error(`${sourceFile}: triggers must be a non-empty list`);
+  }
+  if (!Array.isArray(fm.tools_required) || fm.tools_required.length === 0) {
+    throw new Error(`${sourceFile}: tools_required must be a non-empty list`);
+  }
+
+  return {
+    name: fm.name as string,
+    description: fm.description as string,
+    triggers: fm.triggers as string[],
+    audience: fm.audience as string,
+    tools_required: fm.tools_required as string[],
+    output: fm.output as string,
+    body,
+  };
+}
+
+function discoverSkills(): ParsedSkill[] {
+  if (!existsSync(SKILLS_ROOT)) {
+    return [];
+  }
+  const entries = readdirSync(SKILLS_ROOT, { withFileTypes: true });
+  const skills: ParsedSkill[] = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const skillFile = join(SKILLS_ROOT, entry.name, "SKILL.md");
+    if (!existsSync(skillFile)) continue;
+    const src = readFileSync(skillFile, "utf-8");
+    const parsed = parseFrontmatter(src, `src/skills/${entry.name}/SKILL.md`);
+    if (parsed.name !== entry.name) {
+      throw new Error(
+        `src/skills/${entry.name}/SKILL.md: frontmatter name "${parsed.name}" must match directory name "${entry.name}"`,
+      );
+    }
+    skills.push(parsed);
+  }
+  skills.sort((a, b) => a.name.localeCompare(b.name));
+  return skills;
+}
+
+function emit(skills: ParsedSkill[]): string {
+  const header = `// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+
+/**
+ * GENERATED FILE — DO NOT EDIT BY HAND.
+ *
+ * Regenerated by \`scripts/build-skills.ts\` from \`src/skills/<name>/SKILL.md\`.
+ * Runs in \`prebuild\`. See ADR-140 Phase 2b.
+ */
+
+export interface Skill {
+  name: string;
+  description: string;
+  triggers: string[];
+  audience: string;
+  tools_required: string[];
+  output: string;
+  body: string;
+}
+
+`;
+  const lines: string[] = [header, "export const SKILLS: Record<string, Skill> = {"];
+  for (const skill of skills) {
+    lines.push(`  ${JSON.stringify(skill.name)}: {`);
+    lines.push(`    name: ${JSON.stringify(skill.name)},`);
+    lines.push(`    description: ${JSON.stringify(skill.description)},`);
+    lines.push(`    triggers: ${JSON.stringify(skill.triggers)},`);
+    lines.push(`    audience: ${JSON.stringify(skill.audience)},`);
+    lines.push(`    tools_required: ${JSON.stringify(skill.tools_required)},`);
+    lines.push(`    output: ${JSON.stringify(skill.output)},`);
+    lines.push(`    body: ${JSON.stringify(skill.body)},`);
+    lines.push(`  },`);
+  }
+  lines.push("};");
+  lines.push("");
+  lines.push(
+    `export const SKILL_NAMES: ReadonlyArray<string> = ${JSON.stringify(skills.map((s) => s.name))};`,
+  );
+  lines.push("");
+  return lines.join("\n");
+}
+
+function main(): void {
+  const skills = discoverSkills();
+  const output = emit(skills);
+  writeFileSync(OUTPUT_PATH, output, "utf-8");
+  console.log(
+    `[build-skills/directory] Wrote ${skills.length} skill(s) to src/skills/skills.generated.ts`,
+  );
+  for (const skill of skills) {
+    console.log(`  - ${skill.name} (${skill.body.length} bytes body)`);
+  }
+}
+
+main();

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

@@ -1,28 +1,29 @@
 // Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
 
 /**
- * Directory Skill Registry Tests
+ * Directory Prompt Registry Tests
  */
 
 import { describe, it, expect, beforeAll } from "@jest/globals";
 import { PromptRegistry } from "../../prompts/index";
 
-describe("Directory Skill Registry", () => {
+describe("Directory Prompt Registry", () => {
   const registry = new PromptRegistry();
 
   describe("listPrompts", () => {
-    it("returns 2 skills", () => {
+    it("returns 3 prompts", () => {
       const prompts = registry.listPrompts();
-      expect(prompts).toHaveLength(2);
+      expect(prompts).toHaveLength(3);
     });
 
-    it("includes all expected skills", () => {
+    it("includes all expected prompts", () => {
       const names = registry.listPrompts().map((p) => p.name);
-      expect(names).toContain("discover-music");
+      expect(names).toContain("find-music");
       expect(names).toContain("research-creator");
+      expect(names).toContain("directory-autopilot");
     });
 
-    it("skill names are unique and kebab-case", () => {
+    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);
@@ -33,7 +34,7 @@ describe("Directory Skill Registry", () => {
   });
 
   describe("getPrompt", () => {
-    it("resolves all skills without error", async () => {
+    it("resolves all prompts without error", async () => {
       const prompts = registry.listPrompts();
       for (const prompt of prompts) {
         const result = await registry.getPrompt(prompt.name);
@@ -49,28 +50,50 @@ describe("Directory Skill Registry", () => {
         "Prompt not found",
       );
     });
+  });
 
-    it("every skill includes the shared preamble", 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("llms://primer");
-        expect(text).toContain("Discovery principle");
-      }
+  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("discover-music skill", () => {
+  describe("find-music workflow", () => {
     it("references audio search tool", async () => {
-      const result = await registry.getPrompt("discover-music");
+      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_full");
+      expect(text).toContain("directory_lookup_work");
     });
 
     it("includes mood-to-parameter translation guide", async () => {
-      const result = await registry.getPrompt("discover-music");
+      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");
@@ -78,39 +101,20 @@ describe("Directory Skill Registry", () => {
     });
 
     it("accepts optional brief argument", async () => {
-      const result = await registry.getPrompt("discover-music", {
+      const result = await registry.getPrompt("find-music", {
         brief: "dark moody piano",
       });
       const text = result.messages[0].content.text;
       expect(text).toContain("dark moody piano");
     });
-
-    it("emphasises equal discovery principle", async () => {
-      const result = await registry.getPrompt("discover-music");
-      const text = result.messages[0].content.text;
-      expect(text).toMatch(/equal discovery/i);
-      expect(text).toMatch(/not.*popularity|not.*fame/i);
-    });
-
-    it("includes reference track search path", async () => {
-      const result = await registry.getPrompt("discover-music");
-      const text = result.messages[0].content.text;
-      expect(text).toMatch(/reference track/i);
-    });
-
-    it("includes similarity exploration path", async () => {
-      const result = await registry.getPrompt("discover-music");
-      const text = result.messages[0].content.text;
-      expect(text).toMatch(/similar/i);
-    });
   });
 
-  describe("research-creator skill", () => {
+  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_full");
-      expect(text).toContain("directory_lookup_work_full");
+      expect(text).toContain("directory_lookup_person");
+      expect(text).toContain("directory_lookup_work");
     });
 
     it("accepts optional name argument", async () => {
@@ -120,26 +124,5 @@ describe("Directory Skill Registry", () => {
       const text = result.messages[0].content.text;
       expect(text).toContain("Max Martin");
     });
-
-    it("handles identifier routing from old directory-autopilot", async () => {
-      const result = await registry.getPrompt("research-creator");
-      const text = result.messages[0].content.text;
-      expect(text).toContain("directory_lookup_isrc");
-      expect(text).toContain("directory_list_works");
-      expect(text).toContain("directory_list_people");
-    });
-
-    it("includes collaborator network exploration", async () => {
-      const result = await registry.getPrompt("research-creator");
-      const text = result.messages[0].content.text;
-      expect(text).toMatch(/collaborator.*network/i);
-    });
-
-    it("includes similarity search", async () => {
-      const result = await registry.getPrompt("research-creator");
-      const text = result.messages[0].content.text;
-      expect(text).toContain("directory_search_recordings");
-      expect(text).toMatch(/similar/i);
-    });
   });
 });