@withpica/mcp-server 2.1.0

package/dist/tools/works.js

@@ -0,0 +1,517 @@
+/**
+ * Works Tools - MCP tools for managing musical works
+ */
+import { formatAsText, formatSuccess, formatStructuredList, mapGapsToHints, } from "../utils/formatting.js";
+export class WorksTools {
+    pica;
+    constructor(pica) {
+        this.pica = pica;
+    }
+    /**
+     * Get all works tools
+     */
+    getTools() {
+        return [
+            {
+                definition: {
+                    name: "pica_works_list",
+                    description: "List musical works from PICA catalog with optional filters. " +
+                        "→ then: pica_works_get_full (full details), pica_work_completeness (gap check), pica_credits_list (see credits)",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            limit: {
+                                type: "number",
+                                description: "Maximum number of results to return (default: 50)",
+                            },
+                            search: {
+                                type: "string",
+                                description: "Search query to filter works by title or ISWC",
+                            },
+                            verified: {
+                                type: "boolean",
+                                description: "Filter by verification status (true = verified only, false = unverified only)",
+                            },
+                        },
+                    },
+                },
+                executor: this.listWorks.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_works_get",
+                    description: "Get details of a specific musical work by ID. " +
+                        "→ then: pica_works_get_full (all context in one call), pica_credits_list (see credits), pica_work_completeness (gap check)",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            id: {
+                                type: "string",
+                                description: "Work ID",
+                            },
+                        },
+                        required: ["id"],
+                    },
+                },
+                executor: this.getWork.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_works_create",
+                    description: "Create a new musical work. Any field from the Work schema can be passed — " +
+                        "the most commonly used fields are listed below, but additional fields " +
+                        "are also accepted via additionalProperties. " +
+                        "→ then: pica_credits_update (add writers), pica_work_completeness (check gaps), pica_enrich_work (fill identifiers)",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            title: {
+                                type: "string",
+                                description: "Work title (required)",
+                            },
+                            work_type: {
+                                type: "string",
+                                description: "Type of work (required)",
+                                enum: ["song", "library", "demo", "sample"],
+                            },
+                            work_status: {
+                                type: "string",
+                                enum: [
+                                    "demo",
+                                    "unreleased",
+                                    "released",
+                                    "pitched",
+                                    "placed",
+                                    "archived",
+                                ],
+                                description: "Work status (default: unreleased)",
+                            },
+                            iswc: {
+                                type: "string",
+                                description: "International Standard Musical Work Code",
+                            },
+                            isrc: {
+                                type: "string",
+                                description: "International Standard Recording Code",
+                            },
+                            duration_seconds: {
+                                type: "number",
+                                description: "Duration in seconds",
+                            },
+                            genre: {
+                                type: "array",
+                                items: { type: "string" },
+                                description: "Genre tags",
+                            },
+                            mood: {
+                                type: "array",
+                                items: { type: "string" },
+                                description: "Mood tags",
+                            },
+                            primary_artist: {
+                                type: "string",
+                                description: "Primary artist name",
+                            },
+                            primary_artist_id: {
+                                type: "string",
+                                description: "Primary artist person ID",
+                            },
+                            label: {
+                                type: "string",
+                                description: "Record label name",
+                            },
+                            spotify_track_uri: {
+                                type: "string",
+                                description: "Spotify track URI",
+                            },
+                            spotify_url: {
+                                type: "string",
+                                description: "Spotify URL",
+                            },
+                            album_name: {
+                                type: "string",
+                                description: "Album name",
+                            },
+                            album_release_date: {
+                                type: "string",
+                                description: "Album release date (ISO 8601)",
+                            },
+                            album_art_url: {
+                                type: "string",
+                                description: "URL to album artwork",
+                            },
+                            track_number: {
+                                type: "number",
+                                description: "Track number on album",
+                            },
+                            upc: {
+                                type: "string",
+                                description: "Universal Product Code",
+                            },
+                            publisher_name: {
+                                type: "string",
+                                description: "Publisher name",
+                            },
+                            lyrics: {
+                                type: "string",
+                                description: "Lyrics text",
+                            },
+                            lyrics_language: {
+                                type: "string",
+                                description: "Language of lyrics (ISO 639-1)",
+                            },
+                            notes: {
+                                type: "string",
+                                description: "Internal notes",
+                            },
+                        },
+                        required: ["title", "work_type"],
+                        additionalProperties: true,
+                    },
+                },
+                executor: this.createWork.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_works_update",
+                    description: "Update an existing musical work. Any field from the Work schema can be passed — " +
+                        "the most commonly used fields are listed below, but additional fields " +
+                        "(e.g. album_name, album_art_url, track_number, upc, notes, published, " +
+                        "available_for_licensing, vocal_type, energy, danceability, tempo, key) " +
+                        "are also accepted.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            id: {
+                                type: "string",
+                                description: "Work ID (required)",
+                            },
+                            title: {
+                                type: "string",
+                                description: "Work title",
+                            },
+                            iswc: {
+                                type: "string",
+                                description: "International Standard Musical Work Code",
+                            },
+                            isrc: {
+                                type: "string",
+                                description: "International Standard Recording Code (prefer setting on recordings table instead)",
+                            },
+                            duration_seconds: {
+                                type: "number",
+                                description: "Duration in seconds",
+                            },
+                            lyrics: {
+                                type: "string",
+                                description: "Lyrics text",
+                            },
+                            work_status: {
+                                type: "string",
+                                enum: [
+                                    "demo",
+                                    "unreleased",
+                                    "released",
+                                    "pitched",
+                                    "placed",
+                                    "archived",
+                                ],
+                                description: "Work status (state machine validates transitions)",
+                            },
+                            work_type: {
+                                type: "string",
+                                enum: ["song", "library", "demo", "sample"],
+                                description: "Type of work",
+                            },
+                            genre: {
+                                type: "array",
+                                items: { type: "string" },
+                                description: "Genre tags (e.g. ['R&B', 'Soul'])",
+                            },
+                            mood: {
+                                type: "array",
+                                items: { type: "string" },
+                                description: "Mood tags (e.g. ['Uplifting', 'Reflective'])",
+                            },
+                            primary_artist: {
+                                type: "string",
+                                description: "Primary artist name",
+                            },
+                            primary_artist_id: {
+                                type: "string",
+                                description: "Primary artist person ID",
+                            },
+                            label: {
+                                type: "string",
+                                description: "Record label name",
+                            },
+                            spotify_track_uri: {
+                                type: "string",
+                                description: "Spotify track URI (e.g. spotify:track:0b8ZtRm9u3xSzRazABeHFF)",
+                            },
+                            spotify_url: {
+                                type: "string",
+                                description: "Spotify URL (e.g. https://open.spotify.com/track/...)",
+                            },
+                            album_name: {
+                                type: "string",
+                                description: "Album name",
+                            },
+                            album_release_date: {
+                                type: "string",
+                                description: "Album release date (ISO 8601, e.g. 2020-03-06)",
+                            },
+                            album_art_url: {
+                                type: "string",
+                                description: "URL to album artwork image",
+                            },
+                            track_number: {
+                                type: "number",
+                                description: "Track number on album",
+                            },
+                            upc: {
+                                type: "string",
+                                description: "Universal Product Code (album-level barcode)",
+                            },
+                            publisher_name: {
+                                type: "string",
+                                description: "Publisher name",
+                            },
+                            lyrics_language: {
+                                type: "string",
+                                description: "Language of lyrics (ISO 639-1, e.g. 'en')",
+                            },
+                            notes: {
+                                type: "string",
+                                description: "Internal notes",
+                            },
+                        },
+                        required: ["id"],
+                        additionalProperties: true,
+                    },
+                },
+                executor: this.updateWork.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_works_delete",
+                    description: "Delete a musical work",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            id: {
+                                type: "string",
+                                description: "Work ID",
+                            },
+                        },
+                        required: ["id"],
+                    },
+                },
+                executor: this.deleteWork.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_works_verify",
+                    description: "Mark a work as verified",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            id: {
+                                type: "string",
+                                description: "Work ID",
+                            },
+                        },
+                        required: ["id"],
+                    },
+                },
+                executor: this.verifyWork.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_works_search",
+                    description: "Search works by title, ISWC, or other criteria. " +
+                        "→ then: pica_works_get_full (full details), pica_work_completeness (gap check), pica_enrich_work (fill gaps)",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            query: {
+                                type: "string",
+                                description: "Search query",
+                            },
+                            limit: {
+                                type: "number",
+                                description: "Maximum number of results (default: 50)",
+                            },
+                        },
+                        required: ["query"],
+                    },
+                },
+                executor: this.searchWorks.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_works_bulk_delete",
+                    description: "Delete multiple works at once",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            ids: {
+                                type: "array",
+                                description: "Array of work IDs to delete",
+                                items: {
+                                    type: "string",
+                                },
+                            },
+                        },
+                        required: ["ids"],
+                    },
+                },
+                executor: this.bulkDeleteWorks.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_works_get_full",
+                    description: "Get FULL context for a work in a single call — the work record plus all its " +
+                        "credits, recordings, audio files, agreements, completeness score, and registration " +
+                        "status across PROs. Use this instead of making 6+ separate tool calls when you need " +
+                        "to understand or reason about a work's complete state. " +
+                        "→ then: pica_enrich_work (fill gaps), pica_credits_update (fix credits), pica_export_song_registration (register)",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            id: {
+                                type: "string",
+                                description: "Work ID",
+                            },
+                        },
+                        required: ["id"],
+                    },
+                },
+                executor: this.getWorkFull.bind(this),
+            },
+        ];
+    }
+    /**
+     * List works (server-side search and pagination)
+     */
+    async listWorks(args) {
+        const limit = args.limit || 50;
+        const result = await this.pica.works.search({
+            query: args.search,
+            limit,
+        });
+        let items = result.data;
+        // Client-side verified filter (not supported by API query params)
+        if (args.verified !== undefined) {
+            items = items.filter((work) => work.is_verified === args.verified);
+        }
+        return formatStructuredList(items, "work", {
+            total: result.total,
+            limit,
+            hasMore: result.hasMore,
+        });
+    }
+    /**
+     * Get work by ID
+     */
+    async getWork(args) {
+        const work = await this.pica.works.get(args.id);
+        // Enrich with ISRC prefix intelligence if work has ISRC
+        let prefix_intel = null;
+        if (work.isrc) {
+            prefix_intel = await this.pica.recordings.prefixLookup(work.isrc);
+        }
+        return formatAsText({ ...work, prefix_intel });
+    }
+    /**
+     * Create work
+     */
+    async createWork(args) {
+        const work = await this.pica.works.create(args);
+        // Generate completion hints for the newly created work
+        const hints = [];
+        if (work?.id) {
+            try {
+                const completeness = await this.pica.health.getWorkCompleteness(work.id);
+                hints.push(...mapGapsToHints(completeness?.gaps || completeness?.missing || []));
+            }
+            catch {
+                // Best-effort — don't fail the create
+            }
+            // Hint about AI disclosure if not set
+            if (!args.ai_disclosure) {
+                hints.push({
+                    gap: "no_ai_disclosure",
+                    suggestion: "Set AI disclosure — is this work human-made, AI-assisted, or AI-generated? (pica_works_update with ai_disclosure: none/assisted/generated)",
+                    severity: "important",
+                });
+            }
+        }
+        return formatSuccess("Work created successfully", work, hints);
+    }
+    /**
+     * Update work
+     */
+    async updateWork(args) {
+        const { id, ...updates } = args;
+        const work = await this.pica.works.update(id, updates);
+        return formatSuccess("Work updated successfully", work);
+    }
+    /**
+     * Delete work
+     */
+    async deleteWork(args) {
+        await this.pica.works.delete(args.id);
+        return formatSuccess(`Work ${args.id} deleted successfully`);
+    }
+    /**
+     * Verify work
+     */
+    async verifyWork(args) {
+        const work = await this.pica.works.verify(args.id);
+        return formatSuccess("Work verified successfully", work);
+    }
+    /**
+     * Search works (server-side)
+     */
+    async searchWorks(args) {
+        const limit = args.limit || 50;
+        const result = await this.pica.works.search({
+            query: args.query,
+            limit,
+        });
+        return formatStructuredList(result.data, "work", {
+            query: args.query,
+            total: result.total,
+            limit,
+            hasMore: result.hasMore,
+        });
+    }
+    /**
+     * Bulk delete works
+     */
+    async bulkDeleteWorks(args) {
+        await this.pica.works.bulkDelete(args.ids);
+        return formatSuccess(`${args.ids.length} works deleted successfully`);
+    }
+    /**
+     * Get full work context bundle
+     */
+    async getWorkFull(args) {
+        const result = await this.pica.entityContext.getWorkFull(args.id);
+        const data = result;
+        const creditCount = data.credits?.length || 0;
+        const recordingCount = data.recordings?.length || 0;
+        const agreementCount = data.agreements?.length || 0;
+        const title = data.work?.title || args.id;
+        const score = data.work?.completeness_score;
+        const registeredPros = (data.registration || [])
+            .filter((r) => r.registered === true)
+            .map((r) => r.pro);
+        return formatSuccess(`"${title}" — ${creditCount} credits, ${recordingCount} recordings, ` +
+            `${agreementCount} agreements. ` +
+            `Completeness: ${score != null ? `${score}/100` : "not scored"}. ` +
+            `PROs registered: ${registeredPros.length > 0 ? registeredPros.join(", ") : "none"}.`, result);
+    }
+}
+//# sourceMappingURL=works.js.map

package/dist/tools/works.js.map

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

package/dist/utils/credit-gate.d.ts

@@ -0,0 +1,17 @@
+/**
+ * MCP-level pre-flight credit check with MPP inline payment fallback.
+ *
+ * Resolution order:
+ * 1. Check credit balance → sufficient → deduct at API layer → execute tool
+ * 2. Insufficient + MPP configured + credential → charge via MPP → execute + receipt
+ * 3. Insufficient + MPP configured + no credential → return -32042 payment challenge
+ * 4. Insufficient + MPP not configured → return insufficient_credits error with purchase hint
+ *
+ * Credit spending still happens at the API layer for path 1.
+ * MPP charges bypass credits entirely — the agent pays per-operation.
+ */
+import type { PicaClient } from "../pica-sdk.js";
+import type { ToolExecutor } from "../tools/index.js";
+export declare const COST_MAP: Record<string, number>;
+export declare function withCreditGate(pica: PicaClient, actionKey: string, operationName: string, executor: ToolExecutor): ToolExecutor;
+//# sourceMappingURL=credit-gate.d.ts.map

package/dist/utils/credit-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credit-gate.d.ts","sourceRoot":"","sources":["../../src/utils/credit-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAc,MAAM,mBAAmB,CAAC;AASlE,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAQ3C,CAAC;AAeF,wBAAgB,cAAc,CAC5B,IAAI,EAAE,UAAU,EAChB,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,YAAY,GACrB,YAAY,CAgGd"}

package/dist/utils/credit-gate.js

@@ -0,0 +1,111 @@
+/**
+ * MCP-level pre-flight credit check with MPP inline payment fallback.
+ *
+ * Resolution order:
+ * 1. Check credit balance → sufficient → deduct at API layer → execute tool
+ * 2. Insufficient + MPP configured + credential → charge via MPP → execute + receipt
+ * 3. Insufficient + MPP configured + no credential → return -32042 payment challenge
+ * 4. Insufficient + MPP not configured → return insufficient_credits error with purchase hint
+ *
+ * Credit spending still happens at the API layer for path 1.
+ * MPP charges bypass credits entirely — the agent pays per-operation.
+ */
+import { chargeMpp, formatMppPrice, isMppConfigured, MPP_DEFAULT_CURRENCY, } from "./mpp.js";
+export const COST_MAP = {
+    analysis_audio: 1,
+    analysis_lyrics: 1,
+    analysis_audio_identify: 3,
+    external_mlc_lookup: 1,
+    export_song_registration: 1,
+    export_industry_csv: 1,
+    export_catalog_asset_report: 5,
+};
+const GRACE_DEBT_LIMIT = -5;
+/** Operation names for MPP charge descriptions */
+const OPERATION_NAMES = {
+    analysis_audio: "Audio analysis",
+    analysis_lyrics: "Lyrics transcription",
+    analysis_audio_identify: "Audio identification",
+    external_mlc_lookup: "MLC enrichment",
+    export_song_registration: "Song registration export",
+    export_industry_csv: "Industry-ready export",
+    export_catalog_asset_report: "Catalog asset report",
+};
+export function withCreditGate(pica, actionKey, operationName, executor) {
+    const cost = COST_MAP[actionKey];
+    if (!cost)
+        return executor; // free or unknown — pass through
+    return async (args) => {
+        // --- Path 1: Check credit balance ---
+        let balanceInsufficient = false;
+        let available = 0;
+        try {
+            const balanceData = await pica.creditsBalance.getBalance();
+            available =
+                balanceData?.balance ??
+                    balanceData?.data?.balance ??
+                    0;
+            if (available - cost >= GRACE_DEBT_LIMIT) {
+                // Sufficient credits — execute normally (API layer deducts)
+                return executor(args);
+            }
+            balanceInsufficient = true;
+        }
+        catch {
+            // Fail open on credit check errors — let the tool execute
+            return executor(args);
+        }
+        // --- Balance insufficient from here ---
+        // --- Path 2 & 3: Try MPP if configured ---
+        if (balanceInsufficient && isMppConfigured()) {
+            try {
+                // Extract _meta from args if present (threaded from MCP request)
+                const extra = args._meta ? { _meta: args._meta } : {};
+                const currency = args._mpp_currency || MPP_DEFAULT_CURRENCY;
+                const mppResult = await chargeMpp(cost, OPERATION_NAMES[actionKey] || operationName, currency, extra);
+                if (mppResult) {
+                    if (mppResult.status === 402) {
+                        // Path 3: No credential — return payment challenge
+                        // The McpError will be thrown and handled by the MCP SDK
+                        throw mppResult.challenge;
+                    }
+                    // Path 2: Payment succeeded — execute and attach receipt
+                    const toolResult = await executor(args);
+                    return mppResult.withReceipt(toolResult);
+                }
+            }
+            catch (error) {
+                // Re-throw MCP payment errors (they're the 402 challenge)
+                if (error &&
+                    typeof error === "object" &&
+                    "code" in error &&
+                    error.code === -32042) {
+                    throw error;
+                }
+                // MPP failed for other reason — fall through to insufficient_credits
+            }
+        }
+        // --- Path 4: No MPP or MPP failed — return insufficient_credits ---
+        const priceHint = isMppConfigured()
+            ? ` (${formatMppPrice(cost)} via inline payment)`
+            : "";
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        error: "insufficient_credits",
+                        message: `${operationName} costs ${cost} pica credit${cost !== 1 ? "s" : ""}, but you only have ${available}. Purchase more credits to continue.${priceHint}`,
+                        balance: available,
+                        cost,
+                        action: actionKey,
+                        purchase_hint: "Use pica_credits_purchase to get a checkout link, or visit /settings (credits tab).",
+                        fallback_url: "https://withpica.com/settings?tab=credits",
+                    }, null, 2),
+                },
+            ],
+            isError: true,
+        };
+    };
+}
+//# sourceMappingURL=credit-gate.js.map