@withpica/mcp-server 2.7.0 → 2.9.0

package/dist/tools/comparisons.js

@@ -0,0 +1,78 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+import { formatSuccess } from "@withpica/mcp-utils";
+export class ComparisonTools {
+    pica;
+    constructor(pica) {
+        this.pica = pica;
+    }
+    getTools() {
+        return [
+            {
+                definition: {
+                    name: "pica_enrichment_compare",
+                    description: "Compare enrichment source data vs catalog for a work or person. " +
+                        "Returns a side-by-side comparison showing what each source (MusicBrainz, MLC, Spotify, " +
+                        "YouTube, Discogs, ISNI) has vs what's in the catalog, with match status and suggested actions. " +
+                        "Use this to identify gaps, discrepancies, and enrichment opportunities.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            entity_type: {
+                                type: "string",
+                                description: "Type of entity to compare",
+                                enum: ["work", "person"],
+                            },
+                            entity_id: {
+                                type: "string",
+                                description: "Work ID or Person ID",
+                            },
+                        },
+                        required: ["entity_type", "entity_id"],
+                    },
+                },
+                executor: this.enrichmentCompare.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_registrations_compare",
+                    description: "Compare registration status across PROs (PRS, MCPS, PPL, VPL) for a work. " +
+                        "Returns which PROs the work is registered with, registration dates/IDs, and " +
+                        "suggested actions for missing registrations. Also identifies cascade opportunities " +
+                        "(e.g. ISRC available → PPL registration is ready).",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            work_id: {
+                                type: "string",
+                                description: "Work ID to check registrations for",
+                            },
+                        },
+                        required: ["work_id"],
+                    },
+                },
+                executor: this.registrationsCompare.bind(this),
+            },
+        ];
+    }
+    async enrichmentCompare(args) {
+        const result = await this.pica.comparisons.enrichmentCompare({
+            entityType: args.entity_type,
+            entityId: args.entity_id,
+        });
+        // SDK request() unwraps data.data, so result is the inner object directly
+        const data = result;
+        const fieldCount = data.fields?.length || 0;
+        const fieldsWithValue = data.fields?.filter((f) => f.currentValue != null).length || 0;
+        const actionCount = data.suggestedActions?.length || 0;
+        return formatSuccess(`Enrichment comparison for "${data.title}": ${fieldsWithValue}/${fieldCount} fields populated. ${actionCount} suggested action${actionCount !== 1 ? "s" : ""}.`, result);
+    }
+    async registrationsCompare(args) {
+        const result = await this.pica.comparisons.registrationsCompare(args.work_id);
+        const data = result;
+        const registeredCount = data.registrations?.filter((r) => r.registered === true).length || 0;
+        const totalPros = data.registrations?.length || 0;
+        const actionCount = data.suggestedActions?.length || 0;
+        return formatSuccess(`Registration status for "${data.title}": ${registeredCount}/${totalPros} PROs registered. ${actionCount} suggested action${actionCount !== 1 ? "s" : ""}.`, result);
+    }
+}
+//# sourceMappingURL=comparisons.js.map

package/dist/tools/comparisons.js.map

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

package/dist/tools/credits.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Credits Tools - MCP tools for managing work credits (collaborators and splits)
+ */
+import { PicaClient } from "@withpica/mcp-sdk";
+import { ToolDefinition, ToolExecutor } from "./index.js";
+export declare class CreditsTools {
+    private pica;
+    constructor(pica: PicaClient);
+    getTools(): Array<{
+        definition: ToolDefinition;
+        executor: ToolExecutor;
+    }>;
+    private getBalance;
+    private listCredits;
+    private updateCredits;
+}
+//# sourceMappingURL=credits.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"credits.d.ts","sourceRoot":"","sources":["../../src/tools/credits.ts"],"names":[],"mappings":"AAEA;;GAEG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,YAAY,EAAc,MAAM,YAAY,CAAC;AActE,qBAAa,YAAY;IACvB,OAAO,CAAC,IAAI,CAAa;gBAEb,IAAI,EAAE,UAAU;IAI5B,QAAQ,IAAI,KAAK,CAAC;QAAE,UAAU,EAAE,cAAc,CAAC;QAAC,QAAQ,EAAE,YAAY,CAAA;KAAE,CAAC;YA4I3D,UAAU;YAeV,WAAW;YA2BX,aAAa;CA+L5B"}

package/dist/tools/credits.js

@@ -0,0 +1,312 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+import { formatSuccess, formatStructuredList, mapGapsToHints, } from "@withpica/mcp-utils";
+import { notifyParties, summarizeNotifications, } from "@withpica/mcp-utils";
+export class CreditsTools {
+    pica;
+    constructor(pica) {
+        this.pica = pica;
+    }
+    getTools() {
+        return [
+            {
+                definition: {
+                    name: "pica_credits_balance",
+                    description: "Check your current credit balance and see what each operation costs. " +
+                        "Use this before triggering audio analysis or identification to check affordability. If balance is low, use pica_credits_purchase to generate a checkout link.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {},
+                    },
+                },
+                executor: this.getBalance.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_credits_list",
+                    description: "Get all credits (collaborators, roles, and splits) for a specific work. Returns who wrote, composed, arranged, or produced the work and their percentage splits. " +
+                        "→ then: pica_credits_update (fix credits), pica_people_inspect (inspect a credited person)",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            work_id: {
+                                type: "string",
+                                description: "The work ID to get credits for",
+                            },
+                        },
+                        required: ["work_id"],
+                    },
+                },
+                executor: this.listCredits.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_credits_update",
+                    description: "Set credits on a work. Replaces all existing credits. Splits must total 100%. " +
+                        "15 roles: writer, composer, arranger, lyricist, producer, performer, engineer, mixer, mastering, owner, vocalist, instrumentalist, conductor, programmer, remixer. " +
+                        "Supports publisher fields (publisher_name, publisher_ipi, publisher_split_percentage) and territory/rights metadata. " +
+                        "IMPORTANT: After updating, call pica_credits_list to verify the credits actually persisted — silent failures are possible if roles are invalid. " +
+                        "→ then: pica_credits_list (verify saved), pica_works_inspect (check progress)",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            work_id: {
+                                type: "string",
+                                description: "The work ID to set credits on",
+                            },
+                            credits: {
+                                type: "array",
+                                description: "Array of credit entries. Splits must total 100%.",
+                                items: {
+                                    type: "object",
+                                    properties: {
+                                        person_id: {
+                                            type: "string",
+                                            description: "Person ID of the credited collaborator",
+                                        },
+                                        role: {
+                                            type: "string",
+                                            description: "Role: writer, composer, arranger, lyricist, producer, performer, engineer, mixer, mastering, owner, vocalist, instrumentalist, conductor, programmer, remixer",
+                                            enum: [
+                                                "writer",
+                                                "composer",
+                                                "arranger",
+                                                "lyricist",
+                                                "producer",
+                                                "performer",
+                                                "engineer",
+                                                "mixer",
+                                                "mastering",
+                                                "owner",
+                                                "vocalist",
+                                                "instrumentalist",
+                                                "conductor",
+                                                "programmer",
+                                                "remixer",
+                                            ],
+                                        },
+                                        splits: {
+                                            type: "number",
+                                            description: "Percentage split (0-100). All splits must total 100%.",
+                                        },
+                                        publisher_name: {
+                                            type: "string",
+                                            description: "Publisher name for this credit (optional — for publishing credits)",
+                                        },
+                                        publisher_ipi: {
+                                            type: "string",
+                                            description: "Publisher's IPI number (9-11 digits)",
+                                        },
+                                        publisher_split_percentage: {
+                                            type: "number",
+                                            description: "Publisher's share percentage (0-100). Separate from writer split.",
+                                        },
+                                        territory: {
+                                            type: "array",
+                                            items: { type: "string" },
+                                            description: 'Territories where this credit applies (e.g., ["worldwide"], ["UK", "US"]). Default: ["worldwide"].',
+                                        },
+                                        rights_type: {
+                                            type: "string",
+                                            enum: [
+                                                "all",
+                                                "performing",
+                                                "mechanical",
+                                                "synchronization",
+                                            ],
+                                            description: "Type of rights covered. Default: all.",
+                                        },
+                                        start_date: {
+                                            type: "string",
+                                            description: "When rights start (ISO date). Null = from inception.",
+                                        },
+                                        end_date: {
+                                            type: "string",
+                                            description: "When rights end (ISO date). Null = perpetual.",
+                                        },
+                                    },
+                                    required: ["person_id", "role", "splits"],
+                                },
+                            },
+                        },
+                        required: ["work_id", "credits"],
+                    },
+                },
+                executor: this.updateCredits.bind(this),
+            },
+        ];
+    }
+    async getBalance(_args) {
+        const result = await this.pica.creditsBalance.getBalance();
+        const balance = result.balance ?? 0;
+        const costs = result.credit_costs ?? [];
+        const costSummary = costs
+            .map((c) => `${c.action_key}: ${c.credits_required} credit(s)`)
+            .join(", ");
+        return formatSuccess(`Credit balance: ${balance}. Operations: ${costSummary}`, result);
+    }
+    async listCredits(args) {
+        // Fetch both publishing collaborators and recording credits
+        const [collabSettled, creditsSettled] = await Promise.allSettled([
+            this.pica.credits.listCollaborators(args.work_id),
+            this.pica.credits.listForWork(args.work_id),
+        ]);
+        const collaborators = collabSettled.status === "fulfilled"
+            ? collabSettled.value
+            : { collaborators: [], count: 0 };
+        const recordingCredits = creditsSettled.status === "fulfilled" ? creditsSettled.value : [];
+        // Merge both into a single list
+        const collabArray = Array.isArray(collaborators)
+            ? collaborators
+            : collaborators?.collaborators || [];
+        const creditArray = Array.isArray(recordingCredits)
+            ? recordingCredits
+            : recordingCredits?.credits || [];
+        const allCredits = [...collabArray, ...creditArray];
+        return formatStructuredList(allCredits, "credit", {
+            work_id: args.work_id,
+        });
+    }
+    async updateCredits(args) {
+        // Validate splits total 100% before saving
+        const splitTotal = args.credits.reduce((sum, c) => sum + (c.splits || 0), 0);
+        if (splitTotal !== 100) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Splits total ${splitTotal}%, must be exactly 100%. Adjust the splits and try again.`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        // Split credits by role type: publishing roles → /collaborators, recording roles → /credits
+        const PUBLISHING_ROLES = new Set([
+            "writer",
+            "composer",
+            "lyricist",
+            "arranger",
+        ]);
+        const allCredits = args.credits.map((c) => {
+            const credit = {
+                person_id: c.person_id,
+                role: c.role,
+                splits: c.splits || 0,
+            };
+            if (c.publisher_name)
+                credit.publisher_name = c.publisher_name;
+            if (c.publisher_ipi)
+                credit.publisher_ipi = c.publisher_ipi;
+            if (c.publisher_split_percentage !== undefined)
+                credit.publisher_split_percentage = c.publisher_split_percentage;
+            if (c.territory)
+                credit.territory = c.territory;
+            if (c.rights_type)
+                credit.rights_type = c.rights_type;
+            if (c.start_date)
+                credit.start_date = c.start_date;
+            if (c.end_date)
+                credit.end_date = c.end_date;
+            return credit;
+        });
+        const publishingCredits = allCredits.filter((c) => PUBLISHING_ROLES.has(String(c.role || "writer")
+            .split(", ")[0]
+            .trim()));
+        const recordingCredits = allCredits.filter((c) => !PUBLISHING_ROLES.has(String(c.role || "writer")
+            .split(", ")[0]
+            .trim()));
+        let credits;
+        // Route to correct endpoint(s)
+        if (publishingCredits.length > 0 && recordingCredits.length > 0) {
+            // Mixed — call both endpoints, use allSettled so a partial failure is reported not silently swallowed
+            const [pubSettled, recSettled] = await Promise.allSettled([
+                this.pica.credits.updateCollaborators(args.work_id, {
+                    credits: publishingCredits,
+                }),
+                this.pica.credits.updateForWork(args.work_id, {
+                    credits: recordingCredits,
+                }),
+            ]);
+            const pubResult = pubSettled.status === "fulfilled" ? pubSettled.value : null;
+            const recResult = recSettled.status === "fulfilled" ? recSettled.value : null;
+            const pubError = pubSettled.status === "rejected"
+                ? pubSettled.reason
+                : null;
+            const recError = recSettled.status === "rejected"
+                ? recSettled.reason
+                : null;
+            if (pubError && recError) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `both publishing and recording credits failed to save — publishing error: ${pubError?.message ?? pubError}, recording error: ${recError?.message ?? recError}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            if (pubError) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `recording credits updated, but publishing credits failed — ${pubError?.message ?? pubError}. retry the publishing portion.`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            if (recError) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `publishing credits updated, but recording credits failed — ${recError?.message ?? recError}. retry the recording portion.`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            credits = { collaborators: pubResult, credits: recResult };
+        }
+        else if (publishingCredits.length > 0) {
+            credits = await this.pica.credits.updateCollaborators(args.work_id, {
+                credits: publishingCredits,
+            });
+        }
+        else {
+            credits = await this.pica.credits.updateForWork(args.work_id, {
+                credits: recordingCredits,
+            });
+        }
+        // Check completeness for hints about next steps
+        const hints = [];
+        try {
+            const completeness = await this.pica.health.getWorkCompleteness(args.work_id);
+            hints.push(...mapGapsToHints(completeness?.gaps || completeness?.missing || [], 3));
+        }
+        catch {
+            // Best-effort
+        }
+        // Notify all credited people about their credit
+        const parties = args.credits
+            .filter((c) => c.person_id)
+            .map((c) => ({
+            person_id: c.person_id,
+            message: `you've been credited as ${c.role || "writer"} (${c.splits || 0}%) on a work — please verify`,
+            work_id: args.work_id,
+            notification_type: "credit_added",
+        }));
+        let notifySummary = "";
+        if (parties.length > 0) {
+            const results = await notifyParties(this.pica, parties);
+            notifySummary = summarizeNotifications(results);
+        }
+        const msg = notifySummary
+            ? `Credits updated. ${notifySummary}`
+            : "Credits updated successfully";
+        return formatSuccess(msg, credits, hints);
+    }
+}
+//# sourceMappingURL=credits.js.map

package/dist/tools/credits.js.map

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

package/dist/tools/custody-hints.d.ts

@@ -0,0 +1,16 @@
+/**
+ * ADR-158 Plan C Phase 2 — completion hints for pica_works_create.
+ *
+ * When a fresh work is created, the custody columns default to
+ * "entry_default" (the org that typed it in is the placeholder custodian
+ * until an actual claim is made). These hints nudge the agent to have
+ * the rights conversation immediately rather than leaving custody dangling.
+ *
+ * The helper is intentionally defensive — the SDK's `Work` TS interface
+ * does not declare `composition_custody_source` / `master_custody_source`,
+ * but the API returns them as JSON pass-through from `worksService.create`.
+ * Callers pass the raw work object; we read the fields with a typed wrapper.
+ */
+import type { CompletionHint } from "@withpica/mcp-utils";
+export declare function buildCustodyHints(work: unknown): CompletionHint[];
+//# sourceMappingURL=custody-hints.d.ts.map

package/dist/tools/custody-hints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"custody-hints.d.ts","sourceRoot":"","sources":["../../src/tools/custody-hints.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAO1D,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,EAAE,CA+BjE"}

package/dist/tools/custody-hints.js

@@ -0,0 +1,27 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+export function buildCustodyHints(work) {
+    const w = (work ?? {});
+    const hints = [];
+    if (w.composition_custody_source === "entry_default") {
+        hints.push({
+            gap: "custody_unclaimed_composition",
+            severity: "important",
+            suggestion: "Who holds the publishing (composition) rights? If you, call pica_custody_claim with chain='composition'. If someone else (publisher, co-writer), invite them via pica_collaborators_invite and let them claim custody on acceptance.",
+        });
+    }
+    if (w.master_custody_source === "entry_default") {
+        hints.push({
+            gap: "custody_unclaimed_master",
+            severity: "important",
+            suggestion: "Who holds the recording (master) rights? Label, distributor, self-released? Same pattern — claim it yourself via pica_custody_claim with chain='master', or invite the rightsholder.",
+        });
+    }
+    // Always fire the split hint — we never know splits from a single work row.
+    hints.push({
+        gap: "rights_share_unknown",
+        severity: "nice_to_have",
+        suggestion: "Is the publishing 100% yours or split with co-writers? If split, add co-writers via pica_work_credits_add with their percentage shares so the splits sum to 100. Then invite them via pica_collaborators_invite to confirm.",
+    });
+    return hints;
+}
+//# sourceMappingURL=custody-hints.js.map

package/dist/tools/custody-hints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"custody-hints.js","sourceRoot":"","sources":["../../src/tools/custody-hints.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAuB7D,MAAM,UAAU,iBAAiB,CAAC,IAAa;IAC7C,MAAM,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAAoB,CAAC;IAC1C,MAAM,KAAK,GAAqB,EAAE,CAAC;IAEnC,IAAI,CAAC,CAAC,0BAA0B,KAAK,eAAe,EAAE,CAAC;QACrD,KAAK,CAAC,IAAI,CAAC;YACT,GAAG,EAAE,+BAA+B;YACpC,QAAQ,EAAE,WAAW;YACrB,UAAU,EACR,sOAAsO;SACzO,CAAC,CAAC;IACL,CAAC;IAED,IAAI,CAAC,CAAC,qBAAqB,KAAK,eAAe,EAAE,CAAC;QAChD,KAAK,CAAC,IAAI,CAAC;YACT,GAAG,EAAE,0BAA0B;YAC/B,QAAQ,EAAE,WAAW;YACrB,UAAU,EACR,sLAAsL;SACzL,CAAC,CAAC;IACL,CAAC;IAED,4EAA4E;IAC5E,KAAK,CAAC,IAAI,CAAC;QACT,GAAG,EAAE,sBAAsB;QAC3B,QAAQ,EAAE,cAAc;QACxB,UAAU,EACR,6NAA6N;KAChO,CAAC,CAAC;IAEH,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/tools/custody.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Custody MCP Tools — ADR-158 Plan C Phase 1
+ *
+ * Six tools covering the custody claim lifecycle + reconciliation, exposed
+ * on the stdio transport. Thin wrappers around this.pica.custody.* which
+ * calls the HTTP routes under /api/admin/custody/.
+ *
+ * Tools:
+ *   pica_custody_claim             — request custody of a work's chain
+ *   pica_custody_respond           — accept/decline/dispute an incoming claim
+ *   pica_custody_list              — list incoming + outgoing claims
+ *   pica_custody_history           — custody-related provenance_history rows
+ *   pica_custody_resolve_pending   — preview inheritable works for a global_publisher_id
+ *   pica_custody_reconcile         — bulk-claim inheritable works
+ *
+ * RBAC (enforced at the HTTP route layer, see app/api/admin/custody/*):
+ *   claim, respond, resolve_pending, reconcile → admin/owner only
+ *   list, history                              → any authenticated member
+ *
+ * Pricing: FREE. ADR-162 deprecates credit gating as a user-facing concept.
+ */
+import { PicaClient } from "@withpica/mcp-sdk";
+import type { ToolDefinition, ToolExecutor } from "./index.js";
+export declare class CustodyTools {
+    private pica;
+    constructor(pica: PicaClient);
+    getTools(): Array<{
+        definition: ToolDefinition;
+        executor: ToolExecutor;
+    }>;
+    private claim;
+    private respond;
+    private list;
+    private history;
+    private resolvePending;
+    private reconcile;
+}
+//# sourceMappingURL=custody.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"custody.d.ts","sourceRoot":"","sources":["../../src/tools/custody.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAc,MAAM,YAAY,CAAC;AAG3E,qBAAa,YAAY;IACvB,OAAO,CAAC,IAAI,CAAa;gBAEb,IAAI,EAAE,UAAU;IAI5B,QAAQ,IAAI,KAAK,CAAC;QAAE,UAAU,EAAE,cAAc,CAAC;QAAC,QAAQ,EAAE,YAAY,CAAA;KAAE,CAAC;YAwM3D,KAAK;YAYL,OAAO;YAeP,IAAI;YA0BJ,OAAO;YAeP,cAAc;YAuBd,SAAS;CAgBxB"}