@withpica/mcp-server 2.102.0 → 2.104.0

package/dist/tools/work-themes.js

@@ -0,0 +1,330 @@
+// Copyright (c) 2025-2026 Withpica Ltd. All rights reserved.
+import { formatSuccess } from "@withpica/mcp-utils";
+/** Mirrors lib/services/directory/themes.ts THEME_VOCABULARY (parity test). */
+export const THEME_VOCABULARY = [
+    "love",
+    "heartbreak",
+    "longing",
+    "desire",
+    "friendship",
+    "family",
+    "home",
+    "nostalgia",
+    "loss",
+    "loneliness",
+    "hope",
+    "faith",
+    "worship",
+    "gratitude",
+    "joy",
+    "celebration",
+    "freedom",
+    "empowerment",
+    "resilience",
+    "struggle",
+    "rebellion",
+    "identity",
+    "ambition",
+    "money",
+    "peace",
+    "nature",
+    "night",
+    "city",
+    "travel",
+    "summer",
+];
+/** Mirrors lib/services/mood-derivation.ts MOOD_VOCABULARY (parity test). */
+export const MOOD_VOCABULARY = [
+    "aggressive",
+    "ambient",
+    "calm",
+    "contemplative",
+    "dark",
+    "dramatic",
+    "dreamy",
+    "energetic",
+    "epic",
+    "ethereal",
+    "hopeful",
+    "intense",
+    "melancholic",
+    "nostalgic",
+    "passionate",
+    "playful",
+    "romantic",
+    "sad",
+    "tender",
+    "tense",
+    "triumphant",
+    "uplifting",
+    "warm",
+];
+function stateText(s) {
+    const list = (xs) => xs.length > 0 ? xs.map((x) => x.theme).join(", ") : "none";
+    const lines = [
+        `${s.title}: topics ${s.themes_enabled ? "on" : "switched off"}, lyrics shown publicly as: ${s.lyrics_visibility}.`,
+        `Approved topics: ${list(s.approved)}.`,
+        `Awaiting the owner's review: ${list(s.proposed)}.`,
+    ];
+    if (s.proposed_moods.length > 0) {
+        lines.push(`Moods awaiting review: ${s.proposed_moods
+            .map((m) => `${m.moods.join(", ")} (recording ${m.recording_id})`)
+            .join("; ")}.`);
+    }
+    if (!s.has_lyrics)
+        lines.push("This song has no lyrics in PICA.");
+    return lines.join("\n");
+}
+export class WorkThemesTools {
+    pica;
+    constructor(pica) {
+        this.pica = pica;
+    }
+    getTools() {
+        return [
+            {
+                definition: {
+                    name: "pica_topics_untagged",
+                    scope: "read:catalog",
+                    audiences: ["stdio", "http", "public"],
+                    tier: "read",
+                    description: "Songs in this catalogue that are listed in the public directory and have lyrics in PICA, " +
+                        'but no approved topic yet, so people searching the directory by topic ("a song about love") ' +
+                        "cannot find them. Use when the user asks: 'which of my songs need topics?', " +
+                        "'tag my songs for the directory'. Returns each song's id and title and how many proposed " +
+                        "topics already await review. Never returns lyrics. " +
+                        "→ then: pica_topics_inspect (one song) → pica_topics_propose",
+                    workflows: "infrastructure",
+                    vernacular_kind: "creator-entry",
+                    inputSchema: { type: "object", properties: {} },
+                    annotations: { readOnlyHint: true },
+                },
+                executor: this.untagged.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_topics_inspect",
+                    scope: "read:catalog",
+                    audiences: ["stdio", "http", "public"],
+                    tier: "read",
+                    description: "One song's directory topics: those approved (public when the song is listed), those " +
+                        "awaiting the owner's review, moods proposed for its recordings, whether topics are " +
+                        "switched on, and how much of the lyrics the public directory may show. Use when the user " +
+                        "asks: 'what topics does this song have?', 'what's waiting for my approval?'. Only for " +
+                        "songs this catalogue owns. Does not return the lyrics: read them with pica_works_inspect. " +
+                        "→ then: pica_topics_review (approve or change)",
+                    workflows: "infrastructure",
+                    vernacular_kind: "creator-entry",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            work_id: {
+                                type: "string",
+                                description: "The song's id (from pica_works_query).",
+                            },
+                        },
+                        required: ["work_id"],
+                    },
+                    annotations: { readOnlyHint: true },
+                },
+                executor: this.inspect.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_topics_propose",
+                    scope: "write:catalog",
+                    audiences: ["stdio", "http", "public"],
+                    tier: "draft",
+                    description: "Propose the topics a song is about (up to 5, from a fixed list) and moods for its " +
+                        "recordings, for the owner to review. Nothing becomes public: proposals wait until " +
+                        "pica_topics_review approves them. Use when the user asks: 'suggest topics for my " +
+                        "songs', 'tag this song'. Base topics on what the owner's lyrics are actually about (read " +
+                        "them with pica_works_inspect), and moods on how the recording sounds (tempo, key, mode, " +
+                        "energy); never invent a topic outside the list. A new proposal replaces the song's earlier " +
+                        "pending one; approved topics are kept. Only for songs this catalogue owns. " +
+                        "→ first: pica_topics_untagged (which songs) → then: show the proposal to the user, " +
+                        "and pica_topics_review once they decide",
+                    workflows: "infrastructure",
+                    vernacular_kind: "creator-entry",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            work_id: {
+                                type: "string",
+                                description: "The song's id (from pica_works_query).",
+                            },
+                            themes: {
+                                type: "array",
+                                items: { type: "string", enum: [...THEME_VOCABULARY] },
+                                maxItems: 5,
+                                description: "Topics the lyrics are about, most central first. Leave out or empty if none fit.",
+                            },
+                            moods: {
+                                type: "array",
+                                description: "Moods per recording of this song (recording ids from pica_works_inspect).",
+                                items: {
+                                    type: "object",
+                                    properties: {
+                                        recording_id: {
+                                            type: "string",
+                                            description: "A recording of this song.",
+                                        },
+                                        moods: {
+                                            type: "array",
+                                            items: { type: "string", enum: [...MOOD_VOCABULARY] },
+                                            description: "How the recording sounds.",
+                                        },
+                                    },
+                                    required: ["recording_id", "moods"],
+                                },
+                            },
+                        },
+                        required: ["work_id"],
+                    },
+                    annotations: {
+                        readOnlyHint: false,
+                        destructiveHint: false,
+                        idempotentHint: true,
+                        openWorldHint: false,
+                    },
+                },
+                executor: this.propose.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_topics_review",
+                    scope: "write:catalog",
+                    audiences: ["stdio", "http", "public"],
+                    tier: "write",
+                    description: "The owner's decision on a song's topics. Approve proposed topics (one by one or all), " +
+                        "reject topics, approve or discard proposed moods, set the approved topics directly, switch " +
+                        "topics off for the song, or choose how much of the lyrics the public directory may show " +
+                        "(themes only, a snippet, or the full lyrics). Approved topics become public on listed " +
+                        "songs; approved moods are saved on the recording. Use when the user asks: 'approve those " +
+                        "topics', 'drop heartbreak and keep the rest'. ONLY call after the owner has said yes to " +
+                        "exactly this: never approve on their behalf. Only for songs this catalogue owns. " +
+                        "→ first: pica_topics_inspect (see what awaits review)",
+                    workflows: "infrastructure",
+                    vernacular_kind: "creator-entry",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            work_id: {
+                                type: "string",
+                                description: "The song's id.",
+                            },
+                            approve: {
+                                type: "array",
+                                items: { type: "string", enum: [...THEME_VOCABULARY] },
+                                description: "Proposed topics to approve.",
+                            },
+                            approve_all: {
+                                type: "boolean",
+                                description: "true approves every topic awaiting review.",
+                            },
+                            reject: {
+                                type: "array",
+                                items: { type: "string", enum: [...THEME_VOCABULARY] },
+                                description: "Topics to remove, proposed or approved.",
+                            },
+                            set_themes: {
+                                type: "array",
+                                items: { type: "string", enum: [...THEME_VOCABULARY] },
+                                maxItems: 5,
+                                description: "Make exactly these the song's approved topics. Approved topics left out are removed; other suggestions awaiting review are kept.",
+                            },
+                            approve_moods_for: {
+                                type: "array",
+                                items: { type: "string" },
+                                description: "Recording ids whose proposed moods to save.",
+                            },
+                            approve_all_moods: {
+                                type: "boolean",
+                                description: "true saves every proposed mood on this song.",
+                            },
+                            reject_moods_for: {
+                                type: "array",
+                                items: { type: "string" },
+                                description: "Recording ids whose proposed moods to discard.",
+                            },
+                            themes_enabled: {
+                                type: "boolean",
+                                description: "false hides this song's topics from the directory and from topic search.",
+                            },
+                            lyrics_visibility: {
+                                type: "string",
+                                enum: ["themes", "snippet", "full"],
+                                description: "How much of the lyrics the public directory may show. Default themes (topics only).",
+                            },
+                        },
+                        required: ["work_id"],
+                    },
+                    annotations: {
+                        readOnlyHint: false,
+                        destructiveHint: false,
+                        idempotentHint: true,
+                        openWorldHint: false,
+                    },
+                },
+                executor: this.review.bind(this),
+            },
+        ];
+    }
+    async untagged() {
+        const result = await this.pica.directory.untaggedThemes();
+        const songs = result?.songs ?? [];
+        const text = songs.length === 0
+            ? "Every listed song with lyrics has a topic (or none have lyrics in PICA)."
+            : `${songs.length} listed song${songs.length === 1 ? "" : "s"} with lyrics but no topic yet:\n` +
+                songs
+                    .map((s) => `- ${s.title} (${s.work_id})${s.pending_proposals > 0 ? `, ${s.pending_proposals} proposed awaiting review` : ""}`)
+                    .join("\n");
+        return formatSuccess(text, { count: songs.length, songs });
+    }
+    async inspect(args) {
+        const state = await this.pica.works.getThemes(String(args.work_id));
+        return formatSuccess(stateText(state), state);
+    }
+    async propose(args) {
+        const state = await this.pica.works.proposeThemes(String(args.work_id), {
+            themes: args.themes,
+            moods: args.moods,
+        });
+        return formatSuccess(`Proposed, not public. Show the owner and ask before approving.\n${stateText(state)}`, state);
+    }
+    async review(args) {
+        const workId = String(args.work_id);
+        let state = null;
+        if (args.approve !== undefined ||
+            args.approve_all === true ||
+            args.reject !== undefined ||
+            args.approve_moods_for !== undefined ||
+            args.approve_all_moods === true ||
+            args.reject_moods_for !== undefined) {
+            state = await this.pica.works.reviewThemes(workId, {
+                approve: args.approve_all === true
+                    ? "all"
+                    : args.approve,
+                reject: args.reject,
+                approve_moods_for: args.approve_all_moods === true
+                    ? "all"
+                    : args.approve_moods_for,
+                reject_moods_for: args.reject_moods_for,
+            });
+        }
+        if (args.set_themes !== undefined ||
+            args.themes_enabled !== undefined ||
+            args.lyrics_visibility !== undefined) {
+            state = await this.pica.works.setThemes(workId, {
+                themes: args.set_themes,
+                themes_enabled: args.themes_enabled,
+                lyrics_visibility: args.lyrics_visibility,
+            });
+        }
+        if (!state) {
+            return formatSuccess("Nothing to change: pass approve, reject, set_themes, the mood fields, themes_enabled or lyrics_visibility.", {});
+        }
+        return formatSuccess(`Saved.\n${stateText(state)}`, state);
+    }
+}
+//# sourceMappingURL=work-themes.js.map

package/dist/tools/work-themes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"work-themes.js","sourceRoot":"","sources":["../../src/tools/work-themes.ts"],"names":[],"mappings":"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"}

package/dist/tools/works.d.ts

@@ -53,6 +53,17 @@ export declare class WorksTools {
      * when nothing matches, so inspect surfaces a hard not-found (ADR-198).
      */
     private resolveWorkIdByIswc;
+    /**
+     * pica_works_inspect in a CLIENT's catalogue (ADR-333 PR 1.3). Only the
+     * song's own record opens through a relationship (GET /api/admin/works/:id,
+     * in the safe shape — lib/auth/catalogue-routes.ts); every other section's
+     * route is refused there. So: no sections asked → the record, saying what
+     * is not available; a section asked that is not available → refused,
+     * naming it. Never the all-sections path, which fails each refused section
+     * soft and would answer "success" about a song it never read (D2 Gate 2,
+     * holdout run 38435148161).
+     */
+    private inspectWorkInClientCatalogue;
     private inspectWork;
     /**
      * Create work

package/dist/tools/works.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"works.d.ts","sourceRoot":"","sources":["../../src/tools/works.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAEL,UAAU,EAGX,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,cAAc,EAAE,YAAY,EAAc,MAAM,YAAY,CAAC;AAiCtE;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAkKzE,CAAC;AAiDF,qBAAa,UAAU;IACrB,OAAO,CAAC,IAAI,CAAa;gBAEb,IAAI,EAAE,UAAU;IAI5B;;OAEG;IACH,QAAQ,IAAI,KAAK,CAAC;QAAE,UAAU,EAAE,cAAc,CAAC;QAAC,QAAQ,EAAE,YAAY,CAAA;KAAE,CAAC;IA2vBzE;;OAEG;YACW,UAAU;IA+LxB;;OAEG;IACH;;;;;OAKG;YACW,mBAAmB;YAmBnB,WAAW;IAuazB;;OAEG;YACW,UAAU;IAgHxB;;OAEG;YACW,UAAU;IA2CxB;;OAEG;YACW,UAAU;IAKxB;;;;;;;;;;OAUG;YACW,UAAU;IAiBxB;;OAEG;YACW,eAAe;IAe7B;;OAEG;YACW,sBAAsB;IAqBpC;;;;OAIG;YACW,UAAU;YAsCV,mBAAmB;CA6DlC"}
+{"version":3,"file":"works.d.ts","sourceRoot":"","sources":["../../src/tools/works.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAEL,UAAU,EAIX,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,cAAc,EAAE,YAAY,EAAc,MAAM,YAAY,CAAC;AAqCtE;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAkKzE,CAAC;AAyDF,qBAAa,UAAU;IACrB,OAAO,CAAC,IAAI,CAAa;gBAEb,IAAI,EAAE,UAAU;IAI5B;;OAEG;IACH,QAAQ,IAAI,KAAK,CAAC;QAAE,UAAU,EAAE,cAAc,CAAC;QAAC,QAAQ,EAAE,YAAY,CAAA;KAAE,CAAC;IA4vBzE;;OAEG;YACW,UAAU;IA+LxB;;OAEG;IACH;;;;;OAKG;YACW,mBAAmB;IAmBjC;;;;;;;;;OASG;YACW,4BAA4B;YAmC5B,WAAW;IA0azB;;OAEG;YACW,UAAU;IAgHxB;;OAEG;YACW,UAAU;IA6DxB;;OAEG;YACW,UAAU;IAKxB;;;;;;;;;;OAUG;YACW,UAAU;IAiBxB;;OAEG;YACW,eAAe;IAe7B;;OAEG;YACW,sBAAsB;IAqBpC;;;;OAIG;YACW,UAAU;YAsCV,mBAAmB;CA6DlC"}

package/dist/tools/works.js

@@ -18,7 +18,8 @@
  * or `pica_releases_update` with `label_organization_id`, resolving
  * the name via `pica_labels_query` first.
  */
-import { ApiError, EntityNotFoundError, } from "@withpica/mcp-sdk";
+import { ApiError, EntityNotFoundError, currentCatalogue, } from "@withpica/mcp-sdk";
+import { formatProposedChange, readChangeOutcome, } from "./relationship-change.js";
 import { formatSuccess, formatDeletion, formatStructuredList, withBillingGate, buildDecision, mapGapsToHints, pushSectionError, } from "@withpica/mcp-utils";
 import { buildCustodyHints } from "./custody-hints.js";
 import { typedError } from "./error-envelope.js";
@@ -227,6 +228,13 @@ function summariseDossier(dossier) {
  */
 const WORKS_HEALTH_MAX_PAGE = 50;
 const LOW_COMPLETENESS_MAX_PAGE = 200;
+/**
+ * The pica_works_inspect sections whose route opens through a relationship.
+ * A hand-kept mirror of lib/auth/catalogue-routes.ts CATALOGUE_ROUTES (only
+ * GET /api/admin/works/:id there serves a single song's sections): opening
+ * another works sub-route there means adding its section here.
+ */
+const CLIENT_CATALOGUE_WORK_SECTIONS = ["basic"];
 export class WorksTools {
     pica;
     constructor(pica) {
@@ -409,6 +417,8 @@ export class WorksTools {
                             },
                             limit: {
                                 type: "number",
+                                minimum: 1,
+                                maximum: 100,
                                 description: "Max results (default: 50)",
                             },
                             offset: {
@@ -813,7 +823,6 @@ export class WorksTools {
                         required: ["work_ids", "mode"],
                     },
                     annotations: {
-                        title: "verify work registrations",
                         readOnlyHint: false,
                         destructiveHint: false,
                         idempotentHint: true,
@@ -1083,6 +1092,41 @@ export class WorksTools {
         }
         return match.id;
     }
+    /**
+     * pica_works_inspect in a CLIENT's catalogue (ADR-333 PR 1.3). Only the
+     * song's own record opens through a relationship (GET /api/admin/works/:id,
+     * in the safe shape — lib/auth/catalogue-routes.ts); every other section's
+     * route is refused there. So: no sections asked → the record, saying what
+     * is not available; a section asked that is not available → refused,
+     * naming it. Never the all-sections path, which fails each refused section
+     * soft and would answer "success" about a song it never read (D2 Gate 2,
+     * holdout run 38435148161).
+     */
+    async inspectWorkInClientCatalogue(workId, sections) {
+        const unavailable = (sections ?? []).filter((s) => !CLIENT_CATALOGUE_WORK_SECTIONS.includes(s));
+        if (unavailable.length > 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: "CATALOGUE_SECTION_NOT_AVAILABLE",
+                            message: `In a client's catalogue only ${CLIENT_CATALOGUE_WORK_SECTIONS.join(", ")} can be read; not ${unavailable.join(", ")}.`,
+                            available_sections: CLIENT_CATALOGUE_WORK_SECTIONS,
+                        }, null, 2),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        // Refused (out of scope, ended) → thrown, and answered as an error.
+        const work = await this.pica.works.get(workId);
+        return formatSuccess("Work details", {
+            work,
+            available_sections: CLIENT_CATALOGUE_WORK_SECTIONS,
+            note: "in a client's catalogue only the song's own record can be read through the relationship",
+        });
+    }
     async inspectWork(args) {
         // Accept work_id as an alias for id — write tools use work_id, so agents
         // doing read-after-write naturally pass work_id here. Without this alias
@@ -1103,6 +1147,8 @@ export class WorksTools {
             };
         }
         const sections = args.sections;
+        if (currentCatalogue() !== undefined)
+            return this.inspectWorkInClientCatalogue(workId, sections);
         const allSections = !sections || sections.length === 0;
         // Sections kept OFF the default `allSections` surface but still callable
         // via explicit `sections`:
@@ -1239,7 +1285,8 @@ export class WorksTools {
             if (has("agreements") && !result.agreements) {
                 sectionTasks.push((async () => {
                     try {
-                        result.agreements = await this.pica.agreements.list();
+                        // This work's agreements — not the org's first page of them.
+                        result.agreements = await this.pica.works.getAgreements(workId);
                     }
                     catch (e) {
                         result.agreements = useStructured ? null : [];
@@ -1567,13 +1614,28 @@ export class WorksTools {
     async updateWork(args) {
         const { verbose, rest } = takeVerbose(args);
         const { id, ...updates } = rest;
+        // In a client's catalogue the integrity reads are not opened through the
+        // relationship (lib/auth/catalogue-routes.ts): skip them rather than have
+        // each one refused.
+        const inClientCatalogue = currentCatalogue() !== undefined;
         // Compact receipt (ops 61ce1dcc): read the gaps open BEFORE the write so
         // the answer can name only the ones this write opened. Skipped when the
         // caller asked for the full record, which repeats every gap anyway.
-        const before = verbose
+        const before = verbose || inClientCatalogue
             ? null
             : await buildIntegrityPressure(this.pica, "work", id);
-        const work = await this.pica.works.update(id, updates);
+        const outcome = readChangeOutcome(await this.pica.works.update(id, updates));
+        if (outcome.kind === "proposed")
+            return formatProposedChange("work", id, Object.keys(updates), outcome);
+        const work = outcome.record;
+        if (inClientCatalogue) {
+            const { changed, unconfirmed } = changedFields(updates, work);
+            return formatSuccess("Work updated successfully", {
+                id: work?.id ?? id,
+                changed,
+                ...(unconfirmed.length > 0 ? { unconfirmed } : {}),
+            });
+        }
         // Registration integrity floor (Task 9) — same pressure rendering as
         // createWork, so an update that clears (or introduces) a gap keeps the
         // agent informed without a separate inspect round-trip.