@withpica/mcp-server-directory 1.2.0 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@withpica/mcp-server-directory",
-  "version": "1.2.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,6 +8,7 @@
     "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",

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__/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/prompts/public-question-atlas.ts

@@ -537,4 +537,21 @@ export const PUBLIC_ATLAS: AtlasEntry[] = [
         "title + writer | title + year | ISWC if known",
     },
   },
+  {
+    // ADR-140 Phase 2b — skill discovery meta-questions.
+    // Routes to directory_skill_list so an external LLM connecting to the
+    // directory MCP via Anthropic's MCP Directory or ChatGPT Apps catalogue
+    // can ask "what can this server do?" and get a list of named
+    // methodologies (find-music-for-sync-brief, etc.) rather than having
+    // to read the full 9-tool surface description-by-description.
+    question: "what skills do you have?",
+    synonyms: [
+      "what can you do?",
+      "show me your methodologies",
+      "how do I find music here?",
+      "how do I use this directory?",
+      "what workflows are available?",
+    ],
+    resolves_to: { kind: "tool", name: "directory_skill_list" },
+  },
 ];

package/src/server.ts

@@ -16,13 +16,20 @@ 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";
+import { SkillsRegistry } from "./skills/index.js";
 
 export class DirectoryMcpServer {
   private server: Server;
   private client: DirectoryClient;
   private toolRegistry: ToolRegistry;
   private promptRegistry: PromptRegistry;
+  private skillsRegistry: SkillsRegistry;
   private config: ServerConfig;
+  // Logged once after the MCP `initialize` handshake completes so each
+  // session prints a single client-attribution breadcrumb to stderr
+  // (Railway logs / Sentry breadcrumbs). Directory MCP has no DB audit
+  // pipeline today; this is provenance-only.
+  private clientAttributionLogged = false;
 
   constructor(config: ServerConfig) {
     this.config = config;
@@ -48,6 +55,7 @@ export class DirectoryMcpServer {
 
     this.toolRegistry = new ToolRegistry(this.client);
     this.promptRegistry = new PromptRegistry();
+    this.skillsRegistry = new SkillsRegistry();
     this.setupHandlers();
   }
 
@@ -60,17 +68,36 @@ export class DirectoryMcpServer {
     });
 
     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",
-          },
-        ],
-      };
+      const resources: Array<{
+        uri: string;
+        name: string;
+        description: string;
+        mimeType: string;
+      }> = [
+        {
+          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",
+        },
+        {
+          uri: "skill://withpica/index.json",
+          name: "PICA Directory Skills Index",
+          description:
+            "Enumeration of downloadable directory skill methodologies (SEP-2640 bridge). Each entry maps a kebab-case name to its skill:// URI, description, and trigger phrases.",
+          mimeType: "application/json",
+        },
+      ];
+      for (const summary of this.skillsRegistry.listSkills()) {
+        resources.push({
+          uri: `skill://withpica/${summary.name}/SKILL.md`,
+          name: `Skill — ${summary.name}`,
+          description: summary.description,
+          mimeType: "text/markdown",
+        });
+      }
+      return { resources };
     });
 
     this.server.setRequestHandler(
@@ -88,6 +115,9 @@ export class DirectoryMcpServer {
             ],
           };
         }
+        if (uri.startsWith("skill://withpica/")) {
+          return this.readSkillResource(uri);
+        }
         throw new Error(`Resource not found: ${uri}`);
       },
     );
@@ -104,6 +134,8 @@ export class DirectoryMcpServer {
     this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
       const { name, arguments: args } = request.params;
 
+      this.logClientAttributionOnce();
+
       if (this.config.debug) {
         console.error(`[Directory MCP] Executing tool: ${name}`, args);
       }
@@ -117,6 +149,86 @@ export class DirectoryMcpServer {
     });
   }
 
+  /**
+   * Emit a single stderr line per session naming the client that handshook
+   * with us — sourced from `clientInfo` on the MCP `initialize` request.
+   * Self-declared, NOT authenticated; treat as provenance metadata only.
+   *
+   * Directory MCP is unauthenticated and writes no audit rows, so this
+   * stderr breadcrumb is the only attribution surface today. When/if a
+   * directory audit pipeline lands, fold these values into McpAuditEntry
+   * (the wire shape already carries optional client_name + client_version).
+   */
+  private logClientAttributionOnce(): void {
+    if (this.clientAttributionLogged) return;
+    const info = this.server.getClientVersion?.();
+    if (!info) return;
+    this.clientAttributionLogged = true;
+    console.error(
+      `[Directory MCP] client: ${info.name ?? "unknown"} v${info.version ?? "unknown"}`,
+    );
+  }
+
+  /**
+   * Resolve a skill:// URI. ADR-140 Phase 2b — SEP-2640 bridge pattern.
+   * Two URI shapes:
+   *   - skill://withpica/index.json
+   *   - skill://withpica/<name>/SKILL.md
+   */
+  private readSkillResource(uri: string): {
+    contents: Array<{ uri: string; mimeType: string; text: string }>;
+  } {
+    if (uri === "skill://withpica/index.json") {
+      const index = this.skillsRegistry.listSkills().map((s) => ({
+        name: s.name,
+        uri: `skill://withpica/${s.name}/SKILL.md`,
+        description: s.description,
+        triggers: s.triggers,
+        audience: s.audience,
+      }));
+      return {
+        contents: [
+          {
+            uri,
+            mimeType: "application/json",
+            text: JSON.stringify({ skills: index }, null, 2),
+          },
+        ],
+      };
+    }
+    const match = uri.match(/^skill:\/\/withpica\/([a-z0-9-]+)\/SKILL\.md$/);
+    if (!match) {
+      throw new Error(`Malformed skill URI: ${uri}`);
+    }
+    const name = match[1];
+    if (!this.skillsRegistry.has(name)) {
+      throw new Error(`Skill not found: ${name}`);
+    }
+    const skill = this.skillsRegistry.getSkill(name);
+    const frontmatter = [
+      "---",
+      `name: ${skill.name}`,
+      `description: ${skill.description}`,
+      "triggers:",
+      ...skill.triggers.map((t) => `  - ${t}`),
+      `audience: ${skill.audience}`,
+      "tools_required:",
+      ...skill.tools_required.map((t) => `  - ${t}`),
+      `output: ${skill.output}`,
+      "---",
+      "",
+    ].join("\n");
+    return {
+      contents: [
+        {
+          uri,
+          mimeType: "text/markdown",
+          text: frontmatter + skill.body,
+        },
+      ],
+    };
+  }
+
   async start(): Promise<void> {
     const transport = new StdioServerTransport();
     await this.server.connect(transport);

package/src/skills/find-music-for-sync-brief/SKILL.md

@@ -0,0 +1,89 @@
+<!-- Copyright (c) 2024-2026 Withpica Ltd. All rights reserved. -->
+---
+name: find-music-for-sync-brief
+description: Find music in the PICA public directory for a sync brief — translate a mood/vibe/scene description into audio search parameters, run the search, and return a rights-aware shortlist with credit details for licensing.
+triggers:
+  - find music for a sync brief
+  - find me a track for a film scene
+  - music for this brief
+  - find an uplifting indie folk track
+  - I need music that sounds like
+audience: sync supervisor / music library / ad agency / film & TV music team
+tools_required:
+  - directory_search_recordings
+  - directory_lookup_work
+  - directory_lookup_person
+output: A rights-aware shortlist — each result with title, artist, audio characteristics (BPM, key, energy), credits summary for licensing contact, and any flags (unattested credits, low registration score, missing ISRC).
+---
+
+# find-music-for-sync-brief
+
+Help the user find music in PICA's public directory for a sync brief. Translate their description (mood, vibe, scene, era, vocal style) into search parameters, run the search, and return a shortlist that includes the information they need to license — not just the track.
+
+This is a public skill — any AI agent connected to the directory MCP can use it. The directory only contains works from organisations that have opted in.
+
+## Step 1 — Translate the brief
+
+Most sync briefs are described in natural language. Translate before searching:
+
+| User says | Search parameters |
+|---|---|
+| upbeat / uplifting / driving | `min_energy: 0.6`, `min_danceability: 0.5` |
+| dark / moody / brooding | `max_energy: 0.4`, `key_mode: minor` |
+| chill / ambient / background | `max_energy: 0.4`, `max_bpm: 100` |
+| epic / cinematic | `min_energy: 0.7`, often longer durations |
+| specific BPM ("around 120bpm") | `min_bpm: 115`, `max_bpm: 125` |
+| acoustic / sparse | typically lower `danceability` and `energy` |
+| vocal / instrumental | filter on `has_vocals` if available |
+
+If the user gives an artist or song reference ("something like X"), look up that reference first via `directory_lookup_work` or `directory_search_recordings` by title — then mimic its audio profile in the new search.
+
+## Step 2 — Search
+
+Call `directory_search_recordings` with the parameters from step 1. Default limit is fine for an initial scan.
+
+If the brief is vague, do two searches with slightly different parameters and compare. If too many results, narrow on BPM or key. If too few, widen the BPM range first, then drop key_mode.
+
+## Step 3 — Lookup full details
+
+For the top 5-10 promising results, call `directory_lookup_work` to get:
+
+- **Who wrote it** — credits with IPI numbers (essential for the licensing contact path)
+- **Whether credits are attested** — an unattested credit means the ownership claim hasn't been verified; flag this
+- **DSP links** (Spotify, Apple Music) — the user wants to listen before shortlisting
+- **Registration score** — higher score = cleaner rights chain = easier to license
+
+For high-value matches where the user wants to know more about the creator, call `directory_lookup_person` with the IPI to see the writer's broader catalog and collaborator network.
+
+## Step 4 — Present the shortlist
+
+Present each shortlisted track with:
+
+- **Title, artist** — what the user listens for
+- **Audio profile** — BPM, key, energy (one line, the supervisor's quick filter)
+- **Credits summary** — writers with IPI, publisher if known (this is the licensing path)
+- **DSP links** — so the user can listen
+- **Flags** — unattested credits, low registration score, missing ISRC, multiple writers (= multi-party clearance needed)
+
+If a track has all green flags (attested credits, high registration score, ISRC present, single or low-count writers), call it out as "clean to clear."
+
+## Step 5 — If no results
+
+If the search returns nothing, walk the user back through the brief:
+- Widen the BPM range first (most supervisors don't actually mind ±10 BPM)
+- Drop the key filter (key matching matters less than mood for most placements)
+- Drop the energy bounds and search by genre/mood text only
+- Suggest the user expand to adjacent moods ("uplifting" → also try "warm" or "hopeful")
+
+Be honest if the directory is small for a specific style — PICA's directory grows with org opt-ins; some niches are sparse.
+
+## What not to do
+
+- Don't claim to license tracks — this skill returns a shortlist, not a license. The user contacts the rights holder via the credits summary.
+- Don't speculate about pricing — sync fees are negotiated per-placement
+- Don't return results from outside the directory (no general web search, no Spotify metadata directly) — the directory is the source of truth for this skill
+- Don't return tracks with no attested credits without flagging them as "rights chain unverified"
+
+## Follow-on skills
+
+- `due-diligence-on-creator` (Stage 2 candidate) — for deeper research on a specific writer before reaching out