freebeat-mcp 0.1.4 → 0.2.0

package/CHANGELOG.md

@@ -6,6 +6,14 @@ The format is based on Keep a Changelog, and this project follows Semantic Versi
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-10-23
+
+### Added
+- Export `handleHostedMcpRequest` and `FREEBEAT_SCOPES` from `freebeat-mcp/hosted` so the Freebeat website can serve MCP requests with the resolved user credentials and token scopes.
+
+### Removed
+- Standalone hosted HTTP server, OAuth grant resolver, Redis configuration, and Docker/GitOps deployment. The stdio CLI remains unchanged.
+
 ## [0.1.4] - 2026-07-10
 
 ### Added

package/README.md

@@ -4,7 +4,7 @@ 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, Open RPC image/video generation, model discovery, and async task polling.
+It currently supports audio, image, and video upload, Freebeat's music-video, dance, and lyric-video agents, effect templates, live model discovery, image/video/text generation with any model Freebeat publishes, and async task polling.
 
 ## Features
 
@@ -12,10 +12,11 @@ It currently supports audio and image upload, effect template discovery, AI effe
 - Image upload for workflows that accept reference images
 - Supported effect template listing
 - AI effect generation
-- AI music video generation
-- Supported image and video model discovery
+- Music-video, dance, and lyric-video agents in Auto mode
+- Live image, image edit, video, and text model discovery with pricing
 - AI image generation and single-image editing
-- AI text-to-video generation
+- AI video generation (text, image, transition, reference)
+- Text generation with any model on the user's Freebeat gateway
 - Generic task polling and result retrieval
 
 ## Installation
@@ -70,6 +71,13 @@ npx -y freebeat-mcp
 | Variable | Required | Description |
 | --- | --- | --- |
 | `FREEBEAT_API_KEY` | Yes | API authentication key |
+| `FREEBEAT_MV_AGENT_URL` | No | Music-video agent host, default `https://da-api.freebeat.ai` |
+| `FREEBEAT_DANCE_AGENT_URL` | No | Dance agent host, default `https://fb-dance-agent-api.freebeat.ai` |
+| `FREEBEAT_LYRIC_AGENT_URL` | No | Lyric-video agent host, default `https://lyric-video-agent-api.freebeat.ai` |
+| `FREEBEAT_WEB_HOST` | No | Site used for agent session links, default `https://freebeat.ai` |
+
+The hosted MCP endpoint is served by freebeat.ai.
+The website mounts `freebeat-mcp/hosted`.
 
 This package depends on Freebeat online services. Available source platforms, effect templates, and generation capabilities may change with backend updates.
 
@@ -89,18 +97,36 @@ Currently supported platforms:
 - Stable Audio
 - Riffusion
 
-Provide exactly one of `file_path` or `url`.
+Provide exactly one of:
+
+- `file`, a ChatGPT attachment object
+- `file_path`, for local stdio installations only
+- `url`, for a supported music platform
 
-Returns a `music_id` that can be used by either `generate_music_video` or `generate_effect`.
+Returns a `music_id` that can be used by either `create_agent_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`.
+Provide exactly one of `files` (ChatGPT attachments), `file_paths` (local stdio
+only), or `urls` (guarded public HTTPS downloads).
+
+For agent videos, pass the returned `image_urls` into `create_agent_video.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`.
 
+### `upload_video`
+
+Upload one MP4, MOV, or WebM clip and receive a `video_url` for
+`generate_lip_sync_video`. Provide exactly one of `file` (a ChatGPT attachment),
+`file_path` (local stdio only), or `url` (a guarded public HTTPS download).
+
+Hosted HTTP mode never reads caller-provided local file paths. Attachment and
+URL downloads require HTTPS, reject private or reserved network addresses and
+redirects, enforce media content types, and stream to size-limited temporary
+files that are removed after upload.
+
 ### `list_effects`
 
 List supported effects with:
@@ -148,148 +174,63 @@ Returns a task envelope with:
 - `task_type` currently `effect_generation`
 - `status`
 
-### `generate_music_video`
+### `create_agent_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`
+Start one of Freebeat's creative agents on a song in Auto mode, the same way freebeat.ai does: `music_video`, `dance`, or `lyric_video`. The agent plans, generates, and edits on its own, usually in 15-60 minutes, and spends Freebeat credits as it works.
 
 Parameters:
 
+- `product` required: `music_video`, `dance`, or `lyric_video`
 - `music_id` required, from `upload_audio`
-- `prompt` required, trimmed length must be `1` to `2000`
-- `mv_type` optional, default `abstract`
-- `style` optional
+- `prompt` optional creative direction
+- `start_ms` / `end_ms` optional song window, default the first 15 seconds; standard accounts allow 10-15 seconds, VIP accounts up to 360 seconds
 - `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:
+- `resolution` optional: `720p`/`1080p` for `music_video`, `720p` for `dance`, `768P`/`2K` for `lyric_video`
+- `image_urls` optional photos from `upload_image`
+- `remove_watermark` optional, default `false`
 
-- `task_id`
-- `task_type` currently `music_video_generation`
-- `status`
+Returns `task_id`, `task_type`, `status`, and `session_url`, the freebeat.ai page for the session. `get_task_status` reports `running`, `completed`, or `action_required`; on `action_required` (for example the account ran out of credits, or the agent needs a decision) give the user `session_url` to continue on freebeat.ai.
 
 ### `list_models`
 
-List supported Open RPC models for either `image` or `video`.
-
-Recommended flow:
-
-- `list_models` with `type: "image"` before `generate_image` or `edit_image`
-- `list_models` with `type: "video"` before `generate_video`
-- optional `get_model_help` for model-specific examples and constraints
-
-Each model entry includes:
-
-- `model_id`
-- `model`, the API model key when one is available
-- `display_name`
-- `commands`
-- `constraints`
+List the models Freebeat publishes right now. `type` is `image` (for `generate_image`), `image_edit` (for `edit_image`), `video` (for `generate_video`), or `text` (for `generate_text`). Image, image edit, and video lists come live from Freebeat's model configuration, so new models appear without a plugin update. Text models come from the user's Freebeat model gateway. Music and voice models are listed by `list_music_models`.
 
 ### `get_model_help`
 
-Show detailed usage guidance for one Open RPC model.
-
-Parameters:
-
-- `model` required, using either a numeric `model_id` or API model key from `list_models`
-
-Use this before video generation to confirm required `duration`, `resolution`, supported `aspect_ratio`, and whether `generate_audio` is supported.
-For video models, help also lists supported generation modes (`text`, `image`, `transition`, `reference`) and duration values by resolution when the local catalog has that detail.
+Show what one image, image edit, or video model accepts and what it costs, read live from Freebeat. Parameters: `type` and `model_id`. The response has the model description, per-generation-type options (aspect ratios, resolutions, durations, and credits when Freebeat publishes them), and pricing rules: `keys` name the parameters that change the price and `prices` lists the allowed combinations.
 
 ### `generate_image`
 
-Create an async Open RPC image generation batch.
-
-Recommended flow:
-
-- `list_models` with `type: "image"`
-- optional `get_model_help`
-- `generate_image`
-- `get_task_status` with the returned `batch_id`
-
-Parameters:
-
-- `model` required, from `list_models`
-- `prompt` required, trimmed length must be `1` to `2000`
-- `size` optional
-- `resolution` optional
-- `quality` optional
-- `output_format` optional, for supported models such as `png`, `jpeg`, or `webp`
-- `custom_resolution` optional, only accepted for models that support custom pixel dimensions
-- `count` optional, default `1`
+Create an async image generation batch with any model from `list_models(type=image)`.
 
-For GPT-Image 1.5 (`model_id` `70`) and GPT-Image 2 (`model_id` `108`), the MCP server sends `quality: "medium"` and `resolution: "1024x1024"` by default when omitted. GPT-Image 1.5 currently accepts `resolution` values `1024x1024`, `1536x1024`, and `1024x1536`; GPT-Image 2 exposes its broader list through `get_model_help`. If `resolution` is omitted but `size` is provided, that `size` is also sent as `resolution` for compatibility.
+Parameters: `model_id` and `prompt` (1-2000 characters) are required; `size`, `resolution`, `quality`, `output_format`, `custom_resolution`, and `count` (default `1`) are optional and passed through to Freebeat, which validates them per model. A rejected request returns the reason in `message` and the per-item `items[].message`.
 
 ### `edit_image`
 
-Create an async Open RPC single-image edit batch.
+Create an async single-image edit batch with any model from `list_models(type=image_edit)`. Parameters: `model_id`, `image` (an image URL, usually from `upload_image`), `prompt`, and the same optional image options as `generate_image`.
 
-Recommended flow:
+### `generate_video`
 
-- `upload_image` or provide an existing image URL
-- `list_models` with `type: "image"`
-- optional `get_model_help`
-- `edit_image`
-- `get_task_status` with the returned `batch_id`
+Create an async video generation batch with any model from `list_models(type=video)`.
 
 Parameters:
 
-- `model` required, from `list_models`
-- `image` required, a single image URL
-- `prompt` required, trimmed length must be `1` to `2000`
-- `size` optional
-- `resolution` optional
-- `quality` optional
-- `output_format` optional
-- `custom_resolution` optional
-- `count` optional, default `1`
-
-For Qwen Image Edit (`model_id` `76`), the MCP server sends `quality: "medium"`, `resolution: "1024x1024"`, and `customResolution: 1` by default for pricing compatibility.
+- `model_id` and `prompt` (1-2000 characters) required
+- `generation_type` optional, default `text`; `text`, `image`, `transition`, or `reference`
+- `images` image URLs from `upload_image` for non-text modes
+- `duration`, `resolution`, `aspect_ratio`, `style`, `generate_audio`, `multi_clip`, `watermark` optional
 
-### `generate_video`
+Freebeat validates the options per model; check `get_model_help` first and read `message` if a request is rejected.
 
-Create an async Open RPC video generation batch.
+### `generate_text`
 
-Recommended flow:
-
-- `list_models` with `type: "video"`
-- `get_model_help`
-- `generate_video`
-- `get_task_status` with the returned `batch_id`
-
-Parameters:
-
-- `model` required, from `list_models`
-- `prompt` required, trimmed length must be `1` to `2000`
-- `generation_type` optional, default `text`; supported values are `text`, `image`, `transition`, and `reference`
-- `images` required for non-text modes: exactly one for `image`, exactly two for `transition`, at least one for `reference`; entries may be image URLs or local image paths
-- `duration` required when the selected model declares supported durations
-- `resolution` required when the selected model declares supported resolutions
-- `aspect_ratio` optional, validated when the selected model declares supported ratios
-- `style` optional, only accepted for models that declare styles
-- `generate_audio` optional, only accepted for models that support generated audio
-- `multi_clip` optional, only accepted for models that support multi-clip generation
-- `watermark` optional, default `false`; Open RPC video requests send `watermark: 0` unless set
-
-Video model constraints are validated locally before a request is sent. Local images used for video generation must be at least `300x300` and are uploaded automatically. `wan-v2.6-video` is not exposed until its downstream reference image mapping is fixed; `kling-o3-pro` currently exposes `text`, `image`, and `transition`, but not `reference`.
+Ask any text model from `list_models(type=text)` and get its reply. Parameters: `model`, `messages` (`role` and `content`, oldest first), optional `max_tokens` and `temperature`. Usage is billed to the user's Freebeat credits through the user's own gateway token.
 
 ### `get_task_status`
 
 Poll a Freebeat async task or Open RPC batch 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.
 
-For legacy MV/effect tasks, continue polling while the status is still in progress. Only call `get_task_result` after the status is `completed`.
+For agent videos, effects, music, singing, and lip-sync tasks, continue polling while the status is still in progress. Agent videos may also report `action_required` with a `session_url` for the user. Only call `get_task_result` after the status is `completed`.
 
 For Open RPC image/video batches, pass the returned `batch_id` as `task_id`. You can also pass `serial_no` to query a single batch item. Completed batch items include result URLs directly in `get_task_status`, so `get_task_result` is not used for Open RPC batches.
 
@@ -311,7 +252,7 @@ If the task is not completed yet, this tool returns error code `TASK_NOT_COMPLET
 
 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:
+For completed agent videos, `result` is an object containing:
 
 - `video_url`
 - `cover_url`

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

@@ -0,0 +1,4 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { FreebeatApiClient } from "../../services/freebeat-api.js";
+import { ToolAccess } from "../../core/scopes.js";
+export declare function registerAgentTools(server: McpServer, client: FreebeatApiClient, access?: ToolAccess): void;

package/dist/capabilities/agents/register.js

@@ -0,0 +1,7 @@
+import { ALL_TOOL_ACCESS } from "../../core/scopes.js";
+import { registerCreateAgentVideoTool } from "./tools/create-agent-video.js";
+export function registerAgentTools(server, client, access = ALL_TOOL_ACCESS) {
+    if (access.generate)
+        registerCreateAgentVideoTool(server, client);
+}
+//# sourceMappingURL=register.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"register.js","sourceRoot":"","sources":["../../../src/capabilities/agents/register.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAc,MAAM,sBAAsB,CAAC;AACnE,OAAO,EAAE,4BAA4B,EAAE,MAAM,+BAA+B,CAAC;AAE7E,MAAM,UAAU,kBAAkB,CAChC,MAAiB,EACjB,MAAyB,EACzB,SAAqB,eAAe;IAEpC,IAAI,MAAM,CAAC,QAAQ;QAAE,4BAA4B,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AACpE,CAAC"}

package/dist/capabilities/{mv/tools/generate-music-video.d.ts → agents/tools/create-agent-video.d.ts}

@@ -1,3 +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;
+export declare function registerCreateAgentVideoTool(server: McpServer, client: Pick<FreebeatApiClient, "createAgentVideo">): void;

package/dist/capabilities/agents/tools/create-agent-video.js

@@ -0,0 +1,83 @@
+import { z } from "zod";
+import { AGENT_PRODUCT_NAMES } from "../../../core/agent-products.js";
+import { formatToolError, jsonContent } from "../../../core/response.js";
+import { CREATE_TOOL_ANNOTATIONS } from "../../../core/tool-annotations.js";
+export function registerCreateAgentVideoTool(server, client) {
+    server.registerTool("create_agent_video", {
+        description: "Start one of Freebeat's creative agents on a song in Auto mode: music_video (a full story music video), dance (dancers performing to the song; photos become the dancers), or lyric_video (an animated lyric video). Upload the song with upload_audio first and optional photos with upload_image. The agent plans, generates, and edits on its own and usually takes 15-60 minutes; it spends Freebeat credits as it works. Poll get_task_status (statuses: running, completed, action_required) and fetch get_task_result when completed. When the status is action_required, give the user session_url to review or continue on freebeat.ai.",
+        annotations: { title: "Create agent video", ...CREATE_TOOL_ANNOTATIONS },
+        inputSchema: {
+            product: z
+                .enum(AGENT_PRODUCT_NAMES)
+                .describe("Which Freebeat agent makes the video: music_video, dance, or lyric_video."),
+            music_id: z
+                .number()
+                .int()
+                .positive()
+                .describe("An analyzed music_id from upload_audio."),
+            prompt: z
+                .string()
+                .trim()
+                .max(2000)
+                .optional()
+                .describe("The user's creative direction in their own words. Leave empty to let the agent decide."),
+            start_ms: z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .describe("Start of the song window in milliseconds. Defaults to 0."),
+            end_ms: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe("End of the song window in milliseconds. Defaults to start_ms + 15000. Standard accounts allow 10-15 seconds; VIP accounts up to 360 seconds; lyric_video needs at least 4 seconds."),
+            aspect_ratio: z
+                .enum(["16:9", "9:16", "1:1", "4:3", "3:4"])
+                .default("16:9")
+                .describe("Output aspect ratio."),
+            resolution: z
+                .enum(["720p", "1080p", "768P", "2K"])
+                .optional()
+                .describe("music_video: 720p (default) or 1080p. dance: 720p only. lyric_video: 768P (default) or 2K."),
+            image_urls: z
+                .array(z.string().url())
+                .max(5)
+                .optional()
+                .describe("Optional photo URLs from upload_image: people or characters to feature, or dancers for dance."),
+            remove_watermark: z
+                .boolean()
+                .default(false)
+                .describe("Remove the Freebeat watermark if the account allows it."),
+        },
+        outputSchema: {
+            success: z.literal(true),
+            task_id: z
+                .string()
+                .describe("The scoped task ID for get_task_status and get_task_result."),
+            task_type: z.string().describe("The task category."),
+            status: z.string().describe("The initial task status, typically pending."),
+            session_url: z
+                .string()
+                .describe("The freebeat.ai page where the user can watch, review, or continue this session."),
+            message: z.string().describe("What to do next."),
+        },
+    }, async (params) => {
+        try {
+            const result = await client.createAgentVideo(params);
+            return jsonContent({
+                success: true,
+                task_id: result.task_id,
+                task_type: result.task_type,
+                status: result.status,
+                session_url: result.session_url,
+                message: "The Freebeat agent started. Poll get_task_status every few minutes; full videos usually take 15-60 minutes. Share session_url if the user wants to watch it work.",
+            });
+        }
+        catch (error) {
+            return formatToolError(error);
+        }
+    });
+}
+//# sourceMappingURL=create-agent-video.js.map

package/dist/capabilities/agents/tools/create-agent-video.js.map

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

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

@@ -1,3 +1,4 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { FreebeatApiClient } from "../../services/freebeat-api.js";
-export declare function registerAssetTools(server: McpServer, client: FreebeatApiClient): void;
+import { ToolAccess } from "../../core/scopes.js";
+export declare function registerAssetTools(server: McpServer, client: FreebeatApiClient, access?: ToolAccess, allowLocalFiles?: boolean): void;

package/dist/capabilities/assets/register.js

@@ -1,7 +1,12 @@
+import { ALL_TOOL_ACCESS } from "../../core/scopes.js";
 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);
+import { registerUploadVideoTool } from "./tools/upload-video.js";
+export function registerAssetTools(server, client, access = ALL_TOOL_ACCESS, allowLocalFiles = true) {
+    if (!access.generate)
+        return;
+    registerUploadAudioTool(server, client, allowLocalFiles);
+    registerUploadImageTool(server, client, allowLocalFiles);
+    registerUploadVideoTool(server, client, allowLocalFiles);
 }
 //# sourceMappingURL=register.js.map

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

@@ -1 +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"}
+{"version":3,"file":"register.js","sourceRoot":"","sources":["../../../src/capabilities/assets/register.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAc,MAAM,sBAAsB,CAAC;AACnE,OAAO,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAElE,MAAM,UAAU,kBAAkB,CAChC,MAAiB,EACjB,MAAyB,EACzB,SAAqB,eAAe,EACpC,eAAe,GAAG,IAAI;IAEtB,IAAI,CAAC,MAAM,CAAC,QAAQ;QAAE,OAAO;IAC7B,uBAAuB,CAAC,MAAM,EAAE,MAAM,EAAE,eAAe,CAAC,CAAC;IACzD,uBAAuB,CAAC,MAAM,EAAE,MAAM,EAAE,eAAe,CAAC,CAAC;IACzD,uBAAuB,CAAC,MAAM,EAAE,MAAM,EAAE,eAAe,CAAC,CAAC;AAC3D,CAAC"}

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

@@ -1,3 +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;
+export declare function registerUploadAudioTool(server: McpServer, client: Pick<FreebeatApiClient, "createUploadUrl" | "uploadToPreSignedUrl" | "saveMusicSource">, allowLocalFiles?: boolean): void;

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

@@ -1,45 +1,76 @@
 import { z } from "zod";
 import { AppError } from "../../../core/errors.js";
+import { validateSupportedMusicSourceUrl } from "../../../core/music-source-url.js";
+import { openAiFileSchema } from "../../../core/openai-file.js";
 import { formatToolError, jsonContent } from "../../../core/response.js";
+import { CREATE_TOOL_ANNOTATIONS } from "../../../core/tool-annotations.js";
+import { downloadRemoteMedia, removeRemoteMedia, } from "../../../services/remote-media.js";
 import { UploadService } from "../../../services/upload-service.js";
 import { detectAudioMimeType, validateAudioFile, } from "../../../utils/file.js";
-export function registerUploadAudioTool(server, client) {
+const REMOTE_AUDIO_TYPES = {
+    "audio/mpeg": "mp3",
+    "audio/wav": "wav",
+    "audio/x-wav": "wav",
+    "audio/ogg": "ogg",
+    "audio/flac": "flac",
+    "audio/x-flac": "flac",
+    "audio/aac": "aac",
+    "audio/x-aac": "aac",
+};
+const MAX_AUDIO_BYTES = 50 * 1024 * 1024;
+export function registerUploadAudioTool(server, client, allowLocalFiles = true) {
     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.",
+        description: "Upload an attached audio file, 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, file_path, or url. Returns a music_id for Freebeat video workflows.",
+        annotations: { title: "Upload audio", ...CREATE_TOOL_ANNOTATIONS },
+        _meta: { "openai/fileParams": ["file"] },
         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."),
+                .describe("The audio asset ID to pass into create_agent_video or generate_effect."),
             message: z
                 .string()
                 .describe("A human-readable summary of the audio source preparation result."),
         },
         inputSchema: {
+            file: openAiFileSchema
+                .optional()
+                .describe("Audio attachment supplied by ChatGPT."),
             file_path: z
                 .string()
                 .optional()
-                .describe("Local audio file path. Set this or url, not both."),
+                .describe("Local audio file path for stdio installations. Not available on the hosted server."),
             url: z
                 .string()
+                .url()
                 .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 }) => {
+    }, async ({ file, file_path, url }) => {
+        let remotePath;
         try {
-            if ((!file_path && !url) || (file_path && url)) {
-                return formatToolError(new AppError("Exactly one of file_path or url must be provided", "INVALID_PARAMS"));
+            const inputCount = Number(Boolean(file)) + Number(Boolean(file_path)) + Number(Boolean(url));
+            if (inputCount !== 1) {
+                return formatToolError(new AppError("Exactly one of file, file_path, or url must be provided", "INVALID_PARAMS"));
+            }
+            if (file_path && !allowLocalFiles) {
+                return formatToolError(new AppError("This hosted server cannot read local file paths. Provide url instead.", "INVALID_PARAMS"));
             }
             let musicId;
-            if (file_path) {
-                validateAudioFile(file_path);
+            if (file || file_path) {
+                const localPath = file_path
+                    ?? (remotePath = await downloadRemoteMedia(file.download_url, {
+                        acceptedTypes: REMOTE_AUDIO_TYPES,
+                        maxBytes: MAX_AUDIO_BYTES,
+                    }));
+                validateAudioFile(localPath);
                 const finalStaticUrl = await uploadService.uploadLocalFile({
-                    filePath: file_path,
+                    filePath: localPath,
                     keyPrefix: "dance/music",
-                    contentType: detectAudioMimeType(file_path),
+                    contentType: detectAudioMimeType(localPath),
                 });
                 try {
                     musicId = await client.saveMusicSource(finalStaticUrl);
@@ -50,21 +81,23 @@ export function registerUploadAudioTool(server, client) {
                 }
             }
             else {
-                if (!url) {
-                    return formatToolError(new AppError("Exactly one of file_path or url must be provided", "INVALID_PARAMS"));
-                }
+                validateSupportedMusicSourceUrl(url);
                 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.",
+                    "create_agent_video or generate_effect.",
             });
         }
         catch (error) {
             return formatToolError(error);
         }
+        finally {
+            if (remotePath)
+                await removeRemoteMedia(remotePath).catch(() => { });
+        }
     });
 }
 //# sourceMappingURL=upload-audio.js.map

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

@@ -1 +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"}
+{"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,+BAA+B,EAAE,MAAM,mCAAmC,CAAC;AACpF,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACzE,OAAO,EAAE,uBAAuB,EAAE,MAAM,mCAAmC,CAAC;AAE5E,OAAO,EACL,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,qCAAqC,CAAC;AACpE,OAAO,EACL,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,wBAAwB,CAAC;AAEhC,MAAM,kBAAkB,GAAG;IACzB,YAAY,EAAE,KAAK;IACnB,WAAW,EAAE,KAAK;IAClB,aAAa,EAAE,KAAK;IACpB,WAAW,EAAE,KAAK;IAClB,YAAY,EAAE,MAAM;IACpB,cAAc,EAAE,MAAM;IACtB,WAAW,EAAE,KAAK;IAClB,aAAa,EAAE,KAAK;CACrB,CAAC;AACF,MAAM,eAAe,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;AAEzC,MAAM,UAAU,uBAAuB,CACrC,MAAiB,EACjB,MAGC,EACD,eAAe,GAAG,IAAI;IAEtB,MAAM,aAAa,GAAG,IAAI,aAAa,CAAC,MAAM,CAAC,CAAC;IAEhD,MAAM,CAAC,YAAY,CACjB,cAAc,EACd;QACE,WAAW,EACT,6RAA6R;QAC/R,WAAW,EAAE,EAAE,KAAK,EAAE,cAAc,EAAE,GAAG,uBAAuB,EAAE;QAClE,KAAK,EAAE,EAAE,mBAAmB,EAAE,CAAC,MAAM,CAAC,EAAE;QACxC,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,wEAAwE,CAAC;YACrF,OAAO,EAAE,CAAC;iBACP,MAAM,EAAE;iBACR,QAAQ,CAAC,kEAAkE,CAAC;SAChF;QACD,WAAW,EAAE;YACX,IAAI,EAAE,gBAAgB;iBACnB,QAAQ,EAAE;iBACV,QAAQ,CAAC,uCAAuC,CAAC;YACpD,SAAS,EAAE,CAAC;iBACT,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CACP,oFAAoF,CACrF;YACH,GAAG,EAAE,CAAC;iBACH,MAAM,EAAE;iBACR,GAAG,EAAE;iBACL,QAAQ,EAAE;iBACV,QAAQ,CACP,uIAAuI,CACxI;SACJ;KACF,EACD,KAAK,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,EAAE,EAAE;QACjC,IAAI,UAA8B,CAAC;QACnC,IAAI,CAAC;YACH,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;YAC7F,IAAI,UAAU,KAAK,CAAC,EAAE,CAAC;gBACrB,OAAO,eAAe,CACpB,IAAI,QAAQ,CAAC,yDAAyD,EAAE,gBAAgB,CAAC,CAC1F,CAAC;YACJ,CAAC;YACD,IAAI,SAAS,IAAI,CAAC,eAAe,EAAE,CAAC;gBAClC,OAAO,eAAe,CACpB,IAAI,QAAQ,CACV,uEAAuE,EACvE,gBAAgB,CACjB,CACF,CAAC;YACJ,CAAC;YAED,IAAI,OAAe,CAAC;YAEpB,IAAI,IAAI,IAAI,SAAS,EAAE,CAAC;gBACtB,MAAM,SAAS,GAAG,SAAS;uBACtB,CAAC,UAAU,GAAG,MAAM,mBAAmB,CAAC,IAAK,CAAC,YAAY,EAAE;wBAC7D,aAAa,EAAE,kBAAkB;wBACjC,QAAQ,EAAE,eAAe;qBAC1B,CAAC,CAAC,CAAC;gBACN,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,+BAA+B,CAAC,GAAI,CAAC,CAAC;gBACtC,OAAO,GAAG,MAAM,MAAM,CAAC,eAAe,CAAC,GAAI,CAAC,CAAC;YAC/C,CAAC;YAED,OAAO,WAAW,CAAC;gBACjB,OAAO,EAAE,IAAI;gBACb,QAAQ,EAAE,OAAO;gBACjB,OAAO,EACL,oCAAoC,OAAO,QAAQ;oBACnD,wCAAwC;aAC3C,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,OAAO,eAAe,CAAC,KAAK,CAAC,CAAC;QAChC,CAAC;gBAAS,CAAC;YACT,IAAI,UAAU;gBAAE,MAAM,iBAAiB,CAAC,UAAU,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QACtE,CAAC;IACH,CAAC,CACF,CAAC;AACJ,CAAC"}

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

@@ -1,3 +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;
+export declare function registerUploadImageTool(server: McpServer, client: Pick<FreebeatApiClient, "createUploadUrl" | "uploadToPreSignedUrl">, allowLocalFiles?: boolean): void;