@centrali-io/centrali-mcp 4.5.1 → 4.5.2

package/dist/tools/describe.js

@@ -368,6 +368,37 @@ function registerDescribeTools(server) {
                                     "}",
                                 ].join("\n"),
                             },
+                            media_metadata: {
+                                description: "When audio or video files are uploaded, Centrali automatically extracts metadata (duration, codec, resolution, bitrate) using FFprobe and stores it on the file record.",
+                                api_response: "GET /files/meta/{id} returns duration (seconds), width, height, codec, and bitrate fields for media files. These fields are null for non-media files.",
+                                render_url_headers: {
+                                    description: "The render URL response includes media metadata as HTTP headers — no separate API call needed.",
+                                    headers: {
+                                        "X-Media-Duration": "Duration in seconds (e.g., '42.350')",
+                                        "X-Media-Width": "Video width in pixels",
+                                        "X-Media-Height": "Video height in pixels",
+                                        "X-Media-Codec": "Primary codec (e.g., 'opus', 'aac', 'h264')",
+                                        "X-Media-Bitrate": "Bitrate in bits per second",
+                                    },
+                                    note: "Headers are only present when metadata is available. Use a HEAD request to retrieve metadata without downloading the file. All X-Media-* headers are exposed via CORS.",
+                                },
+                                example: [
+                                    "// Get duration from render URL headers (no extra API call)",
+                                    "const url = centrali.getFileRenderUrl(renderId);",
+                                    "const resp = await fetch(url, {",
+                                    "  method: 'HEAD',",
+                                    "  headers: { Authorization: `Bearer ${token}` }",
+                                    "});",
+                                    "const duration = parseFloat(resp.headers.get('X-Media-Duration') ?? '0');",
+                                    "const codec = resp.headers.get('X-Media-Codec');",
+                                    "",
+                                    "// Or get it from the file metadata API",
+                                    "const fileMeta = await centrali.getFileMeta(fileId);",
+                                    "console.log(fileMeta.duration); // 42.35 (seconds)",
+                                    "console.log(fileMeta.codec);    // 'opus'",
+                                ].join("\n"),
+                                supported_formats: "All formats FFprobe can parse — MP3, AAC, WAV, FLAC, OGG, WebM/Opus, MP4, WebM/VP9, MOV, AVI, and more.",
+                            },
                             download_url: {
                                 method: "client.getFileDownloadUrl(renderId)",
                                 note: "Returns a URL that triggers a file download. Same auth rules as render URLs.",
@@ -378,6 +409,7 @@ function registerDescribeTools(server) {
                                 "Store the renderId on a record field — then use getFileRenderUrl() to build the URL when displaying",
                                 "Use image transformations for thumbnails instead of uploading multiple sizes",
                                 "For private images in browser apps: either use a server-side proxy route or a publishable key with storage scope",
+                                "For audio/video files: use X-Media-Duration header or file metadata API to get duration — don't rely on browser metadata parsing, which fails for some container formats (e.g., WebM/Opus)",
                             ],
                         },
                         realtime: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@centrali-io/centrali-mcp",
-  "version": "4.5.1",
+  "version": "4.5.2",
   "description": "Centrali MCP Server - AI assistant integration for Centrali workspaces",
   "main": "dist/index.js",
   "type": "commonjs",

package/src/tools/describe.ts

@@ -376,6 +376,37 @@ export function registerDescribeTools(server: McpServer) {
                     "}",
                   ].join("\n"),
                 },
+                media_metadata: {
+                  description: "When audio or video files are uploaded, Centrali automatically extracts metadata (duration, codec, resolution, bitrate) using FFprobe and stores it on the file record.",
+                  api_response: "GET /files/meta/{id} returns duration (seconds), width, height, codec, and bitrate fields for media files. These fields are null for non-media files.",
+                  render_url_headers: {
+                    description: "The render URL response includes media metadata as HTTP headers — no separate API call needed.",
+                    headers: {
+                      "X-Media-Duration": "Duration in seconds (e.g., '42.350')",
+                      "X-Media-Width": "Video width in pixels",
+                      "X-Media-Height": "Video height in pixels",
+                      "X-Media-Codec": "Primary codec (e.g., 'opus', 'aac', 'h264')",
+                      "X-Media-Bitrate": "Bitrate in bits per second",
+                    },
+                    note: "Headers are only present when metadata is available. Use a HEAD request to retrieve metadata without downloading the file. All X-Media-* headers are exposed via CORS.",
+                  },
+                  example: [
+                    "// Get duration from render URL headers (no extra API call)",
+                    "const url = centrali.getFileRenderUrl(renderId);",
+                    "const resp = await fetch(url, {",
+                    "  method: 'HEAD',",
+                    "  headers: { Authorization: `Bearer ${token}` }",
+                    "});",
+                    "const duration = parseFloat(resp.headers.get('X-Media-Duration') ?? '0');",
+                    "const codec = resp.headers.get('X-Media-Codec');",
+                    "",
+                    "// Or get it from the file metadata API",
+                    "const fileMeta = await centrali.getFileMeta(fileId);",
+                    "console.log(fileMeta.duration); // 42.35 (seconds)",
+                    "console.log(fileMeta.codec);    // 'opus'",
+                  ].join("\n"),
+                  supported_formats: "All formats FFprobe can parse — MP3, AAC, WAV, FLAC, OGG, WebM/Opus, MP4, WebM/VP9, MOV, AVI, and more.",
+                },
                 download_url: {
                   method: "client.getFileDownloadUrl(renderId)",
                   note: "Returns a URL that triggers a file download. Same auth rules as render URLs.",
@@ -386,6 +417,7 @@ export function registerDescribeTools(server: McpServer) {
                   "Store the renderId on a record field — then use getFileRenderUrl() to build the URL when displaying",
                   "Use image transformations for thumbnails instead of uploading multiple sizes",
                   "For private images in browser apps: either use a server-side proxy route or a publishable key with storage scope",
+                  "For audio/video files: use X-Media-Duration header or file metadata API to get duration — don't rely on browser metadata parsing, which fails for some container formats (e.g., WebM/Opus)",
                 ],
               },
               realtime: {