@withpica/mcp-server 1.3.0

package/dist/tools/telegram.js

@@ -0,0 +1,144 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+import { formatAsText, formatSuccess, formatValidationError, } from "@withpica/mcp-utils";
+export class TelegramTools {
+    pica;
+    constructor(pica) {
+        this.pica = pica;
+    }
+    getTools() {
+        return [
+            {
+                definition: {
+                    name: "pica_telegram_status",
+                    description: "Check if the user has Telegram connected. Use this before promising to send Telegram notifications. " +
+                        "Returns connection status, username, and notification preferences. " +
+                        "If not connected, suggest the user visit /connect to set up Telegram.",
+                    workflows: "infrastructure",
+                    inputSchema: {
+                        type: "object",
+                        properties: {},
+                    },
+                },
+                executor: this.getStatus.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_notify_user",
+                    description: "Send a notification to the user's connected Telegram. Use for long-running tasks: " +
+                        "enrichment, exports, duplicate merges, bulk operations. The message should be concise " +
+                        "and actionable — tell them what finished and what to do next. " +
+                        "Fails gracefully if Telegram is not connected (returns error, does not throw).",
+                    workflows: "infrastructure",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            message: {
+                                type: "string",
+                                description: "Notification message (markdown supported). Keep it short — 1-3 sentences. " +
+                                    "Include what completed and any action needed.",
+                            },
+                        },
+                        required: ["message"],
+                    },
+                },
+                executor: this.notifyUser.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_telegram_connect",
+                    description: "Pair the user's Telegram account with PICA so the agent can send " +
+                        "notifications via pica_notify_user. Returns a short magic code the " +
+                        "user sends to @withpica_bot, then call pica_telegram_status on the " +
+                        "next turn to confirm the connection landed. If the user is already " +
+                        "paired, short-circuits and returns { already_connected: true }. " +
+                        "Idempotent — repeated calls within 10 minutes return the same code. " +
+                        "Rate-limited to 3 new codes per user per rolling hour. " +
+                        "Use when the user asks the agent to send them anything via Telegram " +
+                        "but pica_telegram_status reports not connected.",
+                    workflows: "infrastructure",
+                    inputSchema: {
+                        type: "object",
+                        properties: {},
+                    },
+                },
+                executor: this.connect.bind(this),
+            },
+        ];
+    }
+    async getStatus(_args) {
+        const result = await this.pica.telegram.getStatus();
+        const data = result.data || result;
+        if (!data.connected) {
+            return formatAsText({
+                connected: false,
+                message: "Telegram is not connected. The user can set it up at /connect.",
+                bot_username: data.botUsername,
+            });
+        }
+        return formatSuccess(`Telegram connected as @${data.telegramUsername || data.telegramFirstName}. You can send notifications via pica_notify_user.`, {
+            connected: true,
+            telegram_username: data.telegramUsername,
+            telegram_first_name: data.telegramFirstName,
+            preferences: data.preferences,
+        });
+    }
+    async notifyUser(args) {
+        if (!args.message?.trim()) {
+            return formatValidationError({ message: "message is required" });
+        }
+        try {
+            const result = await this.pica.telegram.sendNotification(args.message.trim());
+            const data = result.data || result;
+            return formatSuccess(`Notification sent to @${data.telegramUsername || "user"} on Telegram.`, { sent: true, telegram_username: data.telegramUsername });
+        }
+        catch (err) {
+            // Graceful failure — don't throw, return error text
+            const message = err?.message || String(err);
+            if (message.includes("not connected") || message.includes("400")) {
+                return formatAsText({
+                    sent: false,
+                    error: "Telegram is not connected. The user can set it up at /connect.",
+                });
+            }
+            return formatAsText({
+                sent: false,
+                error: `Failed to send notification: ${message}`,
+            });
+        }
+    }
+    async connect(_args) {
+        try {
+            const result = await this.pica.telegram.connect();
+            const data = result.data || result;
+            if (data.already_connected) {
+                return formatSuccess(`Telegram is already paired as @${data.telegram_username || "user"}. You can send notifications via pica_notify_user.`, {
+                    already_connected: true,
+                    telegram_username: data.telegram_username,
+                    telegram_first_name: data.telegram_first_name,
+                });
+            }
+            return formatSuccess(data.instructions ||
+                `Open ${data.bot_url} and send the code ${data.code}. Call pica_telegram_status on the next turn to confirm.`, {
+                already_connected: false,
+                code: data.code,
+                bot_url: data.bot_url,
+                expires_at: data.expires_at,
+                instructions: data.instructions,
+                completion_hints: data.completion_hints,
+            });
+        }
+        catch (err) {
+            const message = err?.message || String(err);
+            if (message.includes("rate_limited") || message.includes("429")) {
+                return formatAsText({
+                    error: "rate_limited",
+                    message: "Too many Telegram pairing attempts. Try again in an hour.",
+                });
+            }
+            return formatAsText({
+                error: `Failed to generate pairing code: ${message}`,
+            });
+        }
+    }
+}
+//# sourceMappingURL=telegram.js.map

package/dist/tools/telegram.js.map

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

package/dist/tools/uploads.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Upload Tools - MCP tools for uploading any file type (images, videos, documents)
+ * Uses the generic storage presigned upload route that supports all PICA storage providers.
+ */
+import { PicaClient } from "@withpica/mcp-sdk";
+import { ToolDefinition, ToolExecutor } from "./index.js";
+export declare class UploadTools {
+    private pica;
+    constructor(pica: PicaClient);
+    getTools(): Array<{
+        definition: ToolDefinition;
+        executor: ToolExecutor;
+    }>;
+    private presignedUpload;
+    private completeUpload;
+}
+//# sourceMappingURL=uploads.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"uploads.d.ts","sourceRoot":"","sources":["../../src/tools/uploads.ts"],"names":[],"mappings":"AAEA;;;GAGG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,YAAY,EAAc,MAAM,YAAY,CAAC;AAGtE,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;YA+H3D,eAAe;YA0Bf,cAAc;CAwB7B"}

package/dist/tools/uploads.js

@@ -0,0 +1,165 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+import { formatSuccess } from "@withpica/mcp-utils";
+export class UploadTools {
+    pica;
+    constructor(pica) {
+        this.pica = pica;
+    }
+    getTools() {
+        return [
+            {
+                definition: {
+                    name: "pica_upload_file",
+                    description: "Generate a signed URL for uploading ANY file type — images, videos, documents, or audio. " +
+                        "The storage category is auto-detected from the MIME type. After uploading the file via HTTP PUT " +
+                        "to the returned URL, call pica_upload_complete to finalize. " +
+                        "Supported: images (JPEG, PNG, GIF, WebP, HEIC, AVIF, TIFF), " +
+                        "videos (MP4, QuickTime, WebM, MKV), " +
+                        "documents (PDF, Word, Excel), " +
+                        "audio (WAV, MP3, FLAC, AIFF, OGG, WebM). " +
+                        "For audio files that need BPM/key analysis, use pica_audio_presigned_upload instead. " +
+                        "TIP: if you are in ChatGPT or another external client, users cannot upload files " +
+                        "through the chat. Direct them to https://withpica.com/workspace where they can " +
+                        "drag and drop files, then offer to help link or organise them afterwards.",
+                    workflows: "infrastructure",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            filename: {
+                                type: "string",
+                                description: "Original filename with extension (e.g. 'promo-photo.jpg', 'contract.pdf')",
+                            },
+                            content_type: {
+                                type: "string",
+                                description: "MIME type — detect from the filename extension (e.g. .jpg→image/jpeg, " +
+                                    ".png→image/png, .mp4→video/mp4, .pdf→application/pdf, " +
+                                    ".wav→audio/wav, .mp3→audio/mpeg). Do not ask the user for this.",
+                            },
+                            file_size: {
+                                type: "number",
+                                description: "File size in bytes",
+                            },
+                        },
+                        required: ["filename", "content_type", "file_size"],
+                    },
+                },
+                executor: this.presignedUpload.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_upload_complete",
+                    description: "Finalize a file upload after the file has been PUT to the signed URL from pica_upload_file. " +
+                        "Creates the appropriate database record (multimedia item for images/video, document for PDFs, " +
+                        "audio file for audio). Use the uploadId, key, bucket, and storageCategory from pica_upload_file.",
+                    workflows: "infrastructure",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            upload_id: {
+                                type: "string",
+                                description: "The uploadId returned from pica_upload_file",
+                            },
+                            key: {
+                                type: "string",
+                                description: "The storage key returned from pica_upload_file",
+                            },
+                            bucket: {
+                                type: "string",
+                                description: "The bucket returned from pica_upload_file",
+                            },
+                            storage_category: {
+                                type: "string",
+                                description: "The storageCategory returned from pica_upload_file",
+                                enum: ["audio", "media", "documents"],
+                            },
+                            filename: {
+                                type: "string",
+                                description: "Original filename",
+                            },
+                            content_type: {
+                                type: "string",
+                                description: "MIME type of the uploaded file",
+                            },
+                            file_size: {
+                                type: "number",
+                                description: "File size in bytes",
+                            },
+                            title: {
+                                type: "string",
+                                description: "Optional title. Defaults to filename without extension.",
+                            },
+                            work_id: {
+                                type: "string",
+                                description: "Optional work ID to link the file to (audio only). For images/videos, use pica_multimedia_link_work after upload.",
+                            },
+                            classification: {
+                                type: "string",
+                                description: "For media: classification type (e.g. 'press_photo', 'album_artwork', 'music_video'). " +
+                                    "For documents: category (e.g. 'agreement', 'statement', 'other').",
+                            },
+                            linked_to_type: {
+                                type: "string",
+                                description: "For documents: entity type to link to (e.g. 'work', 'person', 'agreement')",
+                            },
+                            linked_to_id: {
+                                type: "string",
+                                description: "For documents: entity ID to link to",
+                            },
+                        },
+                        required: [
+                            "upload_id",
+                            "key",
+                            "bucket",
+                            "storage_category",
+                            "filename",
+                            "content_type",
+                            "file_size",
+                        ],
+                    },
+                },
+                executor: this.completeUpload.bind(this),
+            },
+        ];
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- matches ToolExecutor signature
+    async presignedUpload(args) {
+        const result = await this.pica.storage.presignedUpload({
+            filename: args.filename,
+            contentType: args.content_type,
+            fileSize: args.file_size,
+        });
+        return formatSuccess(`Upload URL generated for "${args.filename}" (category: ${result.storageCategory}). ` +
+            `PUT the file to the uploadUrl, then call pica_upload_complete with uploadId, key, bucket, ` +
+            `storageCategory, and metadata to finalize.`, {
+            uploadUrl: result.uploadUrl,
+            uploadId: result.uploadId,
+            key: result.key,
+            bucket: result.bucket,
+            storageCategory: result.storageCategory,
+            expiresAt: result.expiresAt,
+            metadata: result.metadata,
+        });
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- matches ToolExecutor signature
+    async completeUpload(args) {
+        const result = await this.pica.storage.completeUpload({
+            uploadId: args.upload_id,
+            key: args.key,
+            bucket: args.bucket,
+            metadata: {
+                filename: args.filename,
+                contentType: args.content_type,
+                fileSize: args.file_size,
+                storageCategory: args.storage_category,
+                title: args.title,
+                workId: args.work_id,
+                classification: args.classification,
+                documentCategory: args.classification,
+                linkedToType: args.linked_to_type,
+                linkedToId: args.linked_to_id,
+            },
+        });
+        return formatSuccess(`Upload finalized. Created ${result.recordType} record with ID: ${result.recordId}.`, result);
+    }
+}
+//# sourceMappingURL=uploads.js.map

package/dist/tools/uploads.js.map

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

package/dist/tools/works.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Works Tools — MCP tools for managing musical works.
+ *
+ * ADR-174 Phase 2 item 2 reconciliation: the write surface covers only
+ * real columns on `public.works`. Seven phantom fields previously
+ * accepted via `additionalProperties: true` have been removed:
+ *   - `label` (no column; recordings/releases store label via org FK)
+ *   - `spotify_url` (lives on recordings/releases)
+ *   - `album_name`, `album_release_date`, `album_art_url`, `track_number`,
+ *     `upc` (all album/release metadata — handled via `pica_releases_*`)
+ *
+ * Five add-candidates surfaced per the audit at
+ * docs/audits/2026-04-14-mcp-db-reconciliation.md §1:
+ *   tempo, key, display_artist, published, tunecode.
+ *
+ * Agents that need to set label metadata call `pica_releases_create`
+ * or `pica_releases_update` with `label_organization_id`, resolving
+ * the name via `pica_labels_query` first.
+ */
+import { PicaClient } from "@withpica/mcp-sdk";
+import { ToolDefinition, ToolExecutor } from "./index.js";
+/**
+ * Canonical write-schema for `works`. Every property below must
+ * correspond to a real column on `public.works` — verified against
+ * `lib/db/database.types.ts`. Keep this list tight: reintroducing a
+ * phantom field is the exact regression ADR-174 Phase 2 exists to
+ * prevent. The HTTP route at `app/api/admin/works/[id]/route.ts`
+ * carries a broader allow-list that includes admin-UI-posted satellite
+ * fields; this list is the narrower MCP-agent contract.
+ */
+export declare const WORK_WRITE_PROPERTIES: Record<string, Record<string, unknown>>;
+export declare class WorksTools {
+    private pica;
+    constructor(pica: PicaClient);
+    /**
+     * Get all works tools
+     */
+    getTools(): Array<{
+        definition: ToolDefinition;
+        executor: ToolExecutor;
+    }>;
+    /**
+     * Query works — unified search, list, and health filter
+     */
+    private queryWorks;
+    /**
+     * Inspect work — unified detail view with selectable sections
+     */
+    private inspectWork;
+    /**
+     * Create work
+     */
+    private createWork;
+    /**
+     * Update work
+     */
+    private updateWork;
+    /**
+     * Delete work
+     */
+    private deleteWork;
+    /**
+     * Verify work
+     */
+    private verifyWork;
+    /**
+     * Bulk delete works
+     */
+    private bulkDeleteWorks;
+}
+//# sourceMappingURL=works.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"works.d.ts","sourceRoot":"","sources":["../../src/tools/works.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,YAAY,EAAc,MAAM,YAAY,CAAC;AAatE;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAkHzE,CAAC;AAEF,qBAAa,UAAU;IACrB,OAAO,CAAC,IAAI,CAAa;gBAEb,IAAI,EAAE,UAAU;IAI5B;;OAEG;IACH,QAAQ,IAAI,KAAK,CAAC;QAAE,UAAU,EAAE,cAAc,CAAC;QAAC,QAAQ,EAAE,YAAY,CAAA;KAAE,CAAC;IA8PzE;;OAEG;YACW,UAAU;IAsDxB;;OAEG;YACW,WAAW;IAwPzB;;OAEG;YACW,UAAU;IAkCxB;;OAEG;YACW,UAAU;IAMxB;;OAEG;YACW,UAAU;IAKxB;;OAEG;YACW,UAAU;IAiDxB;;OAEG;YACW,eAAe;CAM9B"}