@withpica/mcp-server 2.5.1 → 2.5.4

package/dist/tools/agreement-types.js

@@ -6,512 +6,370 @@ export class AgreementTypesTools {
     constructor(pica) {
         this.pica = pica;
     }
+    getResource(type) {
+        switch (type) {
+            case "template":
+                return this.pica.agreementTemplates;
+            case "producer":
+                return this.pica.producerAgreements;
+            case "work_for_hire":
+                return this.pica.workForHire;
+            default:
+                throw new Error(`Unknown agreement type: ${type}`);
+        }
+    }
+    labelFor(type) {
+        switch (type) {
+            case "template":
+                return "Agreement template";
+            case "producer":
+                return "Producer agreement";
+            case "work_for_hire":
+                return "Work-for-hire agreement";
+        }
+    }
     getTools() {
         return [
-            // ── Agreement Templates ──────────────────────────────────────────
+            // ── Unified CRUD ────────────────────────────────────────────────
             {
                 definition: {
-                    name: "pica_agreement_templates_list",
-                    description: "List reusable agreement templates — publishing, split sheet, production deals. Returns all templates for the organisation.",
-                    inputSchema: {
-                        type: "object",
-                        properties: {},
-                    },
-                },
-                executor: this.listTemplates.bind(this),
-            },
-            {
-                definition: {
-                    name: "pica_agreement_templates_get",
-                    description: "Get a specific agreement template with its full body, placeholders, and metadata.",
+                    name: "pica_agreement_types_query",
+                    description: "List agreements by type — templates, producer agreements, or work-for-hire contracts.",
                     inputSchema: {
                         type: "object",
                         properties: {
-                            id: {
+                            type: {
                                 type: "string",
-                                description: "Template ID",
+                                enum: ["template", "producer", "work_for_hire"],
+                                description: "Agreement sub-type to query",
+                            },
+                            limit: {
+                                type: "number",
+                                description: "Max results",
                             },
                         },
-                        required: ["id"],
+                        required: ["type"],
                     },
                 },
-                executor: this.getTemplate.bind(this),
+                executor: this.query.bind(this),
             },
             {
                 definition: {
-                    name: "pica_agreement_templates_create",
-                    description: "Create a new agreement template. Define the template body with placeholders like {{work_title}}, {{artist_name}}, {{split_percentage}} that get filled when rendering.",
+                    name: "pica_agreement_types_inspect",
+                    description: "Get a specific agreement by type and ID — full details including body, terms, and metadata.",
                     inputSchema: {
                         type: "object",
                         properties: {
-                            name: {
-                                type: "string",
-                                description: "Template name (e.g. 'Standard Publishing Deal')",
-                            },
-                            template_type: {
+                            type: {
                                 type: "string",
-                                description: "Type of agreement this template produces (e.g. publishing_admin, production, split_sheet)",
+                                enum: ["template", "producer", "work_for_hire"],
+                                description: "Agreement sub-type",
                             },
-                            body: {
-                                type: "string",
-                                description: "Template body with placeholders — use {{placeholder_name}} syntax",
-                            },
-                            description: {
+                            id: {
                                 type: "string",
-                                description: "Short description of when to use this template",
-                            },
-                            is_default: {
-                                type: "boolean",
-                                description: "Whether this is the default template for its type",
+                                description: "Agreement ID",
                             },
                         },
-                        required: ["name", "template_type", "body"],
+                        required: ["type", "id"],
                     },
                 },
-                executor: this.createTemplate.bind(this),
+                executor: this.inspect.bind(this),
             },
             {
                 definition: {
-                    name: "pica_agreement_templates_update",
-                    description: "Update an existing agreement template.",
+                    name: "pica_agreement_types_create",
+                    description: "Create a new agreement of the specified type. Templates need name + template_type + body. " +
+                        "Producer agreements need title (plus optional advance, points, recoupment). " +
+                        "Work-for-hire needs title (plus optional fee, contractor, rights).",
                     inputSchema: {
                         type: "object",
                         properties: {
-                            id: {
+                            type: {
                                 type: "string",
-                                description: "Template ID",
+                                enum: ["template", "producer", "work_for_hire"],
+                                description: "Agreement sub-type to create",
                             },
+                            // Template fields
                             name: {
                                 type: "string",
-                                description: "Updated template name",
+                                description: "Template name (templates only)",
                             },
                             template_type: {
                                 type: "string",
-                                description: "Updated template type",
+                                description: "Type of agreement this template produces (templates only)",
                             },
                             body: {
                                 type: "string",
-                                description: "Updated template body",
+                                description: "Template body with {{placeholders}} (templates only)",
                             },
                             description: {
                                 type: "string",
-                                description: "Updated description",
+                                description: "Short description",
                             },
                             is_default: {
                                 type: "boolean",
-                                description: "Set as default for its type",
-                            },
-                        },
-                        required: ["id"],
-                    },
-                },
-                executor: this.updateTemplate.bind(this),
-            },
-            {
-                definition: {
-                    name: "pica_agreement_templates_delete",
-                    description: "Delete an agreement template.",
-                    inputSchema: {
-                        type: "object",
-                        properties: {
-                            id: {
-                                type: "string",
-                                description: "Template ID",
+                                description: "Set as default for its type (templates only)",
                             },
-                        },
-                        required: ["id"],
-                    },
-                },
-                executor: this.deleteTemplate.bind(this),
-            },
-            {
-                definition: {
-                    name: "pica_agreement_templates_render",
-                    description: "Fill an agreement template with work and people data — generates a ready-to-send agreement. Pass the template ID plus work_id and/or people_ids to populate the placeholders with real catalog data.",
-                    inputSchema: {
-                        type: "object",
-                        properties: {
-                            id: {
+                            // Producer + work-for-hire shared
+                            title: {
                                 type: "string",
-                                description: "Template ID to render",
+                                description: "Agreement title (producer / work-for-hire)",
                             },
                             work_id: {
                                 type: "string",
-                                description: "Work ID to pull title, credits, and metadata from",
-                            },
-                            people_ids: {
-                                type: "array",
-                                items: { type: "string" },
-                                description: "People IDs to include as parties in the agreement",
-                            },
-                            variables: {
-                                type: "object",
-                                description: "Additional variables to substitute — keys match placeholder names in the template body",
-                            },
-                        },
-                        required: ["id"],
-                    },
-                },
-                executor: this.renderTemplate.bind(this),
-            },
-            {
-                definition: {
-                    name: "pica_agreement_templates_duplicate",
-                    description: "Duplicate an agreement template — creates a copy you can customise without changing the original.",
-                    inputSchema: {
-                        type: "object",
-                        properties: {
-                            id: {
-                                type: "string",
-                                description: "Template ID to duplicate",
-                            },
-                        },
-                        required: ["id"],
-                    },
-                },
-                executor: this.duplicateTemplate.bind(this),
-            },
-            {
-                definition: {
-                    name: "pica_agreement_templates_set_default",
-                    description: "Set a template as the default for its type — when creating agreements of that type, this template will be suggested first.",
-                    inputSchema: {
-                        type: "object",
-                        properties: {
-                            id: {
-                                type: "string",
-                                description: "Template ID to set as default",
+                                description: "Work this agreement covers",
                             },
-                        },
-                        required: ["id"],
-                    },
-                },
-                executor: this.setDefaultTemplate.bind(this),
-            },
-            // ── Producer Agreements ──────────────────────────────────────────
-            {
-                definition: {
-                    name: "pica_producer_agreements_list",
-                    description: "List producer agreements — advance + points deals with recoupment tracking. Shows all producer deals for the catalogue.",
-                    inputSchema: {
-                        type: "object",
-                        properties: {},
-                    },
-                },
-                executor: this.listProducerAgreements.bind(this),
-            },
-            {
-                definition: {
-                    name: "pica_producer_agreements_get",
-                    description: "Get a producer agreement with full details including advance amount, points percentage, and recoupment status.",
-                    inputSchema: {
-                        type: "object",
-                        properties: {
-                            id: {
+                            status: {
                                 type: "string",
-                                description: "Producer agreement ID",
+                                enum: ["draft", "active", "completed", "terminated"],
+                                description: "Agreement status",
                             },
-                        },
-                        required: ["id"],
-                    },
-                },
-                executor: this.getProducerAgreement.bind(this),
-            },
-            {
-                definition: {
-                    name: "pica_producer_agreements_create",
-                    description: "Create a producer agreement — set advance, points percentage, and recoupment terms. Links a producer to a work or recording with specific commercial terms.",
-                    inputSchema: {
-                        type: "object",
-                        properties: {
-                            title: {
+                            notes: {
                                 type: "string",
-                                description: "Agreement title",
+                                description: "Internal notes",
                             },
+                            // Producer-specific
                             producer_id: {
                                 type: "string",
-                                description: "Person ID of the producer",
-                            },
-                            work_id: {
-                                type: "string",
-                                description: "Work this agreement covers",
+                                description: "Person ID of the producer (producer only)",
                             },
                             recording_id: {
                                 type: "string",
-                                description: "Recording this agreement covers (if specific)",
+                                description: "Recording this agreement covers (producer only)",
                             },
                             advance_amount: {
                                 type: "number",
-                                description: "Advance amount in the agreement currency",
+                                description: "Advance amount (producer only)",
                             },
                             advance_currency: {
                                 type: "string",
-                                description: "Currency code (e.g. GBP, USD, EUR)",
+                                description: "Currency code (producer only)",
                             },
                             points_percentage: {
                                 type: "number",
-                                description: "Producer points as a percentage of revenue (e.g. 3.5 for 3.5%)",
+                                description: "Producer points percentage (producer only)",
                             },
                             recoupment_terms: {
                                 type: "string",
-                                description: "Description of recoupment terms (e.g. 'Advance recouped from producer share before royalty payments begin')",
+                                description: "Recoupment terms (producer only)",
                             },
-                            status: {
+                            // Work-for-hire-specific
+                            contractor_id: {
                                 type: "string",
-                                description: "Agreement status",
-                                enum: ["draft", "active", "completed", "terminated"],
+                                description: "Person ID of the contractor (work-for-hire only)",
                             },
-                            notes: {
+                            fee_amount: {
+                                type: "number",
+                                description: "Flat fee amount (work-for-hire only)",
+                            },
+                            fee_currency: {
                                 type: "string",
-                                description: "Internal notes",
+                                description: "Currency code (work-for-hire only)",
+                            },
+                            rights_assigned: {
+                                type: "string",
+                                description: "Rights being assigned (work-for-hire only)",
                             },
                         },
-                        required: ["title"],
+                        required: ["type"],
                     },
                 },
-                executor: this.createProducerAgreement.bind(this),
+                executor: this.create.bind(this),
             },
             {
                 definition: {
-                    name: "pica_producer_agreements_update",
-                    description: "Update a producer agreement — change advance, points, recoupment terms, or status.",
+                    name: "pica_agreement_types_update",
+                    description: "Update an existing agreement by type and ID.",
                     inputSchema: {
                         type: "object",
                         properties: {
-                            id: {
-                                type: "string",
-                                description: "Producer agreement ID",
-                            },
-                            title: {
-                                type: "string",
-                                description: "Updated title",
-                            },
-                            producer_id: {
-                                type: "string",
-                                description: "Updated producer person ID",
-                            },
-                            work_id: {
-                                type: "string",
-                                description: "Updated work ID",
-                            },
-                            recording_id: {
-                                type: "string",
-                                description: "Updated recording ID",
-                            },
-                            advance_amount: {
-                                type: "number",
-                                description: "Updated advance amount",
-                            },
-                            advance_currency: {
+                            type: {
                                 type: "string",
-                                description: "Updated currency code",
-                            },
-                            points_percentage: {
-                                type: "number",
-                                description: "Updated points percentage",
+                                enum: ["template", "producer", "work_for_hire"],
+                                description: "Agreement sub-type",
                             },
-                            recoupment_terms: {
+                            id: {
                                 type: "string",
-                                description: "Updated recoupment terms",
+                                description: "Agreement ID",
                             },
+                            // All possible update fields (same as create minus type/id)
+                            name: { type: "string" },
+                            template_type: { type: "string" },
+                            body: { type: "string" },
+                            description: { type: "string" },
+                            is_default: { type: "boolean" },
+                            title: { type: "string" },
+                            work_id: { type: "string" },
                             status: {
                                 type: "string",
-                                description: "Updated status",
                                 enum: ["draft", "active", "completed", "terminated"],
                             },
-                            notes: {
-                                type: "string",
-                                description: "Updated notes",
-                            },
+                            notes: { type: "string" },
+                            producer_id: { type: "string" },
+                            recording_id: { type: "string" },
+                            advance_amount: { type: "number" },
+                            advance_currency: { type: "string" },
+                            points_percentage: { type: "number" },
+                            recoupment_terms: { type: "string" },
+                            contractor_id: { type: "string" },
+                            fee_amount: { type: "number" },
+                            fee_currency: { type: "string" },
+                            rights_assigned: { type: "string" },
                         },
-                        required: ["id"],
+                        required: ["type", "id"],
                     },
                 },
-                executor: this.updateProducerAgreement.bind(this),
+                executor: this.update.bind(this),
             },
             {
                 definition: {
-                    name: "pica_producer_agreements_delete",
-                    description: "Delete a producer agreement.",
+                    name: "pica_agreement_types_delete",
+                    description: "Delete an agreement by type and ID.",
                     inputSchema: {
                         type: "object",
                         properties: {
-                            id: {
+                            type: {
                                 type: "string",
-                                description: "Producer agreement ID",
+                                enum: ["template", "producer", "work_for_hire"],
+                                description: "Agreement sub-type",
                             },
-                        },
-                        required: ["id"],
-                    },
-                },
-                executor: this.deleteProducerAgreement.bind(this),
-            },
-            // ── Work-for-Hire ────────────────────────────────────────────────
-            {
-                definition: {
-                    name: "pica_work_for_hire_list",
-                    description: "List work-for-hire agreements — flat-fee contracts where all rights are assigned to the commissioning party.",
-                    inputSchema: {
-                        type: "object",
-                        properties: {},
-                    },
-                },
-                executor: this.listWorkForHire.bind(this),
-            },
-            {
-                definition: {
-                    name: "pica_work_for_hire_get",
-                    description: "Get a work-for-hire agreement with full details — fee, contractor, rights assignment, and linked works.",
-                    inputSchema: {
-                        type: "object",
-                        properties: {
                             id: {
                                 type: "string",
-                                description: "Work-for-hire agreement ID",
+                                description: "Agreement ID",
                             },
                         },
-                        required: ["id"],
+                        required: ["type", "id"],
                     },
                 },
-                executor: this.getWorkForHire.bind(this),
+                executor: this.delete.bind(this),
             },
+            // ── Template-specific operations ────────────────────────────────
             {
                 definition: {
-                    name: "pica_work_for_hire_create",
-                    description: "Create a work-for-hire agreement — flat fee, contractor assigns all rights. Used when commissioning music where the creator doesn't retain ownership.",
+                    name: "pica_agreement_templates_render",
+                    description: "Fill an agreement template with work and people data — generates a ready-to-send agreement. Pass the template ID plus work_id and/or people_ids to populate the placeholders with real catalog data.",
                     inputSchema: {
                         type: "object",
                         properties: {
-                            title: {
-                                type: "string",
-                                description: "Agreement title",
-                            },
-                            contractor_id: {
+                            id: {
                                 type: "string",
-                                description: "Person ID of the contractor (the one doing the work)",
+                                description: "Template ID to render",
                             },
                             work_id: {
                                 type: "string",
-                                description: "Work being created under this agreement",
-                            },
-                            fee_amount: {
-                                type: "number",
-                                description: "Flat fee amount",
-                            },
-                            fee_currency: {
-                                type: "string",
-                                description: "Currency code (e.g. GBP, USD, EUR)",
-                            },
-                            rights_assigned: {
-                                type: "string",
-                                description: "Description of rights being assigned (e.g. 'All publishing and master rights')",
+                                description: "Work ID to pull title, credits, and metadata from",
                             },
-                            status: {
-                                type: "string",
-                                description: "Agreement status",
-                                enum: ["draft", "active", "completed", "terminated"],
+                            people_ids: {
+                                type: "array",
+                                items: { type: "string" },
+                                description: "People IDs to include as parties in the agreement",
                             },
-                            notes: {
-                                type: "string",
-                                description: "Internal notes",
+                            variables: {
+                                type: "object",
+                                description: "Additional variables to substitute — keys match placeholder names in the template body",
                             },
                         },
-                        required: ["title"],
+                        required: ["id"],
                     },
                 },
-                executor: this.createWorkForHire.bind(this),
+                executor: this.renderTemplate.bind(this),
             },
             {
                 definition: {
-                    name: "pica_work_for_hire_update",
-                    description: "Update a work-for-hire agreement — change fee, contractor, rights, or status.",
+                    name: "pica_agreement_templates_duplicate",
+                    description: "Duplicate an agreement template — creates a copy you can customise without changing the original.",
                     inputSchema: {
                         type: "object",
                         properties: {
                             id: {
                                 type: "string",
-                                description: "Work-for-hire agreement ID",
-                            },
-                            title: {
-                                type: "string",
-                                description: "Updated title",
-                            },
-                            contractor_id: {
-                                type: "string",
-                                description: "Updated contractor person ID",
-                            },
-                            work_id: {
-                                type: "string",
-                                description: "Updated work ID",
-                            },
-                            fee_amount: {
-                                type: "number",
-                                description: "Updated fee amount",
-                            },
-                            fee_currency: {
-                                type: "string",
-                                description: "Updated currency code",
-                            },
-                            rights_assigned: {
-                                type: "string",
-                                description: "Updated rights description",
-                            },
-                            status: {
-                                type: "string",
-                                description: "Updated status",
-                                enum: ["draft", "active", "completed", "terminated"],
-                            },
-                            notes: {
-                                type: "string",
-                                description: "Updated notes",
+                                description: "Template ID to duplicate",
                             },
                         },
                         required: ["id"],
                     },
                 },
-                executor: this.updateWorkForHire.bind(this),
+                executor: this.duplicateTemplate.bind(this),
             },
             {
                 definition: {
-                    name: "pica_work_for_hire_delete",
-                    description: "Delete a work-for-hire agreement.",
+                    name: "pica_agreement_templates_set_default",
+                    description: "Set a template as the default for its type — when creating agreements of that type, this template will be suggested first.",
                     inputSchema: {
                         type: "object",
                         properties: {
                             id: {
                                 type: "string",
-                                description: "Work-for-hire agreement ID",
+                                description: "Template ID to set as default",
                             },
                         },
                         required: ["id"],
                     },
                 },
-                executor: this.deleteWorkForHire.bind(this),
+                executor: this.setDefaultTemplate.bind(this),
             },
         ];
     }
-    // ── Template executors ─────────────────────────────────────────────
-    async listTemplates() {
-        const templates = await this.pica.agreementTemplates.list();
-        return formatList(templates, { total: templates.length });
+    // ── Unified CRUD executors ──────────────────────────────────────────
+    async query(args) {
+        const resource = this.getResource(args.type);
+        const items = await resource.list();
+        return formatList(items, { total: items.length });
     }
-    async getTemplate(args) {
-        const template = await this.pica.agreementTemplates.get(args.id);
-        return formatAsText(template);
+    async inspect(args) {
+        const resource = this.getResource(args.type);
+        const item = await resource.get(args.id);
+        return formatAsText(item);
     }
-    async createTemplate(args) {
-        const template = await this.pica.agreementTemplates.create(args);
-        return formatSuccess("Agreement template created", template);
+    async create(args) {
+        const { type, ...fields } = args;
+        const resource = this.getResource(type);
+        const item = await resource.create(fields);
+        // Notification for producer agreements
+        if (type === "producer" && fields.producer_id) {
+            const results = await notifyParties(this.pica, [
+                {
+                    person_id: fields.producer_id,
+                    message: `a producer agreement has been created for "${fields.title || "untitled"}" — please review the terms`,
+                    work_id: fields.work_id,
+                    notification_type: "agreement_created",
+                },
+            ]);
+            const notifySummary = summarizeNotifications(results);
+            if (notifySummary) {
+                return formatSuccess(`Producer agreement created. ${notifySummary}`, item);
+            }
+        }
+        // Notification for work-for-hire
+        if (type === "work_for_hire" && fields.contractor_id) {
+            const results = await notifyParties(this.pica, [
+                {
+                    person_id: fields.contractor_id,
+                    message: `a work-for-hire agreement has been created: "${fields.title || "untitled"}" — please review`,
+                    work_id: fields.work_id,
+                    notification_type: "agreement_created",
+                },
+            ]);
+            const notifySummary = summarizeNotifications(results);
+            if (notifySummary) {
+                return formatSuccess(`Work-for-hire agreement created. ${notifySummary}`, item);
+            }
+        }
+        return formatSuccess(`${this.labelFor(type)} created`, item);
     }
-    async updateTemplate(args) {
-        const { id, ...updates } = args;
-        const template = await this.pica.agreementTemplates.update(id, updates);
-        return formatSuccess("Agreement template updated", template);
+    async update(args) {
+        const { type, id, ...updates } = args;
+        const resource = this.getResource(type);
+        const item = await resource.update(id, updates);
+        return formatSuccess(`${this.labelFor(type)} updated`, item);
     }
-    async deleteTemplate(args) {
-        await this.pica.agreementTemplates.delete(args.id);
-        return formatSuccess(`Agreement template ${args.id} deleted`);
+    async delete(args) {
+        const { type, id } = args;
+        const resource = this.getResource(type);
+        await resource.delete(id);
+        return formatSuccess(`${this.labelFor(type)} ${id} deleted`);
     }
+    // ── Template-specific executors ─────────────────────────────────────
     async renderTemplate(args) {
         const { id, ...renderData } = args;
         const rendered = await this.pica.agreementTemplates.render(id, renderData);
@@ -525,79 +383,5 @@ export class AgreementTypesTools {
         const result = await this.pica.agreementTemplates.setDefault(args.id);
         return formatSuccess("Template set as default for its type", result);
     }
-    // ── Producer agreement executors ───────────────────────────────────
-    async listProducerAgreements() {
-        const agreements = await this.pica.producerAgreements.list();
-        return formatList(agreements, { total: agreements.length });
-    }
-    async getProducerAgreement(args) {
-        const agreement = await this.pica.producerAgreements.get(args.id);
-        return formatAsText(agreement);
-    }
-    async createProducerAgreement(args) {
-        const agreement = await this.pica.producerAgreements.create(args);
-        let notifySummary = "";
-        if (args.producer_id) {
-            const results = await notifyParties(this.pica, [
-                {
-                    person_id: args.producer_id,
-                    message: `a producer agreement has been created for "${args.title || "untitled"}" — please review the terms`,
-                    work_id: args.work_id,
-                    notification_type: "agreement_created",
-                },
-            ]);
-            notifySummary = summarizeNotifications(results);
-        }
-        const msg = notifySummary
-            ? `Producer agreement created. ${notifySummary}`
-            : "Producer agreement created";
-        return formatSuccess(msg, agreement);
-    }
-    async updateProducerAgreement(args) {
-        const { id, ...updates } = args;
-        const agreement = await this.pica.producerAgreements.update(id, updates);
-        return formatSuccess("Producer agreement updated", agreement);
-    }
-    async deleteProducerAgreement(args) {
-        await this.pica.producerAgreements.delete(args.id);
-        return formatSuccess(`Producer agreement ${args.id} deleted`);
-    }
-    // ── Work-for-hire executors ────────────────────────────────────────
-    async listWorkForHire() {
-        const agreements = await this.pica.workForHire.list();
-        return formatList(agreements, { total: agreements.length });
-    }
-    async getWorkForHire(args) {
-        const agreement = await this.pica.workForHire.get(args.id);
-        return formatAsText(agreement);
-    }
-    async createWorkForHire(args) {
-        const agreement = await this.pica.workForHire.create(args);
-        let notifySummary = "";
-        if (args.contractor_id) {
-            const results = await notifyParties(this.pica, [
-                {
-                    person_id: args.contractor_id,
-                    message: `a work-for-hire agreement has been created: "${args.title || "untitled"}" — please review`,
-                    work_id: args.work_id,
-                    notification_type: "agreement_created",
-                },
-            ]);
-            notifySummary = summarizeNotifications(results);
-        }
-        const msg = notifySummary
-            ? `Work-for-hire agreement created. ${notifySummary}`
-            : "Work-for-hire agreement created";
-        return formatSuccess(msg, agreement);
-    }
-    async updateWorkForHire(args) {
-        const { id, ...updates } = args;
-        const agreement = await this.pica.workForHire.update(id, updates);
-        return formatSuccess("Work-for-hire agreement updated", agreement);
-    }
-    async deleteWorkForHire(args) {
-        await this.pica.workForHire.delete(args.id);
-        return formatSuccess(`Work-for-hire agreement ${args.id} deleted`);
-    }
 }
 //# sourceMappingURL=agreement-types.js.map