@withpica/mcp-server 2.7.0 → 2.8.0

package/dist/tools/import-documents.js

@@ -0,0 +1,203 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+import { formatStructuredList, formatSuccess } from "@withpica/mcp-utils";
+export class ImportDocumentTools {
+    pica;
+    constructor(pica) {
+        this.pica = pica;
+    }
+    /**
+     * Get all import document tools
+     */
+    getTools() {
+        return [
+            {
+                definition: {
+                    name: "pica_import_documents_query",
+                    description: "List canonical ingestion documents — the readable, diffable record of every statement import. Filter by source (prs, distrokid, ascap, etc.), period (Q1 2024), or document type (statement, csv_import). Returns summaries without full body text. Use pica_import_documents_inspect for the full document.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            source: {
+                                type: "string",
+                                description: "Filter by source identifier. PROs: prs, ascap, bmi, sesac, socan, apra, gema, sacem. NROs: ppl, soundexchange, gvl. Mechanical: mcps. Distributors: distrokid, tunecore, cdbaby. Revenue: content_id.",
+                            },
+                            period: {
+                                type: "string",
+                                description: "Filter by period label (e.g. Q1 2024, 2024-01)",
+                            },
+                            document_type: {
+                                type: "string",
+                                description: "Filter by document type (e.g. statement, csv_import)",
+                            },
+                            limit: {
+                                type: "number",
+                                description: "Maximum number of results to return (default: 50)",
+                            },
+                        },
+                    },
+                },
+                executor: this.queryImportDocuments.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_import_documents_inspect",
+                    description: "Inspect a specific import document. By default returns the full canonical document " +
+                        "(summary, identity extractions, line items, field mapping, warnings). " +
+                        "Include 'diff' in sections to compare with a second document.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            id: {
+                                type: "string",
+                                description: "Import document ID",
+                            },
+                            sections: {
+                                type: "array",
+                                items: {
+                                    type: "string",
+                                    enum: ["basic", "diff"],
+                                },
+                                description: "Which sections to return (default: ['basic']). Add 'diff' to compare with compare_id.",
+                            },
+                            compare_id: {
+                                type: "string",
+                                description: "Second document ID for diff comparison (required when sections includes 'diff')",
+                            },
+                        },
+                        required: ["id"],
+                    },
+                },
+                executor: this.inspectImportDocument.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_ingest_statement",
+                    description: "Ingest a royalty or distribution statement into PICA. Before calling this tool, convert the raw file contents to canonical Markdown with YAML frontmatter containing: source, period, currency, type. Line items should be structured as a Markdown table. The LLM should perform this conversion from CSV or PDF text before passing to this tool.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            markdown: {
+                                type: "string",
+                                description: "The statement converted to canonical PICA Markdown format with YAML frontmatter and structured body",
+                            },
+                        },
+                        required: ["markdown"],
+                    },
+                },
+                executor: this.ingestStatement.bind(this),
+            },
+        ];
+    }
+    async queryImportDocuments(args) {
+        const docs = await this.pica.importDocuments.list(args);
+        return formatStructuredList(docs, "import document");
+    }
+    async inspectImportDocument(args) {
+        if (!args.id) {
+            return {
+                content: [{ type: "text", text: "id is required" }],
+                isError: true,
+            };
+        }
+        const sections = args.sections || ["basic"];
+        const doc = await this.pica.importDocuments.get(args.id);
+        // If diff is requested, compute and append the diff
+        if (sections.includes("diff")) {
+            if (!args.compare_id) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "compare_id is required when sections includes 'diff'",
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const docB = await this.pica.importDocuments.get(args.compare_id);
+            const diffResult = this.computeDiff(args.id, doc, args.compare_id, docB);
+            if (sections.includes("basic")) {
+                // Return both basic + diff
+                const basicText = doc.body ?? JSON.stringify(doc, null, 2);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: basicText + "\n\n" + diffResult.text,
+                        },
+                    ],
+                    structuredContent: {
+                        document: doc,
+                        diff: diffResult.structured,
+                    },
+                };
+            }
+            // Diff only
+            return {
+                content: [{ type: "text", text: diffResult.text }],
+                structuredContent: diffResult.structured,
+            };
+        }
+        // Basic only (default)
+        return {
+            content: [
+                { type: "text", text: doc.body ?? JSON.stringify(doc, null, 2) },
+            ],
+            structuredContent: doc,
+        };
+    }
+    async ingestStatement(args) {
+        if (!args.markdown) {
+            return {
+                content: [{ type: "text", text: "markdown is required" }],
+                isError: true,
+            };
+        }
+        const result = await this.pica.importDocuments.ingest(args.markdown);
+        return formatSuccess(`Statement ingested successfully. Document ID: ${result.id}`, result);
+    }
+    computeDiff(idA, docA, idB, docB) {
+        const summaryA = docA.summary ?? {};
+        const summaryB = docB.summary ?? {};
+        const lineItemsDelta = (summaryB.line_count ?? 0) - (summaryA.line_count ?? 0);
+        const totalConvertedDelta = (summaryB.total_converted ?? 0) - (summaryA.total_converted ?? 0);
+        const matchedWorksDelta = (summaryB.matched_works ?? 0) - (summaryA.matched_works ?? 0);
+        const warningsDelta = (summaryB.warning_count ?? 0) - (summaryA.warning_count ?? 0);
+        const sign = (n) => (n > 0 ? `+${n}` : String(n));
+        const signF = (n) => (n > 0 ? `+${n.toFixed(2)}` : n.toFixed(2));
+        const table = [
+            `## import document diff`,
+            ``,
+            `| metric | document a | document b | delta |`,
+            `| --- | --- | --- | --- |`,
+            `| source | ${docA.source ?? "—"} | ${docB.source ?? "—"} | — |`,
+            `| period | ${docA.period ?? "—"} | ${docB.period ?? "—"} | — |`,
+            `| line items | ${summaryA.line_count ?? "—"} | ${summaryB.line_count ?? "—"} | ${sign(lineItemsDelta)} |`,
+            `| total converted | ${summaryA.total_converted ?? "—"} | ${summaryB.total_converted ?? "—"} | ${signF(totalConvertedDelta)} |`,
+            `| matched works | ${summaryA.matched_works ?? "—"} | ${summaryB.matched_works ?? "—"} | ${sign(matchedWorksDelta)} |`,
+            `| warnings | ${summaryA.warning_count ?? "—"} | ${summaryB.warning_count ?? "—"} | ${sign(warningsDelta)} |`,
+        ].join("\n");
+        const structured = {
+            document_a: {
+                id: idA,
+                source: docA.source,
+                period: docA.period,
+                summary: summaryA,
+            },
+            document_b: {
+                id: idB,
+                source: docB.source,
+                period: docB.period,
+                summary: summaryB,
+            },
+            deltas: {
+                line_count: lineItemsDelta,
+                total_converted: totalConvertedDelta,
+                matched_works: matchedWorksDelta,
+                warning_count: warningsDelta,
+            },
+        };
+        return { text: table, structured };
+    }
+}
+//# sourceMappingURL=import-documents.js.map

package/dist/tools/import-documents.js.map

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

package/dist/tools/import.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Import Tools - MCP tools for bulk CSV import of works, people, recordings, etc.
+ *
+ * Typical agent flow:
+ * 1. pica_import_analyze — parse CSV and get AI-suggested mappings
+ * 2. pica_import_validate — validate all rows against the mapping
+ * 3. pica_import_execute — run the import (with optional dry_run first)
+ *
+ * Alternative flows:
+ * - pica_import_fields — get available target fields for a domain
+ * - pica_import_template — get an example CSV template
+ */
+import { PicaClient } from "@withpica/mcp-sdk";
+import { ToolDefinition, ToolExecutor } from "./index.js";
+export declare class ImportTools {
+    private pica;
+    constructor(pica: PicaClient);
+    getTools(): Array<{
+        definition: ToolDefinition;
+        executor: ToolExecutor;
+    }>;
+    private analyzeImport;
+    private validateImport;
+    private executeImport;
+    private getImportFields;
+    private getImportTemplate;
+    private importFromSpotify;
+    private importStreamingLink;
+}
+//# sourceMappingURL=import.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"import.d.ts","sourceRoot":"","sources":["../../src/tools/import.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,YAAY,EAAc,MAAM,YAAY,CAAC;AAiBtE,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;YAsP3D,aAAa;YAuBb,cAAc;YAgCd,aAAa;YAkCb,eAAe;YAUf,iBAAiB;YAUjB,iBAAiB;YAgDjB,mBAAmB;CA+HlC"}