@withpica/mcp-server 1.3.0

package/dist/tools/public-filter.js

@@ -0,0 +1,356 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+import { PUBLIC_FORBIDDEN_KEYWORDS_FULL } from "./forbidden-keywords.js";
+// ── Class C: explicit exclude (Phase 1: empty per ADR-202 sign-off 2026-04-27) ──
+const CLASS_C_EXCLUDE = new Set([]);
+// ── Class B: include name, sanitized description ──
+// The source-of-truth descriptions in the per-domain tool files name third-party
+// services (MLC / ISNI / MusicBrainz / Spotify / YouTube / Discogs / ACRCloud /
+// Librosa / Groq) or internal architecture (cascade engine / Tier A/B / identity
+// graph / CAR scoring). The strings here are rewrites that preserve capability
+// signal without leaking the algorithm or vendor binding.
+const CLASS_B_SANITIZED = {
+    // Reclassified from Class C → B per 2026-04-27 sign-off
+    pica_graph_traverse: "Traverse identifier-based connections from any external identifier. Returns connected works, recordings, and people across the catalog.",
+    pica_run_work_cascade: "Re-run metadata enrichment for a work to fill gaps from external sources.",
+    pica_run_person_cascade: "Re-run metadata enrichment for a person to fill gaps from external identity sources.",
+    pica_cascade_health: "Snapshot of recent metadata-enrichment activity — outcome counts and recent failures.",
+    pica_export_catalog_asset_report: "Generate a catalog asset report — a structured summary of catalog completeness and provenance.",
+    pica_car_preview: "Preview a catalog asset report inline before generating the full export.",
+    // Original Class B
+    pica_resolve_work: "Resolve a work against external metadata sources. Returns structured proposals and applied updates.",
+    pica_resolve_person: "Resolve a person against external identity sources. Returns structured proposals and applied updates.",
+    pica_resolve_recording: "Resolve a recording against external metadata sources. Returns structured proposals and applied updates.",
+    pica_enrichment_candidates: "Find catalog entries that are good candidates for metadata enrichment.",
+    pica_enrichment_compare: "Compare what external sources say about a catalog entry, side by side.",
+    pica_registrations_compare: "Compare a work's registration status across society and platform records.",
+    pica_enrichment_propose: "Propose a metadata enrichment from agent research; goes to a review queue.",
+    pica_enrichment_proposals_list: "List pending metadata-enrichment proposals awaiting review.",
+    pica_enrichment_proposal_apply: "Apply a previously proposed metadata enrichment.",
+    pica_enrichment_proposal_reject: "Reject a previously proposed metadata enrichment.",
+    pica_audio_analyze: "Analyze an audio file for tempo, key, energy, and lyric transcription.",
+    pica_audio_identify: "Identify a track via audio fingerprinting. Returns matched metadata with confidence score.",
+    pica_documents_analyse: "Analyse a document with AI. Extracts structured fields from invoices, statements, contracts.",
+    pica_import_streaming_link: "Import a work or recording from a public streaming-service link.",
+    pica_import_from_spotify: "Import a work or recording from a Spotify link.",
+    pica_import_youtube_link: "Import a recording from a YouTube link.",
+    pica_multimedia_import_url: "Import multimedia from a public URL.",
+    pica_multimedia_link_youtube: "Link a YouTube video to a work.",
+    pica_ingest_statement: "Ingest a royalty statement document into the catalog.",
+};
+// ── Class A: explicit allowlist, descriptions ship as-is ──
+// Every Class A tool is enumerated here. New tools added to ToolRegistry must
+// also be added to this list (or to CLASS_B_SANITIZED / CLASS_C_EXCLUDE) to
+// appear on the public surface — default-exclude.
+const CLASS_A_ALLOWLIST = new Set([
+    // Works
+    "pica_works_query",
+    "pica_works_inspect",
+    "pica_works_create",
+    "pica_works_update",
+    "pica_works_delete",
+    "pica_works_verify",
+    "pica_works_bulk_delete",
+    "pica_works_bulk_update",
+    // People
+    "pica_people_query",
+    "pica_people_inspect",
+    "pica_people_create",
+    "pica_people_update",
+    "pica_people_delete",
+    "pica_people_bulk_update_roles",
+    // Recordings
+    "pica_recordings_query",
+    "pica_recordings_inspect",
+    "pica_recordings_create",
+    "pica_recordings_update",
+    "pica_recordings_delete",
+    // Credits (work_credits)
+    "pica_credits_list",
+    "pica_credits_update",
+    // Agreements
+    "pica_agreements_query",
+    "pica_agreements_inspect",
+    "pica_agreements_create",
+    "pica_agreements_update",
+    "pica_agreements_delete",
+    "pica_agreements_link_work",
+    // Agreement types & templates
+    "pica_agreement_types_query",
+    "pica_agreement_types_inspect",
+    "pica_agreement_types_create",
+    "pica_agreement_types_update",
+    "pica_agreement_types_delete",
+    "pica_agreement_templates_render",
+    "pica_agreement_templates_duplicate",
+    "pica_agreement_templates_set_default",
+    // Splits
+    "pica_split_sheet_list",
+    "pica_split_sheet_get",
+    "pica_split_sheet_generate",
+    "pica_split_sheet_send",
+    "pica_recording_splits_list",
+    "pica_recording_splits_create",
+    "pica_recording_splits_verify",
+    // Royalties & statements
+    "pica_royalties_list",
+    "pica_royalties_get",
+    "pica_royalties_summary",
+    "pica_statements_list",
+    "pica_statements_get",
+    // Disputes
+    "pica_disputes_list",
+    // Custody (chain/ trade-secret service backs these — names + read-side
+    // descriptions are publicly used product language; algorithm stays sealed)
+    "pica_custody_list",
+    "pica_custody_history",
+    "pica_custody_claim",
+    "pica_custody_respond",
+    "pica_custody_resolve_pending",
+    "pica_custody_reconcile",
+    // Search & discovery substrate
+    "pica_search_all",
+    "pica_catalog_stats",
+    "pica_search_for_sync",
+    "pica_submit_license_enquiry",
+    "pica_claim_credit",
+    "pica_claim_custody",
+    "pica_claim_artist",
+    "pica_discoveries_query",
+    "pica_discoveries_review",
+    // Dashboard
+    "pica_dashboard_attention",
+    "pica_dashboard_briefing",
+    "pica_dashboard_pulse",
+    // MCP Apps cards (UI-only render, safe)
+    "pica_upload",
+    "pica_download",
+    // Audio (analyze + identify are Class B; the rest are A)
+    "pica_audio_query",
+    "pica_audio_inspect",
+    "pica_audio_presigned_upload",
+    "pica_audio_complete_upload",
+    // Multimedia (import_url + link_youtube are Class B; the rest are A)
+    "pica_multimedia_search",
+    "pica_multimedia_create",
+    "pica_multimedia_link_work",
+    // Uploads
+    "pica_upload_file",
+    "pica_upload_complete",
+    // Exports (CAR is Class B; the rest are A)
+    "pica_export_catalog_csv",
+    "pica_export_song_registration",
+    "pica_export_industry_ready",
+    "pica_export_ai_consent",
+    // Calendar
+    "pica_calendar_events",
+    // Duplicates
+    "pica_find_duplicates",
+    "pica_merge_duplicates",
+    // Projects
+    "pica_projects_list",
+    "pica_projects_get",
+    "pica_projects_create",
+    "pica_projects_update",
+    "pica_projects_delete",
+    "pica_projects_attach_works",
+    // Releases
+    "pica_releases_list",
+    "pica_releases_get",
+    "pica_releases_create",
+    "pica_releases_update",
+    "pica_releases_attach_track",
+    "pica_releases_list_tracks",
+    "pica_releases_detach_track",
+    "pica_releases_reorder_tracks",
+    "pica_releases_attach_recording_with_work",
+    "pica_releases_bulk_attach_tracks",
+    "pica_releases_move_track",
+    "pica_releases_attach_track_by_identifier",
+    "pica_releases_create_with_tracks",
+    "pica_releases_completeness_check",
+    // ADR-208 Phase 3 Primitive D — rich render
+    "pica_release_show",
+    // Sessions
+    "pica_sessions_list",
+    "pica_sessions_get",
+    "pica_sessions_create",
+    "pica_sessions_types",
+    // Notes
+    "pica_notes_list",
+    "pica_notes_get",
+    "pica_notes_create",
+    "pica_notes_delete",
+    // Physical assets
+    "pica_physical_assets_query",
+    "pica_physical_assets_inspect",
+    "pica_physical_assets_create",
+    "pica_physical_assets_update",
+    "pica_physical_assets_delete",
+    "pica_physical_assets_stats",
+    "pica_physical_assets_export",
+    "pica_physical_assets_link_work",
+    "pica_physical_assets_link_recording",
+    "pica_physical_assets_unlink_work",
+    "pica_physical_assets_unlink_recording",
+    // Analytics
+    "pica_carbon_footprint",
+    "pica_carbon_live",
+    "pica_provenance_stats",
+    "pica_provenance_work",
+    "pica_provenance_certificate",
+    "pica_catalog_diligence",
+    // Import (streaming/spotify/youtube/ingest_statement are Class B; the rest are A)
+    "pica_import_analyze",
+    "pica_import_validate",
+    "pica_import_execute",
+    "pica_import_fields",
+    "pica_import_template",
+    "pica_import_documents_query",
+    "pica_import_documents_inspect",
+    // Notifications
+    "pica_notifications_list",
+    "pica_notify_person",
+    "pica_notifications_mark_read",
+    // Collaborators
+    "pica_collaborators_invite",
+    "pica_collaborators_invites_list",
+    "pica_collaborators_invite_resend",
+    "pica_collaborators_incoming_list",
+    "pica_collaborators_accept",
+    "pica_collaborators_dispute",
+    "pica_collaborators_invite_bulk",
+    // Send hub
+    "pica_send_message",
+    "pica_send_query",
+    "pica_send_resend",
+    // Share links
+    "pica_share_links_list",
+    "pica_share_links_create",
+    // Telegram
+    "pica_telegram_status",
+    "pica_telegram_connect",
+    "pica_notify_user",
+    "pica_notify_user_at",
+    "pica_notify_user_list_pending",
+    "pica_notify_user_cancel",
+    // Publishers / labels
+    "pica_publishers_query",
+    "pica_publishers_create",
+    "pica_labels_query",
+    // Licensing
+    "pica_list_license_enquiries",
+    "pica_get_license_enquiry",
+    "pica_update_license_enquiry_status",
+    // Team
+    "pica_team_list",
+    "pica_team_get",
+    "pica_team_invite",
+    "pica_team_update_role",
+    "pica_team_remove",
+    // Audit
+    "pica_audit_list",
+    // Memory
+    "pica_memory_list",
+    "pica_memory_search",
+    "pica_memory_save",
+    "pica_memory_delete",
+    // Settings
+    "pica_storage_status",
+    "pica_organisation_profile",
+    "pica_user_profile",
+    "pica_directory_settings",
+    "pica_integrations_status",
+    "pica_get_privacy_settings",
+    "pica_update_privacy_settings",
+    "pica_export_my_data",
+    "pica_delete_my_account",
+    "pica_update_my_identity",
+    "pica_update_organisation_profile",
+    // Feedback / report-issue
+    "pica_submit_feedback",
+    "pica_report_issue",
+    "pica_my_reported_issues",
+    // Agent identity
+    "pica_create_agent_identity",
+    "pica_issue_agent_grant",
+    "pica_list_my_agent_grants",
+    "pica_revoke_agent_grant",
+    "pica_get_agent_activity",
+]);
+// ── Meta-tools — never on the public surface ──
+// pica_discover / pica_tool_details / pica_execute only make sense once
+// authenticated; pica_sign_in / pica_sign_out are stdio-lobby tools.
+const META_TOOL_EXCLUDE = new Set([
+    "pica_discover",
+    "pica_tool_details",
+    "pica_execute",
+    "pica_sign_in",
+    "pica_sign_out",
+]);
+// ── Forbidden keywords (AC-4 in ADR-202) ──
+// Source-of-truth list lives at `./forbidden-keywords.ts` and is shared
+// with the `scripts/lint-mcp-tools.ts` description-hygiene check
+// (ADR-180 Rule 9, 2026-05-02 amendment).
+//
+// The lobby surface uses the full union (PUBLIC ∪ AUTHENTICATED) — every
+// vendor / data-source / infra / library / concept term that's banned for
+// any audience is also banned at the unauthenticated boundary.
+const FORBIDDEN_KEYWORD_FRAGMENTS = PUBLIC_FORBIDDEN_KEYWORDS_FULL;
+/**
+ * Apply ADR-202 filtering to a list of ToolDefinitions.
+ *
+ * Order of operations:
+ *   1. Drop META_TOOL_EXCLUDE
+ *   2. Drop CLASS_C_EXCLUDE
+ *   3. Drop anything not in CLASS_A_ALLOWLIST and not in CLASS_B_SANITIZED
+ *      (default-exclude)
+ *   4. If readOnlyOnly: drop tools whose risk metadata is not "safe"
+ *   5. Replace description for CLASS_B_SANITIZED entries
+ *   6. Strip executor reference (return PublicToolDefinition only)
+ */
+export function filterToolsForPublicDiscovery(tools, options) {
+    const readOnlyOnly = options.readOnlyOnly ?? true;
+    const result = [];
+    for (const tool of tools) {
+        if (META_TOOL_EXCLUDE.has(tool.name))
+            continue;
+        if (CLASS_C_EXCLUDE.has(tool.name))
+            continue;
+        const isB = tool.name in CLASS_B_SANITIZED;
+        const isA = CLASS_A_ALLOWLIST.has(tool.name);
+        if (!isA && !isB)
+            continue; // default-exclude
+        if (readOnlyOnly) {
+            const meta = options.metadataLookup(tool.name);
+            if (meta?.risk !== "safe")
+                continue;
+        }
+        const description = isB ? CLASS_B_SANITIZED[tool.name] : tool.description;
+        result.push({
+            name: tool.name,
+            description,
+            inputSchema: tool.inputSchema,
+            annotations: tool.annotations,
+        });
+    }
+    return result;
+}
+/** Returns the first forbidden keyword found in a string, or null. */
+export function findForbiddenKeyword(text) {
+    const lower = text.toLowerCase();
+    for (const fragment of FORBIDDEN_KEYWORD_FRAGMENTS) {
+        if (lower.includes(fragment.toLowerCase()))
+            return fragment;
+    }
+    return null;
+}
+// Internal exports for test introspection only — consumers use
+// filterToolsForPublicDiscovery + findForbiddenKeyword.
+export const _internal = {
+    CLASS_A_ALLOWLIST,
+    CLASS_B_SANITIZED,
+    CLASS_C_EXCLUDE,
+    META_TOOL_EXCLUDE,
+    FORBIDDEN_KEYWORD_FRAGMENTS,
+};
+//# sourceMappingURL=public-filter.js.map

package/dist/tools/public-filter.js.map

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

package/dist/tools/publishers.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Publishers Tools - MCP tools for querying and creating publisher records.
+ *
+ * ADR-174 Phase 2 item 22: `pica_publishers_create` is stdio-only (no
+ * mcp-server-business counterpart) so the schema lives inline rather than
+ * going through `@withpica/mcp-utils/write-schemas`. The route-layer
+ * allow-list at `lib/services/publishers-write-constants.ts` is the
+ * authoritative enforcement boundary; this schema is the agent-facing
+ * contract and surfaces the same shape so the tool advertises every
+ * writable column on `global_publishers`.
+ *
+ * Pre-slice the schema accepted `{ name, ipi }` and every other DB
+ * column was invisible to agents. Post-slice all 8 audit-row-22
+ * Add-candidates are exposed, and the `ipi → ipi_number` rename is
+ * explicit (the route returns a PHANTOM_FIELD error with a rename hint
+ * if `ipi` is still sent).
+ */
+import { PicaClient } from "@withpica/mcp-sdk";
+import { ToolDefinition, ToolExecutor } from "./index.js";
+export declare class PublishersTools {
+    private pica;
+    constructor(pica: PicaClient);
+    getTools(): Array<{
+        definition: ToolDefinition;
+        executor: ToolExecutor;
+    }>;
+    private queryPublishers;
+    private createPublisher;
+}
+//# sourceMappingURL=publishers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"publishers.d.ts","sourceRoot":"","sources":["../../src/tools/publishers.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,YAAY,EAAc,MAAM,YAAY,CAAC;AAGtE,qBAAa,eAAe;IAC1B,OAAO,CAAC,IAAI,CAAa;gBAEb,IAAI,EAAE,UAAU;IAI5B,QAAQ,IAAI,KAAK,CAAC;QAAE,UAAU,EAAE,cAAc,CAAC;QAAC,QAAQ,EAAE,YAAY,CAAA;KAAE,CAAC;YA0F3D,eAAe;YAaf,eAAe;CAQ9B"}

package/dist/tools/publishers.js

@@ -0,0 +1,105 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+import { formatStructuredList, formatSuccess } from "@withpica/mcp-utils";
+export class PublishersTools {
+    pica;
+    constructor(pica) {
+        this.pica = pica;
+    }
+    getTools() {
+        return [
+            {
+                definition: {
+                    name: "pica_publishers_query",
+                    description: "Find publishers by name or IPI. Use before setting publisher on credits. " +
+                        "→ then: pica_credits_update (link publisher to a credit)",
+                    workflows: "infrastructure",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            query: {
+                                type: "string",
+                                description: "Search by publisher name or IPI",
+                            },
+                            limit: {
+                                type: "number",
+                                description: "Max results (default: 50)",
+                            },
+                        },
+                    },
+                },
+                executor: this.queryPublishers.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_publishers_create",
+                    description: "Create (or fetch existing) publisher in the catalog-wide " +
+                        "`global_publishers` table. Idempotent by ipi_number — if a " +
+                        "publisher with the same IPI already exists, returns the existing " +
+                        "row. Check `pica_publishers_query` first to avoid duplicates and " +
+                        "to resolve parent_publisher_id.",
+                    workflows: "infrastructure",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            name: { type: "string", description: "Publisher name." },
+                            ipi_number: {
+                                type: "string",
+                                description: "Publisher IPI number (9-11 digits; normalised to 11 with " +
+                                    "leading zero-padding). Required.",
+                            },
+                            legal_name: {
+                                type: "string",
+                                description: "Legal entity name (e.g. 'Example Publishing Ltd.') — optional.",
+                            },
+                            country: {
+                                type: "string",
+                                description: "ISO country code (e.g. 'GB', 'US').",
+                            },
+                            isni: {
+                                type: "string",
+                                description: "ISNI identifier (16-character alphanumeric) if the publisher has one.",
+                            },
+                            publisher_type: {
+                                type: "string",
+                                description: "Category label (e.g. 'major', 'indie', 'admin', 'self_published'). Freeform — no backend CHECK.",
+                            },
+                            wikidata_id: {
+                                type: "string",
+                                description: "Wikidata Q-number (e.g. 'Q123456').",
+                            },
+                            parent_publisher_id: {
+                                type: "string",
+                                description: "UUID of parent publisher for subsidiary/admin relationships. FK → global_publishers.id. Use `pica_publishers_query` to find the parent's ID before passing it here; the route returns FK_NOT_FOUND if the UUID does not exist.",
+                            },
+                            founded_date: {
+                                type: "string",
+                                description: "Founding date (YYYY-MM-DD).",
+                            },
+                            headquarters: {
+                                type: "string",
+                                description: "Freeform location (e.g. 'London, UK').",
+                            },
+                        },
+                        required: ["name", "ipi_number"],
+                    },
+                },
+                executor: this.createPublisher.bind(this),
+            },
+        ];
+    }
+    async queryPublishers(args) {
+        const result = await this.pica.publishers.list({
+            query: args.query,
+            limit: args.limit || 50,
+        });
+        const publishers = Array.isArray(result) ? result : result?.data || [];
+        return formatStructuredList(publishers, "publisher", {
+            total: publishers.length,
+        });
+    }
+    async createPublisher(args) {
+        const result = await this.pica.publishers.create(args);
+        return formatSuccess("Publisher created", result);
+    }
+}
+//# sourceMappingURL=publishers.js.map

package/dist/tools/publishers.js.map

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

package/dist/tools/purchases.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Purchases Tools — intentionally empty.
+ *
+ * `pica_credits_purchase` was removed from the MCP surface 2026-04-22 (see
+ * docs/MCP_REFINEMENT_LOG.md entry B-001). The underlying SDK method,
+ * `POST /api/admin/credits/purchase` route, and `createCreditPurchaseSession`
+ * were retired 2026-05-06 with the move to capacity-tier subscriptions
+ * (ADR-205). The Stripe webhook handler still recognises the legacy
+ * `credit_purchase` metadata to award credits if any stale checkout session
+ * completes; `creditsService.getPackageById` and `getPackages` are retained
+ * for that webhook path plus historical revenue reporting in
+ * `app/api/team/finances/overview/route.ts`. Do not delete those helpers
+ * even though the active surface looks dead.
+ *
+ * Kept as a class with an empty `getTools()` so tools/index.ts doesn't need
+ * to change imports or wiring — the class is a deliberate tombstone.
+ */
+import { PicaClient } from "@withpica/mcp-sdk";
+import { ToolDefinition, ToolExecutor } from "./index.js";
+export declare class PurchasesTools {
+    constructor(_pica: PicaClient);
+    getTools(): Array<{
+        definition: ToolDefinition;
+        executor: ToolExecutor;
+    }>;
+}
+//# sourceMappingURL=purchases.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"purchases.d.ts","sourceRoot":"","sources":["../../src/tools/purchases.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1D,qBAAa,cAAc;gBAEb,KAAK,EAAE,UAAU;IAE7B,QAAQ,IAAI,KAAK,CAAC;QAAE,UAAU,EAAE,cAAc,CAAC;QAAC,QAAQ,EAAE,YAAY,CAAA;KAAE,CAAC;CAG1E"}

package/dist/tools/purchases.js

@@ -0,0 +1,9 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+export class PurchasesTools {
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    constructor(_pica) { }
+    getTools() {
+        return [];
+    }
+}
+//# sourceMappingURL=purchases.js.map

package/dist/tools/purchases.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"purchases.js","sourceRoot":"","sources":["../../src/tools/purchases.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAuB7D,MAAM,OAAO,cAAc;IACzB,6DAA6D;IAC7D,YAAY,KAAiB,IAAG,CAAC;IAEjC,QAAQ;QACN,OAAO,EAAE,CAAC;IACZ,CAAC;CACF"}

package/dist/tools/recording-attribution-hints.d.ts

@@ -0,0 +1,24 @@
+/**
+ * ADR-213 Primitive A — completion hints for pica_recordings_create.
+ *
+ * Mirror of buildCustodyHints (works-side) for recordings. When a fresh
+ * recording is created, three Important-severity hints prompt the rights
+ * conversation by default:
+ *
+ * 1. recording_ownership_unset — fires when ownership_percentage IS NULL.
+ *    NULL = "not set"; 0 = explicit zero (no hint, user has declared no
+ *    ownership); 1-100 = already declared.
+ * 2. recording_no_credits — always fires (we never know credits from a
+ *    single fresh row). Points at pica_recording_credits_update.
+ * 3. recording_master_unclaimed — fires when ownership_percentage IS NULL.
+ *    Alternative path to #1 for orgs that want a formal chain claim
+ *    (label / co-producer scenarios) rather than a flat percentage.
+ *
+ * Defensive shape — the SDK's `Recording` TS interface does not declare
+ * `ownership_percentage`, but the API returns it as JSON pass-through
+ * from `recordingsService.create`. Callers pass the raw recording object;
+ * we read fields with a typed wrapper.
+ */
+import type { CompletionHint } from "@withpica/mcp-utils";
+export declare function buildRecordingAttributionHints(recording: unknown): CompletionHint[];
+//# sourceMappingURL=recording-attribution-hints.d.ts.map

package/dist/tools/recording-attribution-hints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recording-attribution-hints.d.ts","sourceRoot":"","sources":["../../src/tools/recording-attribution-hints.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAM1D,wBAAgB,8BAA8B,CAC5C,SAAS,EAAE,OAAO,GACjB,cAAc,EAAE,CAiClB"}

package/dist/tools/recording-attribution-hints.js

@@ -0,0 +1,27 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+export function buildRecordingAttributionHints(recording) {
+    const r = (recording ?? {});
+    const hints = [];
+    const ownershipUnset = r.ownership_percentage === null || r.ownership_percentage === undefined;
+    if (ownershipUnset) {
+        hints.push({
+            gap: "recording_ownership_unset",
+            severity: "important",
+            suggestion: "What % of this recording's master is owned by your org? Call pica_recordings_update with ownership_percentage:N (0-100). Skip if you hold no master stake.",
+        });
+    }
+    hints.push({
+        gap: "recording_no_credits",
+        severity: "important",
+        suggestion: "Who performed on this recording? Add performer / producer / engineer credits via pica_recording_credits_update — one call per credited person. Resolve names to person_id via pica_people_query first.",
+    });
+    if (ownershipUnset) {
+        hints.push({
+            gap: "recording_master_unclaimed",
+            severity: "important",
+            suggestion: "If the master is co-owned (label, co-producer, multi-party), claim a formal chain stake via pica_custody_claim with chain='master' instead of just setting ownership_percentage. Same outcome, richer attribution.",
+        });
+    }
+    return hints;
+}
+//# sourceMappingURL=recording-attribution-hints.js.map

package/dist/tools/recording-attribution-hints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recording-attribution-hints.js","sourceRoot":"","sources":["../../src/tools/recording-attribution-hints.ts"],"names":[],"mappings":"AAAA,6DAA6D;AA8B7D,MAAM,UAAU,8BAA8B,CAC5C,SAAkB;IAElB,MAAM,CAAC,GAAG,CAAC,SAAS,IAAI,EAAE,CAA6B,CAAC;IACxD,MAAM,KAAK,GAAqB,EAAE,CAAC;IAEnC,MAAM,cAAc,GAClB,CAAC,CAAC,oBAAoB,KAAK,IAAI,IAAI,CAAC,CAAC,oBAAoB,KAAK,SAAS,CAAC;IAE1E,IAAI,cAAc,EAAE,CAAC;QACnB,KAAK,CAAC,IAAI,CAAC;YACT,GAAG,EAAE,2BAA2B;YAChC,QAAQ,EAAE,WAAW;YACrB,UAAU,EACR,4JAA4J;SAC/J,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,IAAI,CAAC;QACT,GAAG,EAAE,sBAAsB;QAC3B,QAAQ,EAAE,WAAW;QACrB,UAAU,EACR,wMAAwM;KAC3M,CAAC,CAAC;IAEH,IAAI,cAAc,EAAE,CAAC;QACnB,KAAK,CAAC,IAAI,CAAC;YACT,GAAG,EAAE,4BAA4B;YACjC,QAAQ,EAAE,WAAW;YACrB,UAAU,EACR,oNAAoN;SACvN,CAAC,CAAC;IACL,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}