@withpica/mcp-server-directory 1.2.0 → 1.4.0

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/lib/changelog.ts

@@ -0,0 +1,119 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+
+/**
+ * Runtime CHANGELOG parser. Mirrors scripts/parse-changelog.ts but takes
+ * the markdown body as a string (no fs dependency) so the MCP runtime
+ * can read from a build-time embedded constant. Sister of
+ * mcp-server/src/lib/changelog.ts and team-mcp-server/src/lib/changelog.ts.
+ */
+
+export type ChangelogSectionName =
+  | "Added"
+  | "Changed"
+  | "Fixed"
+  | "Removed"
+  | "Security"
+  | "Deprecated";
+
+export const CHANGELOG_SECTION_NAMES: ChangelogSectionName[] = [
+  "Added",
+  "Changed",
+  "Fixed",
+  "Removed",
+  "Security",
+  "Deprecated",
+];
+
+export interface ChangelogEntry {
+  version: string;
+  date: string | null;
+  sections: Partial<Record<ChangelogSectionName, string[]>>;
+  markdown: string;
+}
+
+const HEADING_RE = /^##\s+\[([^\]]+)\](?:\s*-\s*(\d{4}-\d{2}-\d{2}))?\s*$/;
+const SECTION_RE = /^###\s+(\w+)\s*$/;
+const BULLET_RE = /^-\s+(.*)$/;
+
+export function parseChangelogText(text: string): ChangelogEntry[] {
+  const lines = text.split("\n");
+
+  const entries: ChangelogEntry[] = [];
+  let current: (ChangelogEntry & { _start: number }) | null = null;
+  let currentSection: ChangelogSectionName | null = null;
+  let currentBullet: {
+    entry: ChangelogEntry;
+    section: ChangelogSectionName;
+    index: number;
+  } | null = null;
+
+  const flush = (endLine: number) => {
+    if (current && current.version !== "Unreleased") {
+      current.markdown = lines
+        .slice(current._start, endLine)
+        .join("\n")
+        .trimEnd();
+      const { _start: _start, ...rest } = current;
+      entries.push(rest);
+    }
+    current = null;
+    currentSection = null;
+    currentBullet = null;
+  };
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const headingMatch = line.match(HEADING_RE);
+    if (headingMatch) {
+      flush(i);
+      current = {
+        version: headingMatch[1],
+        date: headingMatch[2] ?? null,
+        sections: {},
+        markdown: "",
+        _start: i,
+      };
+      currentSection = null;
+      continue;
+    }
+
+    if (!current) continue;
+
+    const sectionMatch = line.match(SECTION_RE);
+    if (sectionMatch) {
+      const name = sectionMatch[1] as ChangelogSectionName;
+      if (CHANGELOG_SECTION_NAMES.includes(name)) {
+        currentSection = name;
+        if (!current.sections[name]) current.sections[name] = [];
+      } else {
+        currentSection = null;
+      }
+      currentBullet = null;
+      continue;
+    }
+
+    const bulletMatch = line.match(BULLET_RE);
+    if (bulletMatch && currentSection) {
+      const arr = current.sections[currentSection]!;
+      arr.push(bulletMatch[1].trim());
+      currentBullet = {
+        entry: current,
+        section: currentSection,
+        index: arr.length - 1,
+      };
+      continue;
+    }
+
+    if (currentBullet && line.startsWith("  ") && line.trim().length > 0) {
+      const arr = currentBullet.entry.sections[currentBullet.section]!;
+      arr[currentBullet.index] = `${arr[currentBullet.index]} ${line.trim()}`;
+      continue;
+    }
+
+    currentBullet = null;
+  }
+
+  flush(lines.length);
+
+  return entries;
+}

package/src/prompts/public-question-atlas.ts

@@ -145,8 +145,7 @@ export const PUBLIC_ATLAS: AtlasEntry[] = [
         "No work matched that title in our index. The work may not be " +
         "registered with a society we mirror, or the title may be " +
         "ambiguous — try a writer name or year of release to narrow.",
-      suggest_query_shape:
-        "title + writer | title + year | ISWC if known",
+      suggest_query_shape: "title + writer | title + year | ISWC if known",
     },
   },
   {
@@ -230,8 +229,7 @@ export const PUBLIC_ATLAS: AtlasEntry[] = [
         "No work matched that title. The song may not be in our index " +
         "yet, or the title may be ambiguous (many works share the same " +
         "title) — try a writer name or year of release.",
-      suggest_query_shape:
-        "title + writer | title + year | ISWC if known",
+      suggest_query_shape: "title + writer | title + year | ISWC if known",
     },
   },
   {
@@ -242,8 +240,7 @@ export const PUBLIC_ATLAS: AtlasEntry[] = [
       message:
         "No work matched that title in our index. Try refining with the " +
         "writer's name, year of release, or the ISWC if you have it.",
-      suggest_query_shape:
-        "title + writer | title + year | ISWC if known",
+      suggest_query_shape: "title + writer | title + year | ISWC if known",
     },
   },
   {
@@ -510,8 +507,7 @@ export const PUBLIC_ATLAS: AtlasEntry[] = [
         "No matches in our public directory across works or creators. " +
         "Try narrowing to one entity type (work title or creator name), " +
         "or supply an identifier if you have one.",
-      suggest_query_shape:
-        "title + writer | creator name + role | identifier",
+      suggest_query_shape: "title + writer | creator name + role | identifier",
     },
   },
 
@@ -533,8 +529,38 @@ export const PUBLIC_ATLAS: AtlasEntry[] = [
         "unregistered, registered with a society we don't mirror, or the " +
         "title is ambiguous. Try a writer name or year to narrow, or " +
         "look up by ISWC if you have one.",
-      suggest_query_shape:
-        "title + writer | title + year | ISWC if known",
+      suggest_query_shape: "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" },
+  },
+
+  // ─────────────────────────────────────────────────────────────────
+  // Directory-surface self-introspection — what shipped in this MCP
+  // ─────────────────────────────────────────────────────────────────
+  {
+    question: "what's new in the directory mcp",
+    synonyms: [
+      "what changed in the directory",
+      "directory release notes",
+      "what version is the directory on",
+      "directory changelog",
+    ],
+    resolves_to: { kind: "tool", name: "directory_release_notes" },
+  },
 ];