@speakai/mcp-server 1.1.0 → 1.2.0

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/>
-  82 tools, 5 resources, 3 prompts, 28 CLI commands — transcribe, analyze, search, and manage media at scale.
+  83 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 (82)
+## MCP Tools (83)
 
 <details>
-<summary>Media (15 tools)</summary>
+<summary>Media (16 tools)</summary>
 
 | Tool | Description |
 |---|---|
@@ -171,11 +171,12 @@ SPEAK_API_KEY=your-key npx @speakai/mcp-server
 | `upload_media` | Upload media from a public URL for transcription |
 | `upload_local_file` | Upload a local file directly from disk |
 | `upload_and_analyze` | Upload, wait for processing, return transcript + insights in one call |
-| `list_media` | List and search media files with filters and pagination |
+| `list_media` | List and search media files with filters, pagination, and optional inline data (transcripts, speakers, keywords) via `include` param |
 | `get_media_insights` | Get AI insights — topics, sentiment, summaries, action items |
 | `get_transcript` | Get full transcript with speaker labels and timestamps |
 | `get_captions` | Get subtitle-formatted captions for a media file |
 | `update_transcript_speakers` | Rename speaker labels in a transcript |
+| `bulk_update_transcript_speakers` | Rename speaker labels across multiple media files in one call (max 500) |
 | `get_media_status` | Check processing status (pending -> processed) |
 | `update_media_metadata` | Update name, description, tags, or folder |
 | `delete_media` | Permanently delete a media file |
@@ -658,6 +659,8 @@ curl -X POST https://api.speakai.co/v1/auth/refreshToken \
 - 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
+- Use `bulk_update_transcript_speakers` to rename speakers across many files instead of calling `update_transcript_speakers` per file
+- Use `list_media` with `include: ["transcription"]` to fetch media with transcripts inline, avoiding N+1 calls to `get_transcript`
 
 ### Error Format
 

package/dist/index.js

@@ -1145,7 +1145,7 @@ function register(server, client) {
   );
   server.tool(
     "list_media",
-    "List and search media files in the workspace with filtering, pagination, and sorting. Use filterName for text search, mediaType to filter by audio/video/text, folderId for folder-specific results, and from/to for date ranges. Returns mediaIds you can pass to get_transcript, get_media_insights, or ask_magic_prompt. For deep full-text search across transcripts, use search_media instead.",
+    "List and search media files in the workspace with filtering, pagination, and sorting. Use filterName for text search, mediaType to filter by audio/video/text, folderId for folder-specific results, and from/to for date ranges. Use the include param to embed additional data (transcripts, speakers, keywords) inline with each result, avoiding N+1 API calls. Returns mediaIds you can pass to get_transcript, get_media_insights, or ask_magic_prompt. For deep full-text search across transcripts, use search_media instead.",
     {
       mediaType: import_zod.z.enum([MediaType.AUDIO, MediaType.VIDEO, MediaType.TEXT]).optional().describe('Filter by media type: "audio", "video", or "text"'),
       page: import_zod.z.number().int().min(0).optional().describe("Page number for pagination (0-based, default: 0)"),
@@ -1156,11 +1156,27 @@ function register(server, client) {
       folderId: import_zod.z.string().optional().describe("Filter media within a specific folder"),
       from: import_zod.z.string().optional().describe("Start date for date range filter (ISO 8601)"),
       to: import_zod.z.string().optional().describe("End date for date range filter (ISO 8601)"),
-      isFavorites: import_zod.z.boolean().optional().describe("Filter to only show favorited media")
+      isFavorites: import_zod.z.boolean().optional().describe("Filter to only show favorited media"),
+      include: import_zod.z.array(
+        import_zod.z.enum([
+          "transcription",
+          "keywords",
+          "speakers",
+          "sentiment",
+          "custom",
+          "fields"
+        ])
+      ).optional().describe(
+        "Additional data to include with each media item. Without this, only metadata is returned. Use 'transcription' to include full transcripts inline, 'speakers' for speaker details, 'keywords' for extracted keywords, etc. Avoids N+1 API calls when you need data for multiple files."
+      )
     },
-    async (params) => {
+    async ({ include, ...params }) => {
       try {
-        const result = await api.get("/v1/media", { params });
+        const queryParams = { ...params };
+        if (include?.length) {
+          queryParams.requestTypes = include.join(",");
+        }
+        const result = await api.get("/v1/media", { params: queryParams });
         return {
           content: [
             { type: "text", text: JSON.stringify(result.data, null, 2) }
@@ -1428,6 +1444,45 @@ function register(server, client) {
       }
     }
   );
+  server.tool(
+    "bulk_update_transcript_speakers",
+    "Update or rename speaker labels across multiple media files in a single operation. Applies the same speaker mappings to every specified media file. Use this instead of calling update_transcript_speakers repeatedly when renaming speakers across a project or folder.",
+    {
+      mediaIds: import_zod.z.array(import_zod.z.string().min(1)).min(1).max(500).describe("Array of media IDs to update speakers for (max 500 per call)"),
+      speakers: import_zod.z.array(
+        import_zod.z.object({
+          id: import_zod.z.string().min(1).describe("Speaker identifier from the transcript"),
+          name: import_zod.z.string().min(1).describe("Display name to assign to the speaker")
+        })
+      ).describe("Array of speaker ID to name mappings to apply to all specified media files")
+    },
+    async ({ mediaIds, speakers }) => {
+      const results = [];
+      for (const mediaId of mediaIds) {
+        try {
+          await api.put(`/v1/media/speakers/${mediaId}`, { speakers });
+          results.push({ mediaId, success: true });
+        } catch (err) {
+          results.push({ mediaId, success: false, error: formatAxiosError(err) });
+        }
+      }
+      const succeeded = results.filter((r) => r.success).length;
+      const failed = results.filter((r) => !r.success).length;
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              { summary: { total: mediaIds.length, succeeded, failed }, results },
+              null,
+              2
+            )
+          }
+        ],
+        isError: failed === mediaIds.length
+      };
+    }
+  );
   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.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@speakai/mcp-server",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "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",
@@ -27,7 +27,7 @@
   "author": "Speak AI",
   "license": "MIT",
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "files": [
     "dist"
@@ -40,7 +40,7 @@
     "zod": "^3.22.0"
   },
   "devDependencies": {
-    "@speakai/shared": "^1.5.1",
+    "@speakai/shared": "^1.6.2",
     "@types/node": "^20.0.0",
     "@vitest/coverage-v8": "^4.1.2",
     "tsup": "^8.5.1",