@withpica/mcp-server 1.3.0

package/dist/tools/collaborators.js

@@ -0,0 +1,381 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+import { elicitBulkConfirmation, formatSuccess, formatList, } from "@withpica/mcp-utils";
+export class CollaboratorsTools {
+    pica;
+    constructor(pica) {
+        this.pica = pica;
+    }
+    getTools() {
+        return [
+            {
+                definition: {
+                    name: "pica_collaborators_invite",
+                    description: "Invite a collaborator to a work by email. Creates the person if they don't exist, sends an invite email, and sets up their credit on the work. Requires the work ID, person details (name + email), the inviter's person ID, and credit details.",
+                    workflows: "infrastructure",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            work_id: {
+                                type: "string",
+                                description: "The work ID to invite the collaborator to",
+                            },
+                            name: {
+                                type: "string",
+                                description: "Full name of the collaborator",
+                            },
+                            email: {
+                                type: "string",
+                                description: "Email address of the collaborator",
+                            },
+                            role: {
+                                type: "string",
+                                description: "Role on the work (e.g. 'producer', 'songwriter', 'drummer', 'vocalist')",
+                            },
+                            invited_by: {
+                                type: "string",
+                                description: "Person ID of the person sending the invite (the catalog owner). Use pica_people_query to find this ID.",
+                            },
+                            credit_type: {
+                                type: "string",
+                                description: "Type of credit (e.g. 'production', 'songwriting', 'drums', 'vocals', 'mixing')",
+                            },
+                            percentage_split: {
+                                type: "number",
+                                description: "Percentage split for this credit (0-100)",
+                            },
+                        },
+                        required: ["work_id", "name", "email", "invited_by", "credit_type"],
+                    },
+                },
+                executor: this.inviteCollaborator.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_collaborators_invites_list",
+                    description: "Sender-side: list collaboration invites you have sent. Filter by status (pending / verified / confirmed / expired / cancelled / disputed) or by work. For the recipient-side equivalent see pica_collaborators_incoming_list.",
+                    workflows: "infrastructure",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            status: {
+                                type: "string",
+                                description: "Filter by status (default: 'pending')",
+                                enum: [
+                                    "pending",
+                                    "verified",
+                                    "confirmed",
+                                    "expired",
+                                    "cancelled",
+                                    "disputed",
+                                ],
+                            },
+                            work_id: {
+                                type: "string",
+                                description: "Filter invites for a specific work",
+                            },
+                            limit: {
+                                type: "number",
+                                description: "Maximum results to return (default: 50, max: 100)",
+                            },
+                        },
+                    },
+                },
+                executor: this.listInvites.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_collaborators_incoming_list",
+                    description: "List collaboration invites addressed to YOUR email across every inviting org. Returns pending invites by default — pass status to see disputed/confirmed history. Each row includes work_title, inviter_org_name, credit_type, and percentage_split so you can decide whether to accept.",
+                    workflows: "infrastructure",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            status: {
+                                type: "string",
+                                description: "Filter by status (default: 'pending')",
+                                enum: [
+                                    "pending",
+                                    "verified",
+                                    "confirmed",
+                                    "expired",
+                                    "cancelled",
+                                    "disputed",
+                                ],
+                            },
+                            limit: {
+                                type: "number",
+                                description: "Maximum results to return (default: 50, max: 100)",
+                            },
+                        },
+                    },
+                },
+                executor: this.listIncoming.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_collaborators_accept",
+                    description: "Accept a collaboration invite addressed to your email. Writes a real work_credits row on the inviter's work and notifies them. Fails if the invite is not addressed to your authenticated email. Use pica_collaborators_incoming_list to find the invite_id first.",
+                    workflows: "infrastructure",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            invite_id: {
+                                type: "string",
+                                description: "The invite id to accept",
+                            },
+                        },
+                        required: ["invite_id"],
+                    },
+                },
+                executor: this.acceptInvite.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_collaborators_dispute",
+                    description: 'Dispute a collaboration invite addressed to your email ("that\'s not me" or "I wasn\'t on this work"). Flips the invite to disputed and notifies the inviter. Does NOT create any credits.',
+                    workflows: "infrastructure",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            invite_id: {
+                                type: "string",
+                                description: "The invite id to dispute",
+                            },
+                            reason: {
+                                type: "string",
+                                description: "Optional freeform reason for the dispute",
+                            },
+                        },
+                        required: ["invite_id"],
+                    },
+                },
+                executor: this.disputeInvite.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_collaborators_invite_bulk",
+                    description: "Send multiple collaboration invites in one call. Thin wrapper over pica_collaborators_invite — same per-row schema, returns per-row { ok, email, invite?, error? } so partial failures are visible.",
+                    workflows: "infrastructure",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            invites: {
+                                type: "array",
+                                description: "Array of invites to send",
+                                items: {
+                                    type: "object",
+                                    properties: {
+                                        work_id: {
+                                            type: "string",
+                                            description: "UUID of the work to invite the collaborator to",
+                                        },
+                                        name: {
+                                            type: "string",
+                                            description: "Full name of the collaborator",
+                                        },
+                                        email: {
+                                            type: "string",
+                                            description: "Email address to send the invite to",
+                                        },
+                                        role: {
+                                            type: "string",
+                                            description: "Role on the work (e.g. writer, producer)",
+                                        },
+                                        invited_by: {
+                                            type: "string",
+                                            description: "Name of the person sending the invite",
+                                        },
+                                        credit_type: {
+                                            type: "string",
+                                            description: "Type of credit (e.g. writer, composer, producer)",
+                                        },
+                                        percentage_split: {
+                                            type: "number",
+                                            description: "Split percentage (0-100)",
+                                        },
+                                    },
+                                    required: [
+                                        "work_id",
+                                        "name",
+                                        "email",
+                                        "invited_by",
+                                        "credit_type",
+                                    ],
+                                },
+                            },
+                            dry_run: {
+                                type: "boolean",
+                                description: "When true, returns { dry_run: true, would_affect, sample } without sending any invite emails. Bulk invites send real email — preview before committing.",
+                            },
+                        },
+                        required: ["invites"],
+                    },
+                    previewMode: "dry_run",
+                },
+                executor: this.inviteBulk.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_collaborators_invite_resend",
+                    description: "Resend a pending collaboration invite. Regenerates the invite token and sends a new email.",
+                    workflows: "infrastructure",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            invite_id: {
+                                type: "string",
+                                description: "The invite ID to resend",
+                            },
+                        },
+                        required: ["invite_id"],
+                    },
+                },
+                executor: this.resendInvite.bind(this),
+            },
+        ];
+    }
+    async inviteCollaborator(args) {
+        const result = await this.pica.collaborators.invite({
+            workId: args.work_id,
+            personData: {
+                name: args.name,
+                email: args.email,
+                role: args.role,
+            },
+            invitedBy: args.invited_by,
+            creditData: {
+                credit_type: args.credit_type,
+                percentage_split: args.percentage_split,
+            },
+        });
+        const hints = [
+            {
+                gap: "collaborator_missing_identifiers",
+                suggestion: `Enrich ${args.name} with ISNI or IPI for royalty collection (pica_resolve_person)`,
+                severity: "important",
+            },
+        ];
+        return formatSuccess(`Invite sent to ${args.name} (${args.email}) for credit "${args.credit_type}" on work ${args.work_id}.`, result, hints);
+    }
+    async listInvites(args) {
+        // ADR-157 sub-step 4b (superseded form): the original plan surfaced
+        // an "events since last review" watermark hint, but sub-step 4a
+        // already delivers confirmed/disputed receipts instantly via
+        // Telegram — making the duplicated completion-hint surface
+        // redundant. ADR-160 reinforces the receipts-layer principle. All
+        // that remains is nudging unpaired orgs towards Telegram, via a
+        // single parallel call to the existing telegram status endpoint.
+        // Status-check failure degrades to "no nudge" so the primary read
+        // path stays resilient.
+        const [invites, telegramStatus] = await Promise.all([
+            this.pica.collaborators.listInvites({
+                status: args.status,
+                workId: args.work_id,
+                limit: args.limit,
+            }),
+            this.pica.telegram.getStatus().catch(() => null),
+        ]);
+        const hints = [];
+        if (telegramStatus && telegramStatus.connected === false) {
+            hints.push({
+                gap: "telegram_not_connected",
+                suggestion: "Want collaborator accept/dispute receipts delivered instantly? Pair Telegram with pica_telegram_connect — the message body is the receipt, no dashboard trip.",
+                severity: "nice_to_have",
+            });
+        }
+        return formatList(invites, {
+            status: args.status || "pending",
+            completion_hints: hints,
+        });
+    }
+    async resendInvite(args) {
+        const result = await this.pica.collaborators.resendInvite(args.invite_id);
+        return formatSuccess(`Invite ${args.invite_id} resent successfully.`, result);
+    }
+    async listIncoming(args) {
+        const invites = await this.pica.collaborators.listIncoming({
+            status: args.status,
+            limit: args.limit,
+        });
+        const hints = [];
+        if (invites.length > 0) {
+            hints.push({
+                gap: "pending_incoming_invites",
+                suggestion: `You have ${invites.length} pending invite${invites.length === 1 ? "" : "s"}. Accept with pica_collaborators_accept or reject with pica_collaborators_dispute.`,
+                severity: "important",
+            });
+        }
+        return formatList(invites, {
+            status: args.status || "pending",
+            count: invites.length,
+            completion_hints: hints,
+        });
+    }
+    async acceptInvite(args) {
+        const result = await this.pica.collaborators.accept(args.invite_id);
+        const hints = [
+            {
+                gap: "credit_attested",
+                suggestion: "Your credit is now live on the inviter's work. Use pica_works_query to see works you're credited on.",
+                severity: "nice_to_have",
+            },
+        ];
+        return formatSuccess(`Invite ${args.invite_id} accepted. Credit written.`, result, hints);
+    }
+    async disputeInvite(args) {
+        const result = await this.pica.collaborators.dispute(args.invite_id, args.reason);
+        return formatSuccess(`Invite ${args.invite_id} disputed. The inviter has been notified.`, result);
+    }
+    async inviteBulk(args, ctx) {
+        // ADR-199 Stream 5b — dry_run preview before invite-email send.
+        // Bulk invites send real email through Postmark; dry_run lets the
+        // caller verify the recipient list before triggering the send.
+        if (args.dry_run === true) {
+            const invites = args.invites || [];
+            const sample = invites.slice(0, 3).map((i) => ({
+                email: i.email,
+                name: i.name,
+                work_id: i.work_id,
+                credit_type: i.credit_type,
+            }));
+            return formatSuccess(`Dry run — would send ${invites.length} collaboration invite(s)`, {
+                dry_run: true,
+                would_affect: invites.map((i) => i.email),
+                sample,
+                target_count: invites.length,
+            });
+        }
+        // ADR-200 Phase 1 — Class D form-confirmation gate. Bulk invites
+        // dispatch real email through Postmark; once sent, they cannot be
+        // unsent. Surface the recipient count and a sample for the user to
+        // confirm before the batch fires.
+        const invitesArr = args.invites || [];
+        const sampleEmails = invitesArr
+            .slice(0, 3)
+            .map((i) => i.email)
+            .join(", ");
+        const tail = invitesArr.length > 3 ? `, +${invitesArr.length - 3} more` : "";
+        const gate = await elicitBulkConfirmation({
+            server: ctx?.server,
+            args,
+            action: "Send bulk collaboration invites",
+            impactSummary: `${invitesArr.length} invite(s) (${sampleEmails}${tail})`,
+            warning: "Each invite triggers a real email; sent emails cannot be recalled.",
+        });
+        if (gate.kind === "abort")
+            return gate.result;
+        const results = await this.pica.collaborators.inviteBulk(invitesArr.map((i) => ({
+            workId: i.work_id,
+            personData: { name: i.name, email: i.email, role: i.role },
+            invitedBy: i.invited_by,
+            creditData: {
+                credit_type: i.credit_type,
+                percentage_split: i.percentage_split,
+            },
+        })));
+        const okCount = results.filter((r) => r.ok).length;
+        const failCount = results.length - okCount;
+        return formatSuccess(`Bulk invite complete: ${okCount} sent, ${failCount} failed.`, { results, ok: okCount, failed: failCount });
+    }
+}
+//# sourceMappingURL=collaborators.js.map

package/dist/tools/collaborators.js.map

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

package/dist/tools/comparisons.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Comparison Tools - MCP tools for comparing enrichment sources vs catalog data
+ * and registration status across PROs.
+ *
+ * ADR-116 Phase 2: Comparative views
+ *
+ * These tools return structured comparisons that agents can reason over directly,
+ * eliminating the need for 4-6 separate tool calls to assemble context manually.
+ */
+import { PicaClient } from "@withpica/mcp-sdk";
+import { ToolDefinition, ToolExecutor } from "./index.js";
+export declare class ComparisonTools {
+    private pica;
+    constructor(pica: PicaClient);
+    getTools(): Array<{
+        definition: ToolDefinition;
+        executor: ToolExecutor;
+    }>;
+    private enrichmentCompare;
+    private registrationsCompare;
+}
+//# sourceMappingURL=comparisons.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"comparisons.d.ts","sourceRoot":"","sources":["../../src/tools/comparisons.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,YAAY,EAAc,MAAM,YAAY,CAAC;AAGtE,qBAAa,eAAe;IAC1B,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;YAsD3D,iBAAiB;YAqBjB,oBAAoB;CAkBnC"}

package/dist/tools/comparisons.js

@@ -0,0 +1,80 @@
+// 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.",
+                    workflows: "infrastructure",
+                    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).",
+                    workflows: "infrastructure",
+                    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,39 @@
+/**
+ * Credits Tools - MCP tools for managing work credits (collaborators and splits)
+ *
+ * Per ADR-213 (2026-04-30) this module also hosts pica_recording_credits_update
+ * — the first-party recording-side write tool that closes the work/recording
+ * credit-write asymmetry. It writes to the `recording_credits` table (NOT the
+ * trade-secret enrichment-cascade-fed `credits` table; see
+ * .claude/rules/ip-protection.md). Roles use the 16-entry RECORDING_CREDIT_ROLES
+ * enum defined inline below; the canonical source is
+ * lib/services/recording-credits.ts.
+ */
+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 listCredits;
+    private updateCredits;
+    /**
+     * ADR-213 Primitive B — pica_recording_credits_update
+     *
+     * Writes a single first-party recording credit to the recording_credits
+     * table via POST /admin/recordings/{recording_id}/credits.
+     *
+     * Validates role against RECORDING_CREDIT_ROLES (16 entries) before the
+     * round trip so we get a structured error rather than a generic 400 from
+     * the route. credited_name is required (NOT NULL on the table); the route
+     * also validates this but we surface it earlier.
+     *
+     * On success, includes a notification to the credited person if person_id
+     * is set, mirroring the work-side updateCredits notification flow.
+     */
+    private updateRecordingCredits;
+}
+//# 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;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,YAAY,EAAc,MAAM,YAAY,CAAC;AAsCtE,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;YAuQ3D,WAAW;YA2BX,aAAa;IAqM3B;;;;;;;;;;;;;OAaG;YACW,sBAAsB;CA2GrC"}