@speakai/mcp-server 1.0.10 → 1.0.11

package/README.md

@@ -6,7 +6,7 @@
 
 <p align="center">
   Connect Claude, Cursor, Windsurf, and other AI assistants to your <a href="https://speakai.co">Speak AI</a> workspace.<br/>
-  81 tools, 5 resources, 3 prompts, 26 CLI commands — transcribe, analyze, search, and manage media at scale.
+  82 tools, 5 resources, 3 prompts, 28 CLI commands — transcribe, analyze, search, and manage media at scale.
 </p>
 
 <p align="center">
@@ -160,10 +160,10 @@ SPEAK_API_KEY=your-key npx @speakai/mcp-server
 
 ---
 
-## MCP Tools (81)
+## MCP Tools (82)
 
 <details>
-<summary>Media (14 tools)</summary>
+<summary>Media (15 tools)</summary>
 
 | Tool | Description |
 |---|---|
@@ -181,6 +181,7 @@ SPEAK_API_KEY=your-key npx @speakai/mcp-server
 | `delete_media` | Permanently delete a media file |
 | `toggle_media_favorite` | Mark or unmark media as a favorite |
 | `reanalyze_media` | Re-run AI analysis with latest models |
+| `bulk_move_media` | Move multiple media files to a folder in one call |
 
 </details>
 
@@ -331,7 +332,7 @@ SPEAK_API_KEY=your-key npx @speakai/mcp-server
 
 | Tool | Description |
 |---|---|
-| `export_media` | Export as PDF, DOCX, SRT, VTT, TXT, CSV, or Markdown |
+| `export_media` | Export as PDF, DOCX, SRT, VTT, TXT, or CSV |
 | `export_multiple_media` | Batch export with optional merge into one file |
 
 </details>
@@ -407,7 +408,7 @@ Parameters: days (optional, default: 7), folder (optional)
 
 ---
 
-## CLI (26 Commands)
+## CLI (28 Commands)
 
 Install globally and configure once:
 
@@ -436,12 +437,12 @@ npx @speakai/mcp-server config set-key
 
 | Command | Description |
 |---|---|
-| `list-media` / `ls` | List media files with filtering and pagination |
+| `list-media` / `ls` | List media files with filtering, date ranges, and pagination |
 | `upload <source>` | Upload media from URL or local file (`--wait` to poll) |
 | `get-transcript` / `transcript <id>` | Get transcript (`--plain` or `--json`) |
 | `get-insights` / `insights <id>` | Get AI insights (topics, sentiment, keywords) |
 | `status <id>` | Check media processing status |
-| `export <id>` | Export transcript (`-f pdf\|docx\|srt\|vtt\|txt\|csv\|md`) |
+| `export <id>` | Export transcript (`-f pdf\|docx\|srt\|vtt\|txt\|csv`) |
 | `update <id>` | Update media metadata (name, description, tags, folder) |
 | `delete <id>` | Delete a media file |
 | `favorites <id>` | Toggle favorite status |
@@ -461,6 +462,7 @@ npx @speakai/mcp-server config set-key
 | Command | Description |
 |---|---|
 | `list-folders` / `folders` | List all folders |
+| `move <folderId> <mediaIds...>` | Move media files to a folder |
 | `create-folder <name>` | Create a new folder |
 | `clips` | List clips (filter by media or folder) |
 | `clip <mediaId>` | Create a clip (`--start` and `--end` in seconds) |
@@ -515,6 +517,12 @@ speakai-mcp schedule-meeting "https://zoom.us/j/123456" -t "Weekly Standup"
 
 # List videos as JSON for scripting
 speakai-mcp ls --type video --json | jq '.mediaList[].name'
+
+# List media from the last week
+speakai-mcp ls --from 2026-03-19 --to 2026-03-26
+
+# Move 3 files to a folder
+speakai-mcp move folder123 media1 media2 media3
 ```
 
 ---
@@ -589,14 +597,67 @@ AI: -> list_media(from: "2026-03-18", mediaType: "audio")
 
 ### Authentication
 
-All requests require `x-speakai-key` (API key) and `x-access-token` (JWT) headers. The MCP server handles token management automatically. Access tokens expire — the client refreshes them via `POST /v1/auth/accessToken`.
+The MCP server and CLI handle token management automatically. If you're calling the REST API directly, here's the full auth flow:
+
+**Step 1 — Get an access token:**
+
+```bash
+curl -X POST https://api.speakai.co/v1/auth/accessToken \
+  -H "Content-Type: application/json" \
+  -H "x-speakai-key: YOUR_API_KEY"
+```
+
+Response:
+```json
+{
+  "data": {
+    "email": "you@example.com",
+    "accessToken": "eyJhbG...",
+    "refreshToken": "eyJhbG..."
+  }
+}
+```
+
+**Step 2 — Use the token on all subsequent requests:**
+
+```bash
+curl https://api.speakai.co/v1/media \
+  -H "x-speakai-key: YOUR_API_KEY" \
+  -H "x-access-token: ACCESS_TOKEN_FROM_STEP_1"
+```
+
+**Step 3 — Refresh before expiry:**
+
+```bash
+curl -X POST https://api.speakai.co/v1/auth/refreshToken \
+  -H "Content-Type: application/json" \
+  -H "x-speakai-key: YOUR_API_KEY" \
+  -H "x-access-token: CURRENT_ACCESS_TOKEN" \
+  -d '{"refreshToken": "REFRESH_TOKEN_FROM_STEP_1"}'
+```
+
+**Token Lifetimes:**
+
+| Token | Expiry | How to Renew |
+|---|---|---|
+| Access token | 80 minutes | Refresh endpoint or re-authenticate |
+| Refresh token | 24 hours | Re-authenticate with API key |
+
+**Auth Rate Limits:** 5 requests per 60 seconds on both `/v1/auth/accessToken` and `/v1/auth/refreshToken`.
+
+### Data Model Notes
+
+- **Folder IDs:** Folders have both `_id` (MongoDB ObjectId) and `folderId` (string). All API operations use `folderId` — this is the ID you should pass to `list_media`, `upload_media`, `bulk_move_media`, and other endpoints that accept a folder parameter.
+- **Media IDs:** Media items use `mediaId` (returned in list responses as `_id`).
 
 ### Rate Limits
 
-- Implement exponential backoff on `429` responses
+- The MCP client automatically retries on `429` with exponential backoff
+- For direct API usage, implement exponential backoff and respect `Retry-After` headers
 - Cache stable data (folder lists, field definitions, supported languages)
 - Use `export_multiple_media` over individual exports for batch operations
 - Use `upload_and_analyze` instead of manual upload + poll + fetch loops
+- Use `bulk_move_media` to move multiple items at once instead of updating one by one
 
 ### Error Format
 

package/dist/index.js

@@ -166,6 +166,16 @@ var init_client = __esm({
           originalRequest.headers["x-access-token"] = accessToken;
           return speakClient(originalRequest);
         }
+        if (error.response?.status === 429 && retryCount < 3) {
+          const retryAfter = error.response.headers["retry-after"];
+          const delaySeconds = retryAfter ? parseInt(retryAfter, 10) : Math.pow(2, retryCount + 1);
+          const delayMs = (Number.isFinite(delaySeconds) ? delaySeconds : 2) * 1e3;
+          process.stderr.write(`[speakai-mcp] Rate limited, retrying in ${delayMs / 1e3}s...
+`);
+          await new Promise((resolve) => setTimeout(resolve, delayMs));
+          originalRequest._retryCount = retryCount + 1;
+          return speakClient(originalRequest);
+        }
         return Promise.reject(error);
       }
     );
@@ -1418,6 +1428,29 @@ function register(server, client) {
       }
     }
   );
+  server.tool(
+    "bulk_move_media",
+    "Move multiple media files to a folder in a single operation. Use this for batch reorganization instead of updating media one by one.",
+    {
+      folderId: import_zod.z.string().min(1).describe("Target folder ID to move media into"),
+      mediaIds: import_zod.z.array(import_zod.z.string().min(1)).min(1).describe("Array of media IDs to move")
+    },
+    async (body) => {
+      try {
+        const result = await api.put("/v1/media/move", body);
+        return {
+          content: [
+            { type: "text", text: JSON.stringify(result.data, null, 2) }
+          ]
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text", text: `Error: ${formatAxiosError(err)}` }],
+          isError: true
+        };
+      }
+    }
+  );
 }
 var import_zod;
 var init_media3 = __esm({
@@ -1562,10 +1595,10 @@ function register3(server, client) {
   const api = client ?? speakClient;
   server.tool(
     "export_media",
-    "Export a media file's transcript or insights in various formats (pdf, docx, srt, vtt, txt, csv, md).",
+    "Export a media file's transcript or insights in various formats (pdf, docx, srt, vtt, txt, csv).",
     {
       mediaId: import_zod3.z.string().min(1).describe("Unique identifier of the media file"),
-      fileType: import_zod3.z.enum(["pdf", "docx", "srt", "vtt", "txt", "csv", "md"]).describe("Desired export format"),
+      fileType: import_zod3.z.enum(["pdf", "docx", "srt", "vtt", "txt", "csv"]).describe("Desired export format"),
       isSpeakerNames: import_zod3.z.boolean().optional().describe("Include speaker names in export"),
       isSpeakerEmail: import_zod3.z.boolean().optional().describe("Include speaker emails in export"),
       isTimeStamps: import_zod3.z.boolean().optional().describe("Include timestamps in export"),
@@ -1573,12 +1606,11 @@ function register3(server, client) {
       isRedacted: import_zod3.z.boolean().optional().describe("Apply PII redaction to export"),
       redactedCategories: import_zod3.z.array(import_zod3.z.string()).optional().describe("Specific categories to redact")
     },
-    async ({ mediaId, fileType, ...query }) => {
+    async ({ mediaId, fileType, ...body }) => {
       try {
         const result = await api.post(
           `/v1/media/export/${mediaId}/${fileType}`,
-          null,
-          { params: query }
+          body
         );
         return {
           content: [
@@ -1598,7 +1630,7 @@ function register3(server, client) {
     "Export multiple media files at once, optionally merged into a single file.",
     {
       mediaIds: import_zod3.z.array(import_zod3.z.string()).describe("Array of media IDs to export"),
-      fileType: import_zod3.z.enum(["pdf", "docx", "srt", "vtt", "txt", "csv", "md"]).describe("Desired export format"),
+      fileType: import_zod3.z.enum(["pdf", "docx", "srt", "vtt", "txt", "csv"]).describe("Desired export format"),
       isSpeakerNames: import_zod3.z.boolean().optional().describe("Include speaker names in export"),
       isSpeakerEmail: import_zod3.z.boolean().optional().describe("Include speaker emails in export"),
       isTimeStamps: import_zod3.z.boolean().optional().describe("Include timestamps in export"),
@@ -3957,7 +3989,7 @@ function createCli() {
     rl.close();
     printSuccess("Setup complete! You're ready to go.");
   });
-  program.command("list-media").alias("ls").description("List media files").option("-t, --type <type>", "Filter by type (audio, video, text)").option("-p, --page <n>", "Page number (0-based)", "0").option("-s, --page-size <n>", "Results per page", "20").option("--sort <field>", "Sort field", "createdAt:desc").option("-f, --folder <id>", "Filter by folder ID").option("-n, --name <filter>", "Filter by name").option("--favorites", "Show only favorites").option("--json", "Output raw JSON").action(async (opts) => {
+  program.command("list-media").alias("ls").description("List media files").option("-t, --type <type>", "Filter by type (audio, video, text)").option("-p, --page <n>", "Page number (0-based)", "0").option("-s, --page-size <n>", "Results per page", "20").option("--sort <field>", "Sort field", "createdAt:desc").option("-f, --folder <id>", "Filter by folder ID").option("-n, --name <filter>", "Filter by name").option("--from <date>", "Start date filter (ISO 8601, e.g. 2026-01-01)").option("--to <date>", "End date filter (ISO 8601)").option("--favorites", "Show only favorites").option("--json", "Output raw JSON").action(async (opts) => {
     requireApiKey();
     const client = await getClient();
     try {
@@ -3971,6 +4003,8 @@ function createCli() {
       if (opts.type) params.mediaType = opts.type;
       if (opts.folder) params.folderId = opts.folder;
       if (opts.name) params.filterName = opts.name;
+      if (opts.from) params.from = opts.from;
+      if (opts.to) params.to = opts.to;
       if (opts.favorites) params.isFavorites = true;
       const res = await client.get("/v1/media", { params });
       const data = res.data?.data;
@@ -4164,20 +4198,19 @@ function createCli() {
   });
   program.command("export").description("Export media transcript/insights").argument("<mediaId>", "Media file ID").option(
     "-f, --format <type>",
-    "Export format (pdf, docx, srt, vtt, txt, csv, md)",
+    "Export format (pdf, docx, srt, vtt, txt, csv)",
     "txt"
   ).option("--speakers", "Include speaker names").option("--timestamps", "Include timestamps").option("--redacted", "Apply PII redaction").option("--json", "Output raw JSON").action(async (mediaId, opts) => {
     requireApiKey();
     const client = await getClient();
     try {
-      const params = {};
-      if (opts.speakers) params.isSpeakerNames = true;
-      if (opts.timestamps) params.isTimeStamps = true;
-      if (opts.redacted) params.isRedacted = true;
+      const body = {};
+      if (opts.speakers) body.isSpeakerNames = true;
+      if (opts.timestamps) body.isTimeStamps = true;
+      if (opts.redacted) body.isRedacted = true;
       const res = await client.post(
         `/v1/media/export/${mediaId}/${opts.format}`,
-        null,
-        { params }
+        body
       );
       if (opts.json) {
         printJson(res.data);
@@ -4256,8 +4289,8 @@ function createCli() {
       }
       const folders = Array.isArray(data) ? data : data?.folderList ?? data?.folders ?? [];
       printTable(folders, [
-        { key: "_id", label: "ID", width: 14 },
-        { key: "name", label: "Name", width: 40 },
+        { key: "folderId", label: "Folder ID", width: 20 },
+        { key: "name", label: "Name", width: 34 },
         { key: "createdAt", label: "Created", width: 20 }
       ]);
     } catch (err) {
@@ -4441,6 +4474,22 @@ function createCli() {
       process.exit(1);
     }
   });
+  program.command("move").description("Move one or more media files to a folder").argument("<folderId>", "Target folder ID").argument("<mediaIds...>", "Media file IDs to move").option("--json", "Output raw JSON").action(async (folderId, mediaIds, opts) => {
+    requireApiKey();
+    const client = await getClient();
+    try {
+      const res = await client.put("/v1/media/move", { folderId, mediaIds });
+      const data = res.data?.data;
+      if (opts.json) {
+        printJson(data);
+      } else {
+        printSuccess(`Moved ${mediaIds.length} item(s) to folder ${folderId}`);
+      }
+    } catch (err) {
+      printError(err.response?.data?.message ?? err.message);
+      process.exit(1);
+    }
+  });
   program.command("create-folder").description("Create a new folder").argument("<name>", "Folder name").option("--json", "Output raw JSON").action(async (name, opts) => {
     requireApiKey();
     const client = await getClient();
@@ -4450,7 +4499,7 @@ function createCli() {
       if (opts.json) {
         printJson(data);
       } else {
-        printSuccess(`Folder created: ${data?._id ?? "OK"} \u2014 ${name}`);
+        printSuccess(`Folder created: ${data?.folderId ?? data?._id ?? "OK"} \u2014 ${name}`);
       }
     } catch (err) {
       printError(err.response?.data?.message ?? err.message);
@@ -4479,21 +4528,23 @@ function createCli() {
         printJson(data);
         return;
       }
-      const total = data?.totalCount ?? data?.total ?? "\u2014";
-      const audio = data?.audioCount ?? data?.audio ?? "\u2014";
-      const video = data?.videoCount ?? data?.video ?? "\u2014";
-      const text = data?.textCount ?? data?.text ?? "\u2014";
-      console.log(`Total media:  ${total}`);
-      console.log(`  Audio:      ${audio}`);
-      console.log(`  Video:      ${video}`);
-      console.log(`  Text:       ${text}`);
-      if (data?.totalDuration) {
-        const hrs = Math.round(data.totalDuration / 3600 * 10) / 10;
-        console.log(`Duration:     ${hrs}h total`);
-      }
-      if (data?.totalSize) {
-        const gb = Math.round(data.totalSize / (1024 * 1024 * 1024) * 100) / 100;
-        console.log(`Storage:      ${gb} GB`);
+      const total = data?.totalMedia ?? "\u2014";
+      const analyzed = data?.analyzedMedia ?? "\u2014";
+      const notAnalyzed = data?.notAnalyzedMedia ?? "\u2014";
+      console.log(`Total media:     ${total}`);
+      console.log(`  Analyzed:      ${analyzed}`);
+      console.log(`  Not analyzed:  ${notAnalyzed}`);
+      if (data?.duration) {
+        const hrs = Math.round(data.duration / 3600 * 10) / 10;
+        console.log(`Duration:        ${hrs}h total`);
+      }
+      if (data?.analyzedMinutes) {
+        const hrs = Math.round(data.analyzedMinutes / 60 * 10) / 10;
+        console.log(`Analyzed:        ${hrs}h (${data.analyzedMinutes} min)`);
+      }
+      if (data?.fileSize) {
+        const gb = Math.round(data.fileSize / (1024 * 1024 * 1024) * 100) / 100;
+        console.log(`Storage:         ${gb} GB`);
       }
     } catch (err) {
       printError(err.response?.data?.message ?? err.message);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@speakai/mcp-server",
-  "version": "1.0.10",
+  "version": "1.0.11",
   "description": "Official Speak AI MCP Server — connect Claude and other AI assistants to Speak AI's transcription, insights, and media management API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",