@centrali-io/centrali-mcp 4.5.0 → 4.5.2

package/README.md

@@ -17,7 +17,7 @@ Add to your MCP client configuration (e.g., Claude Desktop, Cursor):
       "command": "npx",
       "args": ["@centrali-io/centrali-mcp"],
       "env": {
-        "CENTRALI_URL": "https://dev.centrali.io",
+        "CENTRALI_URL": "https://centrali.io",
         "CENTRALI_CLIENT_ID": "<service-account-client-id>",
         "CENTRALI_CLIENT_SECRET": "<service-account-secret>",
         "CENTRALI_WORKSPACE": "my-workspace"
@@ -31,7 +31,7 @@ Add to your MCP client configuration (e.g., Claude Desktop, Cursor):
 
 | Variable | Required | Description |
 |----------|----------|-------------|
-| `CENTRALI_URL` | Yes | Centrali instance URL (e.g., `https://dev.centrali.io`) |
+| `CENTRALI_URL` | Yes | Centrali instance URL (e.g., `https://centrali.io`) |
 | `CENTRALI_CLIENT_ID` | Yes | Service account client ID |
 | `CENTRALI_CLIENT_SECRET` | Yes | Service account client secret |
 | `CENTRALI_WORKSPACE` | Yes | Workspace slug to operate in |
@@ -268,7 +268,7 @@ npm install
 npm run build
 
 # Test with MCP inspector
-CENTRALI_URL=https://dev.centrali.io \
+CENTRALI_URL=https://centrali.io \
 CENTRALI_CLIENT_ID=... \
 CENTRALI_CLIENT_SECRET=... \
 CENTRALI_WORKSPACE=my-workspace \

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: {
@@ -598,6 +630,24 @@ function registerDescribeTools(server) {
                             description: "Comma-separated list of reference field names to expand (join). Returns the full referenced record instead of just the ID.",
                             example: "expand: 'customer,product'",
                         },
+                        dateWindow: {
+                            description: "Date range filter. Restricts results to records where a date field falls within a given range. Both 'from' and 'to' are optional (open-ended ranges allowed).",
+                            shape: {
+                                field: "string — date field to filter on (e.g., 'createdAt', 'updatedAt', or a custom date field)",
+                                from: "string? — ISO 8601 lower bound (inclusive)",
+                                to: "string? — ISO 8601 upper bound (inclusive)",
+                            },
+                            examples: {
+                                "Last 30 days": { field: "createdAt", from: "2024-03-01T00:00:00Z" },
+                                "Specific range": { field: "updatedAt", from: "2024-01-01T00:00:00Z", to: "2024-03-31T23:59:59Z" },
+                            },
+                        },
+                        includeDeleted: {
+                            description: "Set to true to include soft-deleted records in the results (default: false). Alias: includeArchived, all.",
+                        },
+                        includeTotal: {
+                            description: "Set to true to include the total record count in response metadata (default: false).",
+                        },
                         upsert: {
                             description: "Atomic create-or-update. Provide 'match' fields to find existing record and 'data' for the full record body.",
                             example: {

package/dist/tools/records.js

@@ -90,14 +90,14 @@ function createRecordsClient(sdk, centraliUrl, workspaceId, recordSlug) {
     return client;
 }
 function registerRecordTools(server, sdk, centraliUrl, workspaceId) {
-    server.tool("query_records", "Query records from a collection with optional filters, sorting, and pagination. Filters use 'data.' prefix for custom fields and bracket notation for operators (e.g., 'data.status': 'active', 'data.price[lte]': 100).", {
+    server.tool("query_records", "Query records from a collection with optional filters, sorting, pagination, and date range filtering. Filters use 'data.' prefix for custom fields and bracket notation for operators (e.g., 'data.status': 'active', 'data.price[lte]': 100). Use dateWindow for date range queries.", {
         recordSlug: zod_1.z
             .string()
             .describe("The collection's record slug (e.g., 'orders')"),
         filters: zod_1.z
             .record(zod_1.z.string(), zod_1.z.any())
             .optional()
-            .describe("Filter object with keys like 'data.fieldName' or 'data.fieldName[operator]'. Operators: eq, ne, gt, gte, lt, lte, in, nin, contains, startswith, endswith"),
+            .describe("Filter object with keys like 'data.fieldName' or 'data.fieldName[operator]'. Operators: eq, ne, gt, gte, lt, lte, in, nin, contains, startswith, endswith, hasAny, hasAll"),
         sort: zod_1.z
             .string()
             .optional()
@@ -111,12 +111,31 @@ function registerRecordTools(server, sdk, centraliUrl, workspaceId) {
             .string()
             .optional()
             .describe("Comma-separated reference fields to expand (e.g., 'customer,product')"),
-    }, (_a) => __awaiter(this, [_a], void 0, function* ({ recordSlug, filters, sort, page, pageSize, expand }) {
+        dateWindow: zod_1.z
+            .object({
+            field: zod_1.z.string().describe("Date field to filter on (e.g., 'createdAt', 'updatedAt')"),
+            from: zod_1.z.string().optional().describe("ISO 8601 lower bound (inclusive)"),
+            to: zod_1.z.string().optional().describe("ISO 8601 upper bound (inclusive)"),
+        })
+            .optional()
+            .describe("Date range filter. Restricts results to records where the specified date field falls within the given range."),
+        includeDeleted: zod_1.z
+            .boolean()
+            .optional()
+            .describe("Include soft-deleted records (default: false)"),
+        includeTotal: zod_1.z
+            .boolean()
+            .optional()
+            .describe("Include total record count in response metadata (default: false)"),
+    }, (_a) => __awaiter(this, [_a], void 0, function* ({ recordSlug, filters, sort, page, pageSize, expand, dateWindow, includeDeleted, includeTotal }) {
         try {
             const params = Object.assign(Object.assign({}, filters), { sort,
                 page,
                 pageSize,
-                expand });
+                expand,
+                dateWindow,
+                includeDeleted,
+                includeTotal });
             // Remove undefined values
             Object.keys(params).forEach((key) => params[key] === undefined && delete params[key]);
             const result = yield sdk.queryRecords(recordSlug, params);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@centrali-io/centrali-mcp",
-  "version": "4.5.0",
+  "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: {
@@ -642,6 +674,25 @@ export function registerDescribeTools(server: McpServer) {
                   "Comma-separated list of reference field names to expand (join). Returns the full referenced record instead of just the ID.",
                 example: "expand: 'customer,product'",
               },
+              dateWindow: {
+                description:
+                  "Date range filter. Restricts results to records where a date field falls within a given range. Both 'from' and 'to' are optional (open-ended ranges allowed).",
+                shape: {
+                  field: "string — date field to filter on (e.g., 'createdAt', 'updatedAt', or a custom date field)",
+                  from: "string? — ISO 8601 lower bound (inclusive)",
+                  to: "string? — ISO 8601 upper bound (inclusive)",
+                },
+                examples: {
+                  "Last 30 days": { field: "createdAt", from: "2024-03-01T00:00:00Z" },
+                  "Specific range": { field: "updatedAt", from: "2024-01-01T00:00:00Z", to: "2024-03-31T23:59:59Z" },
+                },
+              },
+              includeDeleted: {
+                description: "Set to true to include soft-deleted records in the results (default: false). Alias: includeArchived, all.",
+              },
+              includeTotal: {
+                description: "Set to true to include the total record count in response metadata (default: false).",
+              },
               upsert: {
                 description:
                   "Atomic create-or-update. Provide 'match' fields to find existing record and 'data' for the full record body.",

package/src/tools/records.ts

@@ -84,7 +84,7 @@ function createRecordsClient(sdk: CentraliSDK, centraliUrl: string, workspaceId:
 export function registerRecordTools(server: McpServer, sdk: CentraliSDK, centraliUrl: string, workspaceId: string) {
   server.tool(
     "query_records",
-    "Query records from a collection with optional filters, sorting, and pagination. Filters use 'data.' prefix for custom fields and bracket notation for operators (e.g., 'data.status': 'active', 'data.price[lte]': 100).",
+    "Query records from a collection with optional filters, sorting, pagination, and date range filtering. Filters use 'data.' prefix for custom fields and bracket notation for operators (e.g., 'data.status': 'active', 'data.price[lte]': 100). Use dateWindow for date range queries.",
     {
       recordSlug: z
         .string()
@@ -93,7 +93,7 @@ export function registerRecordTools(server: McpServer, sdk: CentraliSDK, central
         .record(z.string(), z.any())
         .optional()
         .describe(
-          "Filter object with keys like 'data.fieldName' or 'data.fieldName[operator]'. Operators: eq, ne, gt, gte, lt, lte, in, nin, contains, startswith, endswith"
+          "Filter object with keys like 'data.fieldName' or 'data.fieldName[operator]'. Operators: eq, ne, gt, gte, lt, lte, in, nin, contains, startswith, endswith, hasAny, hasAll"
         ),
       sort: z
         .string()
@@ -112,8 +112,26 @@ export function registerRecordTools(server: McpServer, sdk: CentraliSDK, central
         .describe(
           "Comma-separated reference fields to expand (e.g., 'customer,product')"
         ),
+      dateWindow: z
+        .object({
+          field: z.string().describe("Date field to filter on (e.g., 'createdAt', 'updatedAt')"),
+          from: z.string().optional().describe("ISO 8601 lower bound (inclusive)"),
+          to: z.string().optional().describe("ISO 8601 upper bound (inclusive)"),
+        })
+        .optional()
+        .describe(
+          "Date range filter. Restricts results to records where the specified date field falls within the given range."
+        ),
+      includeDeleted: z
+        .boolean()
+        .optional()
+        .describe("Include soft-deleted records (default: false)"),
+      includeTotal: z
+        .boolean()
+        .optional()
+        .describe("Include total record count in response metadata (default: false)"),
     },
-    async ({ recordSlug, filters, sort, page, pageSize, expand }) => {
+    async ({ recordSlug, filters, sort, page, pageSize, expand, dateWindow, includeDeleted, includeTotal }) => {
       try {
         const params: Record<string, any> = {
           ...filters,
@@ -121,6 +139,9 @@ export function registerRecordTools(server: McpServer, sdk: CentraliSDK, central
           page,
           pageSize,
           expand,
+          dateWindow,
+          includeDeleted,
+          includeTotal,
         };
         // Remove undefined values
         Object.keys(params).forEach(