freebeat-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Freebeat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,210 @@
+# freebeat-mcp
+
+MCP server for Freebeat creative workflows.
+
+Use it from MCP clients such as Claude Desktop and Cursor through `npx freebeat-mcp`.
+
+It currently supports audio and image upload, effect template discovery, AI effect generation, AI music video generation, and async task polling.
+
+## Features
+
+- Local audio upload or source URL import
+- Image upload for workflows that accept reference images
+- Supported effect template listing
+- AI effect generation
+- AI music video generation
+- Generic task polling and result retrieval
+
+## Installation
+
+Run the server through npm without a separate install step:
+
+```bash
+npx -y freebeat-mcp
+```
+
+## Prerequisites
+
+- Get your API key from [freebeat.ai](https://freebeat.ai).
+- Use an MCP client such as Claude Desktop or Cursor.
+
+## Configuration
+
+### Claude Desktop
+
+```json
+{
+  "mcpServers": {
+    "freebeat": {
+      "command": "npx",
+      "args": ["-y", "freebeat-mcp"],
+      "env": {
+        "FREEBEAT_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+```json
+{
+  "mcpServers": {
+    "freebeat": {
+      "command": "npx",
+      "args": ["-y", "freebeat-mcp"],
+      "env": {
+        "FREEBEAT_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+## Environment Variables
+
+| Variable | Required | Description |
+| --- | --- | --- |
+| `FREEBEAT_API_KEY` | Yes | API authentication key |
+
+This package depends on Freebeat online services. Available source platforms, effect templates, and generation capabilities may change with backend updates.
+
+## Tools
+
+### `upload_audio`
+
+Upload a local audio file or import from a music platform URL.
+
+Currently supported platforms:
+
+- SoundCloud
+- YouTube
+- Suno
+- Udio
+- TikTok
+- Stable Audio
+- Riffusion
+
+Provide exactly one of `file_path` or `url`.
+
+Returns a `music_id` that can be used by either `generate_music_video` or `generate_effect`.
+
+### `upload_image`
+
+Upload one or two images and receive `image_urls`.
+
+For MV generation, pass the returned `image_urls` into `generate_music_video.reference_image_urls`.
+
+For effect generation, the default recommendation is still `list_effects.image_url`, but you can also upload one image and pass `image_urls[0]` into `generate_effect.reference_image_urls`.
+
+### `list_effects`
+
+List supported effects with:
+
+- `effect_id`
+- `display_name`
+- `image_url`
+- `preview_video_url`
+- `default_music_id`
+- `default_music_name`
+- `aspect_ratio`
+
+For effect generation, pass:
+
+- `effect_id` into `generate_effect.effect_id`
+- `default_music_id` into `generate_effect.music_id`
+- `image_url` as the default single entry in `generate_effect.reference_image_urls`
+
+You can use the built-in effect image directly, or replace it with a single uploaded image URL from `upload_image`.
+
+### `generate_effect`
+
+Start an async effect generation task.
+
+Recommended flow:
+
+- `list_effects`
+- optional `upload_audio` if you want to replace the effect's default music
+- optional `upload_image` if you want to replace the effect's default image
+- `generate_effect`
+- `get_task_status`
+- `get_task_result` only after status is `completed`
+
+Parameters:
+
+- `effect_id` required
+- `music_id` required, usually `default_music_id` from `list_effects`, or a `music_id` from `upload_audio` if you want to replace it
+- `prompt` required, trimmed length must be `1` to `2000`
+- `watermark` optional, default `false`
+- `reference_image_urls` required and must contain exactly one image URL; recommended default is `list_effects.image_url`, but you can also use `upload_image.image_urls[0]`
+
+Returns a task envelope with:
+
+- `task_id`
+- `task_type` currently `effect_generation`
+- `status`
+
+### `generate_music_video`
+
+Start an async MV generation task from a `music_id` returned by `upload_audio`.
+
+Recommended flow:
+
+- `upload_audio`
+- optional `upload_image`
+- `generate_music_video`
+- `get_task_status`
+- `get_task_result` only after status is `completed`
+
+Parameters:
+
+- `music_id` required, from `upload_audio`
+- `prompt` required, trimmed length must be `1` to `2000`
+- `mv_type` optional, default `abstract`
+- `style` optional
+- `aspect_ratio` optional, default `16:9`
+- `resolution` optional, default `720`
+- `watermark` optional, default `false`
+- `start_ms` optional
+- `end_ms` optional
+- `reference_image_urls` optional
+
+Returns a task envelope with:
+
+- `task_id`
+- `task_type` currently `music_video_generation`
+- `status`
+
+### `get_task_status`
+
+Poll a Freebeat async task until it reaches a terminal status. Current MCP endpoints return lowercase status values such as `pending`, `completed`, and `failed`; older backends may still return uppercase variants.
+
+Continue polling while the status is still in progress. Only call `get_task_result` after the status is `completed`.
+
+Returns a stable task envelope including:
+
+- `task_id`
+- `task_type`
+- `status`
+- `error_message` optional, present when backend reports a failed task
+- `error_code` optional, present when backend reports a failed task
+- `message` optional, present when status is `completed` or `failed`
+
+### `get_task_result`
+
+Retrieve the output for a completed task. Only call this after `get_task_status` returns `completed`. The response uses a stable envelope with `task_id`, `task_type`, `status`, and `result`.
+
+If the task is not completed yet, this tool returns error code `TASK_NOT_COMPLETED`.
+
+If the task has failed, this tool surfaces the backend failure as an error.
+
+For current supported completed MV tasks, `result` is an object containing:
+
+- `video_url`
+- `cover_url`
+
+Completed effect generation results use the same `result` object fields:
+
+- `video_url`
+- `cover_url`

package/dist/capabilities/assets/register.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { FreebeatApiClient } from "../../services/freebeat-api.js";
+export declare function registerAssetTools(server: McpServer, client: FreebeatApiClient): void;

package/dist/capabilities/assets/register.js

@@ -0,0 +1,7 @@
+import { registerUploadAudioTool } from "./tools/upload-audio.js";
+import { registerUploadImageTool } from "./tools/upload-image.js";
+export function registerAssetTools(server, client) {
+    registerUploadAudioTool(server, client);
+    registerUploadImageTool(server, client);
+}
+//# sourceMappingURL=register.js.map

package/dist/capabilities/assets/register.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.js","sourceRoot":"","sources":["../../../src/capabilities/assets/register.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAElE,MAAM,UAAU,kBAAkB,CAChC,MAAiB,EACjB,MAAyB;IAEzB,uBAAuB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,uBAAuB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAC1C,CAAC"}

package/dist/capabilities/assets/tools/upload-audio.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { FreebeatApiClient } from "../../../services/freebeat-api.js";
+export declare function registerUploadAudioTool(server: McpServer, client: Pick<FreebeatApiClient, "createUploadUrl" | "uploadToPreSignedUrl" | "saveMusicSource">): void;

package/dist/capabilities/assets/tools/upload-audio.js

@@ -0,0 +1,70 @@
+import { z } from "zod";
+import { AppError } from "../../../core/errors.js";
+import { formatToolError, jsonContent } from "../../../core/response.js";
+import { UploadService } from "../../../services/upload-service.js";
+import { detectAudioMimeType, validateAudioFile, } from "../../../utils/file.js";
+export function registerUploadAudioTool(server, client) {
+    const uploadService = new UploadService(client);
+    server.registerTool("upload_audio", {
+        description: "Upload a local audio file or import from a supported music URL. Supported platforms: SoundCloud, YouTube, Suno, Udio, TikTok, Stable Audio, and Riffusion. Provide exactly one of file_path or url. Returns a music_id for generate_music_video or generate_effect.",
+        outputSchema: {
+            success: z
+                .literal(true)
+                .describe("Whether the audio upload or import completed successfully."),
+            music_id: z
+                .number()
+                .describe("The audio asset ID to pass into generate_music_video or generate_effect."),
+            message: z
+                .string()
+                .describe("A human-readable summary of the audio source preparation result."),
+        },
+        inputSchema: {
+            file_path: z
+                .string()
+                .optional()
+                .describe("Local audio file path. Set this or url, not both."),
+            url: z
+                .string()
+                .optional()
+                .describe("Supported music source URL from SoundCloud, YouTube, Suno, Udio, TikTok, Stable Audio, or Riffusion. Set this or file_path, not both."),
+        },
+    }, async ({ file_path, url }) => {
+        try {
+            if ((!file_path && !url) || (file_path && url)) {
+                return formatToolError(new AppError("Exactly one of file_path or url must be provided", "INVALID_PARAMS"));
+            }
+            let musicId;
+            if (file_path) {
+                validateAudioFile(file_path);
+                const finalStaticUrl = await uploadService.uploadLocalFile({
+                    filePath: file_path,
+                    keyPrefix: "dance/music",
+                    contentType: detectAudioMimeType(file_path),
+                });
+                try {
+                    musicId = await client.saveMusicSource(finalStaticUrl);
+                }
+                catch (error) {
+                    console.error(`File uploaded (${finalStaticUrl}) but saveMusicSource failed. Orphan file may exist.`);
+                    throw error;
+                }
+            }
+            else {
+                if (!url) {
+                    return formatToolError(new AppError("Exactly one of file_path or url must be provided", "INVALID_PARAMS"));
+                }
+                musicId = await client.saveMusicSource(url);
+            }
+            return jsonContent({
+                success: true,
+                music_id: musicId,
+                message: `Audio source ready. Use music_id=${musicId} with ` +
+                    "generate_music_video or generate_effect.",
+            });
+        }
+        catch (error) {
+            return formatToolError(error);
+        }
+    });
+}
+//# sourceMappingURL=upload-audio.js.map

package/dist/capabilities/assets/tools/upload-audio.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload-audio.js","sourceRoot":"","sources":["../../../../src/capabilities/assets/tools/upload-audio.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAEzE,OAAO,EAAE,aAAa,EAAE,MAAM,qCAAqC,CAAC;AACpE,OAAO,EACL,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,wBAAwB,CAAC;AAEhC,MAAM,UAAU,uBAAuB,CACrC,MAAiB,EACjB,MAGC;IAED,MAAM,aAAa,GAAG,IAAI,aAAa,CAAC,MAAM,CAAC,CAAC;IAEhD,MAAM,CAAC,YAAY,CACjB,cAAc,EACd;QACE,WAAW,EACT,qQAAqQ;QACvQ,YAAY,EAAE;YACZ,OAAO,EAAE,CAAC;iBACP,OAAO,CAAC,IAAI,CAAC;iBACb,QAAQ,CAAC,4DAA4D,CAAC;YACzE,QAAQ,EAAE,CAAC;iBACR,MAAM,EAAE;iBACR,QAAQ,CAAC,0EAA0E,CAAC;YACvF,OAAO,EAAE,CAAC;iBACP,MAAM,EAAE;iBACR,QAAQ,CAAC,kEAAkE,CAAC;SAChF;QACD,WAAW,EAAE;YACX,SAAS,EAAE,CAAC;iBACT,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CACP,mDAAmD,CACpD;YACH,GAAG,EAAE,CAAC;iBACH,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CACP,uIAAuI,CACxI;SACJ;KACF,EACD,KAAK,EAAE,EAAE,SAAS,EAAE,GAAG,EAAE,EAAE,EAAE;QAC3B,IAAI,CAAC;YACH,IAAI,CAAC,CAAC,SAAS,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,IAAI,GAAG,CAAC,EAAE,CAAC;gBAC/C,OAAO,eAAe,CACpB,IAAI,QAAQ,CAAC,kDAAkD,EAAE,gBAAgB,CAAC,CACnF,CAAC;YACJ,CAAC;YAED,IAAI,OAAe,CAAC;YAEpB,IAAI,SAAS,EAAE,CAAC;gBACd,iBAAiB,CAAC,SAAS,CAAC,CAAC;gBAE7B,MAAM,cAAc,GAAG,MAAM,aAAa,CAAC,eAAe,CAAC;oBACzD,QAAQ,EAAE,SAAS;oBACnB,SAAS,EAAE,aAAa;oBACxB,WAAW,EAAE,mBAAmB,CAAC,SAAS,CAAC;iBAC5C,CAAC,CAAC;gBAEH,IAAI,CAAC;oBACH,OAAO,GAAG,MAAM,MAAM,CAAC,eAAe,CAAC,cAAc,CAAC,CAAC;gBACzD,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,OAAO,CAAC,KAAK,CACX,kBAAkB,cAAc,sDAAsD,CACvF,CAAC;oBACF,MAAM,KAAK,CAAC;gBACd,CAAC;YACH,CAAC;iBAAM,CAAC;gBACN,IAAI,CAAC,GAAG,EAAE,CAAC;oBACT,OAAO,eAAe,CACpB,IAAI,QAAQ,CAAC,kDAAkD,EAAE,gBAAgB,CAAC,CACnF,CAAC;gBACJ,CAAC;gBAED,OAAO,GAAG,MAAM,MAAM,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC;YAC9C,CAAC;YAED,OAAO,WAAW,CAAC;gBACjB,OAAO,EAAE,IAAI;gBACb,QAAQ,EAAE,OAAO;gBACjB,OAAO,EACL,oCAAoC,OAAO,QAAQ;oBACnD,0CAA0C;aAC7C,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,OAAO,eAAe,CAAC,KAAK,CAAC,CAAC;QAChC,CAAC;IACH,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/capabilities/assets/tools/upload-image.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { FreebeatApiClient } from "../../../services/freebeat-api.js";
+export declare function registerUploadImageTool(server: McpServer, client: Pick<FreebeatApiClient, "createUploadUrl" | "uploadToPreSignedUrl">): void;

package/dist/capabilities/assets/tools/upload-image.js

@@ -0,0 +1,67 @@
+import { z } from "zod";
+import { formatToolError, jsonContent } from "../../../core/response.js";
+import { UploadService } from "../../../services/upload-service.js";
+import { detectImageMimeType, validateImageFile, } from "../../../utils/file.js";
+export function registerUploadImageTool(server, client) {
+    const uploadService = new UploadService(client);
+    server.registerTool("upload_image", {
+        description: "Upload one or two image files (PNG/JPG/JPEG, max 10MB each) for Freebeat workflows. Use returned image_urls in generate_music_video.reference_image_urls, or pass a single uploaded image URL to generate_effect.reference_image_urls to replace the default list_effects.image_url.",
+        outputSchema: {
+            success: z
+                .literal(true)
+                .describe("Whether the image upload completed successfully."),
+            image_urls: z
+                .array(z
+                .string()
+                .describe("A static URL for an uploaded image."))
+                .describe("The uploaded image URLs returned by Freebeat."),
+            message: z
+                .string()
+                .describe("A human-readable summary of the upload result."),
+        },
+        inputSchema: {
+            file_paths: z
+                .array(z.string())
+                .min(1)
+                .max(2)
+                .describe("Local image file paths to upload. Provide 1 to 2 image files."),
+        },
+    }, async ({ file_paths }) => {
+        try {
+            for (const filePath of file_paths) {
+                validateImageFile(filePath);
+            }
+            const imageUrls = [];
+            for (let index = 0; index < file_paths.length; index += 1) {
+                const filePath = file_paths[index];
+                try {
+                    const finalStaticUrl = await uploadService.uploadLocalFile({
+                        filePath,
+                        keyPrefix: "agent/character",
+                        contentType: detectImageMimeType(filePath),
+                        keySuffix: String(index),
+                    });
+                    imageUrls.push(finalStaticUrl);
+                }
+                catch (error) {
+                    if (imageUrls.length > 0) {
+                        console.error(`Image upload failed at file ${index + 1}/${file_paths.length}. ` +
+                            `${imageUrls.length} previously uploaded image(s) may be orphaned on S3: ${imageUrls.join(", ")}`);
+                    }
+                    throw error;
+                }
+            }
+            return jsonContent({
+                success: true,
+                image_urls: imageUrls,
+                message: `Uploaded ${imageUrls.length} image(s). Use image_urls with ` +
+                    "generate_music_video.reference_image_urls, or use one uploaded image URL in " +
+                    "generate_effect.reference_image_urls to replace the default effect image.",
+            });
+        }
+        catch (error) {
+            return formatToolError(error);
+        }
+    });
+}
+//# sourceMappingURL=upload-image.js.map

package/dist/capabilities/assets/tools/upload-image.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload-image.js","sourceRoot":"","sources":["../../../../src/capabilities/assets/tools/upload-image.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAEzE,OAAO,EAAE,aAAa,EAAE,MAAM,qCAAqC,CAAC;AACpE,OAAO,EACL,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,wBAAwB,CAAC;AAEhC,MAAM,UAAU,uBAAuB,CACrC,MAAiB,EACjB,MAA2E;IAE3E,MAAM,aAAa,GAAG,IAAI,aAAa,CAAC,MAAM,CAAC,CAAC;IAEhD,MAAM,CAAC,YAAY,CACjB,cAAc,EACd;QACE,WAAW,EACT,sRAAsR;QACxR,YAAY,EAAE;YACZ,OAAO,EAAE,CAAC;iBACP,OAAO,CAAC,IAAI,CAAC;iBACb,QAAQ,CAAC,kDAAkD,CAAC;YAC/D,UAAU,EAAE,CAAC;iBACV,KAAK,CACJ,CAAC;iBACE,MAAM,EAAE;iBACR,QAAQ,CAAC,qCAAqC,CAAC,CACnD;iBACA,QAAQ,CAAC,+CAA+C,CAAC;YAC5D,OAAO,EAAE,CAAC;iBACP,MAAM,EAAE;iBACR,QAAQ,CAAC,gDAAgD,CAAC;SAC9D;QACD,WAAW,EAAE;YACX,UAAU,EAAE,CAAC;iBACV,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;iBACjB,GAAG,CAAC,CAAC,CAAC;iBACN,GAAG,CAAC,CAAC,CAAC;iBACN,QAAQ,CAAC,+DAA+D,CAAC;SAC7E;KACF,EACD,KAAK,EAAE,EAAE,UAAU,EAAE,EAAE,EAAE;QACvB,IAAI,CAAC;YACH,KAAK,MAAM,QAAQ,IAAI,UAAU,EAAE,CAAC;gBAClC,iBAAiB,CAAC,QAAQ,CAAC,CAAC;YAC9B,CAAC;YAED,MAAM,SAAS,GAAa,EAAE,CAAC;YAC/B,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,UAAU,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;gBAC1D,MAAM,QAAQ,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;gBAEnC,IAAI,CAAC;oBACH,MAAM,cAAc,GAAG,MAAM,aAAa,CAAC,eAAe,CAAC;wBACzD,QAAQ;wBACR,SAAS,EAAE,iBAAiB;wBAC5B,WAAW,EAAE,mBAAmB,CAAC,QAAQ,CAAC;wBAC1C,SAAS,EAAE,MAAM,CAAC,KAAK,CAAC;qBACzB,CAAC,CAAC;oBACH,SAAS,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;gBACjC,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;wBACzB,OAAO,CAAC,KAAK,CACX,+BAA+B,KAAK,GAAG,CAAC,IAAI,UAAU,CAAC,MAAM,IAAI;4BAC/D,GAAG,SAAS,CAAC,MAAM,wDAAwD,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACpG,CAAC;oBACJ,CAAC;oBACD,MAAM,KAAK,CAAC;gBACd,CAAC;YACH,CAAC;YAED,OAAO,WAAW,CAAC;gBACjB,OAAO,EAAE,IAAI;gBACb,UAAU,EAAE,SAAS;gBACrB,OAAO,EACL,YAAY,SAAS,CAAC,MAAM,iCAAiC;oBAC7D,8EAA8E;oBAC9E,2EAA2E;aAC9E,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,OAAO,eAAe,CAAC,KAAK,CAAC,CAAC;QAChC,CAAC;IACH,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/capabilities/effects/register.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { FreebeatApiClient } from "../../services/freebeat-api.js";
+export declare function registerEffectTools(server: McpServer, client: FreebeatApiClient): void;

package/dist/capabilities/effects/register.js

@@ -0,0 +1,7 @@
+import { registerGenerateEffectTool } from "./tools/generate-effect.js";
+import { registerListEffectsTool } from "./tools/list-effects.js";
+export function registerEffectTools(server, client) {
+    registerListEffectsTool(server, client);
+    registerGenerateEffectTool(server, client);
+}
+//# sourceMappingURL=register.js.map

package/dist/capabilities/effects/register.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.js","sourceRoot":"","sources":["../../../src/capabilities/effects/register.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,0BAA0B,EAAE,MAAM,4BAA4B,CAAC;AACxE,OAAO,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAElE,MAAM,UAAU,mBAAmB,CACjC,MAAiB,EACjB,MAAyB;IAEzB,uBAAuB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,0BAA0B,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAC7C,CAAC"}

package/dist/capabilities/effects/task-type.d.ts

@@ -0,0 +1 @@
+export { EFFECT_TASK_TYPE } from "../../core/task-types.js";

package/dist/capabilities/effects/task-type.js

@@ -0,0 +1,2 @@
+export { EFFECT_TASK_TYPE } from "../../core/task-types.js";
+//# sourceMappingURL=task-type.js.map

package/dist/capabilities/effects/task-type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-type.js","sourceRoot":"","sources":["../../../src/capabilities/effects/task-type.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/capabilities/effects/tools/generate-effect.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { FreebeatApiClient } from "../../../services/freebeat-api.js";
+export declare function registerGenerateEffectTool(server: McpServer, client: Pick<FreebeatApiClient, "generateEffect">): void;

package/dist/capabilities/effects/tools/generate-effect.js

@@ -0,0 +1,81 @@
+import { z } from "zod";
+import { AppError } from "../../../core/errors.js";
+import { normalizeGenerationPrompt } from "../../../core/prompt.js";
+import { formatToolError, jsonContent } from "../../../core/response.js";
+export function registerGenerateEffectTool(server, client) {
+    server.registerTool("generate_effect", {
+        description: "Start AI effect generation from an effect template, a music_id, and exactly one reference image URL. Recommended flow: list_effects -> optional upload_audio -> optional upload_image -> generate_effect -> get_task_status -> get_task_result. By default, use list_effects.image_url. You can also use a single uploaded image URL from upload_image. Only call get_task_result after get_task_status returns completed.",
+        outputSchema: {
+            success: z
+                .literal(true)
+                .describe("Whether the effect task was created successfully."),
+            task_id: z
+                .string()
+                .describe("The asynchronous task ID for status and result lookups."),
+            task_type: z
+                .string()
+                .describe("The task category returned by Freebeat."),
+            status: z
+                .string()
+                .describe("The initial task status, typically pending."),
+            message: z
+                .string()
+                .describe("A human-readable summary of the task creation result."),
+        },
+        inputSchema: {
+            effect_id: z.number().int().describe("Effect ID returned by list_effects."),
+            music_id: z
+                .number()
+                .int()
+                .describe("Music ID to use for the effect. Usually default_music_id from list_effects, or a music_id from upload_audio if you want to replace it."),
+            prompt: z
+                .string()
+                .trim()
+                .min(1, "prompt must not be empty or whitespace only")
+                .max(2000, "prompt must be at most 2000 characters after trimming")
+                .describe("Required task instruction. After trimming whitespace it must be 1 to 2000 characters and should describe how you want the effect task to be done."),
+            watermark: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe("Whether to apply a watermark to the generated effect video."),
+            reference_image_urls: z
+                .array(z
+                .string()
+                .describe("Single image URL. Recommended: list_effects.image_url. You may also use a single uploaded image URL from upload_image."))
+                .length(1, "reference_image_urls must contain exactly one image URL")
+                .describe("Exactly one image URL. Recommended: use list_effects.image_url. You may also use a single uploaded image URL from upload_image."),
+        },
+    }, async ({ effect_id, music_id, prompt, watermark, reference_image_urls, }) => {
+        try {
+            const normalizedPrompt = normalizeGenerationPrompt(prompt);
+            if (!Number.isInteger(effect_id)) {
+                return formatToolError(new AppError("effect_id must be an integer", "INVALID_PARAMS"));
+            }
+            if (!Number.isInteger(music_id)) {
+                return formatToolError(new AppError("music_id must be an integer", "INVALID_PARAMS"));
+            }
+            if (reference_image_urls.length !== 1) {
+                return formatToolError(new AppError("reference_image_urls must contain exactly one image URL", "INVALID_PARAMS"));
+            }
+            const result = await client.generateEffect({
+                effect_id,
+                music_id,
+                prompt: normalizedPrompt,
+                watermark: watermark ?? false,
+                reference_image_urls,
+            });
+            return jsonContent({
+                success: true,
+                task_id: result.task_id,
+                task_type: result.task_type,
+                status: result.status,
+                message: `Effect generation queued. Use get_task_status with task_id="${result.task_id}" to check status.`,
+            });
+        }
+        catch (error) {
+            return formatToolError(error);
+        }
+    });
+}
+//# sourceMappingURL=generate-effect.js.map

package/dist/capabilities/effects/tools/generate-effect.js.map

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

package/dist/capabilities/effects/tools/list-effects.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { FreebeatApiClient } from "../../../services/freebeat-api.js";
+export declare function registerListEffectsTool(server: McpServer, client: Pick<FreebeatApiClient, "listEffects">): void;

package/dist/capabilities/effects/tools/list-effects.js

@@ -0,0 +1,55 @@
+import { z } from "zod";
+import { formatToolError, jsonContent } from "../../../core/response.js";
+function normalizeEffect(effect) {
+    return {
+        effect_id: effect.effectsTypeId,
+        display_name: effect.effectsDisplayName,
+        image_url: effect.coverUrl,
+        preview_video_url: effect.videoUrl,
+        default_music_id: effect.musicId,
+        default_music_name: effect.musicName,
+        aspect_ratio: effect.aspectRatio,
+    };
+}
+export function registerListEffectsTool(server, client) {
+    server.registerTool("list_effects", {
+        description: "List supported effects with the metadata needed to select an effect and create an effect task. Each effect includes a default image_url and default_music_id you can use directly.",
+        outputSchema: {
+            success: z
+                .literal(true)
+                .describe("Whether the effects list was retrieved successfully."),
+            effects: z
+                .array(z.object({
+                effect_id: z.number().describe("Effect ID for generate_effect.effect_id."),
+                display_name: z.string().describe("Human-readable effect name."),
+                image_url: z
+                    .string()
+                    .describe("Default cover image URL for generate_effect.reference_image_urls[0]. You may also replace it with a single uploaded image URL from upload_image."),
+                preview_video_url: z.string().describe("Preview video URL for the effect."),
+                default_music_id: z
+                    .number()
+                    .describe("Default music ID to pass to generate_effect.music_id."),
+                default_music_name: z.string().describe("Default music display name."),
+                aspect_ratio: z.string().describe("Preview aspect ratio."),
+            }))
+                .describe("Supported effects with the metadata needed to create an effect task."),
+            message: z
+                .string()
+                .describe("A human-readable summary of the retrieved effects."),
+        },
+        inputSchema: {},
+    }, async () => {
+        try {
+            const effects = await client.listEffects();
+            return jsonContent({
+                success: true,
+                effects: effects.map(normalizeEffect),
+                message: `Retrieved ${effects.length} effect(s).`,
+            });
+        }
+        catch (error) {
+            return formatToolError(error);
+        }
+    });
+}
+//# sourceMappingURL=list-effects.js.map

package/dist/capabilities/effects/tools/list-effects.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-effects.js","sourceRoot":"","sources":["../../../../src/capabilities/effects/tools/list-effects.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAGzE,SAAS,eAAe,CAAC,MAAsB;IAC7C,OAAO;QACL,SAAS,EAAE,MAAM,CAAC,aAAa;QAC/B,YAAY,EAAE,MAAM,CAAC,kBAAkB;QACvC,SAAS,EAAE,MAAM,CAAC,QAAQ;QAC1B,iBAAiB,EAAE,MAAM,CAAC,QAAQ;QAClC,gBAAgB,EAAE,MAAM,CAAC,OAAO;QAChC,kBAAkB,EAAE,MAAM,CAAC,SAAS;QACpC,YAAY,EAAE,MAAM,CAAC,WAAW;KACjC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,uBAAuB,CACrC,MAAiB,EACjB,MAA8C;IAE9C,MAAM,CAAC,YAAY,CACjB,cAAc,EACd;QACE,WAAW,EACT,oLAAoL;QACtL,YAAY,EAAE;YACZ,OAAO,EAAE,CAAC;iBACP,OAAO,CAAC,IAAI,CAAC;iBACb,QAAQ,CAAC,sDAAsD,CAAC;YACnE,OAAO,EAAE,CAAC;iBACP,KAAK,CACJ,CAAC,CAAC,MAAM,CAAC;gBACP,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,0CAA0C,CAAC;gBAC1E,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,6BAA6B,CAAC;gBAChE,SAAS,EAAE,CAAC;qBACT,MAAM,EAAE;qBACR,QAAQ,CAAC,kJAAkJ,CAAC;gBAC/J,iBAAiB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,mCAAmC,CAAC;gBAC3E,gBAAgB,EAAE,CAAC;qBAChB,MAAM,EAAE;qBACR,QAAQ,CAAC,uDAAuD,CAAC;gBACpE,kBAAkB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,6BAA6B,CAAC;gBACtE,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,uBAAuB,CAAC;aAC3D,CAAC,CACH;iBACA,QAAQ,CAAC,sEAAsE,CAAC;YACnF,OAAO,EAAE,CAAC;iBACP,MAAM,EAAE;iBACR,QAAQ,CAAC,oDAAoD,CAAC;SAClE;QACD,WAAW,EAAE,EAAE;KAChB,EACD,KAAK,IAAI,EAAE;QACT,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,WAAW,EAAE,CAAC;YAE3C,OAAO,WAAW,CAAC;gBACjB,OAAO,EAAE,IAAI;gBACb,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC;gBACrC,OAAO,EAAE,aAAa,OAAO,CAAC,MAAM,aAAa;aAClD,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,OAAO,eAAe,CAAC,KAAK,CAAC,CAAC;QAChC,CAAC;IACH,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/capabilities/mv/register.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { FreebeatApiClient } from "../../services/freebeat-api.js";
+export declare function registerMvTools(server: McpServer, client: FreebeatApiClient): void;

package/dist/capabilities/mv/register.js

@@ -0,0 +1,5 @@
+import { registerGenerateMusicVideoTool } from "./tools/generate-music-video.js";
+export function registerMvTools(server, client) {
+    registerGenerateMusicVideoTool(server, client);
+}
+//# sourceMappingURL=register.js.map

package/dist/capabilities/mv/register.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.js","sourceRoot":"","sources":["../../../src/capabilities/mv/register.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,8BAA8B,EAAE,MAAM,iCAAiC,CAAC;AAEjF,MAAM,UAAU,eAAe,CAC7B,MAAiB,EACjB,MAAyB;IAEzB,8BAA8B,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AACjD,CAAC"}

package/dist/capabilities/mv/task-type.d.ts

@@ -0,0 +1 @@
+export { MUSIC_VIDEO_TASK_TYPE } from "../../core/task-types.js";

package/dist/capabilities/mv/task-type.js

@@ -0,0 +1,2 @@
+export { MUSIC_VIDEO_TASK_TYPE } from "../../core/task-types.js";
+//# sourceMappingURL=task-type.js.map

package/dist/capabilities/mv/task-type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-type.js","sourceRoot":"","sources":["../../../src/capabilities/mv/task-type.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/capabilities/mv/tools/generate-music-video.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { FreebeatApiClient } from "../../../services/freebeat-api.js";
+export declare function registerGenerateMusicVideoTool(server: McpServer, client: Pick<FreebeatApiClient, "generateMusicVideo">): void;