UNPKG

@withpica/mcp-server

Version:

MCP Server for withPICA — enables AI assistants to interact with your withPICA music catalog

843 lines • 39.5 kB
// Copyright (c) 2025-2026 Withpica Ltd. All rights reserved. export const ATLAS = [ // ───────────────────────────────────────────────────────────────── // A. Analytical / dashboard funnels // ───────────────────────────────────────────────────────────────── { question: "what's new?", synonyms: ["any updates?", "catch me up", "what's been happening?"], natural_domain: "briefing", resolves_to: { kind: "tool", name: "pica_dashboard_briefing" }, }, { question: "what's wrong with my songs?", synonyms: [ "what's broken?", "what needs fixing?", "what should I do?", "anything urgent?", ], natural_domain: "briefing", resolves_to: { kind: "tool", name: "pica_dashboard_attention" }, }, { // ADR-247 PR (c) — pulse deprecated; resolver now routes to // pica_dashboard_briefing for the catalog-gaps glance. Briefing // flows through the ADR-242 coherence contract; pulse used a // separate predicate set and disagreed in practice. question: "give me the pulse", synonyms: ["how's my catalog?", "where's my catalog at?"], natural_domain: "briefing", resolves_to: { kind: "tool", name: "pica_dashboard_briefing" }, }, { question: "what did I ask the AI?", synonyms: [ "what have I been doing?", "show me my recent activity", "show me what the AI ran", "what AI tasks did I confirm?", ], natural_domain: "memory", // resolves to tool created in Phase 5 resolves_to: { kind: "tool", name: "pica_my_recent_questions" }, }, { question: "where was I?", synonyms: [ "pick up where I left off", "continue what I was doing", "what was I working on?", ], // resolves to prompt created in Phase 5 resolves_to: { kind: "prompt", name: "pica_continue" }, }, // ───────────────────────────────────────────────────────────────── // B. Royalties / earnings // ───────────────────────────────────────────────────────────────── { question: "why isn't this song being paid?", synonyms: [ "what's holding up my money?", "why am I not getting paid for X?", "what's stopping my songs being paid?", "what do I need to fix to get paid?", ], natural_domain: "royalties_statements", resolves_to: { kind: "tool", name: "pica_royalties_blockers" }, }, { // ADR-321 §9 — PICA's own rules (song, master and share rules) and what // they would hold. Society-side blockers stay with the entry above. question: "who gets paid on this song?", synonyms: [ "is this song programmable?", "who still needs to confirm the rule?", "what money would PICA hold on this song, and why?", ], natural_domain: "rights", resolves_to: { kind: "tool", name: "pica_rights_inspect" }, }, { // ADR-321 Phase 3 — what income WOULD pay each party (never "paid"), and // a society statement checked against the locked split. question: "what would I get from this money?", synonyms: [ "who gets what from this sync fee?", "does my PRS statement match my split?", "is my song registered right?", ], natural_domain: "rights", resolves_to: { kind: "tool", name: "pica_rights_statements" }, }, { // 2026-09-30 — the founder forwarded a split sheet and their agent could // not tell it had arrived, nor what it became. question: "did my email arrive?", synonyms: [ "I forwarded you a split sheet", "what happened to the email I sent PICA?", ], natural_domain: "import", resolves_to: { kind: "tool", name: "pica_import_emails_query" }, }, { question: "how much has this song earned?", synonyms: [ "how much have I made on X?", "what's X earned?", "what's this song worth?", "did I get paid for this?", ], natural_domain: "royalties_statements", resolves_to: { kind: "tool", name: "pica_royalties_get" }, fallback_when_empty: { message: "I don't see any earnings statements for this song yet. " + "Would you like to import a recent PRO, NRO, or sync statement?", next_tool: "pica_ingest_statement", }, }, { question: "show me my statements", synonyms: ["list royalty statements", "what statements are imported?"], natural_domain: "royalties_statements", // Tier 2 (MCP tool-surface consolidation, ADR-149): pica_statements_list // was replaced by pica_statements_query (the old name was removed in // mcp-server 2.99.0) — the Atlas resolves to the canonical name so it // stays cross-listed under CATEGORIES.royalties_statements.tools. resolves_to: { kind: "tool", name: "pica_statements_query" }, }, { question: "import a royalty statement", synonyms: ["log a statement", "ingest a PRO statement"], natural_domain: "royalties_statements", resolves_to: { kind: "tool", name: "pica_ingest_statement" }, }, { question: "what royalties has X paid me?", synonyms: ["earnings from PRS", "MLC payouts", "royalty entries from X"], natural_domain: "royalties_statements", resolves_to: { kind: "tool", name: "pica_royalties_list" }, }, // ───────────────────────────────────────────────────────────────── // C. File-handoff (≥5 required per ADR Amendment 2) // ───────────────────────────────────────────────────────────────── { question: "can I upload audio from here?", synonyms: ["can I send you a song?", "how do I upload from chat?"], natural_domain: "audio", resolves_to: { kind: "tool", name: "pica_upload", default_args: { accept: "audio" }, }, }, { question: "send me the export", synonyms: ["download that file", "give me the file"], natural_domain: "export", resolves_to: { kind: "tool", name: "pica_download" }, }, { question: "export this work to my PRO", synonyms: [ "register this song with PRS / ASCAP / BMI", "send to my distributor", "make a sync one-sheet", ], natural_domain: "export", resolves_to: { kind: "tool", name: "pica_export_catalog_csv" }, }, { question: "upload the contract", synonyms: ["can I send you a PDF?", "attach an agreement"], natural_domain: "documents", resolves_to: { kind: "tool", name: "pica_upload", default_args: { accept: "document" }, }, }, { question: "upload some session photos", synonyms: ["add photos from a session", "upload images from a session"], natural_domain: "multimedia", resolves_to: { kind: "tool", name: "pica_upload", default_args: { accept: "image", purpose: "session photos" }, }, }, { question: "export an industry-ready package", synonyms: ["get a registration-ready bundle", "export for registration"], natural_domain: "export", resolves_to: { kind: "tool", name: "pica_export_industry_ready" }, }, // ───────────────────────────────────────────────────────────────── // D. Collaborators / credits (≥4 required per ADR Amendment 2) // ───────────────────────────────────────────────────────────────── { question: "who's on this song?", synonyms: ["who owns this work?", "who's credited?"], natural_domain: "credits", resolves_to: { kind: "tool", name: "pica_credits_list" }, fallback_when_empty: { message: "I don't see any credits on this work yet. " + "Want to add yours, or invite collaborators to confirm theirs?", next_tool: "pica_claim_credit", }, }, { question: "what was my role on this?", synonyms: ["am I credited on X?", "what did I do on this song?"], natural_domain: "credits", resolves_to: { kind: "tool", name: "pica_credits_list" }, fallback_when_empty: { message: "I don't see your credit on this work yet. " + "Want to claim it now?", next_tool: "pica_claim_credit", }, }, { question: "who wrote it?", synonyms: ["do you know who wrote it?", "who's the writer?"], natural_domain: "credits", resolves_to: { kind: "tool", name: "pica_credits_list" }, fallback_when_empty: { message: "I don't see writer credits on this work yet. " + "Want to invite the people you worked with on it?", next_tool: "pica_collaborators_invite", }, }, { question: "let's notify the people on this song", synonyms: ["ask everyone to verify", "get my collaborators to confirm"], natural_domain: "collaborators", resolves_to: { kind: "tool", name: "pica_collaborators_invite", default_args: { purpose: "verify_credits" }, }, }, { question: "who's pending invites?", synonyms: ["who hasn't accepted yet?", "outstanding invites"], natural_domain: "collaborators", resolves_to: { kind: "tool", name: "pica_collaborators_invites_list" }, }, { question: "I want to claim my credit on X", synonyms: ["add me as a writer on X", "credit me on this song"], natural_domain: "credits", resolves_to: { kind: "tool", name: "pica_claim_credit" }, }, { question: "who owes me something?", synonyms: [ "who hasn't responded?", "who owes me a reply?", "what's outstanding?", ], // resolves to prompt created in Phase 5 resolves_to: { kind: "prompt", name: "who-owes-me-something" }, }, // ───────────────────────────────────────────────────────────────── // E. Continuity / auditability (some entries fold into A above; this // section deliberately stays narrow — most natural phrasings live as // synonyms of #4 and #5 above) // ───────────────────────────────────────────────────────────────── // ───────────────────────────────────────────────────────────────── // F. Vocabulary / memory // ───────────────────────────────────────────────────────────────── { question: "remember that I call X 'Y'", synonyms: [ "when I say jingles, I mean sync placements", "save this vocabulary", ], natural_domain: "memory", resolves_to: { kind: "tool", name: "pica_memory_save", default_args: { type: "vocabulary" }, }, }, { question: "forget what I told you about X", synonyms: ["drop that memory", "delete that note"], natural_domain: "memory", resolves_to: { kind: "tool", name: "pica_memory_delete" }, }, { question: "what have you remembered about me?", synonyms: ["what notes do you have?", "list my memories"], natural_domain: "memory", resolves_to: { kind: "tool", name: "pica_memory_list" }, }, // ───────────────────────────────────────────────────────────────── // G. Search / inspect // ───────────────────────────────────────────────────────────────── { question: "find this song", synonyms: ["look up X", "search for X"], natural_domain: "search", resolves_to: { kind: "tool", name: "pica_search_all", default_args: { kind: "work" }, }, }, { question: "tell me about this song", synonyms: ["show me this song", "what do you know about this work?"], natural_domain: "works", resolves_to: { kind: "tool", name: "pica_works_inspect" }, }, { // E8 (prod audit 2026-08-28): the weekly roundup's pica-scores block has // invited readers to say "show my pica score" since ADR-234 Phase 4, and // the phrase resolved to NOTHING — the reader who did what the email asked // got a shrug. `pica_works_inspect`'s `score` section is the only surface // that serves it (`this.pica.picaScore.get()`, mcp-server/src/tools/ // works.ts): the score is org-level, so the work id scopes the rest of the // call and not this section. question: "show my pica score", synonyms: [ "what's my pica score?", "how complete is my catalogue?", "show my grade", ], natural_domain: "works", resolves_to: { kind: "tool", name: "pica_works_inspect", default_args: { sections: ["score"] }, }, }, { question: "find this person", synonyms: ["look up artist X", "who is X?"], natural_domain: "search", resolves_to: { kind: "tool", name: "pica_search_all", default_args: { kind: "person" }, }, }, { question: "tell me about this person", synonyms: ["show me everything on X", "what do you know about artist X?"], natural_domain: "people", resolves_to: { kind: "tool", name: "pica_people_inspect" }, }, // ───────────────────────────────────────────────────────────────── // H. Status & registration // ───────────────────────────────────────────────────────────────── { question: "am I ready to register?", synonyms: ["can I submit X to MLC?", "is X complete?"], natural_domain: "works", resolves_to: { kind: "tool", name: "pica_catalog_diligence" }, }, { // Eval-driven re-route 2026-05-07: am-i-ready-to-register is the Phase 5 // alias of register-my-works (PromptRegistry resolves both names to the // same handler). The alias's framing wins the embedding match for natural // creator phrasing because it's worded like a question; both prompts // orchestrate identical tool sequences. question: "register my works", synonyms: ["submit my songs", "send my catalog to the registries"], resolves_to: { kind: "prompt", name: "am-i-ready-to-register" }, }, { question: "what's pending registration?", synonyms: ["what hasn't been registered yet?", "unregistered works"], natural_domain: "works", resolves_to: { kind: "tool", name: "pica_works_query", default_args: { registration_status: "pending" }, }, }, // ───────────────────────────────────────────────────────────────── // I. Recording splits // ───────────────────────────────────────────────────────────────── { // Work-side splits = composer / publisher percentages on the work itself. // Recording-side has its own entries below; the eval was correctly picking // the recording-side tool for ambiguous "splits" framing — this entry now // explicitly disambiguates to the work side. question: "what are the work credits on this song?", synonyms: [ "what are the splits on this song?", "show me the work credits", "who gets what on this work?", ], natural_domain: "credits", resolves_to: { kind: "tool", name: "pica_credits_list" }, }, { question: "what are the recording splits on this?", synonyms: [ "show me the master splits", "who's on the master?", "list the recording-side splits", ], natural_domain: "recording_splits", resolves_to: { kind: "tool", name: "pica_recording_splits_list" }, }, { question: "set the work credits", synonyms: [ "update the work credits", "fix the splits on this work", "change the songwriter splits", ], natural_domain: "credits", resolves_to: { kind: "tool", name: "pica_credits_update" }, }, { // Eval-driven re-route 2026-05-07: pica_recording_splits_create is the // semantic-natural target for "set the recording splits" (creator-side // verb is "set" = create new). pica_recording_credits_update is the // update-existing path; reachable via "update the recording credits" // synonym + the recording-side cross-listing under CATEGORIES.recording_splits. question: "set the recording splits", synonyms: [ "log splits for this recording", "update master splits", "update the recording credits", ], natural_domain: "recording_splits", resolves_to: { kind: "tool", name: "pica_recording_splits_create" }, }, { question: "how do I split this with my co-writer?", synonyms: ["set up a split sheet", "generate a split sheet"], natural_domain: "recording_splits", resolves_to: { kind: "tool", name: "pica_split_sheet_generate" }, }, // ADR-232 — atomic credit primitives. Composable adds and removes for // single-row collaboration edits, distinct from the full-replace shape of // pica_credits_update / pica_recording_credits_update. { question: "add Mary as additional songwriter at 25%", synonyms: [ "credit Bob as producer", "add a vocalist to this recording", "add another collaborator", ], natural_domain: "credits", resolves_to: { kind: "tool", name: "pica_credit_add" }, }, { question: "credit a producer on this recording", synonyms: [ "add a recording credit", "credit a performer", "add a producer to this track", "add a remixer", ], natural_domain: "credits", resolves_to: { kind: "tool", name: "pica_credit_add" }, }, { question: "take Bob off this song", synonyms: [ "remove this credit", "unlist Mary as performer", "delete a single credit", ], natural_domain: "credits", resolves_to: { kind: "tool", name: "pica_credit_remove" }, }, { question: "delete one credit without rewriting all of them", synonyms: [ "remove a single collaborator", "drop this credit but keep the others", "atomic remove a credit by id", ], natural_domain: "credits", resolves_to: { kind: "tool", name: "pica_credit_remove" }, }, // ADR-232 § Decision 2 — share trace explainability. { question: "why does Tony have access to this song?", synonyms: [ "who can see this work?", "how did this person see my recording?", "explain access to this work", "trace sharing on this work", ], natural_domain: "sharing", resolves_to: { kind: "tool", name: "pica_share_trace" }, }, { question: "how does this collaborator see this work?", synonyms: [ "show me the chain of access", "what gives this person access?", "is this share via a link or a grant?", ], natural_domain: "sharing", resolves_to: { kind: "tool", name: "pica_share_trace" }, }, // ADR-232 § Decision 3 — count discrepancy explainer. { question: "why does the dashboard say 80 but I counted 78?", synonyms: [ "where are the missing works?", "explain this number", "reconcile this count", "why are these counts different?", ], natural_domain: "explainability", resolves_to: { kind: "tool", name: "pica_count_explain" }, }, { question: "where are the missing 2?", synonyms: [ "explain this count", "what's in this total?", "what query backs this number?", "show me the breakdown", ], natural_domain: "explainability", resolves_to: { kind: "tool", name: "pica_count_explain" }, }, // ADR-232 § Decision 4 — audio pipeline status. { question: "what's stuck in audio analysis?", synonyms: [ "why hasn't this audio been analysed?", "show me the audio pipeline status", "what audio is failed or pending?", "audio analysis stuck", ], natural_domain: "audio", resolves_to: { kind: "tool", name: "pica_audio_pipeline_status" }, }, { question: "any audio issues?", synonyms: [ "audio pipeline health", "list failed audio analyses", "audio backlog", "stuck audio over 24 hours", ], natural_domain: "audio", resolves_to: { kind: "tool", name: "pica_audio_pipeline_status" }, }, // ───────────────────────────────────────────────────────────────── // J. Agreements / contracts // ───────────────────────────────────────────────────────────────── { question: "what agreements do I have?", synonyms: ["list contracts", "my deals"], natural_domain: "agreements", resolves_to: { kind: "tool", name: "pica_agreements_query" }, }, { question: "show me this contract", synonyms: ["what's in this agreement?", "open this contract"], natural_domain: "agreements", resolves_to: { kind: "tool", name: "pica_agreements_inspect" }, }, { question: "create a new agreement", synonyms: ["start a contract", "draft a deal"], natural_domain: "agreements", resolves_to: { kind: "tool", name: "pica_agreements_create" }, }, // ───────────────────────────────────────────────────────────────── // K. Sync placements // ───────────────────────────────────────────────────────────────── { question: "any sync placements?", synonyms: ["what jingles are on?", "list my syncs"], natural_domain: "sync_placements", resolves_to: { kind: "tool", name: "pica_sync_placements_query" }, }, { question: "log a new sync placement", synonyms: ["log a jingle", "add a sync"], natural_domain: "sync_placements", resolves_to: { kind: "tool", name: "pica_sync_placements_create" }, }, // ───────────────────────────────────────────────────────────────── // L. Notifications // ───────────────────────────────────────────────────────────────── { question: "what notifications do I have?", synonyms: ["anything from the team?", "recent alerts"], natural_domain: "notifications", resolves_to: { kind: "tool", name: "pica_notifications_recent" }, }, // ───────────────────────────────────────────────────────────────── // M. Privacy / consent / data export // ───────────────────────────────────────────────────────────────── { question: "what data have I consented to AI training?", synonyms: ["show my AI consent", "AI training opt-in status"], natural_domain: "privacy", resolves_to: { kind: "tool", name: "pica_export_ai_consent" }, }, { question: "export my data", synonyms: ["get all my data", "download everything you have on me"], natural_domain: "export", resolves_to: { kind: "tool", name: "pica_export_my_data" }, }, { question: "delete my data", synonyms: ["close my account", "erase me"], natural_domain: "account", resolves_to: { kind: "tool", name: "pica_delete_my_account" }, }, // ───────────────────────────────────────────────────────────────── // N. Account / subscription // ───────────────────────────────────────────────────────────────── { question: "what's my plan?", synonyms: ["what tier am I on?", "show my subscription"], natural_domain: "subscription", resolves_to: { kind: "tool", name: "pica_subscription_status" }, }, { question: "how do i pay pica?", synonyms: [ "what does pica cost?", "send me a payment link", "how much is a resident month?", "unlock what you're holding", ], natural_domain: "subscription", resolves_to: { kind: "tool", name: "pica_billing_pay" }, }, { question: "show my account info", synonyms: ["what do you have on me?", "my profile"], natural_domain: "profile", resolves_to: { kind: "tool", name: "pica_user_profile" }, }, // ───────────────────────────────────────────────────────────────── // O2. Consent readiness (ADR-300) // ───────────────────────────────────────────────────────────────── { question: "how much of my catalogue is clearable for AI training?", synonyms: [ "can I license this for AI?", "what's my AI consent coverage?", "who hasn't given consent?", "what's blocking an AI deal?", ], natural_domain: "consent", resolves_to: { kind: "tool", name: "pica_consent_readiness" }, }, // ───────────────────────────────────────────────────────────────── // O. Custody (intentionally minimal vernacular per IP rules) // ───────────────────────────────────────────────────────────────── { question: "who has custody of X right now?", synonyms: ["who owns the asset?"], natural_domain: "custody", resolves_to: { kind: "tool", name: "pica_custody_list" }, }, { question: "claim custody", synonyms: ["take over X"], natural_domain: "custody", // TODO Phase 3 — verify canonical between pica_claim_custody and pica_custody_claim resolves_to: { kind: "tool", name: "pica_claim_custody" }, }, // ───────────────────────────────────────────────────────────────── // P. Disputes // ───────────────────────────────────────────────────────────────── { question: "I disagree with this", synonyms: ["dispute that", "contest this credit"], natural_domain: "collaborators", resolves_to: { kind: "tool", name: "pica_collaborators_dispute" }, }, { question: "show me my open disputes", synonyms: ["what's contested?", "list active disputes"], natural_domain: "collaborators", resolves_to: { kind: "tool", name: "pica_disputes_list" }, }, // ───────────────────────────────────────────────────────────────── // ADR-140 Phase 2b — Skill discovery (creator-vernacular) // ───────────────────────────────────────────────────────────────── { // Catalog-domain meta-discovery. Phrasing intentionally distinct // from the public-directory atlas equivalent ("what skills do you // have?") to satisfy ADR-229 AC-3 cross-pollination isolation. question: "what catalog workflows are available?", synonyms: [ "what can you help me do with my songs?", "show me my workflow options", "what workflows do you have for my catalog?", "list my catalog workflows", ], natural_domain: "skills", resolves_to: { kind: "tool", name: "pica_skill_list" }, }, // ───────────────────────────────────────────────────────────────── // ADR-231 — User-initiated asset sharing // ───────────────────────────────────────────────────────────────── { question: "send this song to <name>", synonyms: [ "share this work with <name>", "email this to <person>", "shoot this over to <name>", "forward this to <person>", "send the track to <email>", ], natural_domain: "sharing", resolves_to: { kind: "tool", name: "pica_share_send" }, }, // ───────────────────────────────────────────────────────────────── // WS2 Oracle — pica_catalog_stats counting intents (ADR-226 Decision 2: // flipped from vernacular_kind 'specialist' to 'creator-entry' now that // it carries entity/group_by breakdowns; these entries are the required // Atlas backing, natural_domain "search" matches the CATEGORIES bucket // pica_catalog_stats belongs to (discovery.ts). // ───────────────────────────────────────────────────────────────── { question: "how many songs do I have?", synonyms: [ "how many recordings do I have?", "how many releases do I have?", "how many people do I have?", "how big is my catalog?", "catalog size", "how many songs/recordings/releases/people do I have?", ], natural_domain: "search", resolves_to: { kind: "tool", name: "pica_catalog_stats" }, }, { question: "how many have I produced?", synonyms: [ "how many songs have I produced?", "how many tracks have I produced?", "what's my production count?", "top production count", ], natural_domain: "search", resolves_to: { kind: "tool", name: "pica_catalog_stats" }, }, { question: "who's my top collaborator?", synonyms: [ "who's my most frequent collaborator?", "who have I worked with the most?", "who do I collaborate with most?", "my most frequent collaborator", ], natural_domain: "search", resolves_to: { kind: "tool", name: "pica_catalog_stats" }, }, { question: "genre breakdown", synonyms: [ "breakdown by genre", "what genres are my songs?", "what genres do I write in?", "give me a genre breakdown", ], natural_domain: "search", resolves_to: { kind: "tool", name: "pica_catalog_stats" }, }, { question: "releases per year", synonyms: [ "how many releases each year?", "releases by year", "how many releases did I put out each year?", "breakdown of releases by year", ], natural_domain: "search", resolves_to: { kind: "tool", name: "pica_catalog_stats" }, }, // ───────────────────────────────────────────────────────────────── // Enrichment resolvers — flipped from vernacular_kind 'specialist' to // 'creator-entry' 2026-07-08. The founder asked "find more information // about this person / this song" in natural language and neither // resolver surfaced — the exact telemetry the ADR-226 Phase 4 deferral // was waiting for. natural_domain "enrichment" matches the CATEGORIES // bucket both tools belong to (discovery.ts). // ───────────────────────────────────────────────────────────────── { question: "find more information about this person", synonyms: [ "enrich this person", "look up this artist's identifiers", "pull their details from external sources", "find their ISNI", "look this artist up on wikidata", "update this person from external databases", ], natural_domain: "enrichment", resolves_to: { kind: "tool", name: "pica_resolve_person" }, }, { question: "find more information about this song", synonyms: [ "enrich this song", "look this song up in the MLC", "pull this track's metadata from external sources", "find this song's external identifiers", "check this song against musicbrainz", "update this work from spotify", ], natural_domain: "enrichment", resolves_to: { kind: "tool", name: "pica_resolve_work" }, }, // ───────────────────────────────────────────────────────────────── // WS3 Confident Recall (2026-07-09) — the one-call person-graph. // pica_people_inspect gained a `connections` section (works, recordings, // releases, agreements as {kind,id,name,via}); these entries make the // "everything connected to X" ask resolve there. natural_domain "people" // matches the CATEGORIES bucket pica_people_inspect belongs to. // ───────────────────────────────────────────────────────────────── { question: "everything connected to this person", synonyms: [ "what have I done with X?", "show me everything with this artist", "all works and recordings with X", "what's X been involved in?", "every song, recording and agreement with X", ], natural_domain: "people", resolves_to: { kind: "tool", name: "pica_people_inspect", default_args: { sections: ["connections"] }, }, }, ]; //# sourceMappingURL=creator-question-atlas.js.map