@withpica/mcp-server 2.1.0

package/dist/tools/multimedia.js

@@ -0,0 +1,293 @@
+/**
+ * Multimedia Tools - MCP tools for managing multimedia assets
+ */
+import { formatList, formatSuccess } from "../utils/formatting.js";
+export class MultimediaTools {
+    pica;
+    constructor(pica) {
+        this.pica = pica;
+    }
+    getTools() {
+        return [
+            {
+                definition: {
+                    name: "pica_multimedia_search",
+                    description: "Search and list multimedia assets — photos, videos, audio, YouTube, Spotify, SoundCloud. Supports filtering by type, classification, published status, and linked work or person.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            query: {
+                                type: "string",
+                                description: "Full-text search across title, caption, and description",
+                            },
+                            content_type: {
+                                type: "string",
+                                description: "Filter by content type",
+                                enum: [
+                                    "uploaded_photo",
+                                    "uploaded_video",
+                                    "uploaded_audio",
+                                    "youtube_video",
+                                    "spotify_track",
+                                    "soundcloud_track",
+                                    "live_performance",
+                                ],
+                            },
+                            classification: {
+                                type: "string",
+                                description: "Filter by classification",
+                                enum: [
+                                    "sync_placement",
+                                    "music_video",
+                                    "behind_the_scenes",
+                                    "live_performance",
+                                    "promo_material",
+                                    "album_artwork",
+                                    "studio_session",
+                                    "artist_showcase",
+                                    "general",
+                                ],
+                            },
+                            is_published: {
+                                type: "boolean",
+                                description: "Filter by published status",
+                            },
+                            work_id: {
+                                type: "string",
+                                description: "Filter by linked work ID",
+                            },
+                            person_id: {
+                                type: "string",
+                                description: "Filter by linked person ID",
+                            },
+                            limit: {
+                                type: "number",
+                                description: "Maximum results (default: 50, max: 200)",
+                            },
+                            offset: {
+                                type: "number",
+                                description: "Pagination offset (default: 0)",
+                            },
+                        },
+                    },
+                },
+                executor: this.searchMultimedia.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_multimedia_create",
+                    description: "Create a multimedia item. Use for linking external content (YouTube, Spotify, SoundCloud URLs) or registering uploaded media.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            title: {
+                                type: "string",
+                                description: "Title of the multimedia item",
+                            },
+                            content_type: {
+                                type: "string",
+                                description: "Type of content",
+                                enum: [
+                                    "uploaded_photo",
+                                    "uploaded_video",
+                                    "uploaded_audio",
+                                    "youtube_video",
+                                    "spotify_track",
+                                    "soundcloud_track",
+                                    "live_performance",
+                                ],
+                            },
+                            url: {
+                                type: "string",
+                                description: "URL of the media (YouTube URL, Spotify URI, SoundCloud URL, etc.)",
+                            },
+                            classification: {
+                                type: "string",
+                                description: "Classification of the content",
+                                enum: [
+                                    "sync_placement",
+                                    "music_video",
+                                    "behind_the_scenes",
+                                    "live_performance",
+                                    "promo_material",
+                                    "album_artwork",
+                                    "studio_session",
+                                    "artist_showcase",
+                                    "general",
+                                ],
+                            },
+                            caption: {
+                                type: "string",
+                                description: "Caption or subtitle",
+                            },
+                            description: {
+                                type: "string",
+                                description: "Detailed description",
+                            },
+                            tags: {
+                                type: "array",
+                                description: "Tags for categorization",
+                                items: { type: "string" },
+                            },
+                        },
+                        required: ["title", "content_type"],
+                    },
+                },
+                executor: this.createMultimedia.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_multimedia_import_url",
+                    description: "Import multimedia from an external URL — downloads the image/video and stores it in PICA. " +
+                        "Works with any public http/https image or video URL (e.g. Spotify artwork, web images). " +
+                        "For YouTube videos, use pica_multimedia_link_youtube instead.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            url: {
+                                type: "string",
+                                description: "Public URL of the image or video to import",
+                            },
+                            title: {
+                                type: "string",
+                                description: "Title for the multimedia item",
+                            },
+                            source: {
+                                type: "string",
+                                description: "Source label (e.g. 'spotify', 'web', 'press_kit')",
+                            },
+                            work_id: {
+                                type: "string",
+                                description: "Optional work ID to link the imported media to",
+                            },
+                        },
+                        required: ["url"],
+                    },
+                },
+                executor: this.importFromUrl.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_multimedia_link_youtube",
+                    description: "Link a YouTube video to PICA. Creates a multimedia item with YouTube metadata " +
+                        "(thumbnail, title, view count). Can optionally link to a work.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            youtube_video_id: {
+                                type: "string",
+                                description: "YouTube video ID (e.g. 'dQw4w9WgXcQ' from youtube.com/watch?v=dQw4w9WgXcQ)",
+                            },
+                            title: {
+                                type: "string",
+                                description: "Title for the multimedia item",
+                            },
+                            classification: {
+                                type: "string",
+                                description: "Classification type",
+                                enum: [
+                                    "sync_placement",
+                                    "music_video",
+                                    "behind_the_scenes",
+                                    "live_performance",
+                                    "promo_material",
+                                    "general",
+                                ],
+                            },
+                            work_id: {
+                                type: "string",
+                                description: "Optional work ID to link the video to",
+                            },
+                            work_relationship_type: {
+                                type: "string",
+                                description: "Relationship type when linking to a work (e.g. 'music_video_for', 'sync_placement')",
+                            },
+                        },
+                        required: ["youtube_video_id", "title"],
+                    },
+                },
+                executor: this.linkYoutube.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_multimedia_link_work",
+                    description: "Link an existing multimedia item to a work. Creates a relationship between " +
+                        "the multimedia (photo, video, audio) and a musical work.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            multimedia_id: {
+                                type: "string",
+                                description: "The multimedia item ID",
+                            },
+                            work_id: {
+                                type: "string",
+                                description: "The work ID to link to",
+                            },
+                            relationship_type: {
+                                type: "string",
+                                description: "Type of relationship",
+                                enum: [
+                                    "featured_in",
+                                    "music_video_for",
+                                    "cover_performance",
+                                    "album_artwork",
+                                    "behind_the_scenes",
+                                    "sync_placement",
+                                    "general",
+                                ],
+                            },
+                            notes: {
+                                type: "string",
+                                description: "Optional notes about the relationship",
+                            },
+                        },
+                        required: ["multimedia_id", "work_id", "relationship_type"],
+                    },
+                },
+                executor: this.linkWork.bind(this),
+            },
+        ];
+    }
+    async searchMultimedia(args) {
+        const result = await this.pica.multimedia.search({
+            query: args.query,
+            content_type: args.content_type,
+            classification: args.classification,
+            is_published: args.is_published,
+            work_id: args.work_id,
+            person_id: args.person_id,
+            limit: args.limit,
+            offset: args.offset,
+        });
+        return formatList(result.data || [], { total: result.count || 0 });
+    }
+    async createMultimedia(args) {
+        const item = await this.pica.multimedia.create(args);
+        return formatSuccess("Multimedia item created", item);
+    }
+    async importFromUrl(args) {
+        const item = await this.pica.multimedia.importFromUrl({
+            url: args.url,
+            title: args.title,
+            source: args.source,
+            work_id: args.work_id,
+        });
+        return formatSuccess(`Imported from URL: "${item.title || args.url}". Multimedia ID: ${item.id}`, item);
+    }
+    async linkYoutube(args) {
+        const item = await this.pica.multimedia.linkYoutube({
+            youtube_video_id: args.youtube_video_id,
+            title: args.title,
+            classification: args.classification,
+            work_id: args.work_id,
+            work_relationship_type: args.work_relationship_type,
+        });
+        return formatSuccess(`YouTube video linked: "${item.title || args.youtube_video_id}". Multimedia ID: ${item.id}`, item);
+    }
+    async linkWork(args) {
+        const result = await this.pica.multimedia.linkWork(args.multimedia_id, args.work_id, args.relationship_type, args.notes);
+        return formatSuccess(`Multimedia ${args.multimedia_id} linked to work ${args.work_id} as "${args.relationship_type}".`, result);
+    }
+}
+//# sourceMappingURL=multimedia.js.map

package/dist/tools/multimedia.js.map

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

package/dist/tools/notes.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Notes Tools — add and manage notes on works, people, and general catalog observations
+ *
+ * Backed by the assistant_memory system (type: "note") via REST routes (/api/admin/notes/*).
+ * Notes support auto-linking to works and people mentioned in the text via Tier 1 extraction.
+ */
+import { PicaClient } from "../pica-sdk.js";
+import { ToolDefinition, ToolExecutor } from "./index.js";
+export declare class NotesTools {
+    private pica;
+    constructor(pica: PicaClient);
+    getTools(): Array<{
+        definition: ToolDefinition;
+        executor: ToolExecutor;
+    }>;
+    private listNotes;
+    private getNote;
+    private createNote;
+    private deleteNote;
+}
+//# sourceMappingURL=notes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"notes.d.ts","sourceRoot":"","sources":["../../src/tools/notes.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,YAAY,EAAc,MAAM,YAAY,CAAC;AAGtE,qBAAa,UAAU;IACrB,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;YA2F3D,SAAS;YAWT,OAAO;YAKP,UAAU;YAQV,UAAU;CAIzB"}

package/dist/tools/notes.js

@@ -0,0 +1,126 @@
+/**
+ * Notes Tools — add and manage notes on works, people, and general catalog observations
+ *
+ * Backed by the assistant_memory system (type: "note") via REST routes (/api/admin/notes/*).
+ * Notes support auto-linking to works and people mentioned in the text via Tier 1 extraction.
+ */
+import { formatSuccess, formatStructuredList } from "../utils/formatting.js";
+export class NotesTools {
+    pica;
+    constructor(pica) {
+        this.pica = pica;
+    }
+    getTools() {
+        return [
+            {
+                definition: {
+                    name: "pica_notes_list",
+                    description: "List notes — filter by search query, linked work, or linked person. Notes can be attached to works, people, or stand alone.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            q: {
+                                type: "string",
+                                description: "Search notes by content or title",
+                            },
+                            work_id: {
+                                type: "string",
+                                description: "Filter notes linked to a specific work",
+                            },
+                            person_id: {
+                                type: "string",
+                                description: "Filter notes linked to a specific person",
+                            },
+                            limit: {
+                                type: "number",
+                                description: "Max results (default 20)",
+                            },
+                        },
+                    },
+                },
+                executor: this.listNotes.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_notes_get",
+                    description: "Get a specific note by ID.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            id: { type: "string", description: "Note ID" },
+                        },
+                        required: ["id"],
+                    },
+                },
+                executor: this.getNote.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_notes_create",
+                    description: "Add a note to the catalog. Notes can be linked to specific works or people, or stand alone as general observations. PICA auto-detects mentions of works and people in the note text.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            content: {
+                                type: "string",
+                                description: "The note text. Can mention work titles or people names — PICA will auto-link them.",
+                            },
+                            work_ids: {
+                                type: "array",
+                                items: { type: "string" },
+                                description: "Optional: explicitly link to these work IDs",
+                            },
+                            people_ids: {
+                                type: "array",
+                                items: { type: "string" },
+                                description: "Optional: explicitly link to these person IDs",
+                            },
+                        },
+                        required: ["content"],
+                    },
+                },
+                executor: this.createNote.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_notes_delete",
+                    description: "Delete a note.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            id: { type: "string", description: "Note ID to delete" },
+                        },
+                        required: ["id"],
+                    },
+                },
+                executor: this.deleteNote.bind(this),
+            },
+        ];
+    }
+    async listNotes(args) {
+        const result = await this.pica.notes.list({
+            q: args.q,
+            work: args.work_id,
+            person: args.person_id,
+            limit: args.limit,
+        });
+        const notes = Array.isArray(result) ? result : [];
+        return formatStructuredList(notes, "note");
+    }
+    async getNote(args) {
+        const note = await this.pica.notes.get(args.id);
+        return formatSuccess("Note retrieved", note);
+    }
+    async createNote(args) {
+        const note = await this.pica.notes.create(args.content, {
+            work_ids: args.work_ids,
+            people_ids: args.people_ids,
+        });
+        return formatSuccess("Note added", note);
+    }
+    async deleteNote(args) {
+        await this.pica.notes.delete(args.id);
+        return formatSuccess(`Note ${args.id} deleted`);
+    }
+}
+//# sourceMappingURL=notes.js.map

package/dist/tools/notes.js.map

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

package/dist/tools/notifications.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Notifications Tools — check and manage PICA notifications via MCP
+ */
+import { PicaClient } from "../pica-sdk.js";
+import { ToolDefinition, ToolExecutor } from "./index.js";
+export declare class NotificationsTools {
+    private pica;
+    constructor(pica: PicaClient);
+    getTools(): Array<{
+        definition: ToolDefinition;
+        executor: ToolExecutor;
+    }>;
+    private listNotifications;
+    private notifyPerson;
+    private markRead;
+}
+//# sourceMappingURL=notifications.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"notifications.d.ts","sourceRoot":"","sources":["../../src/tools/notifications.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,YAAY,EAAc,MAAM,YAAY,CAAC;AAQtE,qBAAa,kBAAkB;IAC7B,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;YAoE3D,iBAAiB;YAcjB,YAAY;YAmCZ,QAAQ;CAOvB"}

package/dist/tools/notifications.js

@@ -0,0 +1,117 @@
+/**
+ * Notifications Tools — check and manage PICA notifications via MCP
+ */
+import { formatAsText, formatSuccess, formatStructuredList, formatValidationError, } from "../utils/formatting.js";
+export class NotificationsTools {
+    pica;
+    constructor(pica) {
+        this.pica = pica;
+    }
+    getTools() {
+        return [
+            {
+                definition: {
+                    name: "pica_notifications_list",
+                    description: "Check for notifications from PICA — new collaborator invites, " +
+                        "enrichment results, verification requests, credit disputes, " +
+                        "and other flagged items that need attention.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {},
+                    },
+                },
+                executor: this.listNotifications.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_notify_person",
+                    description: "Send a notification to a person in the catalog. If the person has a PICA account, " +
+                        "they get an in-app notification + Telegram message (if connected). " +
+                        "If they're not a PICA user yet, returns a hint to use pica_collaborators_invite instead. " +
+                        "Use for credit verification requests, song updates, or any message to a collaborator.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            person_id: {
+                                type: "string",
+                                description: "The person's ID in your catalog",
+                            },
+                            message: {
+                                type: "string",
+                                description: "What to tell them (e.g. 'please verify your writing credit on Midnight Run')",
+                            },
+                            work_id: {
+                                type: "string",
+                                description: "Optional work ID for context — links the notification to a specific work",
+                            },
+                        },
+                        required: ["person_id", "message"],
+                    },
+                },
+                executor: this.notifyPerson.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_notifications_mark_read",
+                    description: "Mark one or more notifications as read.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            notification_ids: {
+                                type: "array",
+                                items: { type: "string" },
+                                description: "IDs of notifications to mark as read",
+                            },
+                        },
+                        required: ["notification_ids"],
+                    },
+                },
+                executor: this.markRead.bind(this),
+            },
+        ];
+    }
+    async listNotifications(_args) {
+        const result = await this.pica.notifications.list();
+        const notifications = result?.notifications || result || [];
+        const items = Array.isArray(notifications) ? notifications : [];
+        const unread = items.filter((n) => !n.read_at);
+        return formatStructuredList(items, "notification", {
+            total: items.length,
+            unread: unread.length,
+        });
+    }
+    async notifyPerson(args) {
+        if (!args.person_id?.trim()) {
+            return formatValidationError({ person_id: "person_id is required" });
+        }
+        if (!args.message?.trim()) {
+            return formatValidationError({ message: "message is required" });
+        }
+        const result = await this.pica.notifications.sendToPerson({
+            person_id: args.person_id,
+            message: args.message,
+            work_id: args.work_id,
+        });
+        const data = result.data || result;
+        if (!data.delivered) {
+            return formatAsText({
+                delivered: false,
+                person_name: data.person_name,
+                reason: data.reason,
+                hint: data.hint,
+            });
+        }
+        const channels = [];
+        if (data.channels?.in_app)
+            channels.push("in-app");
+        if (data.channels?.telegram)
+            channels.push("Telegram");
+        return formatSuccess(`Notified ${data.person_name} via ${channels.join(" + ")}`, data);
+    }
+    async markRead(args) {
+        const ids = args.notification_ids;
+        await this.pica.notifications.markRead(ids);
+        return formatSuccess(`Marked ${ids.length} notification${ids.length !== 1 ? "s" : ""} as read`);
+    }
+}
+//# sourceMappingURL=notifications.js.map

package/dist/tools/notifications.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"notifications.js","sourceRoot":"","sources":["../../src/tools/notifications.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,EACL,YAAY,EACZ,aAAa,EACb,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,wBAAwB,CAAC;AAEhC,MAAM,OAAO,kBAAkB;IACrB,IAAI,CAAa;IAEzB,YAAY,IAAgB;QAC1B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;IAED,QAAQ;QACN,OAAO;YACL;gBACE,UAAU,EAAE;oBACV,IAAI,EAAE,yBAAyB;oBAC/B,WAAW,EACT,gEAAgE;wBAChE,8DAA8D;wBAC9D,8CAA8C;oBAChD,WAAW,EAAE;wBACX,IAAI,EAAE,QAAQ;wBACd,UAAU,EAAE,EAAE;qBACf;iBACF;gBACD,QAAQ,EAAE,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC;aAC5C;YACD;gBACE,UAAU,EAAE;oBACV,IAAI,EAAE,oBAAoB;oBAC1B,WAAW,EACT,oFAAoF;wBACpF,qEAAqE;wBACrE,2FAA2F;wBAC3F,uFAAuF;oBACzF,WAAW,EAAE;wBACX,IAAI,EAAE,QAAQ;wBACd,UAAU,EAAE;4BACV,SAAS,EAAE;gCACT,IAAI,EAAE,QAAQ;gCACd,WAAW,EAAE,iCAAiC;6BAC/C;4BACD,OAAO,EAAE;gCACP,IAAI,EAAE,QAAQ;gCACd,WAAW,EACT,8EAA8E;6BACjF;4BACD,OAAO,EAAE;gCACP,IAAI,EAAE,QAAQ;gCACd,WAAW,EACT,0EAA0E;6BAC7E;yBACF;wBACD,QAAQ,EAAE,CAAC,WAAW,EAAE,SAAS,CAAC;qBACnC;iBACF;gBACD,QAAQ,EAAE,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC;aACvC;YACD;gBACE,UAAU,EAAE;oBACV,IAAI,EAAE,8BAA8B;oBACpC,WAAW,EAAE,yCAAyC;oBACtD,WAAW,EAAE;wBACX,IAAI,EAAE,QAAQ;wBACd,UAAU,EAAE;4BACV,gBAAgB,EAAE;gCAChB,IAAI,EAAE,OAAO;gCACb,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;gCACzB,WAAW,EAAE,sCAAsC;6BACpD;yBACF;wBACD,QAAQ,EAAE,CAAC,kBAAkB,CAAC;qBAC/B;iBACF;gBACD,QAAQ,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC;aACnC;SACF,CAAC;IACJ,CAAC;IAEO,KAAK,CAAC,iBAAiB,CAC7B,KAA0B;QAE1B,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC;QACpD,MAAM,aAAa,GAAG,MAAM,EAAE,aAAa,IAAI,MAAM,IAAI,EAAE,CAAC;QAC5D,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC;QAChE,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAM,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;QAEpD,OAAO,oBAAoB,CAAC,KAAK,EAAE,cAAc,EAAE;YACjD,KAAK,EAAE,KAAK,CAAC,MAAM;YACnB,MAAM,EAAE,MAAM,CAAC,MAAM;SACtB,CAAC,CAAC;IACL,CAAC;IAEO,KAAK,CAAC,YAAY,CAAC,IAAyB;QAClD,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,EAAE,CAAC;YAC5B,OAAO,qBAAqB,CAAC,EAAE,SAAS,EAAE,uBAAuB,EAAE,CAAC,CAAC;QACvE,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,EAAE,CAAC;YAC1B,OAAO,qBAAqB,CAAC,EAAE,OAAO,EAAE,qBAAqB,EAAE,CAAC,CAAC;QACnE,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,YAAY,CAAC;YACxD,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,OAAO,EAAE,IAAI,CAAC,OAAO;SACtB,CAAC,CAAC;QAEH,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC;QAEnC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;YACpB,OAAO,YAAY,CAAC;gBAClB,SAAS,EAAE,KAAK;gBAChB,WAAW,EAAE,IAAI,CAAC,WAAW;gBAC7B,MAAM,EAAE,IAAI,CAAC,MAAM;gBACnB,IAAI,EAAE,IAAI,CAAC,IAAI;aAChB,CAAC,CAAC;QACL,CAAC;QAED,MAAM,QAAQ,GAAG,EAAE,CAAC;QACpB,IAAI,IAAI,CAAC,QAAQ,EAAE,MAAM;YAAE,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACnD,IAAI,IAAI,CAAC,QAAQ,EAAE,QAAQ;YAAE,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAEvD,OAAO,aAAa,CAClB,YAAY,IAAI,CAAC,WAAW,QAAQ,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,EAC1D,IAAI,CACL,CAAC;IACJ,CAAC;IAEO,KAAK,CAAC,QAAQ,CAAC,IAAyB;QAC9C,MAAM,GAAG,GAAG,IAAI,CAAC,gBAA4B,CAAC;QAC9C,MAAM,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QAC5C,OAAO,aAAa,CAClB,UAAU,GAAG,CAAC,MAAM,gBAAgB,GAAG,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,UAAU,CAC1E,CAAC;IACJ,CAAC;CACF"}

package/dist/tools/people.d.ts

@@ -0,0 +1,53 @@
+/**
+ * People Tools - MCP tools for managing people (artists, composers, etc.)
+ */
+import { PicaClient } from "../pica-sdk.js";
+import { ToolDefinition, ToolExecutor } from "./index.js";
+export declare class PeopleTools {
+    private pica;
+    constructor(pica: PicaClient);
+    /**
+     * Get all people tools
+     */
+    getTools(): Array<{
+        definition: ToolDefinition;
+        executor: ToolExecutor;
+    }>;
+    /**
+     * List people
+     */
+    private listPeople;
+    /**
+     * Get person by ID
+     */
+    private getPerson;
+    /**
+     * Create person
+     */
+    private createPerson;
+    /**
+     * Update person
+     */
+    private updatePerson;
+    /**
+     * Delete person
+     */
+    private deletePerson;
+    /**
+     * Search people
+     */
+    private searchPeople;
+    /**
+     * Enrich from ISNI
+     */
+    private enrichFromISNI;
+    /**
+     * Enrich from MusicBrainz
+     */
+    private enrichFromMusicBrainz;
+    /**
+     * Get full person context bundle
+     */
+    private getPersonFull;
+}
+//# sourceMappingURL=people.d.ts.map