perso-mcp-server 1.0.0 → 1.0.1

package/dist/client.d.ts

@@ -15,5 +15,10 @@ export declare class PersoApiClient {
     put<T>(path: string, body?: unknown, query?: Record<string, string>): Promise<T>;
     patch<T>(path: string, body?: unknown, query?: Record<string, string>): Promise<T>;
     delete(path: string, query?: Record<string, string>): Promise<void>;
+    /**
+     * Upload a file buffer directly to Azure Blob Storage via SAS URL.
+     * This bypasses the PERSO API — the SAS URL already contains authentication.
+     */
+    static uploadBlob(blobSasUrl: string, fileBuffer: Buffer): Promise<string>;
 }
 export declare function createClient(): PersoApiClient;

package/dist/client.js

@@ -81,6 +81,30 @@ export class PersoApiClient {
     async delete(path, query) {
         return this.request("DELETE", path, undefined, query);
     }
+    /**
+     * Upload a file buffer directly to Azure Blob Storage via SAS URL.
+     * This bypasses the PERSO API — the SAS URL already contains authentication.
+     */
+    static async uploadBlob(blobSasUrl, fileBuffer) {
+        const response = await fetch(blobSasUrl, {
+            method: "PUT",
+            headers: {
+                "x-ms-blob-type": "BlockBlob",
+                "Content-Type": "application/octet-stream",
+                "Content-Length": String(fileBuffer.byteLength),
+            },
+            body: fileBuffer,
+        });
+        if (response.status === 403) {
+            throw new PersoApiError("SAS_EXPIRED", 403, "SAS URL has expired. Call get_sas_token again to obtain a new URL.");
+        }
+        if (!response.ok) {
+            throw new PersoApiError("BLOB_UPLOAD_FAILED", response.status, `Azure Blob upload failed with HTTP ${response.status}`);
+        }
+        // Extract blob URL (path portion before the '?' query string)
+        const url = new URL(blobSasUrl);
+        return `${url.origin}${url.pathname}`;
+    }
 }
 export function createClient() {
     const apiKey = process.env.PERSO_API_KEY;

package/dist/tools/files.d.ts

@@ -1,3 +1,3 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import type { PersoApiClient } from "../client.js";
+import { PersoApiClient } from "../client.js";
 export declare function registerFileTools(server: McpServer, client: PersoApiClient): void;

package/dist/tools/files.js

@@ -1,15 +1,139 @@
+import { readFile } from "node:fs/promises";
 import { z } from "zod";
+import { PersoApiClient } from "../client.js";
 import { errorResult, textResult } from "../utils/formatting.js";
 export function registerFileTools(server, client) {
-    server.tool("upload_media", "Upload a video or audio file to PERSO. Supports direct file URLs and external platform URLs (YouTube, TikTok, Google Drive). Returns mediaSeq needed for creating translations.", {
-        spaceSeq: z.number().describe("Space ID to upload to"),
-        source: z
-            .enum(["url", "external"])
-            .describe("'url' for direct file URL (.mp4, .webm, .mov, .mp3, .wav). 'external' for YouTube/TikTok/Google Drive URL."),
+    // ──────────────────────────────────────────────
+    // Direct File Upload Workflow (Step 1 of 3)
+    // ──────────────────────────────────────────────
+    server.tool("get_sas_token", [
+        "Get a temporary Azure Blob Storage SAS URL for direct file upload.",
+        "",
+        "** Direct File Upload Workflow **",
+        "  Step 1: get_sas_token        → obtain blobSasUrl + expiresOn",
+        "  Step 2: upload_file_to_blob  → upload local file binary to blobSasUrl",
+        "  Step 3: upload_media (source='blob') → register the blob URL with PERSO",
+    ].join("\n"), {
         mediaType: z
             .enum(["video", "audio"])
             .describe("Type of media to upload"),
+        fileName: z
+            .string()
+            .describe("File name with extension (e.g., 'my_video.mp4')"),
+    }, async ({ mediaType, fileName }) => {
+        try {
+            const result = await client.post("/file/api/v1/upload/sas-token", { mediaType: mediaType.toUpperCase(), fileName });
+            return textResult([
+                `SAS Token obtained`,
+                `Blob SAS URL: ${result.blobSasUrl}`,
+                `Expires: ${result.expiresOn}`,
+                ``,
+                `Next step: call upload_file_to_blob with this blobSasUrl and your local file path.`,
+            ].join("\n"));
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+    // ──────────────────────────────────────────────
+    // Direct File Upload Workflow (Step 2 of 3)
+    // ──────────────────────────────────────────────
+    server.tool("upload_file_to_blob", [
+        "Upload a local file to Azure Blob Storage using the SAS URL from get_sas_token.",
+        "Returns the blob URL (without query string) to use as fileUrl in upload_media.",
+        "",
+        "** Direct File Upload Workflow **",
+        "  Step 1: get_sas_token        → obtain blobSasUrl + expiresOn",
+        "  Step 2: upload_file_to_blob  → upload local file binary to blobSasUrl  ← YOU ARE HERE",
+        "  Step 3: upload_media (source='blob') → register the blob URL with PERSO",
+        "",
+        "Note: The SAS URL contains authentication, so no API key is needed.",
+        "A 403 response means the SAS URL expired — call get_sas_token again.",
+    ].join("\n"), {
+        filePath: z
+            .string()
+            .describe("Absolute path to the local file to upload"),
+        blobSasUrl: z
+            .string()
+            .describe("The blobSasUrl obtained from get_sas_token"),
+    }, async ({ filePath, blobSasUrl }) => {
+        try {
+            const fileBuffer = await readFile(filePath);
+            const blobUrl = await PersoApiClient.uploadBlob(blobSasUrl, fileBuffer);
+            return textResult([
+                `File uploaded to blob storage successfully`,
+                `Blob URL: ${blobUrl}`,
+                `File size: ${fileBuffer.byteLength} bytes`,
+                ``,
+                `Next step: call upload_media with source='blob' and fileUrl='${blobUrl}'`,
+            ].join("\n"));
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+    // ──────────────────────────────────────────────
+    // Validate Media (for both workflows)
+    // ──────────────────────────────────────────────
+    server.tool("validate_media", [
+        "Validate media file constraints (size, duration, resolution) before uploading.",
+        "Use this to check if a file or external URL meets PERSO requirements.",
+        "",
+        "For external platforms (YouTube, TikTok, Google Drive):",
+        "  Step 1: get_external_metadata → preview media info",
+        "  Step 2: validate_media        ← YOU ARE HERE",
+        "  Step 3: upload_media (source='external') → start import",
+    ].join("\n"), {
+        fileName: z
+            .string()
+            .describe("File name with extension (e.g., 'video.mp4')"),
         fileUrl: z.string().describe("Direct file URL or external platform URL"),
+        mediaType: z
+            .enum(["video", "audio"])
+            .describe("Type of media to validate"),
+    }, async ({ fileName, fileUrl, mediaType }) => {
+        try {
+            const result = await client.post("/file/api/v1/media/validate", {
+                fileName,
+                fileUrl,
+                mediaType: mediaType.toUpperCase(),
+            });
+            const lines = [`Validation passed`];
+            if (result.maxDurationMs)
+                lines.push(`Max duration: ${result.maxDurationMs}ms`);
+            if (result.maxSizeBytes)
+                lines.push(`Max size: ${result.maxSizeBytes} bytes`);
+            if (result.maxResolution)
+                lines.push(`Max resolution: ${result.maxResolution}`);
+            if (result.message)
+                lines.push(`Message: ${result.message}`);
+            return textResult(lines.join("\n"));
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+    // ──────────────────────────────────────────────
+    // Upload Media — final registration step
+    // ──────────────────────────────────────────────
+    server.tool("upload_media", [
+        "Register an uploaded file with PERSO. Returns mediaSeq for creating translations.",
+        "",
+        "source='blob'     — Use after uploading a local file via get_sas_token + upload_file_to_blob.",
+        "                    Provide the blob URL (returned by upload_file_to_blob) as fileUrl.",
+        "source='external' — Use for YouTube / TikTok / Google Drive URLs.",
+        "                    Optionally call get_external_metadata and validate_media first.",
+    ].join("\n"), {
+        spaceSeq: z.number().describe("Space ID to upload to"),
+        source: z
+            .enum(["blob", "external"])
+            .describe("'blob' for files uploaded via SAS URL. 'external' for YouTube/TikTok/Google Drive URL."),
+        mediaType: z
+            .enum(["video", "audio"])
+            .describe("Type of media to register"),
+        fileUrl: z
+            .string()
+            .describe("Blob URL (from upload_file_to_blob) or external platform URL"),
         fileName: z
             .string()
             .describe("File name with extension (e.g., 'my_video.mp4')"),
@@ -19,17 +143,14 @@ export function registerFileTools(server, client) {
                 const result = await client.put("/file/api/upload/video/external", { spaceSeq, fileUrl, fileName });
                 return textResult([
                     `Upload successful (external)`,
-                    `Media ID: ${result.seq}`,
+                    `Media ID (mediaSeq): ${result.seq}`,
                     `Duration: ${result.durationMs}ms`,
                     `Size: ${result.size} bytes`,
+                    ``,
+                    `Use mediaSeq=${result.seq} when creating a translation via create_translation.`,
                 ].join("\n"));
             }
-            // Direct URL upload - validate first, then upload
-            await client.post("/file/api/v1/media/validate", {
-                fileName,
-                fileUrl,
-                mediaType: mediaType.toUpperCase(),
-            });
+            // Blob upload — register the blob URL with PERSO
             const endpoint = mediaType === "video"
                 ? "/file/api/upload/video"
                 : "/file/api/upload/audio";
@@ -41,17 +162,30 @@ export function registerFileTools(server, client) {
             const filePath = result.videoFilePath || result.audioFilePath || "";
             return textResult([
                 `Upload successful`,
-                `Media ID: ${result.seq}`,
+                `Media ID (mediaSeq): ${result.seq}`,
                 `File Path: ${filePath}`,
                 `Duration: ${result.durationMs}ms`,
                 `Size: ${result.size} bytes`,
+                ``,
+                `Use mediaSeq=${result.seq} when creating a translation via create_translation.`,
             ].join("\n"));
         }
         catch (error) {
             return errorResult(error);
         }
     });
-    server.tool("get_external_metadata", "Preview metadata of an external video (YouTube, TikTok, Google Drive) without downloading. Returns title, duration, and thumbnail.", {
+    // ──────────────────────────────────────────────
+    // External Metadata — preview external media
+    // ──────────────────────────────────────────────
+    server.tool("get_external_metadata", [
+        "Preview metadata of an external video (YouTube, TikTok, Google Drive) without downloading.",
+        "Returns title, duration, and thumbnail. Use before validate_media and upload_media.",
+        "",
+        "** External Platform Upload Workflow **",
+        "  Step 1: get_external_metadata ← YOU ARE HERE",
+        "  Step 2: validate_media        → check constraints",
+        "  Step 3: upload_media (source='external') → start import",
+    ].join("\n"), {
         url: z.string().describe("YouTube, TikTok, or Google Drive URL"),
     }, async ({ url }) => {
         try {

package/dist/types.d.ts

@@ -18,6 +18,17 @@ export interface ExternalMetadata {
     durationMs: number;
     thumbnailUrl: string;
 }
+export interface SasTokenResult {
+    blobSasUrl: string;
+    expiresOn: string;
+}
+export interface MediaValidationResult {
+    valid: boolean;
+    maxDurationMs?: number;
+    maxSizeBytes?: number;
+    maxResolution?: string;
+    message?: string;
+}
 export interface Project {
     projectSeq: number;
     title: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "perso-mcp-server",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "MCP server for PERSO API - video translation and dubbing platform",
   "type": "module",
   "main": "dist/index.js",