@withpica/mcp-server 2.1.0

package/dist/tools/split-sheets.js

@@ -0,0 +1,189 @@
+/**
+ * Split Sheets & Recording Splits Tools
+ * MCP tools for managing publishing split sheets and master recording ownership splits
+ */
+import { formatAsText, formatSuccess, formatStructuredList, } from "../utils/formatting.js";
+export class SplitSheetsTools {
+    pica;
+    constructor(pica) {
+        this.pica = pica;
+    }
+    /**
+     * Get all split sheet and recording split tools
+     */
+    getTools() {
+        return [
+            {
+                definition: {
+                    name: "pica_split_sheet_list",
+                    description: "List split sheets for a work. Split sheets document how publishing " +
+                        "royalties are divided among writers and publishers for a composition.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            work_id: {
+                                type: "string",
+                                description: "The work ID to list split sheets for",
+                            },
+                        },
+                        required: ["work_id"],
+                    },
+                },
+                executor: this.listSplitSheets.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_split_sheet_generate",
+                    description: "Generate a split sheet from a work's credits. This takes the existing " +
+                        "writer credits on a work and creates a formal split sheet document. " +
+                        "Credits must total 100% before generating.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            work_id: {
+                                type: "string",
+                                description: "The work ID to generate a split sheet for",
+                            },
+                        },
+                        required: ["work_id"],
+                    },
+                },
+                executor: this.generateSplitSheet.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_split_sheet_get",
+                    description: "Get a specific split sheet with its full details including " +
+                        "individual writer shares and signature status.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            work_id: {
+                                type: "string",
+                                description: "The work ID the split sheet belongs to",
+                            },
+                            split_sheet_id: {
+                                type: "string",
+                                description: "The split sheet ID",
+                            },
+                        },
+                        required: ["work_id", "split_sheet_id"],
+                    },
+                },
+                executor: this.getSplitSheet.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_recording_splits_list",
+                    description: "List ownership splits for a recording. These represent master rights " +
+                        "ownership — who owns what percentage of the recorded performance " +
+                        "(as opposed to the underlying composition).",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            recording_id: {
+                                type: "string",
+                                description: "The recording ID to list splits for",
+                            },
+                        },
+                        required: ["recording_id"],
+                    },
+                },
+                executor: this.listRecordingSplits.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_recording_splits_create",
+                    description: "Set an ownership split on a recording. Assigns a percentage of master " +
+                        "rights ownership to a person or entity for this recording.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            recording_id: {
+                                type: "string",
+                                description: "The recording ID to add a split to",
+                            },
+                            person_id: {
+                                type: "string",
+                                description: "The person ID who owns this split",
+                            },
+                            role: {
+                                type: "string",
+                                description: "The role of this split holder (e.g. 'performer', 'producer', 'label')",
+                            },
+                            percentage: {
+                                type: "number",
+                                description: "Ownership percentage (0-100)",
+                            },
+                            notes: {
+                                type: "string",
+                                description: "Optional notes about this split",
+                            },
+                        },
+                        required: ["recording_id"],
+                        additionalProperties: true,
+                    },
+                },
+                executor: this.createRecordingSplit.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_recording_splits_verify",
+                    description: "Verify a recording split. Marks a specific ownership split as " +
+                        "confirmed and agreed upon by the relevant parties.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            recording_id: {
+                                type: "string",
+                                description: "The recording ID",
+                            },
+                            split_id: {
+                                type: "string",
+                                description: "The split ID to verify",
+                            },
+                        },
+                        required: ["recording_id", "split_id"],
+                    },
+                },
+                executor: this.verifyRecordingSplit.bind(this),
+            },
+        ];
+    }
+    // ── Split Sheet Methods ──────────────────────────────────────────────
+    async listSplitSheets(args) {
+        const sheets = await this.pica.splitSheets.listForWork(args.work_id);
+        const data = Array.isArray(sheets) ? sheets : (sheets?.data ?? [sheets]);
+        return formatStructuredList(data, "split_sheet", {
+            work_id: args.work_id,
+            total: data.length,
+        });
+    }
+    async generateSplitSheet(args) {
+        const sheet = await this.pica.splitSheets.generate(args.work_id);
+        return formatSuccess("Split sheet generated successfully", sheet);
+    }
+    async getSplitSheet(args) {
+        const sheet = await this.pica.splitSheets.get(args.work_id, args.split_sheet_id);
+        return formatAsText(sheet);
+    }
+    // ── Recording Split Methods ──────────────────────────────────────────
+    async listRecordingSplits(args) {
+        const splits = await this.pica.recordingSplits.list(args.recording_id);
+        const data = Array.isArray(splits) ? splits : (splits?.data ?? [splits]);
+        return formatStructuredList(data, "recording_split", {
+            recording_id: args.recording_id,
+            total: data.length,
+        });
+    }
+    async createRecordingSplit(args) {
+        const { recording_id, ...data } = args;
+        const split = await this.pica.recordingSplits.create(recording_id, data);
+        return formatSuccess("Recording split created successfully", split);
+    }
+    async verifyRecordingSplit(args) {
+        const result = await this.pica.recordingSplits.verify(args.recording_id, args.split_id);
+        return formatSuccess("Recording split verified successfully", result);
+    }
+}
+//# sourceMappingURL=split-sheets.js.map

package/dist/tools/split-sheets.js.map

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

package/dist/tools/team.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Team Tools — manage team members via MCP
+ *
+ * Backed by REST routes: /api/admin/team/*
+ * Supports listing, viewing, inviting, updating roles, and removing team members.
+ */
+import { PicaClient } from "../pica-sdk.js";
+import { ToolDefinition, ToolExecutor } from "./index.js";
+export declare class TeamTools {
+    private pica;
+    constructor(pica: PicaClient);
+    getTools(): Array<{
+        definition: ToolDefinition;
+        executor: ToolExecutor;
+    }>;
+    private listMembers;
+    private getMember;
+    private inviteMember;
+    private updateRole;
+    private removeMember;
+}
+//# sourceMappingURL=team.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"team.d.ts","sourceRoot":"","sources":["../../src/tools/team.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,YAAY,EAAc,MAAM,YAAY,CAAC;AAGtE,qBAAa,SAAS;IACpB,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;YAuG3D,WAAW;YAQX,SAAS;YAKT,YAAY;YAYZ,UAAU;YAUV,YAAY;CAI3B"}

package/dist/tools/team.js

@@ -0,0 +1,139 @@
+/**
+ * Team Tools — manage team members via MCP
+ *
+ * Backed by REST routes: /api/admin/team/*
+ * Supports listing, viewing, inviting, updating roles, and removing team members.
+ */
+import { formatSuccess, formatStructuredList } from "../utils/formatting.js";
+export class TeamTools {
+    pica;
+    constructor(pica) {
+        this.pica = pica;
+    }
+    getTools() {
+        return [
+            {
+                definition: {
+                    name: "pica_team_list",
+                    description: "List all team members with their roles, status (pending/active), and permissions. Use to answer 'who is on my team?'",
+                    inputSchema: {
+                        type: "object",
+                        properties: {},
+                    },
+                },
+                executor: this.listMembers.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_team_get",
+                    description: "Get details of a specific team member by membership ID, including permissions, status, and activity.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            id: {
+                                type: "string",
+                                description: "Team membership ID",
+                            },
+                        },
+                        required: ["id"],
+                    },
+                },
+                executor: this.getMember.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_team_invite",
+                    description: "Invite someone to join the team by email. Sends an invitation email. Optionally set their name and permissions.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            email: {
+                                type: "string",
+                                description: "Email address of the person to invite",
+                            },
+                            full_name: {
+                                type: "string",
+                                description: "Full name of the invitee (optional)",
+                            },
+                            permissions: {
+                                type: "object",
+                                description: "Permission flags for the team member (e.g. { can_edit_works: true, can_manage_team: false })",
+                            },
+                        },
+                        required: ["email"],
+                    },
+                },
+                executor: this.inviteMember.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_team_update_role",
+                    description: "Update a team member's permissions. Pass the membership ID and the new permissions object.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            id: {
+                                type: "string",
+                                description: "Team membership ID",
+                            },
+                            permissions: {
+                                type: "object",
+                                description: "Updated permission flags (e.g. { can_edit_works: true, can_manage_team: false })",
+                            },
+                        },
+                        required: ["id", "permissions"],
+                    },
+                },
+                executor: this.updateRole.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_team_remove",
+                    description: "Remove a team member by membership ID. This revokes their access.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            id: {
+                                type: "string",
+                                description: "Team membership ID to remove",
+                            },
+                        },
+                        required: ["id"],
+                    },
+                },
+                executor: this.removeMember.bind(this),
+            },
+        ];
+    }
+    async listMembers(_args) {
+        const result = await this.pica.team.list();
+        const members = Array.isArray(result)
+            ? result
+            : (result?.data ?? result?.members ?? []);
+        return formatStructuredList(members, "team member");
+    }
+    async getMember(args) {
+        const member = await this.pica.team.get(args.id);
+        return formatSuccess("Team member retrieved", member?.data ?? member);
+    }
+    async inviteMember(args) {
+        const payload = { email: args.email };
+        if (args.full_name)
+            payload.full_name = args.full_name;
+        if (args.permissions)
+            payload.permissions = args.permissions;
+        const result = await this.pica.team.invite(payload);
+        return formatSuccess(`Invitation sent to ${args.email}`, result?.data ?? result);
+    }
+    async updateRole(args) {
+        const result = await this.pica.team.update(args.id, {
+            permissions: args.permissions,
+        });
+        return formatSuccess(`Permissions updated for membership ${args.id}`, result?.data ?? result);
+    }
+    async removeMember(args) {
+        await this.pica.team.remove(args.id);
+        return formatSuccess(`Team member ${args.id} removed`);
+    }
+}
+//# sourceMappingURL=team.js.map

package/dist/tools/team.js.map

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

package/dist/tools/telegram.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Telegram Tools — MCP tools for user notification via Telegram
+ *
+ * Lets AI agents check if the user has Telegram connected and send them
+ * notifications for long-running tasks. Agents should check status first,
+ * then promise "I'll ping you on Telegram when done" if connected.
+ */
+import { PicaClient } from "../pica-sdk.js";
+import { ToolDefinition, ToolExecutor } from "./index.js";
+export declare class TelegramTools {
+    private pica;
+    constructor(pica: PicaClient);
+    getTools(): Array<{
+        definition: ToolDefinition;
+        executor: ToolExecutor;
+    }>;
+    private getStatus;
+    private notifyUser;
+}
+//# sourceMappingURL=telegram.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"telegram.d.ts","sourceRoot":"","sources":["../../src/tools/telegram.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,YAAY,EAAc,MAAM,YAAY,CAAC;AAOtE,qBAAa,aAAa;IACxB,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;YA0C3D,SAAS;YAwBT,UAAU;CA+BzB"}

package/dist/tools/telegram.js

@@ -0,0 +1,94 @@
+/**
+ * Telegram Tools — MCP tools for user notification via Telegram
+ *
+ * Lets AI agents check if the user has Telegram connected and send them
+ * notifications for long-running tasks. Agents should check status first,
+ * then promise "I'll ping you on Telegram when done" if connected.
+ */
+import { formatAsText, formatSuccess, formatValidationError, } from "../utils/formatting.js";
+export class TelegramTools {
+    pica;
+    constructor(pica) {
+        this.pica = pica;
+    }
+    getTools() {
+        return [
+            {
+                definition: {
+                    name: "pica_telegram_status",
+                    description: "Check if the user has Telegram connected. Use this before promising to send Telegram notifications. " +
+                        "Returns connection status, username, and notification preferences. " +
+                        "If not connected, suggest the user visit /connect to set up Telegram.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {},
+                    },
+                },
+                executor: this.getStatus.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_notify_user",
+                    description: "Send a notification to the user's connected Telegram. Use for long-running tasks: " +
+                        "enrichment, exports, duplicate merges, bulk operations. The message should be concise " +
+                        "and actionable — tell them what finished and what to do next. " +
+                        "Fails gracefully if Telegram is not connected (returns error, does not throw).",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            message: {
+                                type: "string",
+                                description: "Notification message (markdown supported). Keep it short — 1-3 sentences. " +
+                                    "Include what completed and any action needed.",
+                            },
+                        },
+                        required: ["message"],
+                    },
+                },
+                executor: this.notifyUser.bind(this),
+            },
+        ];
+    }
+    async getStatus(_args) {
+        const result = await this.pica.telegram.getStatus();
+        const data = result.data || result;
+        if (!data.connected) {
+            return formatAsText({
+                connected: false,
+                message: "Telegram is not connected. The user can set it up at /connect.",
+                bot_username: data.botUsername,
+            });
+        }
+        return formatSuccess(`Telegram connected as @${data.telegramUsername || data.telegramFirstName}. You can send notifications via pica_notify_user.`, {
+            connected: true,
+            telegram_username: data.telegramUsername,
+            telegram_first_name: data.telegramFirstName,
+            preferences: data.preferences,
+        });
+    }
+    async notifyUser(args) {
+        if (!args.message?.trim()) {
+            return formatValidationError({ message: "message is required" });
+        }
+        try {
+            const result = await this.pica.telegram.sendNotification(args.message.trim());
+            const data = result.data || result;
+            return formatSuccess(`Notification sent to @${data.telegramUsername || "user"} on Telegram.`, { sent: true, telegram_username: data.telegramUsername });
+        }
+        catch (err) {
+            // Graceful failure — don't throw, return error text
+            const message = err?.message || String(err);
+            if (message.includes("not connected") || message.includes("400")) {
+                return formatAsText({
+                    sent: false,
+                    error: "Telegram is not connected. The user can set it up at /connect.",
+                });
+            }
+            return formatAsText({
+                sent: false,
+                error: `Failed to send notification: ${message}`,
+            });
+        }
+    }
+}
+//# sourceMappingURL=telegram.js.map

package/dist/tools/telegram.js.map

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

package/dist/tools/uploads.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Upload Tools - MCP tools for uploading any file type (images, videos, documents)
+ * Uses the generic storage presigned upload route that supports all PICA storage providers.
+ */
+import { PicaClient } from "../pica-sdk.js";
+import { ToolDefinition, ToolExecutor } from "./index.js";
+export declare class UploadTools {
+    private pica;
+    constructor(pica: PicaClient);
+    getTools(): Array<{
+        definition: ToolDefinition;
+        executor: ToolExecutor;
+    }>;
+    private presignedUpload;
+    private completeUpload;
+}
+//# sourceMappingURL=uploads.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"uploads.d.ts","sourceRoot":"","sources":["../../src/tools/uploads.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,YAAY,EAAc,MAAM,YAAY,CAAC;AAGtE,qBAAa,WAAW;IACtB,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;YAuH3D,eAAe;YAyBf,cAAc;CAwB7B"}