perso-mcp-server 1.0.0 → 1.0.2

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/index.js

@@ -2,6 +2,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { createClient } from "./client.js";
+import { SpaceResolver } from "./utils/space-resolver.js";
 import { registerSpaceTools } from "./tools/spaces.js";
 import { registerFileTools } from "./tools/files.js";
 import { registerProjectTools } from "./tools/projects.js";
@@ -13,18 +14,19 @@ import { registerLipSyncTools } from "./tools/lip-sync.js";
 import { registerFeedbackTools } from "./tools/feedback.js";
 async function main() {
     const client = createClient();
+    const resolver = new SpaceResolver(client);
     const server = new McpServer({
         name: "perso-mcp-server",
-        version: "1.0.0",
+        version: "1.0.1",
     });
-    registerSpaceTools(server, client);
-    registerFileTools(server, client);
-    registerProjectTools(server, client);
-    registerScriptTools(server, client);
-    registerUsageTools(server, client);
+    registerSpaceTools(server, client, resolver);
+    registerFileTools(server, client, resolver);
+    registerProjectTools(server, client, resolver);
+    registerScriptTools(server, client, resolver);
+    registerUsageTools(server, client, resolver);
     registerLanguageTools(server, client);
     registerCommunityTools(server, client);
-    registerLipSyncTools(server, client);
+    registerLipSyncTools(server, client, resolver);
     registerFeedbackTools(server, client);
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/dist/tools/files.d.ts

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

package/dist/tools/files.js

@@ -1,57 +1,196 @@
+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."),
+export function registerFileTools(server, client, resolver) {
+    // ──────────────────────────────────────────────
+    // 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.",
+        "spaceSeq is optional — omit to use the default space.",
+        "",
+        "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()
+            .optional()
+            .describe("Space ID (omit to use default space)"),
+        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')"),
     }, async ({ spaceSeq, source, mediaType, fileUrl, fileName }) => {
         try {
+            const resolvedSpaceSeq = await resolver.resolve(spaceSeq);
             if (source === "external") {
-                const result = await client.put("/file/api/upload/video/external", { spaceSeq, fileUrl, fileName });
+                const result = await client.put("/file/api/upload/video/external", { spaceSeq: resolvedSpaceSeq, 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";
             const result = await client.put(endpoint, {
-                spaceSeq,
+                spaceSeq: resolvedSpaceSeq,
                 fileUrl,
                 fileName,
             });
             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/tools/lip-sync.d.ts

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

package/dist/tools/lip-sync.js

@@ -1,10 +1,13 @@
 import { z } from "zod";
 import { errorResult, textResult } from "../utils/formatting.js";
-export function registerLipSyncTools(server, client) {
+export function registerLipSyncTools(server, client, resolver) {
     // Tool: request_lip_sync
-    server.tool("request_lip_sync", "Request lip sync generation for a PERSO translation project. Creates a lip-synced version of the translated video.", {
+    server.tool("request_lip_sync", "Request lip sync generation for a PERSO translation project. Creates a lip-synced version of the translated video. spaceSeq is optional — omit to use the default space.", {
         projectSeq: z.number().describe("Project ID"),
-        spaceSeq: z.number().describe("Space ID"),
+        spaceSeq: z
+            .number()
+            .optional()
+            .describe("Space ID (omit to use default space)"),
         preferredSpeedType: z
             .enum(["GREEN", "RED"])
             .optional()
@@ -12,7 +15,8 @@ export function registerLipSyncTools(server, client) {
             .describe("GREEN = standard speed, RED = expedited"),
     }, async ({ projectSeq, spaceSeq, preferredSpeedType }) => {
         try {
-            const result = await client.post(`/video-translator/api/v1/projects/${projectSeq}/spaces/${spaceSeq}/lip-sync`, { preferredSpeedType });
+            const resolvedSpaceSeq = await resolver.resolve(spaceSeq);
+            const result = await client.post(`/video-translator/api/v1/projects/${projectSeq}/spaces/${resolvedSpaceSeq}/lip-sync`, { preferredSpeedType });
             return textResult([
                 `Lip sync requested successfully.`,
                 `Generation IDs: ${result.generationIds?.join(", ") || "N/A"}`,
@@ -24,14 +28,18 @@ export function registerLipSyncTools(server, client) {
         }
     });
     // Tool: get_lip_sync_history
-    server.tool("get_lip_sync_history", "Get the lip sync generation history for a PERSO project. Shows past VIEW and DOWNLOAD entries with status.", {
+    server.tool("get_lip_sync_history", "Get the lip sync generation history for a PERSO project. Shows past VIEW and DOWNLOAD entries with status. spaceSeq is optional — omit to use the default space.", {
         projectSeq: z.number().describe("Project ID"),
-        spaceSeq: z.number().describe("Space ID"),
+        spaceSeq: z
+            .number()
+            .optional()
+            .describe("Space ID (omit to use default space)"),
         page: z.number().optional().default(0).describe("Page number"),
         pageSize: z.number().optional().default(10).describe("Page size"),
     }, async ({ projectSeq, spaceSeq, page, pageSize }) => {
         try {
-            const result = await client.get(`/video-translator/api/v1/projects/${projectSeq}/spaces/${spaceSeq}/lip-sync/generated`, { page: String(page), pageSize: String(pageSize) });
+            const resolvedSpaceSeq = await resolver.resolve(spaceSeq);
+            const result = await client.get(`/video-translator/api/v1/projects/${projectSeq}/spaces/${resolvedSpaceSeq}/lip-sync/generated`, { page: String(page), pageSize: String(pageSize) });
             if (result.content.length === 0) {
                 return textResult("No lip sync history found.");
             }

package/dist/tools/projects.d.ts

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

package/dist/tools/projects.js

@@ -10,10 +10,13 @@ function formatProject(project) {
         `Updated: ${project.updatedAt}`,
     ].join("\n");
 }
-export function registerProjectTools(server, client) {
+export function registerProjectTools(server, client, resolver) {
     // Tool: create_translation
-    server.tool("create_translation", "Create a new PERSO translation project. Upload media first using upload_media to get the mediaSeq. Returns project IDs for tracking.", {
-        spaceSeq: z.number().describe("Space ID"),
+    server.tool("create_translation", "Create a new PERSO translation project. Upload media first using upload_media to get the mediaSeq. Returns project IDs for tracking. spaceSeq is optional — omit to use the default space.", {
+        spaceSeq: z
+            .number()
+            .optional()
+            .describe("Space ID (omit to use default space)"),
         mediaSeq: z.number().describe("Media sequence ID from upload_media"),
         isVideoProject: z
             .boolean()
@@ -40,8 +43,9 @@ export function registerProjectTools(server, client) {
             .describe("GREEN = standard speed, RED = expedited"),
     }, async ({ spaceSeq, mediaSeq, isVideoProject, sourceLanguageCode, targetLanguageCodes, numberOfSpeakers, withLipSync, preferredSpeedType, }) => {
         try {
+            const resolvedSpaceSeq = await resolver.resolve(spaceSeq);
             // Initialize queue first (idempotent)
-            await client.put(`/video-translator/api/v1/projects/spaces/${spaceSeq}/queue`);
+            await client.put(`/video-translator/api/v1/projects/spaces/${resolvedSpaceSeq}/queue`);
             const body = {
                 mediaSeq,
                 isVideoProject,
@@ -53,7 +57,7 @@ export function registerProjectTools(server, client) {
                 body.numberOfSpeakers = numberOfSpeakers;
             if (withLipSync)
                 body.withLipSync = withLipSync;
-            const result = await client.post(`/video-translator/api/v1/projects/spaces/${spaceSeq}/translate`, body);
+            const result = await client.post(`/video-translator/api/v1/projects/spaces/${resolvedSpaceSeq}/translate`, body);
             const ids = result.startGenerateProjectIdList;
             return textResult([
                 `Translation project(s) created successfully!`,
@@ -66,8 +70,11 @@ export function registerProjectTools(server, client) {
         }
     });
     // Tool: list_projects
-    server.tool("list_projects", "List PERSO translation projects in a space. Supports pagination, sorting, and filtering by type.", {
-        spaceSeq: z.number().describe("Space ID"),
+    server.tool("list_projects", "List PERSO translation projects in a space. Supports pagination, sorting, and filtering by type. spaceSeq is optional — omit to use the default space.", {
+        spaceSeq: z
+            .number()
+            .optional()
+            .describe("Space ID (omit to use default space)"),
         offset: z.number().optional().default(0).describe("Page offset"),
         size: z.number().optional().default(20).describe("Page size (max 100)"),
         sort: z
@@ -81,6 +88,7 @@ export function registerProjectTools(server, client) {
             .describe("Filter by project type"),
     }, async ({ spaceSeq, offset, size, sort, type }) => {
         try {
+            const resolvedSpaceSeq = await resolver.resolve(spaceSeq);
             const query = {
                 offset: String(offset),
                 size: String(size),
@@ -88,7 +96,7 @@ export function registerProjectTools(server, client) {
             };
             if (type)
                 query.type = type;
-            const result = await client.get(`/video-translator/api/v1/projects/spaces/${spaceSeq}`, query);
+            const result = await client.get(`/video-translator/api/v1/projects/spaces/${resolvedSpaceSeq}`, query);
             if (result.content.length === 0) {
                 return textResult("No projects found.");
             }
@@ -101,9 +109,12 @@ export function registerProjectTools(server, client) {
         }
     });
     // Tool: get_project
-    server.tool("get_project", "Get detailed information about a PERSO project. Use the 'include' parameter to fetch multiple types of info in one call.", {
+    server.tool("get_project", "Get detailed information about a PERSO project. Use the 'include' parameter to fetch multiple types of info in one call. spaceSeq is optional — omit to use the default space.", {
         projectSeq: z.number().describe("Project ID"),
-        spaceSeq: z.number().describe("Space ID"),
+        spaceSeq: z
+            .number()
+            .optional()
+            .describe("Space ID (omit to use default space)"),
         include: z
             .array(z.enum([
             "details",
@@ -118,8 +129,9 @@ export function registerProjectTools(server, client) {
             .describe("What info to include: details, progress, video_info, download_info, used_features, retranslation_status"),
     }, async ({ projectSeq, spaceSeq, include }) => {
         try {
-            const basePath = `/video-translator/api/v1/projects/${projectSeq}/spaces/${spaceSeq}`;
-            const basePathAlt = `/video-translator/api/v1/projects/${projectSeq}/space/${spaceSeq}`;
+            const resolvedSpaceSeq = await resolver.resolve(spaceSeq);
+            const basePath = `/video-translator/api/v1/projects/${projectSeq}/spaces/${resolvedSpaceSeq}`;
+            const basePathAlt = `/video-translator/api/v1/projects/${projectSeq}/space/${resolvedSpaceSeq}`;
             const sections = [];
             const fetchers = {
                 details: async () => {
@@ -188,9 +200,12 @@ export function registerProjectTools(server, client) {
         }
     });
     // Tool: manage_project
-    server.tool("manage_project", "Manage a PERSO project: update title, update access permissions, delete, or cancel translation.", {
+    server.tool("manage_project", "Manage a PERSO project: update title, update access permissions, delete, or cancel translation. spaceSeq is optional — omit to use the default space.", {
         projectSeq: z.number().describe("Project ID"),
-        spaceSeq: z.number().describe("Space ID"),
+        spaceSeq: z
+            .number()
+            .optional()
+            .describe("Space ID (omit to use default space)"),
         action: z
             .enum(["update_title", "update_access", "delete", "cancel"])
             .describe("Action to perform"),
@@ -204,7 +219,8 @@ export function registerProjectTools(server, client) {
             .describe("Access level (required for update_access)"),
     }, async ({ projectSeq, spaceSeq, action, title, accessPermission }) => {
         try {
-            const basePath = `/video-translator/api/v1/projects/${projectSeq}/spaces/${spaceSeq}`;
+            const resolvedSpaceSeq = await resolver.resolve(spaceSeq);
+            const basePath = `/video-translator/api/v1/projects/${projectSeq}/spaces/${resolvedSpaceSeq}`;
             switch (action) {
                 case "update_title": {
                     if (!title) {
@@ -237,9 +253,12 @@ export function registerProjectTools(server, client) {
         }
     });
     // Tool: download_project
-    server.tool("download_project", "Get download links for a PERSO project's translated files (video, audio, SRT) or view export history.", {
+    server.tool("download_project", "Get download links for a PERSO project's translated files (video, audio, SRT) or view export history. spaceSeq is optional — omit to use the default space.", {
         projectSeq: z.number().describe("Project ID"),
-        spaceSeq: z.number().describe("Space ID"),
+        spaceSeq: z
+            .number()
+            .optional()
+            .describe("Space ID (omit to use default space)"),
         action: z
             .enum(["get_links", "export_history"])
             .optional()
@@ -247,8 +266,9 @@ export function registerProjectTools(server, client) {
             .describe("get_links: download URLs. export_history: past export records."),
     }, async ({ projectSeq, spaceSeq, action }) => {
         try {
+            const resolvedSpaceSeq = await resolver.resolve(spaceSeq);
             if (action === "export_history") {
-                const basePath = `/video-translator/api/v1/projects/${projectSeq}/space/${spaceSeq}`;
+                const basePath = `/video-translator/api/v1/projects/${projectSeq}/space/${resolvedSpaceSeq}`;
                 const history = await client.get(`${basePath}/export-history`);
                 if (history.content.length === 0) {
                     return textResult("No export history found.");
@@ -257,7 +277,7 @@ export function registerProjectTools(server, client) {
                 return textResult(`Export History:\n${entries.join("\n")}`);
             }
             // get_links
-            const basePath = `/video-translator/api/v1/projects/${projectSeq}/spaces/${spaceSeq}`;
+            const basePath = `/video-translator/api/v1/projects/${projectSeq}/spaces/${resolvedSpaceSeq}`;
             const links = await client.get(`${basePath}/download`);
             const parts = ["Download Links:"];
             if (links.video)

package/dist/tools/scripts.d.ts

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

package/dist/tools/scripts.js

@@ -1,10 +1,13 @@
 import { z } from "zod";
 import { errorResult, textResult } from "../utils/formatting.js";
-export function registerScriptTools(server, client) {
+export function registerScriptTools(server, client, resolver) {
     // Tool: get_script
-    server.tool("get_script", "Get the translation script for a PERSO project. Returns sentences with original text, translated text, matching rate, and audio URLs. Supports cursor-based pagination.", {
+    server.tool("get_script", "Get the translation script for a PERSO project. Returns sentences with original text, translated text, matching rate, and audio URLs. Supports cursor-based pagination. spaceSeq is optional — omit to use the default space.", {
         projectSeq: z.number().describe("Project ID"),
-        spaceSeq: z.number().describe("Space ID"),
+        spaceSeq: z
+            .number()
+            .optional()
+            .describe("Space ID (omit to use default space)"),
         cursorId: z
             .number()
             .optional()
@@ -16,7 +19,8 @@ export function registerScriptTools(server, client) {
             .describe("Number of sentences to return"),
     }, async ({ projectSeq, spaceSeq, cursorId, size }) => {
         try {
-            const basePath = `/video-translator/api/v1/projects/${projectSeq}/spaces/${spaceSeq}/script`;
+            const resolvedSpaceSeq = await resolver.resolve(spaceSeq);
+            const basePath = `/video-translator/api/v1/projects/${projectSeq}/spaces/${resolvedSpaceSeq}/script`;
             const query = { size: String(size) };
             if (cursorId !== undefined)
                 query.cursorId = String(cursorId);
@@ -123,9 +127,12 @@ export function registerScriptTools(server, client) {
         }
     });
     // Tool: request_proofread
-    server.tool("request_proofread", "Request AI proofreading for all sentences in a PERSO translation project.", {
+    server.tool("request_proofread", "Request AI proofreading for all sentences in a PERSO translation project. spaceSeq is optional — omit to use the default space.", {
         projectSeq: z.number().describe("Project ID"),
-        spaceSeq: z.number().describe("Space ID"),
+        spaceSeq: z
+            .number()
+            .optional()
+            .describe("Space ID (omit to use default space)"),
         isLipSync: z
             .boolean()
             .optional()
@@ -138,7 +145,8 @@ export function registerScriptTools(server, client) {
             .describe("GREEN = standard, RED = expedited"),
     }, async ({ projectSeq, spaceSeq, isLipSync, preferredSpeedType }) => {
         try {
-            await client.post(`/video-translator/api/v1/project/${projectSeq}/space/${spaceSeq}/proofread`, { isLipSync, preferredSpeedType });
+            const resolvedSpaceSeq = await resolver.resolve(spaceSeq);
+            await client.post(`/video-translator/api/v1/project/${projectSeq}/space/${resolvedSpaceSeq}/proofread`, { isLipSync, preferredSpeedType });
             return textResult("Proofread request submitted successfully.");
         }
         catch (error) {

package/dist/tools/spaces.d.ts

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

package/dist/tools/spaces.js

@@ -8,7 +8,7 @@ function formatSpace(space) {
         `Role: ${space.memberRole}`,
     ].join("\n");
 }
-export function registerSpaceTools(server, client) {
+export function registerSpaceTools(server, client, resolver) {
     server.tool("list_spaces", "List all PERSO spaces the user belongs to, or get a specific space by ID. Returns space name, plan, member count, and role.", {
         spaceSeq: z
             .number()
@@ -30,4 +30,22 @@ export function registerSpaceTools(server, client) {
             return errorResult(error);
         }
     });
+    server.tool("set_default_space", "Set the default space for all subsequent API calls. Once set, you can omit spaceSeq in other tools. If not called, the first space is used automatically.", {
+        spaceSeq: z.number().describe("Space ID to set as default"),
+    }, async ({ spaceSeq }) => {
+        try {
+            // Verify the space exists
+            const space = await client.get(`/portal/api/v1/spaces/${spaceSeq}`);
+            resolver.setDefault(spaceSeq);
+            return textResult([
+                `Default space set successfully.`,
+                formatSpace(space),
+                ``,
+                `All tools will now use this space when spaceSeq is omitted.`,
+            ].join("\n"));
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
 }

package/dist/tools/usage.d.ts

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

package/dist/tools/usage.js

@@ -1,8 +1,11 @@
 import { z } from "zod";
 import { errorResult, textResult } from "../utils/formatting.js";
-export function registerUsageTools(server, client) {
-    server.tool("get_usage", "Get PERSO plan status, estimate quota usage for a media file, or check queue status.", {
-        spaceSeq: z.number().describe("Space ID"),
+export function registerUsageTools(server, client, resolver) {
+    server.tool("get_usage", "Get PERSO plan status, estimate quota usage for a media file, or check queue status. spaceSeq is optional — omit to use the default space.", {
+        spaceSeq: z
+            .number()
+            .optional()
+            .describe("Space ID (omit to use default space)"),
         action: z
             .enum(["plan_status", "estimate_quota", "queue_status"])
             .default("plan_status")
@@ -27,7 +30,8 @@ export function registerUsageTools(server, client) {
             .describe("Number of target languages (for estimate_quota)"),
     }, async ({ spaceSeq, action, mediaType, durationMs, lipSync, width, height, targetLanguageSize }) => {
         try {
-            const basePath = `/video-translator/api/v1/projects/spaces/${spaceSeq}`;
+            const resolvedSpaceSeq = await resolver.resolve(spaceSeq);
+            const basePath = `/video-translator/api/v1/projects/spaces/${resolvedSpaceSeq}`;
             if (action === "plan_status") {
                 const status = await client.get(`${basePath}/plan/status`);
                 return textResult([

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/dist/utils/space-resolver.d.ts

@@ -0,0 +1,20 @@
+import type { PersoApiClient } from "../client.js";
+/**
+ * Caches the default spaceSeq in memory so tools don't need to
+ * repeatedly call the Spaces API.
+ *
+ * - resolve(spaceSeq?) → returns the provided value, or the cached default.
+ * - On first call without a value, fetches spaces from the API and caches the first one.
+ * - setDefault(spaceSeq) allows explicit override (e.g., via set_default_space tool).
+ */
+export declare class SpaceResolver {
+    private defaultSpaceSeq;
+    private client;
+    constructor(client: PersoApiClient);
+    /** Resolve spaceSeq: use the given value, the cached default, or auto-fetch. */
+    resolve(spaceSeq?: number): Promise<number>;
+    /** Explicitly set the default spaceSeq. */
+    setDefault(spaceSeq: number): void;
+    /** Get the currently cached default (null if not yet resolved). */
+    getDefault(): number | null;
+}

package/dist/utils/space-resolver.js

@@ -0,0 +1,38 @@
+/**
+ * Caches the default spaceSeq in memory so tools don't need to
+ * repeatedly call the Spaces API.
+ *
+ * - resolve(spaceSeq?) → returns the provided value, or the cached default.
+ * - On first call without a value, fetches spaces from the API and caches the first one.
+ * - setDefault(spaceSeq) allows explicit override (e.g., via set_default_space tool).
+ */
+export class SpaceResolver {
+    defaultSpaceSeq = null;
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /** Resolve spaceSeq: use the given value, the cached default, or auto-fetch. */
+    async resolve(spaceSeq) {
+        if (spaceSeq !== undefined) {
+            return spaceSeq;
+        }
+        if (this.defaultSpaceSeq !== null) {
+            return this.defaultSpaceSeq;
+        }
+        const spaces = await this.client.get("/portal/api/v1/spaces");
+        if (spaces.length === 0) {
+            throw new Error("No spaces found. Create a space on PERSO first, or provide spaceSeq explicitly.");
+        }
+        this.defaultSpaceSeq = spaces[0].spaceSeq;
+        return this.defaultSpaceSeq;
+    }
+    /** Explicitly set the default spaceSeq. */
+    setDefault(spaceSeq) {
+        this.defaultSpaceSeq = spaceSeq;
+    }
+    /** Get the currently cached default (null if not yet resolved). */
+    getDefault() {
+        return this.defaultSpaceSeq;
+    }
+}

package/package.json

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