perso-mcp-server 1.0.0

package/dist/client.d.ts

@@ -0,0 +1,19 @@
+export declare class PersoApiError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly description: string;
+    constructor(code: string, status: number, description: string);
+}
+export declare class PersoApiClient {
+    private baseUrl;
+    private apiKey;
+    constructor(baseUrl: string, apiKey: string);
+    private buildUrl;
+    request<T>(method: string, path: string, body?: unknown, query?: Record<string, string>): Promise<T>;
+    get<T>(path: string, query?: Record<string, string>): Promise<T>;
+    post<T>(path: string, body?: unknown, query?: Record<string, string>): Promise<T>;
+    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>;
+}
+export declare function createClient(): PersoApiClient;

package/dist/client.js

@@ -0,0 +1,93 @@
+export class PersoApiError extends Error {
+    code;
+    status;
+    description;
+    constructor(code, status, description) {
+        super(`[${code}] ${description}`);
+        this.code = code;
+        this.status = status;
+        this.description = description;
+        this.name = "PersoApiError";
+    }
+}
+export class PersoApiClient {
+    baseUrl;
+    apiKey;
+    constructor(baseUrl, apiKey) {
+        this.baseUrl = baseUrl.replace(/\/$/, "");
+        this.apiKey = apiKey;
+    }
+    buildUrl(path, query) {
+        const url = new URL(path, this.baseUrl);
+        if (query) {
+            for (const [key, value] of Object.entries(query)) {
+                if (value !== undefined && value !== null) {
+                    url.searchParams.set(key, value);
+                }
+            }
+        }
+        return url.toString();
+    }
+    async request(method, path, body, query) {
+        const url = this.buildUrl(path, query);
+        const headers = {
+            "XP-API-KEY": this.apiKey,
+            "Content-Type": "application/json",
+        };
+        const response = await fetch(url, {
+            method,
+            headers,
+            body: body ? JSON.stringify(body) : undefined,
+        });
+        if (!response.ok) {
+            let errorCode = "UNKNOWN";
+            let errorDescription = `HTTP ${response.status}`;
+            try {
+                const errorBody = await response.json();
+                if (errorBody.code)
+                    errorCode = errorBody.code;
+                if (errorBody.message)
+                    errorDescription = errorBody.message;
+                if (errorBody.description)
+                    errorDescription = errorBody.description;
+            }
+            catch {
+                // response body is not JSON
+            }
+            throw new PersoApiError(errorCode, response.status, errorDescription);
+        }
+        if (response.status === 204) {
+            return undefined;
+        }
+        const json = await response.json();
+        // Unwrap {"result": {...}} if present
+        if (json && typeof json === "object" && "result" in json) {
+            return json.result;
+        }
+        return json;
+    }
+    async get(path, query) {
+        return this.request("GET", path, undefined, query);
+    }
+    async post(path, body, query) {
+        return this.request("POST", path, body, query);
+    }
+    async put(path, body, query) {
+        return this.request("PUT", path, body, query);
+    }
+    async patch(path, body, query) {
+        return this.request("PATCH", path, body, query);
+    }
+    async delete(path, query) {
+        return this.request("DELETE", path, undefined, query);
+    }
+}
+export function createClient() {
+    const apiKey = process.env.PERSO_API_KEY;
+    if (!apiKey) {
+        throw new Error("PERSO_API_KEY environment variable is required. " +
+            "Set it to your PERSO API key (e.g., pk_live_...).");
+    }
+    const baseUrl = process.env.PERSO_API_BASE_URL || "https://dev-developers.perso.ai";
+    return new PersoApiClient(baseUrl, apiKey);
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createClient } from "./client.js";
+import { registerSpaceTools } from "./tools/spaces.js";
+import { registerFileTools } from "./tools/files.js";
+import { registerProjectTools } from "./tools/projects.js";
+import { registerScriptTools } from "./tools/scripts.js";
+import { registerUsageTools } from "./tools/usage.js";
+import { registerLanguageTools } from "./tools/languages.js";
+import { registerCommunityTools } from "./tools/community.js";
+import { registerLipSyncTools } from "./tools/lip-sync.js";
+import { registerFeedbackTools } from "./tools/feedback.js";
+async function main() {
+    const client = createClient();
+    const server = new McpServer({
+        name: "perso-mcp-server",
+        version: "1.0.0",
+    });
+    registerSpaceTools(server, client);
+    registerFileTools(server, client);
+    registerProjectTools(server, client);
+    registerScriptTools(server, client);
+    registerUsageTools(server, client);
+    registerLanguageTools(server, client);
+    registerCommunityTools(server, client);
+    registerLipSyncTools(server, client);
+    registerFeedbackTools(server, client);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("PERSO MCP Server running on stdio");
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});

package/dist/tools/community.d.ts

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

package/dist/tools/community.js

@@ -0,0 +1,101 @@
+import { z } from "zod";
+import { errorResult, textResult } from "../utils/formatting.js";
+export function registerCommunityTools(server, client) {
+    // Tool: manage_sharing
+    server.tool("manage_sharing", "Get or toggle the share link for a PERSO project.", {
+        projectSeq: z.number().describe("Project ID"),
+        action: z
+            .enum(["get_link", "toggle_sharing"])
+            .describe("get_link: get share URL. toggle_sharing: enable/disable sharing."),
+        enabled: z
+            .boolean()
+            .optional()
+            .describe("Enable or disable sharing (required for toggle_sharing)"),
+    }, async ({ projectSeq, action, enabled }) => {
+        try {
+            const basePath = `/video-translator/api/v1/projects/${projectSeq}/share`;
+            if (action === "get_link") {
+                const result = await client.get(basePath);
+                return textResult(`Share link query: ${result.shareQuery}`);
+            }
+            // toggle_sharing
+            if (enabled === undefined) {
+                return errorResult(new Error("enabled is required for toggle_sharing"));
+            }
+            await client.patch(basePath, undefined, {
+                sharedStatus: String(enabled),
+            });
+            return textResult(`Sharing ${enabled ? "enabled" : "disabled"} for project ${projectSeq}.`);
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+    // Tool: browse_community
+    server.tool("browse_community", "Browse PERSO community featured projects or view a shared project.", {
+        action: z
+            .enum(["list_featured", "get_featured", "get_shared"])
+            .describe("list_featured: browse featured projects. get_featured: get details of a featured project. get_shared: view a shared project by query string."),
+        projectSeq: z
+            .number()
+            .optional()
+            .describe("Project ID (required for get_featured)"),
+        sharedQuery: z
+            .string()
+            .optional()
+            .describe("Encrypted query string (required for get_shared)"),
+        page: z.number().optional().default(0).describe("Page number"),
+        size: z.number().optional().default(10).describe("Page size"),
+        languageCode: z
+            .string()
+            .optional()
+            .describe("Filter by language code (for list_featured)"),
+    }, async ({ action, projectSeq, sharedQuery, page, size, languageCode }) => {
+        try {
+            const basePath = "/video-translator/api/v1/projects";
+            if (action === "list_featured") {
+                const query = {
+                    page: String(page),
+                    size: String(size),
+                };
+                if (languageCode)
+                    query.languageCode = languageCode;
+                const result = await client.get(`${basePath}/recommended`, query);
+                if (result.content.length === 0) {
+                    return textResult("No featured projects found.");
+                }
+                const lines = result.content.map((p) => `${p.title} (ID: ${p.projectSeq}) - ${p.sourceLanguageCode} → ${p.targetLanguageCode}`);
+                return textResult(`Featured Projects:\n${lines.join("\n")}`);
+            }
+            if (action === "get_featured") {
+                if (projectSeq === undefined) {
+                    return errorResult(new Error("projectSeq is required for get_featured"));
+                }
+                const project = await client.get(`${basePath}/recommended/${projectSeq}`);
+                return textResult([
+                    `Title: ${project.title}`,
+                    `Languages: ${project.sourceLanguageCode} → ${project.targetLanguageCode}`,
+                    project.videoUrl ? `Video: ${project.videoUrl}` : null,
+                    `Thumbnail: ${project.thumbnailUrl}`,
+                ]
+                    .filter(Boolean)
+                    .join("\n"));
+            }
+            // get_shared
+            if (!sharedQuery) {
+                return errorResult(new Error("sharedQuery is required for get_shared"));
+            }
+            const shared = await client.get(`${basePath}/shared/${sharedQuery}`);
+            return textResult([
+                `Shared Project: ${shared.title}`,
+                `Languages: ${shared.sourceLanguageCode} → ${shared.targetLanguageCode}`,
+                shared.videoUrl ? `Video: ${shared.videoUrl}` : null,
+            ]
+                .filter(Boolean)
+                .join("\n"));
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+}

package/dist/tools/feedback.d.ts

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

package/dist/tools/feedback.js

@@ -0,0 +1,50 @@
+import { z } from "zod";
+import { errorResult, textResult } from "../utils/formatting.js";
+export function registerFeedbackTools(server, client) {
+    server.tool("manage_feedback", "Submit or retrieve feedback for a PERSO translation project. Rate translations from 1 to 5.", {
+        action: z
+            .enum(["submit", "get"])
+            .describe("submit: rate a project. get: retrieve existing feedback."),
+        projectSeq: z.number().describe("Project ID"),
+        rating: z
+            .number()
+            .min(1)
+            .max(5)
+            .optional()
+            .describe("Rating from 1 to 5 (required for submit)"),
+    }, async ({ action, projectSeq, rating }) => {
+        try {
+            const basePath = "/video-translator/api/v1/projects/feedbacks";
+            if (action === "submit") {
+                if (rating === undefined) {
+                    return errorResult(new Error("rating is required for submit"));
+                }
+                const result = await client.post(basePath, {
+                    projectSeq,
+                    rating,
+                });
+                return textResult([
+                    `Feedback submitted.`,
+                    `Average Rating: ${result.averageRating}`,
+                    `Total Feedbacks: ${result.count}`,
+                ].join("\n"));
+            }
+            // get
+            const result = await client.get(basePath, {
+                projectSeq: String(projectSeq),
+            });
+            if (!result) {
+                return textResult("No feedback submitted for this project yet.");
+            }
+            return textResult([
+                `Project ${projectSeq} Feedback:`,
+                `Your Rating: ${result.rating}`,
+                `Average Rating: ${result.averageRating}`,
+                `Total Feedbacks: ${result.count}`,
+            ].join("\n"));
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+}

package/dist/tools/files.d.ts

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

package/dist/tools/files.js

@@ -0,0 +1,69 @@
+import { z } from "zod";
+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."),
+        mediaType: z
+            .enum(["video", "audio"])
+            .describe("Type of media to upload"),
+        fileUrl: z.string().describe("Direct file URL or external platform URL"),
+        fileName: z
+            .string()
+            .describe("File name with extension (e.g., 'my_video.mp4')"),
+    }, async ({ spaceSeq, source, mediaType, fileUrl, fileName }) => {
+        try {
+            if (source === "external") {
+                const result = await client.put("/file/api/upload/video/external", { spaceSeq, fileUrl, fileName });
+                return textResult([
+                    `Upload successful (external)`,
+                    `Media ID: ${result.seq}`,
+                    `Duration: ${result.durationMs}ms`,
+                    `Size: ${result.size} bytes`,
+                ].join("\n"));
+            }
+            // Direct URL upload - validate first, then upload
+            await client.post("/file/api/v1/media/validate", {
+                fileName,
+                fileUrl,
+                mediaType: mediaType.toUpperCase(),
+            });
+            const endpoint = mediaType === "video"
+                ? "/file/api/upload/video"
+                : "/file/api/upload/audio";
+            const result = await client.put(endpoint, {
+                spaceSeq,
+                fileUrl,
+                fileName,
+            });
+            const filePath = result.videoFilePath || result.audioFilePath || "";
+            return textResult([
+                `Upload successful`,
+                `Media ID: ${result.seq}`,
+                `File Path: ${filePath}`,
+                `Duration: ${result.durationMs}ms`,
+                `Size: ${result.size} bytes`,
+            ].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.", {
+        url: z.string().describe("YouTube, TikTok, or Google Drive URL"),
+    }, async ({ url }) => {
+        try {
+            const metadata = await client.post("/file/api/v1/video-translator/external/metadata", { url });
+            return textResult([
+                `Title: ${metadata.title}`,
+                `Duration: ${metadata.durationMs}ms`,
+                `Thumbnail: ${metadata.thumbnailUrl}`,
+            ].join("\n"));
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+}

package/dist/tools/languages.d.ts

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

package/dist/tools/languages.js

@@ -0,0 +1,13 @@
+import { errorResult, textResult } from "../utils/formatting.js";
+export function registerLanguageTools(server, client) {
+    server.tool("list_languages", "List all supported languages for PERSO video translation. Returns language codes, names, and native names.", {}, async () => {
+        try {
+            const languages = await client.get("/video-translator/api/v1/languages");
+            const lines = languages.map((lang) => `${lang.languageCode}: ${lang.languageName} (${lang.nativeName})`);
+            return textResult(`Supported Languages (${languages.length}):\n${lines.join("\n")}`);
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+}

package/dist/tools/lip-sync.d.ts

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

package/dist/tools/lip-sync.js

@@ -0,0 +1,45 @@
+import { z } from "zod";
+import { errorResult, textResult } from "../utils/formatting.js";
+export function registerLipSyncTools(server, client) {
+    // 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.", {
+        projectSeq: z.number().describe("Project ID"),
+        spaceSeq: z.number().describe("Space ID"),
+        preferredSpeedType: z
+            .enum(["GREEN", "RED"])
+            .optional()
+            .default("GREEN")
+            .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 });
+            return textResult([
+                `Lip sync requested successfully.`,
+                `Generation IDs: ${result.generationIds?.join(", ") || "N/A"}`,
+                `Use get_lip_sync_history to check progress.`,
+            ].join("\n"));
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+    // 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.", {
+        projectSeq: z.number().describe("Project ID"),
+        spaceSeq: z.number().describe("Space ID"),
+        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) });
+            if (result.content.length === 0) {
+                return textResult("No lip sync history found.");
+            }
+            const lines = result.content.map((g) => `[${g.createdAt}] #${g.generationSeq} - Type: ${g.type}, Status: ${g.status}`);
+            return textResult(`Lip Sync History:\n${lines.join("\n")}`);
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+}

package/dist/tools/projects.d.ts

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

package/dist/tools/projects.js

@@ -0,0 +1,277 @@
+import { z } from "zod";
+import { errorResult, textResult } from "../utils/formatting.js";
+function formatProject(project) {
+    return [
+        `Project: ${project.title} (ID: ${project.projectSeq})`,
+        `Status: ${project.status}`,
+        `Type: ${project.type}`,
+        `Source: ${project.sourceLanguageCode} → ${(project.targetLanguageCodes || []).join(", ")}`,
+        `Created: ${project.createdAt}`,
+        `Updated: ${project.updatedAt}`,
+    ].join("\n");
+}
+export function registerProjectTools(server, client) {
+    // 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"),
+        mediaSeq: z.number().describe("Media sequence ID from upload_media"),
+        isVideoProject: z
+            .boolean()
+            .describe("true for video project, false for audio-only"),
+        sourceLanguageCode: z
+            .string()
+            .describe("Source language code (e.g., 'en')"),
+        targetLanguageCodes: z
+            .array(z.string())
+            .describe("Target language codes (e.g., ['ko', 'ja'])"),
+        numberOfSpeakers: z
+            .number()
+            .optional()
+            .describe("Number of speakers (auto-detected if omitted)"),
+        withLipSync: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Enable lip sync"),
+        preferredSpeedType: z
+            .enum(["GREEN", "RED"])
+            .optional()
+            .default("GREEN")
+            .describe("GREEN = standard speed, RED = expedited"),
+    }, async ({ spaceSeq, mediaSeq, isVideoProject, sourceLanguageCode, targetLanguageCodes, numberOfSpeakers, withLipSync, preferredSpeedType, }) => {
+        try {
+            // Initialize queue first (idempotent)
+            await client.put(`/video-translator/api/v1/projects/spaces/${spaceSeq}/queue`);
+            const body = {
+                mediaSeq,
+                isVideoProject,
+                sourceLanguageCode,
+                targetLanguageCodes,
+                preferredSpeedType,
+            };
+            if (numberOfSpeakers !== undefined)
+                body.numberOfSpeakers = numberOfSpeakers;
+            if (withLipSync)
+                body.withLipSync = withLipSync;
+            const result = await client.post(`/video-translator/api/v1/projects/spaces/${spaceSeq}/translate`, body);
+            const ids = result.startGenerateProjectIdList;
+            return textResult([
+                `Translation project(s) created successfully!`,
+                `Project IDs: ${ids.join(", ")}`,
+                `Use get_project with these IDs to check progress.`,
+            ].join("\n"));
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+    // 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"),
+        offset: z.number().optional().default(0).describe("Page offset"),
+        size: z.number().optional().default(20).describe("Page size (max 100)"),
+        sort: z
+            .string()
+            .optional()
+            .default("update_date")
+            .describe("Sort field: 'update_date' or 'title'"),
+        type: z
+            .enum(["DUBBING", "LIP_SYNC"])
+            .optional()
+            .describe("Filter by project type"),
+    }, async ({ spaceSeq, offset, size, sort, type }) => {
+        try {
+            const query = {
+                offset: String(offset),
+                size: String(size),
+                sort,
+            };
+            if (type)
+                query.type = type;
+            const result = await client.get(`/video-translator/api/v1/projects/spaces/${spaceSeq}`, query);
+            if (result.content.length === 0) {
+                return textResult("No projects found.");
+            }
+            const header = `Projects (${result.totalElements} total, page ${result.number + 1}/${result.totalPages}):`;
+            const projects = result.content.map(formatProject).join("\n\n");
+            return textResult(`${header}\n\n${projects}`);
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+    // 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.", {
+        projectSeq: z.number().describe("Project ID"),
+        spaceSeq: z.number().describe("Space ID"),
+        include: z
+            .array(z.enum([
+            "details",
+            "progress",
+            "video_info",
+            "download_info",
+            "used_features",
+            "retranslation_status",
+        ]))
+            .optional()
+            .default(["details"])
+            .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 sections = [];
+            const fetchers = {
+                details: async () => {
+                    const project = await client.get(basePath);
+                    return formatProject(project);
+                },
+                progress: async () => {
+                    const progress = await client.get(`${basePathAlt}/progress`);
+                    return [
+                        `--- Progress ---`,
+                        `Progress: ${progress.progress}%`,
+                        `Remaining Time: ${progress.remainingTime}s`,
+                        `Cancelable: ${progress.isCancelable}`,
+                    ].join("\n");
+                },
+                video_info: async () => {
+                    const info = await client.get(`${basePath}/video-info`);
+                    return [
+                        `--- Video Info ---`,
+                        `Resolution: ${info.resolution} (${info.width}x${info.height})`,
+                        `Duration: ${info.durationMs}ms`,
+                        `Aspect Ratio: ${info.aspectRatio}`,
+                        `Status: ${info.status}`,
+                    ].join("\n");
+                },
+                download_info: async () => {
+                    const info = await client.get(`${basePath}/download-info`);
+                    return [
+                        `--- Download Availability ---`,
+                        `Video: ${info.videoAvailable}`,
+                        `Audio: ${info.audioAvailable}`,
+                        `SRT: ${info.srtAvailable}`,
+                    ].join("\n");
+                },
+                used_features: async () => {
+                    const features = await client.get(`${basePath}/used-features`);
+                    return [
+                        `--- Used Features ---`,
+                        `Custom Dictionary: ${features.usedCustomDictionary}`,
+                        `SRT Upload: ${features.usedSrtUpload}`,
+                    ].join("\n");
+                },
+                retranslation_status: async () => {
+                    const status = await client.get(`${basePath}/retranslation/status`);
+                    return `--- Retranslation ---\nAvailable: ${status.retranslateAvailable}`;
+                },
+            };
+            const results = await Promise.allSettled(include.map(async (key) => {
+                const fetcher = fetchers[key];
+                if (fetcher)
+                    return fetcher();
+                return `Unknown include: ${key}`;
+            }));
+            for (const result of results) {
+                if (result.status === "fulfilled") {
+                    sections.push(result.value);
+                }
+                else {
+                    sections.push(`Error: ${result.reason}`);
+                }
+            }
+            return textResult(sections.join("\n\n"));
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+    // Tool: manage_project
+    server.tool("manage_project", "Manage a PERSO project: update title, update access permissions, delete, or cancel translation.", {
+        projectSeq: z.number().describe("Project ID"),
+        spaceSeq: z.number().describe("Space ID"),
+        action: z
+            .enum(["update_title", "update_access", "delete", "cancel"])
+            .describe("Action to perform"),
+        title: z
+            .string()
+            .optional()
+            .describe("New title (required for update_title)"),
+        accessPermission: z
+            .enum(["individual", "all"])
+            .optional()
+            .describe("Access level (required for update_access)"),
+    }, async ({ projectSeq, spaceSeq, action, title, accessPermission }) => {
+        try {
+            const basePath = `/video-translator/api/v1/projects/${projectSeq}/spaces/${spaceSeq}`;
+            switch (action) {
+                case "update_title": {
+                    if (!title) {
+                        return errorResult(new Error("title is required for update_title action"));
+                    }
+                    await client.patch(`${basePath}/title`, { newTitle: title });
+                    return textResult(`Project title updated to: ${title}`);
+                }
+                case "update_access": {
+                    if (!accessPermission) {
+                        return errorResult(new Error("accessPermission is required for update_access action"));
+                    }
+                    await client.patch(`${basePath}/access`, undefined, {
+                        permission: accessPermission,
+                    });
+                    return textResult(`Project access updated to: ${accessPermission}`);
+                }
+                case "delete": {
+                    await client.delete(basePath);
+                    return textResult(`Project ${projectSeq} deleted successfully.`);
+                }
+                case "cancel": {
+                    await client.post(`${basePath}/cancel`);
+                    return textResult(`Project ${projectSeq} translation cancelled.`);
+                }
+            }
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+    // Tool: download_project
+    server.tool("download_project", "Get download links for a PERSO project's translated files (video, audio, SRT) or view export history.", {
+        projectSeq: z.number().describe("Project ID"),
+        spaceSeq: z.number().describe("Space ID"),
+        action: z
+            .enum(["get_links", "export_history"])
+            .optional()
+            .default("get_links")
+            .describe("get_links: download URLs. export_history: past export records."),
+    }, async ({ projectSeq, spaceSeq, action }) => {
+        try {
+            if (action === "export_history") {
+                const basePath = `/video-translator/api/v1/projects/${projectSeq}/space/${spaceSeq}`;
+                const history = await client.get(`${basePath}/export-history`);
+                if (history.content.length === 0) {
+                    return textResult("No export history found.");
+                }
+                const entries = history.content.map((e) => `[${e.createdAt}] ${e.exportType}: ${e.downloadUrl}`);
+                return textResult(`Export History:\n${entries.join("\n")}`);
+            }
+            // get_links
+            const basePath = `/video-translator/api/v1/projects/${projectSeq}/spaces/${spaceSeq}`;
+            const links = await client.get(`${basePath}/download`);
+            const parts = ["Download Links:"];
+            if (links.video)
+                parts.push(`Video: ${links.video}`);
+            if (links.audio)
+                parts.push(`Audio: ${links.audio}`);
+            if (links.srt)
+                parts.push(`SRT: ${links.srt}`);
+            if (parts.length === 1)
+                parts.push("No download links available yet.");
+            return textResult(parts.join("\n"));
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+}

package/dist/tools/scripts.d.ts

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

package/dist/tools/scripts.js

@@ -0,0 +1,148 @@
+import { z } from "zod";
+import { errorResult, textResult } from "../utils/formatting.js";
+export function registerScriptTools(server, client) {
+    // 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.", {
+        projectSeq: z.number().describe("Project ID"),
+        spaceSeq: z.number().describe("Space ID"),
+        cursorId: z
+            .number()
+            .optional()
+            .describe("Cursor for pagination (omit for first page)"),
+        size: z
+            .number()
+            .optional()
+            .default(50)
+            .describe("Number of sentences to return"),
+    }, async ({ projectSeq, spaceSeq, cursorId, size }) => {
+        try {
+            const basePath = `/video-translator/api/v1/projects/${projectSeq}/spaces/${spaceSeq}/script`;
+            const query = { size: String(size) };
+            if (cursorId !== undefined)
+                query.cursorId = String(cursorId);
+            const result = await client.get(basePath, query);
+            if (result.sentences.length === 0) {
+                return textResult("No sentences found.");
+            }
+            const lines = result.sentences.map((s) => [
+                `[#${s.sentenceSeq}] Speaker ${s.speakerSeq}`,
+                `  Original: ${s.originalText}`,
+                `  Translated: ${s.targetText}`,
+                `  Match Rate: ${s.matchingRate}%`,
+                s.audioUrl ? `  Audio: ${s.audioUrl}` : null,
+            ]
+                .filter(Boolean)
+                .join("\n"));
+            const footer = result.hasNext
+                ? `\n--- Has more sentences. Next cursor: ${result.nextCursorId} ---`
+                : "\n--- End of script ---";
+            return textResult(lines.join("\n\n") + footer);
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+    // Tool: edit_sentence
+    server.tool("edit_sentence", "Edit a translated sentence in a PERSO project. Actions: translate (update text), generate_audio (regenerate audio), reset (revert to original), cancel (stop in-progress), temp_save (save draft), match_rewrite (get quality metrics).", {
+        projectSeq: z.number().describe("Project ID"),
+        sentenceSeq: z
+            .number()
+            .describe("Sentence or audio sentence sequence ID"),
+        action: z
+            .enum([
+            "translate",
+            "generate_audio",
+            "reset",
+            "cancel",
+            "temp_save",
+            "match_rewrite",
+        ])
+            .describe("Action to perform on the sentence"),
+        targetText: z
+            .string()
+            .optional()
+            .describe("New translation text (required for translate, generate_audio, temp_save, match_rewrite)"),
+        speakerSeq: z
+            .number()
+            .optional()
+            .describe("Speaker ID (for temp_save)"),
+    }, async ({ projectSeq, sentenceSeq, action, targetText, speakerSeq }) => {
+        try {
+            const basePath = `/video-translator/api/v1/project/${projectSeq}/audio-sentence/${sentenceSeq}`;
+            switch (action) {
+                case "translate": {
+                    if (!targetText) {
+                        return errorResult(new Error("targetText is required for translate"));
+                    }
+                    const result = await client.patch(basePath, { targetText });
+                    return textResult(`Sentence translated. Match rate: ${result.matchingRate}%`);
+                }
+                case "generate_audio": {
+                    if (!targetText) {
+                        return errorResult(new Error("targetText is required for generate_audio"));
+                    }
+                    const result = await client.patch(`${basePath}/generate-audio`, { targetText });
+                    return textResult([
+                        `Audio generated.`,
+                        `File: ${result.generateAudioFilePath}`,
+                        `Match rate: ${result.matchingRate}%`,
+                    ].join("\n"));
+                }
+                case "reset": {
+                    await client.put(`${basePath}/reset`);
+                    return textResult("Sentence reset to original translation.");
+                }
+                case "cancel": {
+                    await client.put(`${basePath}/cancel`);
+                    return textResult("Sentence translation cancelled.");
+                }
+                case "temp_save": {
+                    const body = {};
+                    if (targetText)
+                        body.originalDraftText = targetText;
+                    if (speakerSeq !== undefined)
+                        body.speakerSeq = speakerSeq;
+                    await client.post(`${basePath}/temp-save`, body);
+                    return textResult("Draft saved temporarily.");
+                }
+                case "match_rewrite": {
+                    if (!targetText) {
+                        return errorResult(new Error("targetText is required for match_rewrite"));
+                    }
+                    const result = await client.post(`${basePath}/match-rewrite`, { targetText });
+                    const parts = [`Match rate: ${result.matchingRate}%`];
+                    if (result.rewriteText) {
+                        parts.push(`Suggested rewrite: ${result.rewriteText}`);
+                    }
+                    return textResult(parts.join("\n"));
+                }
+            }
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+    // Tool: request_proofread
+    server.tool("request_proofread", "Request AI proofreading for all sentences in a PERSO translation project.", {
+        projectSeq: z.number().describe("Project ID"),
+        spaceSeq: z.number().describe("Space ID"),
+        isLipSync: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Whether this is a lip sync project"),
+        preferredSpeedType: z
+            .enum(["GREEN", "RED"])
+            .optional()
+            .default("GREEN")
+            .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 });
+            return textResult("Proofread request submitted successfully.");
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+}

package/dist/tools/spaces.d.ts

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

package/dist/tools/spaces.js

@@ -0,0 +1,33 @@
+import { z } from "zod";
+import { errorResult, textResult } from "../utils/formatting.js";
+function formatSpace(space) {
+    return [
+        `Space: ${space.spaceName} (ID: ${space.spaceSeq})`,
+        `Plan: ${space.planName}`,
+        `Members: ${space.memberCount}/${space.seat}`,
+        `Role: ${space.memberRole}`,
+    ].join("\n");
+}
+export function registerSpaceTools(server, client) {
+    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()
+            .optional()
+            .describe("Space ID to get a specific space. Omit to list all spaces."),
+    }, async ({ spaceSeq }) => {
+        try {
+            if (spaceSeq !== undefined) {
+                const space = await client.get(`/portal/api/v1/spaces/${spaceSeq}`);
+                return textResult(formatSpace(space));
+            }
+            const spaces = await client.get("/portal/api/v1/spaces");
+            if (spaces.length === 0) {
+                return textResult("No spaces found.");
+            }
+            return textResult(`Spaces (${spaces.length}):\n\n${spaces.map(formatSpace).join("\n\n")}`);
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+}

package/dist/tools/usage.d.ts

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

package/dist/tools/usage.js

@@ -0,0 +1,69 @@
+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"),
+        action: z
+            .enum(["plan_status", "estimate_quota", "queue_status"])
+            .default("plan_status")
+            .describe("plan_status: current quota and plan info. estimate_quota: estimate how much quota a media file will use. queue_status: check translation queue."),
+        mediaType: z
+            .enum(["VIDEO", "AUDIO"])
+            .optional()
+            .describe("Media type (required for estimate_quota)"),
+        durationMs: z
+            .number()
+            .optional()
+            .describe("Media duration in milliseconds (required for estimate_quota)"),
+        lipSync: z
+            .boolean()
+            .optional()
+            .describe("Whether lip sync is enabled (for estimate_quota)"),
+        width: z.number().optional().describe("Video width in pixels (for estimate_quota)"),
+        height: z.number().optional().describe("Video height in pixels (for estimate_quota)"),
+        targetLanguageSize: z
+            .number()
+            .optional()
+            .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}`;
+            if (action === "plan_status") {
+                const status = await client.get(`${basePath}/plan/status`);
+                return textResult([
+                    `Plan: ${status.planTier}`,
+                    `Remaining Quota: ${status.remainingQuota}`,
+                    `Reset: ${status.resetDateTime}`,
+                    `Cancelled: ${status.isCancelled}`,
+                ].join("\n"));
+            }
+            if (action === "estimate_quota") {
+                const query = {};
+                if (mediaType)
+                    query.mediaType = mediaType;
+                if (durationMs !== undefined)
+                    query.durationMs = String(durationMs);
+                if (lipSync !== undefined)
+                    query.lipSync = String(lipSync);
+                if (width !== undefined)
+                    query.width = String(width);
+                if (height !== undefined)
+                    query.height = String(height);
+                if (targetLanguageSize !== undefined)
+                    query.targetLanguageSize = String(targetLanguageSize);
+                const estimate = await client.get(`${basePath}/media/quota`, query);
+                return textResult([
+                    `Estimated Quota: ${estimate.estimatedQuota}`,
+                    `Remaining Quota: ${estimate.remainingQuota}`,
+                    `Available: ${estimate.isAvailable}`,
+                ].join("\n"));
+            }
+            // queue_status
+            const queue = await client.put(`${basePath}/queue`);
+            return textResult(`Queue: ${queue.usedQueueCount}/${queue.maxQueueCount} used`);
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    });
+}

package/dist/types.d.ts

@@ -0,0 +1,129 @@
+export interface Space {
+    spaceSeq: number;
+    spaceName: string;
+    memberCount: number;
+    seat: number;
+    planName: string;
+    memberRole: string;
+}
+export interface MediaUploadResult {
+    seq: number;
+    videoFilePath?: string;
+    audioFilePath?: string;
+    durationMs: number;
+    size: number;
+}
+export interface ExternalMetadata {
+    title: string;
+    durationMs: number;
+    thumbnailUrl: string;
+}
+export interface Project {
+    projectSeq: number;
+    title: string;
+    status: string;
+    sourceLanguageCode: string;
+    targetLanguageCodes: string[];
+    createdAt: string;
+    updatedAt: string;
+    type: string;
+    progress?: number;
+    thumbnailUrl?: string;
+}
+export interface ProjectListResponse {
+    content: Project[];
+    totalElements: number;
+    totalPages: number;
+    size: number;
+    number: number;
+}
+export interface ProgressInfo {
+    progress: number;
+    remainingTime: number;
+    isCancelable: boolean;
+}
+export interface VideoInfo {
+    resolution: string;
+    durationMs: number;
+    status: string;
+    aspectRatio: string;
+    width: number;
+    height: number;
+}
+export interface DownloadLinks {
+    video?: string;
+    audio?: string;
+    srt?: string;
+}
+export interface DownloadInfo {
+    videoAvailable: boolean;
+    audioAvailable: boolean;
+    srtAvailable: boolean;
+}
+export interface Sentence {
+    sentenceSeq: number;
+    audioSentenceSeq: number;
+    originalText: string;
+    targetText: string;
+    matchingRate: number;
+    audioUrl: string;
+    speakerSeq: number;
+}
+export interface ScriptResponse {
+    sentences: Sentence[];
+    hasNext: boolean;
+    nextCursorId: number | null;
+}
+export interface Language {
+    languageCode: string;
+    languageName: string;
+    nativeName: string;
+}
+export interface PlanStatus {
+    remainingQuota: number;
+    planTier: string;
+    resetDateTime: string;
+    isCancelled: boolean;
+}
+export interface QuotaEstimate {
+    estimatedQuota: number;
+    remainingQuota: number;
+    isAvailable: boolean;
+}
+export interface QueueInfo {
+    usedQueueCount: number;
+    maxQueueCount: number;
+}
+export interface ExportHistoryEntry {
+    exportSeq: number;
+    exportType: string;
+    createdAt: string;
+    downloadUrl: string;
+}
+export interface LipSyncGeneration {
+    generationSeq: number;
+    type: string;
+    createdAt: string;
+    status: string;
+}
+export interface Feedback {
+    projectSeq: number;
+    rating: number;
+    averageRating: number;
+    count: number;
+}
+export interface FeaturedProject {
+    projectSeq: number;
+    title: string;
+    thumbnailUrl: string;
+    sourceLanguageCode: string;
+    targetLanguageCode: string;
+    videoUrl?: string;
+}
+export interface UsedFeatures {
+    usedCustomDictionary: boolean;
+    usedSrtUpload: boolean;
+}
+export interface RetranslationStatus {
+    retranslateAvailable: boolean;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+// PERSO API response types
+export {};

package/dist/utils/formatting.d.ts

@@ -0,0 +1,4 @@
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+export declare function textResult(text: string): CallToolResult;
+export declare function jsonResult(data: unknown): CallToolResult;
+export declare function errorResult(error: unknown): CallToolResult;

package/dist/utils/formatting.js

@@ -0,0 +1,25 @@
+import { PersoApiError } from "../client.js";
+export function textResult(text) {
+    return { content: [{ type: "text", text }] };
+}
+export function jsonResult(data) {
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}
+export function errorResult(error) {
+    if (error instanceof PersoApiError) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `PERSO API Error [${error.code}] (HTTP ${error.status}): ${error.description}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+        content: [{ type: "text", text: `Error: ${message}` }],
+        isError: true,
+    };
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "perso-mcp-server",
+  "version": "1.0.0",
+  "description": "MCP server for PERSO API - video translation and dubbing platform",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "perso-mcp-server": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepare": "npm run build",
+    "start": "node dist/index.js",
+    "inspect": "npx @modelcontextprotocol/inspector node dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "perso",
+    "video-translation",
+    "dubbing",
+    "ai"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  }
+}