@withpica/mcp-server-directory 1.0.0 → 1.2.0

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

@@ -0,0 +1,540 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+
+/**
+ * Public Question Atlas — ADR-229 Decision 1.
+ *
+ * Source-of-truth registry mapping natural public-discovery questions to
+ * the canonical directory-MCP tool resolution. Sister of:
+ *   - `mcp-server/src/prompts/creator-question-atlas.ts` (ADR-226, customer)
+ *   - `team-mcp-server/src/prompts/operator-question-atlas.ts` (ADR-228, operator)
+ *
+ * Read by:
+ *
+ *   - lint Rule 11F (extended in ADR-229) — validates every `directory_*`
+ *     tool's `Use when the user asks` block cites questions resolving
+ *     here, rejects creator/operator atlas cross-pollination, asserts
+ *     mutual exclusivity of `clean_empty_state` and `fallback_when_empty`,
+ *     and asserts `disambiguation` shape integrity
+ *   - `scripts/intent-resolution-eval.ts --surface=directory` (ADR-229 PR-3)
+ *   - the Phase 4 description rewrites — `Use when the user asks` blocks
+ *     pull question + synonym strings from here
+ *
+ * The `AtlasEntry` type is inline-duplicated rather than imported from a
+ * shared package, mirroring ADR-228's choice (Open Question 3 default —
+ * extract to `packages/mcp-atlas-types/` only if a fourth MCP surface
+ * lands or the type drift becomes painful).
+ *
+ * Two shape extensions vs the creator and operator atlases (per ADR-229
+ * Decision 4):
+ *
+ *   1. `clean_empty_state?: { message; suggest_query_shape }` — public-
+ *      surface analog of `fallback_when_empty`. The directory has no
+ *      internal action to nudge toward (the empty state IS the final
+ *      answer for the anonymous user); this field carries the prescribed
+ *      empty-state copy plus a query-shape hint for the calling LLM.
+ *
+ *   2. `disambiguation?: { ambiguous_terms[]; resolver_tool; resolver_intent }` —
+ *      first-class concern on the public surface (creator/operator MCPs
+ *      have a calling-context that narrows the search; the public
+ *      directory hits "Bowie", "Sade", "Madonna", "Lover Boy" constantly
+ *      and must declare an explicit resolver step).
+ *
+ * `clean_empty_state` and `fallback_when_empty` are mutually exclusive on
+ * a single entry — Rule 11F enforces this at lint time.
+ *
+ * The public atlas omits `natural_domain` (creator-side binds to
+ * `discovery.ts` CATEGORIES; the directory MCP has no equivalent
+ * taxonomy — the discovery surface is search and lookup, not category-
+ * faceted browse). It also omits `available_when` (the operator atlas's
+ * forward-compat hook for unshipped sections; the directory has no
+ * deferred-section concept).
+ */
+
+export interface AtlasFallback {
+  message: string;
+  next_tool: string;
+}
+
+export interface AtlasCleanEmptyState {
+  /**
+   * Atlas-prescribed copy for the empty-state response. The calling LLM
+   * may render in its own voice; the suggested-query-shape hint is the
+   * load-bearing part.
+   */
+  message: string;
+  /**
+   * Free-text hint for how to refine the query, interpreted by the LLM
+   * as guidance (not rendered verbatim). Example:
+   * `"title + writer | title + year | ISWC if known"`.
+   */
+  suggest_query_shape: string;
+}
+
+export interface AtlasDisambiguation {
+  /**
+   * Names known to be ambiguous in the music-metadata domain (multiple
+   * persons, artist projects, or works with the same string). v1 ships
+   * a static list; v2 (deferred per ADR-229 § Risks #3) could resolve
+   * dynamically against the index's name-collision frequency.
+   */
+  ambiguous_terms: string[];
+  /**
+   * The directory tool the agent should call FIRST to surface candidate
+   * entities for the user to disambiguate before committing to the
+   * lookup tool in `resolves_to`.
+   */
+  resolver_tool: string;
+  /**
+   * Free-text guidance for the LLM on how to run the resolver step.
+   * Example: `"Call directory_lookup_person first to surface candidates;
+   * ask which one before calling directory_list_works."`
+   */
+  resolver_intent: string;
+}
+
+export type AtlasResolution =
+  | { kind: "tool"; name: string; default_args?: Record<string, unknown> }
+  | { kind: "prompt"; name: string };
+
+export interface AtlasEntry {
+  question: string;
+  synonyms: string[];
+  resolves_to: AtlasResolution;
+  /** Mutually exclusive with `clean_empty_state` (lint-enforced). */
+  fallback_when_empty?: AtlasFallback;
+  /** ADR-229 Decision 4 — public-surface empty-state contract. */
+  clean_empty_state?: AtlasCleanEmptyState;
+  /** ADR-229 Decision 4 — public-surface name-collision contract. */
+  disambiguation?: AtlasDisambiguation;
+}
+
+/**
+ * Names known-ambiguous in the music-metadata domain — multiple persons
+ * sharing a stage name, or artist project names that collide with
+ * person names. Seed list per ADR-229 § Open Q2 (case-insensitive — the
+ * lint and the resolver normalise on lowercase).
+ *
+ * Grow this list as Phase 5 eval data surfaces real collisions the
+ * static seed misses. Do not prune without eval evidence — the cost of
+ * missing a real collision (wrong-tool routing on a public-facing
+ * surface) is higher than the cost of an extra resolver call.
+ */
+export const AMBIGUOUS_NAMES: string[] = [
+  "Bowie",
+  "Sade",
+  "Madonna",
+  "Cher",
+  "Drake",
+  "Prince",
+  "Eminem",
+  "Beyoncé",
+  "Adele",
+  "Sia",
+];
+
+export const PUBLIC_ATLAS: AtlasEntry[] = [
+  // ─────────────────────────────────────────────────────────────────
+  // A. Identifier-lookup — direct resolution, no disambiguation
+  // ─────────────────────────────────────────────────────────────────
+  {
+    question: "what's the ISWC for X?",
+    synonyms: ["ISWC of X", "song code for X", "registration number for X"],
+    resolves_to: { kind: "tool", name: "directory_lookup_work" },
+    clean_empty_state: {
+      message:
+        "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",
+    },
+  },
+  {
+    question: "lookup IPI 12345",
+    synonyms: [
+      "find IPI X",
+      "person with IPI X",
+      "who is IPI X?",
+      "look up IPI number",
+    ],
+    resolves_to: { kind: "tool", name: "directory_lookup_person" },
+    clean_empty_state: {
+      message:
+        "No creator matched that IPI in our index. The IPI may not be " +
+        "mirrored from the source society yet, or it may belong to a " +
+        "publisher rather than a writer — try the directory_list_people " +
+        "filter or search by name.",
+      suggest_query_shape: "IPI | ISNI | writer name | publisher name",
+    },
+  },
+  {
+    question: "lookup ISRC X",
+    synonyms: [
+      "what's the work for ISRC X?",
+      "find the work for this recording",
+      "look up ISRC code",
+    ],
+    resolves_to: { kind: "tool", name: "directory_lookup_isrc" },
+    clean_empty_state: {
+      message:
+        "No work matched that ISRC in our index. The recording may not " +
+        "be linked to a registered work yet, or the ISRC may belong to " +
+        "a recording outside our mirrored societies — try a title or " +
+        "writer-name lookup.",
+      suggest_query_shape: "ISRC | title + artist | ISWC if known",
+    },
+  },
+  {
+    question: "lookup ISNI X",
+    synonyms: [
+      "find creator by ISNI",
+      "person with ISNI X",
+      "look up ISNI identifier",
+    ],
+    resolves_to: { kind: "tool", name: "directory_lookup_person" },
+    clean_empty_state: {
+      message:
+        "No creator matched that ISNI in our index. The creator may not " +
+        "have an ISNI registered, or the ISNI may not be mirrored — try " +
+        "an IPI lookup or a name search.",
+      suggest_query_shape: "ISNI | IPI | creator name",
+    },
+  },
+  {
+    question: "find creator by MusicBrainz ID",
+    synonyms: ["lookup MBID X", "person with MusicBrainz ID"],
+    resolves_to: { kind: "tool", name: "directory_lookup_person" },
+    clean_empty_state: {
+      message:
+        "No creator matched that MusicBrainz ID in our index. The MBID " +
+        "may not be mirrored, or it may identify a release/recording " +
+        "rather than a person — try an ISNI or name lookup.",
+      suggest_query_shape: "MBID | ISNI | creator name",
+    },
+  },
+
+  // ─────────────────────────────────────────────────────────────────
+  // B. Name-lookup — works
+  // ─────────────────────────────────────────────────────────────────
+  {
+    question: "who wrote X?",
+    synonyms: [
+      "who composed X?",
+      "writers of X",
+      "songwriters for X",
+      "credits for song X",
+    ],
+    resolves_to: { kind: "tool", name: "directory_lookup_work" },
+    clean_empty_state: {
+      message:
+        "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",
+    },
+  },
+  {
+    question: "find me song X",
+    synonyms: ["look up song X by title", "is there a song called X?"],
+    resolves_to: { kind: "tool", name: "directory_lookup_work" },
+    clean_empty_state: {
+      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",
+    },
+  },
+  {
+    question: "tell me about song X",
+    synonyms: [
+      "show me song X",
+      "what do you know about song X?",
+      "details for song X",
+    ],
+    resolves_to: { kind: "tool", name: "directory_lookup_work" },
+  },
+  {
+    question: "find recordings of X",
+    synonyms: [
+      "versions of X",
+      "covers of X",
+      "who recorded X?",
+      "list recordings of song X",
+    ],
+    // Disambiguation routes through directory_lookup_work first so the
+    // agent can pick the right work-row; recordings then come from the
+    // work-detail response. NEVER directory_search_recordings — that
+    // tool is audio-feature-only despite the verb match.
+    disambiguation: {
+      ambiguous_terms: AMBIGUOUS_NAMES,
+      resolver_tool: "directory_lookup_work",
+      resolver_intent:
+        "Call directory_lookup_work first to identify the work " +
+        "(multiple works may share the title); then read the recordings[] " +
+        "field from the work-detail response. If the user typed an " +
+        "ISRC-shaped string, call directory_lookup_isrc instead. " +
+        "DO NOT call directory_search_recordings — that tool is for " +
+        "audio-feature filters (BPM/key/energy), not recording lookup.",
+    },
+    resolves_to: { kind: "tool", name: "directory_lookup_work" },
+  },
+
+  // ─────────────────────────────────────────────────────────────────
+  // C. Name-lookup — people (heavy disambiguation)
+  // ─────────────────────────────────────────────────────────────────
+  {
+    question: "find Bowie's songs",
+    synonyms: [
+      "songs by X",
+      "X discography",
+      "X's catalog",
+      "what has X written?",
+    ],
+    disambiguation: {
+      ambiguous_terms: AMBIGUOUS_NAMES,
+      resolver_tool: "directory_lookup_person",
+      resolver_intent:
+        "Call directory_lookup_person first to surface candidate persons " +
+        "(many stage names map to multiple creators); ask the user to " +
+        "pick one before calling directory_list_works with the resolved " +
+        "person ID.",
+    },
+    resolves_to: { kind: "tool", name: "directory_list_works" },
+  },
+  {
+    question: "who is creator X?",
+    synonyms: [
+      "find creator X",
+      "look up artist by name",
+      "find the songwriter X",
+    ],
+    disambiguation: {
+      ambiguous_terms: AMBIGUOUS_NAMES,
+      resolver_tool: "directory_lookup_person",
+      resolver_intent:
+        "Call directory_lookup_person; if the response shows multiple " +
+        "candidates (common for stage names), surface them and let the " +
+        "user pick before any follow-up call.",
+    },
+    resolves_to: { kind: "tool", name: "directory_lookup_person" },
+  },
+  {
+    question: "tell me about creator X",
+    synonyms: [
+      "show me creator X",
+      "what do you know about creator X?",
+      "details for creator X",
+      "what's X's catalog?",
+    ],
+    resolves_to: { kind: "tool", name: "directory_lookup_person" },
+  },
+  {
+    question: "who performs this song?",
+    synonyms: [
+      "who recorded this version?",
+      "performers of this recording",
+      "artist on this ISRC",
+    ],
+    resolves_to: { kind: "tool", name: "directory_lookup_isrc" },
+    clean_empty_state: {
+      message:
+        "No recording matched that identifier. If you have a song title " +
+        "instead of an ISRC, look up the work and read its recordings " +
+        "list. Performer credits surface there per recording.",
+      suggest_query_shape: "ISRC | work title + artist",
+    },
+  },
+
+  // ─────────────────────────────────────────────────────────────────
+  // D. Discovery-traversal / chain (graph shape)
+  // ─────────────────────────────────────────────────────────────────
+  {
+    question: "show me the rights chain for X",
+    synonyms: [
+      "full graph for X",
+      "rights chain on this song",
+      "what's the chain for X?",
+    ],
+    resolves_to: { kind: "tool", name: "directory_chain" },
+  },
+  {
+    question: "give me everything on this song",
+    synonyms: [
+      "everything we know about this work",
+      "what's the full picture for X?",
+      "full picture for X",
+      "the whole graph for X",
+    ],
+    resolves_to: { kind: "tool", name: "directory_chain" },
+  },
+  {
+    question: "trace the chain from this writer to that work",
+    synonyms: [
+      "how is X connected to Y?",
+      "trace this credit",
+      "show the connection between X and Y",
+    ],
+    resolves_to: { kind: "tool", name: "directory_chain" },
+  },
+
+  // ─────────────────────────────────────────────────────────────────
+  // E. Browse / filter
+  // ─────────────────────────────────────────────────────────────────
+  {
+    question: "list works in PICA",
+    synonyms: [
+      "browse the catalog",
+      "what works are in the directory?",
+      "show me all works",
+    ],
+    resolves_to: { kind: "tool", name: "directory_list_works" },
+  },
+  {
+    question: "works starting with B",
+    synonyms: [
+      "list works starting with letter X",
+      "browse catalog by first letter",
+      "alphabetical work browse",
+    ],
+    resolves_to: {
+      kind: "tool",
+      name: "directory_list_works",
+      default_args: { letter: "B" },
+    },
+  },
+  {
+    question: "find works by publisher X",
+    synonyms: [
+      "list publisher X's works",
+      "what's in publisher X's catalog?",
+      "publisher catalog browse",
+    ],
+    resolves_to: { kind: "tool", name: "directory_list_works" },
+  },
+  {
+    question: "find works by label X",
+    synonyms: [
+      "list label X's recordings",
+      "what's on label X?",
+      "label catalog browse",
+    ],
+    resolves_to: { kind: "tool", name: "directory_list_works" },
+  },
+  {
+    question: "list creators in PICA",
+    synonyms: [
+      "browse the people directory",
+      "what creators are in the directory?",
+      "show me all creators",
+    ],
+    resolves_to: { kind: "tool", name: "directory_list_people" },
+  },
+  {
+    question: "people starting with B",
+    synonyms: [
+      "list creators starting with letter X",
+      "browse creators by first letter",
+      "alphabetical people browse",
+    ],
+    resolves_to: {
+      kind: "tool",
+      name: "directory_list_people",
+      default_args: { letter: "B" },
+    },
+  },
+
+  // ─────────────────────────────────────────────────────────────────
+  // F. Audio-feature search (sync licensing — distinct from text search)
+  // ─────────────────────────────────────────────────────────────────
+  {
+    question: "find upbeat tracks around 120 BPM",
+    synonyms: [
+      "find tracks at X BPM",
+      "find energetic music for sync",
+      "tracks with high energy",
+    ],
+    resolves_to: { kind: "tool", name: "directory_search_recordings" },
+  },
+  {
+    question: "find instrumental tracks in C minor",
+    synonyms: [
+      "tracks in [key]",
+      "instrumental tracks for sync",
+      "find moody music in a minor key",
+    ],
+    resolves_to: { kind: "tool", name: "directory_search_recordings" },
+  },
+  {
+    question: "tracks at X BPM in [key]",
+    synonyms: [
+      "find music matching tempo and key",
+      "audio-feature search for sync",
+      "filter recordings by audio characteristics",
+    ],
+    resolves_to: { kind: "tool", name: "directory_search_recordings" },
+  },
+
+  // ─────────────────────────────────────────────────────────────────
+  // G. Cross-type search (entity type unknown)
+  // ─────────────────────────────────────────────────────────────────
+  {
+    question: "find me X",
+    synonyms: [
+      "is there anything about X in the directory?",
+      "find any record of X",
+      "search the directory for X",
+    ],
+    resolves_to: { kind: "tool", name: "directory_search" },
+    clean_empty_state: {
+      message:
+        "No matches in our public directory. The work, creator, or " +
+        "recording may not be mirrored from a society we cover yet, or " +
+        "the spelling may differ — try an identifier (ISWC / ISRC / IPI) " +
+        "if you have one.",
+      suggest_query_shape:
+        "name + role | identifier (ISWC/ISRC/IPI/ISNI) | title + writer",
+    },
+  },
+  {
+    question: "who or what is X?",
+    synonyms: [
+      "is X a song or a person?",
+      "what kind of thing is X?",
+      "fan-out search for X",
+    ],
+    resolves_to: { kind: "tool", name: "directory_search" },
+    clean_empty_state: {
+      message:
+        "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",
+    },
+  },
+
+  // ─────────────────────────────────────────────────────────────────
+  // H. Registration / status (specialised lookups)
+  // ─────────────────────────────────────────────────────────────────
+  {
+    question: "is this song registered?",
+    synonyms: [
+      "is X in PICA?",
+      "is this work known?",
+      "registration status of X",
+      "is the ISWC issued for X?",
+    ],
+    resolves_to: { kind: "tool", name: "directory_lookup_work" },
+    clean_empty_state: {
+      message:
+        "We don't have this work in our directory. That can mean it's " +
+        "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",
+    },
+  },
+];

package/src/resources/llms-primer.ts

@@ -0,0 +1,35 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+
+export const DIRECTORY_PRIMER = `# PICA Directory — Public Music Catalog Search
+
+Read-only access to published music catalog data. No authentication required.
+Works and people are only visible if the owning organisation has opted into
+the directory.
+
+## First Connection
+
+If you're not sure where to start, invoke the **directory-autopilot** prompt.
+It asks what you need and routes to the right workflow: sync search, rights
+research, or identifier lookup.
+
+## What You Can Do
+- Search works by title, ISWC, publisher, label
+- Search people by name, ISNI, IPI
+- Look up works by recording ISRC (directory_lookup_isrc)
+- Search recordings by audio characteristics (BPM, key, mood, energy)
+
+## What You Cannot Do
+- Create, update, or delete anything (read-only)
+- Access unpublished works or private catalog data
+- See financial data, agreements, or internal metadata
+
+## Entity Model
+- **Work**: composition with title, ISWC, credits, recordings
+- **Person**: writer/composer/performer with IPI, ISNI identifiers
+- **Recording**: audio capture with ISRC, linked to one work
+
+## Recommended Flow
+1. directory_search (broad text search across works + people)
+2. directory_lookup_work or directory_lookup_person (detailed view)
+3. directory_search_recordings (audio characteristic search for sync)
+`;