@withpica/mcp-server 1.3.0

package/dist/tools/works.js

@@ -0,0 +1,694 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+import { formatSuccess, formatStructuredList, withBillingGate, mapGapsToHints, pushSectionError, } from "@withpica/mcp-utils";
+import { buildCustodyHints } from "./custody-hints.js";
+import { computeWorkGapHints } from "./gap-hints.js";
+/**
+ * Canonical write-schema for `works`. Every property below must
+ * correspond to a real column on `public.works` — verified against
+ * `lib/db/database.types.ts`. Keep this list tight: reintroducing a
+ * phantom field is the exact regression ADR-174 Phase 2 exists to
+ * prevent. The HTTP route at `app/api/admin/works/[id]/route.ts`
+ * carries a broader allow-list that includes admin-UI-posted satellite
+ * fields; this list is the narrower MCP-agent contract.
+ */
+export const WORK_WRITE_PROPERTIES = {
+    title: {
+        type: "string",
+        description: "Work title",
+    },
+    work_type: {
+        type: "string",
+        description: "Type of work",
+        enum: ["song", "instrumental", "library", "demo", "sample"],
+    },
+    work_status: {
+        type: "string",
+        description: "Work status (state machine validates transitions — demo → unreleased → released, etc.)",
+        enum: ["demo", "unreleased", "released", "pitched", "placed", "archived"],
+    },
+    iswc: {
+        type: "string",
+        description: "International Standard Musical Work Code (composition)",
+    },
+    isrc: {
+        type: "string",
+        description: "International Standard Recording Code. Bridges publishing (works) and masters (recordings).",
+    },
+    tunecode: {
+        type: "string",
+        description: "PRS tunecode (e.g. 851348GT)",
+    },
+    prs_work_id: {
+        type: "string",
+        description: "PRS work ID",
+    },
+    spotify_track_uri: {
+        type: "string",
+        description: "Spotify track URI (e.g. spotify:track:0b8ZtRm9u3xSzRazABeHFF).",
+    },
+    duration_seconds: {
+        type: "number",
+        description: "Duration in seconds",
+    },
+    tempo: {
+        type: "number",
+        description: "BPM (beats per minute)",
+    },
+    key: {
+        type: "string",
+        description: "Musical key (e.g. 'C major', 'Am')",
+    },
+    genre: {
+        type: "array",
+        items: { type: "string" },
+        description: "Genre tags (e.g. ['R&B', 'Soul'])",
+    },
+    mood: {
+        type: "array",
+        items: { type: "string" },
+        description: "Mood tags (e.g. ['Uplifting', 'Reflective'])",
+    },
+    primary_artist: {
+        type: "string",
+        description: "Primary artist name (freetext display value)",
+    },
+    primary_artist_id: {
+        type: "string",
+        description: "Primary artist person ID (FK to people)",
+    },
+    display_artist: {
+        type: "string",
+        description: "Display-friendly artist string (e.g. 'Jane Doe ft. John Smith')",
+    },
+    publisher_name: {
+        type: "string",
+        description: "Publisher name (legacy freetext). Prefer linking via publisher identity where possible.",
+    },
+    lyrics: {
+        type: "string",
+        description: "Lyrics text",
+    },
+    lyrics_language: {
+        type: "string",
+        description: "Language of lyrics (ISO 639-1, e.g. 'en')",
+    },
+    published: {
+        type: "boolean",
+        description: "Whether the work is published on the public directory",
+    },
+    notes: {
+        type: "string",
+        description: "Internal notes",
+    },
+    // Declared jsonb extension points — ADR-174 Phase 2c inverse-phantom fix.
+    // These keys are not columns on public.works; the service routes them to
+    // the `work_licensing` satellite via extractSatelliteFields() (see
+    // lib/services/works/constants.ts WORK_SATELLITE_FIELDS). Same shape as
+    // the parallel fields on `pica_recordings_update` (recordings.ts:193).
+    ai_disclosure: {
+        type: "object",
+        description: "AI disclosure object (UK AI Copyright compliance). Fields: composition, performance, production, mastering ('none'|'assisted'|'generated'), tools_used (string[]), disclosure_date, disclosed_by.",
+    },
+    provenance_attestation: {
+        type: "object",
+        description: "Human creation proof. Fields: human_created (bool), attested_by, attested_at, attestation_method, supporting_evidence, ip_address, signature_hash, certificate_id.",
+    },
+    training_rights: {
+        type: "object",
+        description: "B2B ML licensing compliance object. Fields: available_for_training (bool), training_terms, minimum_fee, excluded_uses, permitted_uses, geographic_restrictions, requires_attribution, requires_notification, license_duration, updated_at, updated_by.",
+    },
+};
+export class WorksTools {
+    pica;
+    constructor(pica) {
+        this.pica = pica;
+    }
+    /**
+     * Get all works tools
+     */
+    getTools() {
+        return [
+            {
+                definition: {
+                    name: "pica_works_query",
+                    description: "Find works by any criteria — text search, verified status, or health filter. " +
+                        "→ then: pica_works_inspect (details for a specific work)",
+                    workflows: "infrastructure",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            query: {
+                                type: "string",
+                                description: "Search by title, ISWC, or artist name",
+                            },
+                            verified: {
+                                type: "boolean",
+                                description: "Filter by verification status",
+                            },
+                            health_filter: {
+                                type: "string",
+                                enum: ["needs_attention", "low_completeness"],
+                                description: "Filter by health status — needs_attention (missing credits, no ISWC) or low_completeness",
+                            },
+                            limit: {
+                                type: "number",
+                                description: "Max results (default: 50)",
+                            },
+                            offset: {
+                                type: "number",
+                                description: "Pagination offset",
+                            },
+                        },
+                    },
+                },
+                executor: this.queryWorks.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_works_inspect",
+                    description: "Get details and quality data for a specific work. Omit sections for everything. " +
+                        "Use sections=['enrichment'] to see cascade provenance (which source wrote each field), " +
+                        "completeness_score, completeness_breakdown, AND live enrichment-job statuses (spotify, mlc, acrcloud, audio analysis) " +
+                        "in one response. " +
+                        "→ then: pica_credits_update (fix credits), pica_resolve_work (fill identifiers + metadata), pica_run_work_cascade (retry)",
+                    workflows: "infrastructure",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            id: {
+                                type: "string",
+                                description: "Work ID",
+                            },
+                            sections: {
+                                type: "array",
+                                items: {
+                                    type: "string",
+                                    enum: [
+                                        "basic",
+                                        "credits",
+                                        "recordings",
+                                        "agreements",
+                                        "health",
+                                        "completeness",
+                                        "registration",
+                                        "score",
+                                        "provenance",
+                                        "enrichment",
+                                        "production_assets",
+                                        "releases",
+                                    ],
+                                },
+                                description: 'Which data sections to include. Omit for all sections. Use ["basic"] for lightweight lookup.',
+                            },
+                        },
+                        required: ["id"],
+                    },
+                    // ADR-199 — work status state machine mirrored from
+                    // lib/utils/state-machine.ts workStatusMachine. Build-step
+                    // assertion (Phase D) catches drift between this map and the
+                    // DB CHECK constraint on works.status.
+                    validTransitionsFrom: {
+                        demo: ["unreleased", "pitched", "archived"],
+                        unreleased: ["released", "pitched", "archived"],
+                        pitched: ["placed", "unreleased", "released", "archived"],
+                        placed: ["released", "archived"],
+                        released: ["archived"],
+                        archived: ["unreleased", "demo"],
+                    },
+                    nextSteps: [
+                        {
+                            tool: "pica_credits_update",
+                            reason: "Fix or fill writer/composer credits when the inspect surfaces gaps.",
+                            when: "on_success",
+                        },
+                        {
+                            tool: "pica_resolve_work",
+                            reason: "Fill identifier gaps (ISWC, ISRC) and metadata via the enrichment cascade.",
+                            when: "on_success",
+                        },
+                    ],
+                },
+                executor: this.inspectWork.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_works_create",
+                    description: "Create a new musical work. IMPORTANT: call pica_works_query first to check for duplicates — same-title works cause split and registration issues. " +
+                        "Album and release metadata (album_name, album_art_url, track_number, upc, spotify_url) live on `pica_releases_create/update`, not here. " +
+                        "For label metadata, set it on the release via pica_releases_*.label_organization_id (resolve the name via pica_labels_query first). " +
+                        "After several mutations, surface a pica_dashboard_briefing to the user. " +
+                        "→ before: pica_works_query (check duplicates) → then: pica_credits_update (add writers), pica_works_inspect (check gaps), pica_resolve_work (fill identifiers)",
+                    workflows: ["work-required"],
+                    inputSchema: {
+                        type: "object",
+                        properties: WORK_WRITE_PROPERTIES,
+                        required: ["title", "work_type"],
+                    },
+                    nextSteps: [
+                        {
+                            tool: "pica_credits_update",
+                            reason: "Add writer/composer credits to the new work — required before registration.",
+                            when: "on_success",
+                        },
+                        {
+                            tool: "pica_works_inspect",
+                            reason: "Read back the created work to confirm fields persisted and surface any gaps.",
+                            when: "on_success",
+                        },
+                    ],
+                },
+                executor: withBillingGate(this.pica, "work creation", this.createWork.bind(this)),
+            },
+            {
+                definition: {
+                    name: "pica_works_update",
+                    description: "Update an existing musical work. Only real `works` columns are accepted — " +
+                        "album and release metadata (album_name, album_art_url, track_number, upc, spotify_url) must go through pica_releases_create/update, not here. " +
+                        "Audio-trait satellite fields (energy, vocal_type, available_for_licensing, danceability) are not exposed through MCP; set them through a release or recording path. " +
+                        "Three jsonb compliance fields (ai_disclosure, provenance_attestation, training_rights) are satellite-routed to work_licensing and ARE set-able here. " +
+                        "→ then: pica_works_inspect (verify changes persisted)",
+                    workflows: ["work-required"],
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            id: {
+                                type: "string",
+                                description: "Work ID (required)",
+                            },
+                            ...WORK_WRITE_PROPERTIES,
+                        },
+                        required: ["id"],
+                    },
+                    nextSteps: [
+                        {
+                            tool: "pica_works_inspect",
+                            reason: "Read back the work after update to confirm every field round-tripped — silent persistence drops are real.",
+                            when: "on_success",
+                        },
+                    ],
+                },
+                executor: withBillingGate(this.pica, "work update", this.updateWork.bind(this)),
+            },
+            {
+                definition: {
+                    name: "pica_works_delete",
+                    description: "Delete a musical work",
+                    workflows: "infrastructure",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            id: {
+                                type: "string",
+                                description: "Work ID",
+                            },
+                        },
+                        required: ["id"],
+                    },
+                },
+                executor: withBillingGate(this.pica, "work deletion", this.deleteWork.bind(this)),
+            },
+            {
+                definition: {
+                    name: "pica_works_verify",
+                    description: "Mark a work as verified",
+                    workflows: "infrastructure",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            id: {
+                                type: "string",
+                                description: "Work ID",
+                            },
+                        },
+                        required: ["id"],
+                    },
+                },
+                executor: withBillingGate(this.pica, "work verification", this.verifyWork.bind(this)),
+            },
+            {
+                definition: {
+                    name: "pica_works_bulk_delete",
+                    description: "Delete multiple works at once",
+                    workflows: "infrastructure",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            ids: {
+                                type: "array",
+                                description: "Array of work IDs to delete",
+                                items: {
+                                    type: "string",
+                                },
+                            },
+                        },
+                        required: ["ids"],
+                    },
+                },
+                executor: withBillingGate(this.pica, "bulk work deletion", this.bulkDeleteWorks.bind(this)),
+            },
+        ];
+    }
+    /**
+     * Query works — unified search, list, and health filter
+     */
+    async queryWorks(args) {
+        const limit = args.limit || 50;
+        // Health filter routes to health/completeness APIs
+        if (args.health_filter === "needs_attention") {
+            const result = await this.pica.health.getWorksHealth();
+            const works = result?.works || result || [];
+            return formatStructuredList(Array.isArray(works) ? works : [works], "work", {
+                filter: "needs_attention",
+                total: Array.isArray(works) ? works.length : 1,
+            });
+        }
+        if (args.health_filter === "low_completeness") {
+            const result = await this.pica.health.getLowScoreWorks();
+            const works = Array.isArray(result) ? result : result?.works || [];
+            return formatStructuredList(works, "work", {
+                filter: "low_completeness",
+                total: works.length,
+            });
+        }
+        // Text search or list
+        if (args.query) {
+            const result = await this.pica.works.search({ query: args.query, limit });
+            let items = result.data || result;
+            if (!Array.isArray(items))
+                items = [];
+            return formatStructuredList(items, "work", {
+                query: args.query,
+                total: result.total || items.length,
+            });
+        }
+        // Default: list with filters
+        const result = await this.pica.works.search({ query: args.search, limit });
+        let items = result.data || result;
+        if (!Array.isArray(items))
+            items = [];
+        // Client-side verified filter
+        if (args.verified !== undefined) {
+            items = items.filter((work) => work.is_verified === args.verified);
+        }
+        return formatStructuredList(items, "work", {
+            total: result.total || items.length,
+            limit,
+            hasMore: result.hasMore,
+        });
+    }
+    /**
+     * Inspect work — unified detail view with selectable sections
+     */
+    async inspectWork(args) {
+        const sections = args.sections;
+        const allSections = !sections || sections.length === 0;
+        // ADR-201 closeout (2026-04-27): `health` and `score` are org-wide
+        // metrics that don't take a workId and cost ~25s and ~2s respectively
+        // on staging. Inspect-one-work shouldn't pay that — agents that want
+        // org-wide metrics call them explicitly. Keep them off the default
+        // `allSections` surface but still callable via explicit `sections`.
+        const ORG_WIDE_OPT_IN = new Set(["health", "score"]);
+        const has = (s) => allSections ? !ORG_WIDE_OPT_IN.has(s) : sections.includes(s);
+        const result = {};
+        const hints = [];
+        // ADR-224 — section-level failures push to errors[] and the host
+        // log pipeline (via pushSectionError) regardless of flag state.
+        // The flag controls whether the public response advertises errors[]
+        // and whether failed sections set the field to null vs the legacy
+        // empty-fallback. Default OFF in Phase 1; flips to default-on at
+        // Phase 4 after the soak window catches any caller depending on
+        // the empty-array shape.
+        const useStructured = process.env.ADR_224_STRUCTURED_ERRORS === "1";
+        const errors = [];
+        const TOOL_NAME = "pica_works_inspect";
+        // Basic — always fetched (either via entityContext.getWorkFull or works.get)
+        if (allSections) {
+            const full = await this.pica.entityContext.getWorkFull(args.id);
+            const data = full;
+            result.work = data?.work || data;
+            result.credits = data?.credits;
+            result.recordings = data?.recordings;
+            result.agreements = data?.agreements;
+        }
+        else if (has("basic")) {
+            const work = await this.pica.works.get(args.id);
+            result.work = work;
+            // Enrich with ISRC prefix intelligence if work has ISRC
+            if (work?.isrc) {
+                try {
+                    result.prefix_intel = await this.pica.recordings.prefixLookup(work.isrc);
+                }
+                catch {
+                    /* best-effort */
+                }
+            }
+        }
+        // ADR-201 closeout (2026-04-27): the section sub-calls used to run
+        // sequentially. With ~8 calls each taking ~1s and one (works-health)
+        // sometimes 25s+, the function would frequently exceed Vercel's 30s
+        // maxDuration on the default `allSections` path. Fan out everything
+        // in parallel — each branch still owns its own try/catch fallback so
+        // a single failing sub-call doesn't poison the whole inspect.
+        const sectionTasks = [];
+        // Targeted basic sections — only when caller listed them explicitly.
+        if (!allSections) {
+            if (has("credits") && !result.credits) {
+                sectionTasks.push((async () => {
+                    try {
+                        result.credits = await this.pica.credits.listForWork(args.id);
+                    }
+                    catch (e) {
+                        result.credits = useStructured ? null : [];
+                        pushSectionError(errors, TOOL_NAME, "credits", e, args.id);
+                    }
+                })());
+            }
+            if (has("recordings") && !result.recordings) {
+                sectionTasks.push((async () => {
+                    try {
+                        result.recordings = await this.pica.recordings.getByWork(args.id);
+                    }
+                    catch (e) {
+                        result.recordings = useStructured ? null : [];
+                        pushSectionError(errors, TOOL_NAME, "recordings", e, args.id);
+                    }
+                })());
+            }
+            if (has("agreements") && !result.agreements) {
+                sectionTasks.push((async () => {
+                    try {
+                        result.agreements = await this.pica.agreements.list();
+                    }
+                    catch (e) {
+                        result.agreements = useStructured ? null : [];
+                        pushSectionError(errors, TOOL_NAME, "agreements", e, args.id);
+                    }
+                })());
+            }
+        }
+        // Quality sections — fan out in parallel.
+        if (has("health")) {
+            sectionTasks.push((async () => {
+                try {
+                    result.health = await this.pica.health.getWorksHealth();
+                }
+                catch (e) {
+                    result.health = null;
+                    pushSectionError(errors, TOOL_NAME, "health", e, args.id);
+                }
+            })());
+        }
+        if (has("completeness")) {
+            sectionTasks.push((async () => {
+                try {
+                    const completeness = await this.pica.health.getWorkCompleteness(args.id);
+                    result.completeness = completeness;
+                    hints.push(...mapGapsToHints(completeness?.gaps || completeness?.missing || []));
+                }
+                catch (e) {
+                    result.completeness = null;
+                    pushSectionError(errors, TOOL_NAME, "completeness", e, args.id);
+                }
+            })());
+        }
+        if (has("registration")) {
+            sectionTasks.push((async () => {
+                try {
+                    result.registration =
+                        await this.pica.registration.getWorkCascadeStatus(args.id);
+                }
+                catch (e) {
+                    result.registration = null;
+                    pushSectionError(errors, TOOL_NAME, "registration", e, args.id);
+                }
+            })());
+        }
+        if (has("score")) {
+            sectionTasks.push((async () => {
+                try {
+                    result.score = await this.pica.picaScore.get();
+                }
+                catch (e) {
+                    result.score = null;
+                    pushSectionError(errors, TOOL_NAME, "score", e, args.id);
+                }
+            })());
+        }
+        if (has("provenance")) {
+            sectionTasks.push((async () => {
+                try {
+                    result.provenance = await this.pica.analytics.provenanceWork(args.id);
+                }
+                catch (e) {
+                    result.provenance = null;
+                    pushSectionError(errors, TOOL_NAME, "provenance", e, args.id);
+                }
+            })());
+        }
+        if (has("enrichment")) {
+            sectionTasks.push((async () => {
+                try {
+                    result.enrichment =
+                        await this.pica.enrichment.getWorkEnrichmentStatus(args.id);
+                }
+                catch (e) {
+                    result.enrichment = null;
+                    pushSectionError(errors, TOOL_NAME, "enrichment", e, args.id);
+                }
+            })());
+        }
+        // ADR-156 op #3 Session B Task 5 — surface linked physical assets
+        // so the inspect tool is discoverable from the work side.
+        if (has("production_assets")) {
+            sectionTasks.push((async () => {
+                try {
+                    result.production_assets =
+                        await this.pica.works.listProductionAssets(args.id);
+                }
+                catch (e) {
+                    result.production_assets = useStructured ? null : [];
+                    pushSectionError(errors, TOOL_NAME, "production_assets", e, args.id);
+                }
+            })());
+        }
+        // ADR-173 Decision 2 — every release this work appears on, with
+        // its track position. Distinct from the `recordings` section,
+        // which lists recordings regardless of release context.
+        if (has("releases")) {
+            sectionTasks.push((async () => {
+                try {
+                    result.releases = await this.pica.works.listReleases(args.id);
+                }
+                catch (e) {
+                    result.releases = useStructured ? null : [];
+                    pushSectionError(errors, TOOL_NAME, "releases", e, args.id);
+                }
+            })());
+        }
+        await Promise.all(sectionTasks);
+        // ADR-193 Surface 2 — proactive peer-MCP hints when the flag is on
+        // and a real gap exists. Additive on top of the CompletionHint path.
+        const gap_hints = computeWorkGapHints(result);
+        const withHints = gap_hints.length > 0 ? { ...result, gap_hints } : result;
+        // ADR-224 — append errors[] to the public response only when the
+        // structured-errors flag is on. In legacy mode, section failures are
+        // still pushed to the errors[] array (so stderr observability fires
+        // via pushSectionError) but the array is dropped from the response
+        // shape so the breaking change ([] → null on failed sections) doesn't
+        // ship until Phase 4's flip.
+        const enriched = useStructured ? { ...withHints, errors } : withHints;
+        return formatSuccess(`Work details${sections ? ` (sections: ${sections.join(", ")})` : ""}`, enriched, hints);
+    }
+    /**
+     * Create work
+     */
+    async createWork(args) {
+        const work = await this.pica.works.create(args);
+        // Generate completion hints for the newly created work
+        const hints = [];
+        if (work?.id) {
+            try {
+                const completeness = await this.pica.health.getWorkCompleteness(work.id);
+                hints.push(...mapGapsToHints(completeness?.gaps || completeness?.missing || []));
+            }
+            catch {
+                // Best-effort — don't fail the create
+            }
+            // Hint about AI disclosure if not set
+            if (!args.ai_disclosure) {
+                hints.push({
+                    gap: "no_ai_disclosure",
+                    suggestion: "Set AI disclosure — is this work human-made, AI-assisted, or AI-generated? (pica_works_update with ai_disclosure: none/assisted/generated)",
+                    severity: "important",
+                });
+            }
+        }
+        // ADR-158 Plan C Phase 2 — append custody-claim hints so every new work
+        // prompts the rights conversation by default.
+        hints.push(...buildCustodyHints(work));
+        return formatSuccess("Work created successfully", work, hints);
+    }
+    /**
+     * Update work
+     */
+    async updateWork(args) {
+        const { id, ...updates } = args;
+        const work = await this.pica.works.update(id, updates);
+        return formatSuccess("Work updated successfully", work);
+    }
+    /**
+     * Delete work
+     */
+    async deleteWork(args) {
+        await this.pica.works.delete(args.id);
+        return formatSuccess(`Work ${args.id} deleted successfully`);
+    }
+    /**
+     * Verify work
+     */
+    async verifyWork(args) {
+        const work = await this.pica.works.verify(args.id);
+        // ADR-146: Also check export readiness
+        let exportReadiness;
+        try {
+            const baseUrl = this.pica.works["baseUrl"];
+            const apiKey = this.pica.works["apiKey"];
+            const res = await fetch(`${baseUrl}/admin/export-readiness/${args.id}`, {
+                headers: {
+                    Authorization: `Bearer ${apiKey}`,
+                    "Content-Type": "application/json",
+                },
+            });
+            if (res.ok) {
+                const json = (await res.json());
+                exportReadiness = json.data ?? json;
+            }
+        }
+        catch {
+            // Readiness check is best-effort — don't fail verification
+        }
+        const summaryParts = ["Work verified successfully"];
+        if (exportReadiness) {
+            summaryParts.push(`Export readiness: ${exportReadiness.ready ? "ready" : "not ready"}`, `Evidence: ${exportReadiness.evidenceStrength}`, `Attestation: ${exportReadiness.attestationCoverage}%`);
+            if (Array.isArray(exportReadiness.blockers) &&
+                exportReadiness.blockers.length > 0) {
+                summaryParts.push(`Blockers (${exportReadiness.blockers.length}):`);
+                for (const b of exportReadiness.blockers) {
+                    summaryParts.push(`  ${b.type}: ${b.resolutionHint}`);
+                }
+            }
+        }
+        return formatSuccess(summaryParts.join("\n"), {
+            ...work,
+            exportReadiness,
+        });
+    }
+    /**
+     * Bulk delete works
+     */
+    async bulkDeleteWorks(args) {
+        await this.pica.works.bulkDelete(args.ids);
+        return formatSuccess(`${args.ids.length} works deleted successfully`);
+    }
+}
+//# sourceMappingURL=works.js.map