@speakai/mcp-server 1.0.5 → 1.0.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +419 -161
  2. package/dist/index.js +1518 -59
  3. package/package.json +11 -4
package/README.md CHANGED
@@ -5,8 +5,8 @@
5
5
  <h1 align="center">Speak AI MCP Server & CLI</h1>
6
6
 
7
7
  <p align="center">
8
- Connect Claude, ChatGPT, and other AI assistants to your <a href="https://speakai.co">Speak AI</a> workspace.<br/>
9
- Transcribe meetings, analyze media, extract insightsthrough AI assistants or the command line.
8
+ Connect Claude, Cursor, Windsurf, and other AI assistants to your <a href="https://speakai.co">Speak AI</a> workspace.<br/>
9
+ 81 tools, 5 resources, 3 prompts, 26 CLI commands transcribe, analyze, search, and manage media at scale.
10
10
  </p>
11
11
 
12
12
  <p align="center">
@@ -17,116 +17,92 @@
17
17
 
18
18
  ---
19
19
 
20
- ## What You Can Do
21
-
22
- **With AI assistants:**
23
-
24
- > "Transcribe this audio file and give me the key takeaways"
25
-
26
- > "What action items came out of yesterday's team meeting?"
27
-
28
- > "Export all Q1 interview transcripts as PDFs with speaker names"
29
-
30
- **From the command line:**
31
-
32
- ```sh
33
- speak-mcp upload https://example.com/meeting.mp3 --wait
34
- speak-mcp transcript abc123 --plain
35
- speak-mcp ask abc123 "What were the action items?"
36
- speak-mcp export abc123 -f pdf --speakers
37
- ```
38
-
39
- ---
40
-
41
20
  ## Quick Start
42
21
 
43
22
  ### 1. Get Your API Key
44
23
 
45
- 1. Log in to [Speak AI](https://app.speakai.co)
46
- 2. Go to **Settings > Developer**
47
- 3. Copy your **API Key**
48
-
49
- That's it — the server handles access token management automatically.
24
+ 1. Go to [Speak AI API Keys](https://app.speakai.co/developers/apikeys)
25
+ 2. Copy your **API Key**
50
26
 
51
27
  ### 2. Choose How to Use It
52
28
 
29
+ | Method | Best for |
30
+ |---|---|
31
+ | **CLI** | Scripts, pipelines, quick one-off tasks |
32
+ | **MCP Server** | AI assistants (Claude, Cursor, Windsurf, VS Code) |
33
+ | **Both** | Full power — agents orchestrate, CLI automates |
34
+
53
35
  ---
54
36
 
55
- ## CLI (Command Line)
37
+ ## Setup
38
+
39
+ ### Auto-Setup (Recommended)
56
40
 
57
- Install globally and configure your API key once:
41
+ Detects installed MCP clients and configures them automatically:
58
42
 
59
43
  ```sh
60
44
  npm install -g @speakai/mcp-server
61
- speak-mcp config set-key
45
+ speakai-mcp init
62
46
  ```
63
47
 
64
- Or run without installing:
48
+ ### Manual Setup
65
49
 
66
- ```sh
67
- npx @speakai/mcp-server config set-key
68
- ```
50
+ <details>
51
+ <summary>Claude Desktop</summary>
69
52
 
70
- Then use any command:
53
+ Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
71
54
 
72
- ```sh
73
- speak-mcp ls # List all media
74
- speak-mcp upload https://example.com/call.mp3 # Upload media
75
- speak-mcp transcript <id> # Get transcript
76
- speak-mcp insights <id> # Get AI insights
77
- speak-mcp ask <id> "Summarize this meeting" # Ask AI questions
78
- speak-mcp export <id> -f pdf --speakers # Export transcript
79
- speak-mcp schedule-meeting <zoom-url> # Join a meeting
55
+ ```json
56
+ {
57
+ "mcpServers": {
58
+ "speak-ai": {
59
+ "command": "npx",
60
+ "args": ["-y", "@speakai/mcp-server"],
61
+ "env": {
62
+ "SPEAK_API_KEY": "your-api-key"
63
+ }
64
+ }
65
+ }
66
+ }
80
67
  ```
81
68
 
82
- ### All CLI Commands
69
+ </details>
83
70
 
84
- | Command | Description |
85
- |---|---|
86
- | `config set-key [key]` | Set your API key (interactive if no key given) |
87
- | `config show` | Show current configuration |
88
- | `config set-url <url>` | Set custom API base URL |
89
- | `list-media` / `ls` | List media files with filtering and pagination |
90
- | `get-transcript` / `transcript <id>` | Get transcript (formatted, `--plain`, or `--json`) |
91
- | `get-insights` / `insights <id>` | Get AI insights (topics, sentiment, keywords) |
92
- | `upload <url>` | Upload media from URL (`--wait` to poll until done) |
93
- | `export <id>` | Export transcript (`-f pdf\|docx\|srt\|vtt\|txt\|csv\|md`) |
94
- | `status <id>` | Check media processing status |
95
- | `create-text <name>` | Create text note (`--text` or pipe via stdin) |
96
- | `list-folders` / `folders` | List all folders |
97
- | `ask <id> <prompt>` | Ask AI a question about a media file |
98
- | `schedule-meeting <url>` | Schedule meeting assistant to join a call |
99
-
100
- ### CLI Options
101
-
102
- Every command supports:
103
- - `--json` — output raw JSON (for scripting and piping)
104
- - `--help` — show command-specific help
71
+ <details>
72
+ <summary>Claude Code</summary>
105
73
 
106
74
  ```sh
107
- # Pipe transcript to a file
108
- speak-mcp transcript abc123 --plain > meeting.txt
109
-
110
- # Upload and wait for processing
111
- speak-mcp upload https://example.com/interview.mp3 -n "Q1 Interview" --wait
75
+ export SPEAK_API_KEY="your-api-key"
76
+ claude mcp add speak-ai -- npx -y @speakai/mcp-server
77
+ ```
112
78
 
113
- # Create text note from stdin
114
- cat notes.txt | speak-mcp create-text "Meeting Notes"
79
+ </details>
115
80
 
116
- # List only video files as JSON
117
- speak-mcp ls --type video --json | jq '.mediaList[].name'
118
- ```
81
+ <details>
82
+ <summary>Cursor</summary>
119
83
 
120
- ---
84
+ Add to `~/.cursor/mcp.json`:
121
85
 
122
- ## MCP Server (AI Assistants)
86
+ ```json
87
+ {
88
+ "mcpServers": {
89
+ "speak-ai": {
90
+ "command": "npx",
91
+ "args": ["-y", "@speakai/mcp-server"],
92
+ "env": {
93
+ "SPEAK_API_KEY": "your-api-key"
94
+ }
95
+ }
96
+ }
97
+ }
98
+ ```
123
99
 
124
- ### Claude Desktop
100
+ </details>
125
101
 
126
- Add to your config file:
102
+ <details>
103
+ <summary>Windsurf</summary>
127
104
 
128
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
129
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
105
+ Add to `~/.windsurf/mcp.json`:
130
106
 
131
107
  ```json
132
108
  {
@@ -142,87 +118,113 @@ Windows: `%APPDATA%\Claude\claude_desktop_config.json`
142
118
  }
143
119
  ```
144
120
 
145
- ### Claude Code
121
+ </details>
146
122
 
147
- ```sh
148
- export SPEAK_API_KEY="your-api-key"
149
- claude mcp add speak-ai -- npx -y @speakai/mcp-server
150
- ```
123
+ <details>
124
+ <summary>VS Code</summary>
151
125
 
152
- ### Claude Web (claude.ai)
126
+ Add to `~/.vscode/mcp.json`:
153
127
 
154
- 1. Go to **Settings > Connectors > Add Connector**
155
- 2. Enter the URL: `https://api.speakai.co/v1/mcp`
156
- 3. Add your `x-speakai-key` and `x-access-token` headers
157
- 4. Start chatting with your Speak AI data
128
+ ```json
129
+ {
130
+ "mcpServers": {
131
+ "speak-ai": {
132
+ "command": "npx",
133
+ "args": ["-y", "@speakai/mcp-server"],
134
+ "env": {
135
+ "SPEAK_API_KEY": "your-api-key"
136
+ }
137
+ }
138
+ }
139
+ }
140
+ ```
158
141
 
159
- ### Any MCP Client
142
+ </details>
160
143
 
161
- Any STDIO-compatible client can connect:
144
+ <details>
145
+ <summary>Any MCP Client (STDIO)</summary>
162
146
 
163
147
  ```sh
164
148
  SPEAK_API_KEY=your-key npx @speakai/mcp-server
165
149
  ```
166
150
 
151
+ </details>
152
+
167
153
  ### Environment Variables
168
154
 
169
155
  | Variable | Required | Default | Description |
170
156
  |---|---|---|---|
171
- | `SPEAK_API_KEY` | Yes | | Your Speak AI API key |
172
- | `SPEAK_ACCESS_TOKEN` | No | Auto-managed | JWT access token (auto-fetched and refreshed using your API key) |
157
+ | `SPEAK_API_KEY` | Yes | -- | Your Speak AI API key |
158
+ | `SPEAK_ACCESS_TOKEN` | No | Auto-managed | JWT access token (auto-fetched and refreshed) |
173
159
  | `SPEAK_BASE_URL` | No | `https://api.speakai.co` | API base URL |
174
160
 
175
161
  ---
176
162
 
177
- ## Available Tools (45)
163
+ ## MCP Tools (81)
178
164
 
179
- ### Media (Audio/Video)
165
+ <details>
166
+ <summary>Media (14 tools)</summary>
180
167
 
181
168
  | Tool | Description |
182
169
  |---|---|
183
170
  | `get_signed_upload_url` | Get a pre-signed S3 URL for direct file upload |
184
171
  | `upload_media` | Upload media from a public URL for transcription |
172
+ | `upload_local_file` | Upload a local file directly from disk |
173
+ | `upload_and_analyze` | Upload, wait for processing, return transcript + insights in one call |
185
174
  | `list_media` | List and search media files with filters and pagination |
186
175
  | `get_media_insights` | Get AI insights — topics, sentiment, summaries, action items |
187
176
  | `get_transcript` | Get full transcript with speaker labels and timestamps |
177
+ | `get_captions` | Get subtitle-formatted captions for a media file |
188
178
  | `update_transcript_speakers` | Rename speaker labels in a transcript |
189
- | `get_media_status` | Check processing status (pending completed) |
179
+ | `get_media_status` | Check processing status (pending -> processed) |
190
180
  | `update_media_metadata` | Update name, description, tags, or folder |
191
181
  | `delete_media` | Permanently delete a media file |
182
+ | `toggle_media_favorite` | Mark or unmark media as a favorite |
183
+ | `reanalyze_media` | Re-run AI analysis with latest models |
192
184
 
193
- ### Text Notes
185
+ </details>
194
186
 
195
- | Tool | Description |
196
- |---|---|
197
- | `create_text_note` | Create a text note for AI analysis |
198
- | `get_text_insight` | Get AI insights for a text note |
199
- | `reanalyze_text` | Re-run AI analysis with latest models |
200
- | `update_text_note` | Update note content (triggers re-analysis) |
201
-
202
- ### Exports
187
+ <details>
188
+ <summary>Magic Prompt / AI Chat (12 tools)</summary>
203
189
 
204
190
  | Tool | Description |
205
191
  |---|---|
206
- | `export_media` | Export as PDF, DOCX, SRT, VTT, TXT, CSV, or Markdown |
207
- | `export_multiple_media` | Batch export with optional merge into one file |
192
+ | `ask_magic_prompt` | Ask AI questions about media, folders, or your whole workspace |
193
+ | `retry_magic_prompt` | Retry a failed or incomplete AI response |
194
+ | `get_chat_history` | List recent Magic Prompt conversations |
195
+ | `get_chat_messages` | Get full message history for conversations |
196
+ | `delete_chat_message` | Delete a specific chat message |
197
+ | `list_prompts` | List available AI prompt templates |
198
+ | `get_favorite_prompts` | Get all favorited prompts and answers |
199
+ | `toggle_prompt_favorite` | Mark or unmark a chat message as favorite |
200
+ | `update_chat_title` | Rename a chat conversation |
201
+ | `submit_chat_feedback` | Rate a chat response (thumbs up/down) |
202
+ | `get_chat_statistics` | Get Magic Prompt usage statistics |
203
+ | `export_chat_answer` | Export a conversation or answer |
208
204
 
209
- ### Folders
205
+ </details>
206
+
207
+ <details>
208
+ <summary>Folders & Views (11 tools)</summary>
210
209
 
211
210
  | Tool | Description |
212
211
  |---|---|
213
- | `list_folders` | List all folders |
212
+ | `list_folders` | List all folders with pagination and sorting |
214
213
  | `get_folder_info` | Get folder details and contents |
215
214
  | `create_folder` | Create a new folder |
216
215
  | `clone_folder` | Duplicate a folder and its contents |
217
- | `update_folder` | Rename a folder |
216
+ | `update_folder` | Rename or update a folder |
218
217
  | `delete_folder` | Delete a folder (media is preserved) |
219
- | `get_all_folder_views` | List all saved views |
218
+ | `get_all_folder_views` | List all saved views across folders |
220
219
  | `get_folder_views` | List views for a specific folder |
221
220
  | `create_folder_view` | Create a saved view with custom filters |
222
221
  | `update_folder_view` | Update a saved view |
223
222
  | `clone_folder_view` | Duplicate a view |
224
223
 
225
- ### Recorder / Survey
224
+ </details>
225
+
226
+ <details>
227
+ <summary>Recorder / Survey (10 tools)</summary>
226
228
 
227
229
  | Tool | Description |
228
230
  |---|---|
@@ -237,23 +239,59 @@ SPEAK_API_KEY=your-key npx @speakai/mcp-server
237
239
  | `check_recorder_status` | Check if recorder is active |
238
240
  | `delete_recorder` | Delete a recorder |
239
241
 
240
- ### Media Embed
242
+ </details>
243
+
244
+ <details>
245
+ <summary>Automations (5 tools)</summary>
241
246
 
242
247
  | Tool | Description |
243
248
  |---|---|
244
- | `create_embed` | Create an embeddable player widget |
245
- | `update_embed` | Update embed settings |
246
- | `check_embed` | Check if embed exists for media |
247
- | `get_embed_iframe_url` | Get iframe URL for your website |
249
+ | `list_automations` | List automation rules |
250
+ | `get_automation` | Get automation details |
251
+ | `create_automation` | Create an automation rule |
252
+ | `update_automation` | Update an automation |
253
+ | `toggle_automation_status` | Enable or disable an automation |
254
+
255
+ </details>
248
256
 
249
- ### Magic Prompt (AI Chat)
257
+ <details>
258
+ <summary>Clips (4 tools)</summary>
250
259
 
251
260
  | Tool | Description |
252
261
  |---|---|
253
- | `list_prompts` | List available AI prompt templates |
254
- | `ask_magic_prompt` | Ask AI questions about any media file |
262
+ | `create_clip` | Create a highlight clip from time ranges across media files |
263
+ | `get_clips` | List clips or get a specific clip with download URL |
264
+ | `update_clip` | Update clip title, description, or tags |
265
+ | `delete_clip` | Permanently delete a clip |
266
+
267
+ </details>
255
268
 
256
- ### Meeting Assistant
269
+ <details>
270
+ <summary>Custom Fields (4 tools)</summary>
271
+
272
+ | Tool | Description |
273
+ |---|---|
274
+ | `list_fields` | List all custom fields |
275
+ | `create_field` | Create a custom field |
276
+ | `update_field` | Update a custom field |
277
+ | `update_multiple_fields` | Batch update multiple fields |
278
+
279
+ </details>
280
+
281
+ <details>
282
+ <summary>Webhooks (4 tools)</summary>
283
+
284
+ | Tool | Description |
285
+ |---|---|
286
+ | `create_webhook` | Create a webhook for event notifications |
287
+ | `list_webhooks` | List all webhooks |
288
+ | `update_webhook` | Update a webhook |
289
+ | `delete_webhook` | Delete a webhook |
290
+
291
+ </details>
292
+
293
+ <details>
294
+ <summary>Meeting Assistant (4 tools)</summary>
257
295
 
258
296
  | Tool | Description |
259
297
  |---|---|
@@ -262,74 +300,287 @@ SPEAK_API_KEY=your-key npx @speakai/mcp-server
262
300
  | `remove_assistant_from_meeting` | Remove assistant from active meeting |
263
301
  | `delete_scheduled_assistant` | Cancel a scheduled meeting assistant |
264
302
 
265
- ### Custom Fields
303
+ </details>
304
+
305
+ <details>
306
+ <summary>Media Embed (4 tools)</summary>
266
307
 
267
308
  | Tool | Description |
268
309
  |---|---|
269
- | `list_fields` | List all custom fields |
270
- | `create_field` | Create a custom field |
271
- | `update_field` | Update a custom field |
272
- | `update_multiple_fields` | Batch update multiple fields |
310
+ | `create_embed` | Create an embeddable player widget |
311
+ | `update_embed` | Update embed settings |
312
+ | `check_embed` | Check if embed exists for media |
313
+ | `get_embed_iframe_url` | Get iframe URL for your website |
273
314
 
274
- ### Automations
315
+ </details>
316
+
317
+ <details>
318
+ <summary>Text Notes (4 tools)</summary>
275
319
 
276
320
  | Tool | Description |
277
321
  |---|---|
278
- | `list_automations` | List automation rules |
279
- | `get_automation` | Get automation details |
280
- | `create_automation` | Create an automation rule |
281
- | `update_automation` | Update an automation |
282
- | `toggle_automation_status` | Enable or disable an automation |
322
+ | `create_text_note` | Create a text note for AI analysis |
323
+ | `get_text_insight` | Get AI insights for a text note |
324
+ | `reanalyze_text` | Re-run AI analysis on a text note |
325
+ | `update_text_note` | Update note content (triggers re-analysis) |
326
+
327
+ </details>
283
328
 
284
- ### Webhooks
329
+ <details>
330
+ <summary>Exports (2 tools)</summary>
285
331
 
286
332
  | Tool | Description |
287
333
  |---|---|
288
- | `create_webhook` | Create a webhook for event notifications |
289
- | `list_webhooks` | List all webhooks |
290
- | `update_webhook` | Update a webhook |
291
- | `delete_webhook` | Delete a webhook |
334
+ | `export_media` | Export as PDF, DOCX, SRT, VTT, TXT, CSV, or Markdown |
335
+ | `export_multiple_media` | Batch export with optional merge into one file |
336
+
337
+ </details>
338
+
339
+ <details>
340
+ <summary>Media Statistics & Languages (2 tools)</summary>
341
+
342
+ | Tool | Description |
343
+ |---|---|
344
+ | `get_media_statistics` | Get workspace-level stats — counts, storage, processing breakdown |
345
+ | `list_supported_languages` | List all supported transcription languages |
346
+
347
+ </details>
348
+
349
+ <details>
350
+ <summary>Search / Analytics (1 tool)</summary>
351
+
352
+ | Tool | Description |
353
+ |---|---|
354
+ | `search_media` | Deep search across transcripts, insights, and metadata with filters |
355
+
356
+ </details>
292
357
 
293
358
  ---
294
359
 
295
- ## Workflows
360
+ ## MCP Resources (5)
361
+
362
+ Resources provide direct data access without tool calls. Clients can read these URIs directly.
363
+
364
+ | Resource | URI | Description |
365
+ |---|---|---|
366
+ | Media Library | `speakai://media` | List of all media files in your workspace |
367
+ | Folders | `speakai://folders` | List of all folders |
368
+ | Supported Languages | `speakai://languages` | Transcription language list |
369
+ | Transcript | `speakai://media/{mediaId}/transcript` | Full transcript for a specific media file |
370
+ | Insights | `speakai://media/{mediaId}/insights` | AI-generated insights for a specific media file |
371
+
372
+ ---
296
373
 
297
- ### Transcribe and Analyze
374
+ ## MCP Prompts (3)
375
+
376
+ Pre-built workflow prompts that agents can invoke to run multi-step tasks.
377
+
378
+ ### `analyze-meeting`
379
+
380
+ Upload a recording and get a full analysis — transcript, insights, action items, and key takeaways.
381
+
382
+ ```
383
+ Parameters: url (required), name (optional)
384
+ ```
385
+
386
+ **Example:** "Use the analyze-meeting prompt with url=https://example.com/standup.mp3"
387
+
388
+ ### `research-across-media`
389
+
390
+ Search for themes, patterns, or topics across multiple recordings or your entire library.
391
+
392
+ ```
393
+ Parameters: topic (required), folder (optional)
394
+ ```
395
+
396
+ **Example:** "Use the research-across-media prompt with topic='customer churn reasons'"
397
+
398
+ ### `meeting-brief`
399
+
400
+ Prepare a brief from recent meetings — pull transcripts, extract decisions, and summarize open items.
401
+
402
+ ```
403
+ Parameters: days (optional, default: 7), folder (optional)
404
+ ```
405
+
406
+ **Example:** "Use the meeting-brief prompt with days=14 to cover the last two weeks"
407
+
408
+ ---
409
+
410
+ ## CLI (26 Commands)
411
+
412
+ Install globally and configure once:
413
+
414
+ ```sh
415
+ npm install -g @speakai/mcp-server
416
+ speakai-mcp config set-key
417
+ ```
418
+
419
+ Or run without installing:
420
+
421
+ ```sh
422
+ npx @speakai/mcp-server config set-key
423
+ ```
424
+
425
+ ### Configuration
426
+
427
+ | Command | Description |
428
+ |---|---|
429
+ | `config set-key [key]` | Set your API key (interactive if no key given) |
430
+ | `config show` | Show current configuration |
431
+ | `config test` | Validate API key and test connectivity |
432
+ | `config set-url <url>` | Set custom API base URL |
433
+ | `init` | Interactive setup — configure key and auto-detect MCP clients |
434
+
435
+ ### Media Management
436
+
437
+ | Command | Description |
438
+ |---|---|
439
+ | `list-media` / `ls` | List media files with filtering and pagination |
440
+ | `upload <source>` | Upload media from URL or local file (`--wait` to poll) |
441
+ | `get-transcript` / `transcript <id>` | Get transcript (`--plain` or `--json`) |
442
+ | `get-insights` / `insights <id>` | Get AI insights (topics, sentiment, keywords) |
443
+ | `status <id>` | Check media processing status |
444
+ | `export <id>` | Export transcript (`-f pdf\|docx\|srt\|vtt\|txt\|csv\|md`) |
445
+ | `update <id>` | Update media metadata (name, description, tags, folder) |
446
+ | `delete <id>` | Delete a media file |
447
+ | `favorites <id>` | Toggle favorite status |
448
+ | `captions <id>` | Get captions for a media file |
449
+ | `reanalyze <id>` | Re-run AI analysis with latest models |
450
+
451
+ ### AI & Search
452
+
453
+ | Command | Description |
454
+ |---|---|
455
+ | `ask <prompt>` | Ask AI about media, folders, or your whole workspace |
456
+ | `chat-history` | List past Magic Prompt conversations |
457
+ | `search <query>` | Full-text search across transcripts and insights |
458
+
459
+ ### Folders & Clips
460
+
461
+ | Command | Description |
462
+ |---|---|
463
+ | `list-folders` / `folders` | List all folders |
464
+ | `create-folder <name>` | Create a new folder |
465
+ | `clips` | List clips (filter by media or folder) |
466
+ | `clip <mediaId>` | Create a clip (`--start` and `--end` in seconds) |
467
+
468
+ ### Workspace
469
+
470
+ | Command | Description |
471
+ |---|---|
472
+ | `stats` | Show workspace media statistics |
473
+ | `languages` | List supported transcription languages |
474
+ | `schedule-meeting <url>` | Schedule AI assistant to join a meeting |
475
+ | `create-text <name>` | Create a text note (`--text` or pipe via stdin) |
476
+
477
+ ### CLI Options
478
+
479
+ Every command supports:
480
+ - `--json` — output raw JSON (for scripting and piping)
481
+ - `--help` — show command-specific help
482
+
483
+ ### CLI Examples
484
+
485
+ ```sh
486
+ # Upload and wait for processing
487
+ speakai-mcp upload https://example.com/interview.mp3 -n "Q1 Interview" --wait
488
+
489
+ # Upload a local file
490
+ speakai-mcp upload ./meeting-recording.mp4
491
+
492
+ # Get plain-text transcript
493
+ speakai-mcp transcript abc123 --plain > meeting.txt
494
+
495
+ # Export as PDF with speaker names
496
+ speakai-mcp export abc123 -f pdf --speakers
497
+
498
+ # Ask AI about a specific media file
499
+ speakai-mcp ask "What were the action items?" -m abc123
500
+
501
+ # Ask across your entire workspace
502
+ speakai-mcp ask "What themes appear in customer interviews?"
503
+
504
+ # Search all transcripts
505
+ speakai-mcp search "pricing concerns" --from 2026-01-01
506
+
507
+ # Create a text note from stdin
508
+ cat notes.txt | speakai-mcp create-text "Meeting Notes"
509
+
510
+ # Create a 30-second clip
511
+ speakai-mcp clip abc123 --start 60 --end 90 -n "Key Quote"
512
+
513
+ # Schedule a meeting bot
514
+ speakai-mcp schedule-meeting "https://zoom.us/j/123456" -t "Weekly Standup"
515
+
516
+ # List videos as JSON for scripting
517
+ speakai-mcp ls --type video --json | jq '.mediaList[].name'
518
+ ```
519
+
520
+ ---
521
+
522
+ ## Workflow Examples
523
+
524
+ ### Transcribe and Analyze a Meeting
298
525
 
299
526
  ```
300
527
  You: "Upload and transcribe this recording: https://example.com/meeting.mp3"
301
528
 
302
- AI: I'll upload that for you.
303
- upload_media(url, name, mediaType: "audio")
304
- → get_media_status(mediaId) [polls until complete]
305
- → get_transcript(mediaId)
306
- → get_media_insights(mediaId)
529
+ AI: I'll upload and analyze that for you.
530
+ -> upload_and_analyze(url, name)
531
+ [waits for processing... returns transcript + insights]
307
532
 
308
533
  Here's your transcript with 3 speakers identified.
309
- Key insights: 5 action items, positive sentiment overall...
534
+ Key insights: 5 action items, positive sentiment overall.
535
+ Top topics: Q2 roadmap, hiring plan, budget review.
310
536
  ```
311
537
 
312
- ### Research Across Recordings
538
+ ### Research Across Your Library
313
539
 
314
540
  ```
315
541
  You: "What themes came up across all our customer interviews this month?"
316
542
 
317
543
  AI: Let me search your media library.
318
- list_media(filterName: "interview", from: "2026-03-01")
319
- get_media_insights(mediaId) [for each result]
320
- → ask_magic_prompt(mediaId, "What are the recurring themes?")
544
+ -> search_media(query: "customer interview", startDate: "2026-03-01")
545
+ -> ask_magic_prompt(mediaIds: [...], prompt: "What are the recurring themes?")
321
546
 
322
- Across 12 interviews, the top themes were...
547
+ Across 12 interviews, the top themes were:
548
+ 1. Pricing sensitivity (mentioned in 8/12)
549
+ 2. Onboarding friction (6/12)
550
+ 3. Feature requests for API access (5/12)
323
551
  ```
324
552
 
325
553
  ### Meeting Automation
326
554
 
327
555
  ```
328
- You: "Join my 2pm Zoom call and send me the summary after"
556
+ You: "Join my 2pm Zoom call, then send me a summary with action items"
557
+
558
+ AI: -> schedule_meeting_event(meetingUrl, scheduledAt: "2026-03-25T14:00:00Z")
559
+
560
+ Done. After the meeting ends and processing completes, I'll pull
561
+ the transcript and insights automatically.
562
+
563
+ [After the meeting]
564
+ -> get_media_insights(mediaId)
565
+ -> ask_magic_prompt(mediaIds: [...], prompt: "List all action items with owners")
566
+
567
+ Here's your meeting summary with 7 action items...
568
+ ```
329
569
 
330
- AI: schedule_meeting_event(meetingUrl, scheduledAt: "2026-03-23T14:00:00Z")
570
+ ### Build a Weekly Brief
331
571
 
332
- Done. After the meeting I'll pull the transcript and insights for you.
572
+ ```
573
+ You: "Prepare a brief from all meetings in the last week"
574
+
575
+ AI: -> list_media(from: "2026-03-18", mediaType: "audio")
576
+ -> get_media_insights(mediaId) [for each of 5 meetings]
577
+
578
+ Weekly Meeting Brief (Mar 18-25):
579
+ - Engineering Standup: Deployed v2.3, 2 bugs triaged
580
+ - Sales Review: Pipeline at $1.2M, 3 deals closing this week
581
+ - Product Sync: Finalized Q2 roadmap, new hire starts Monday
582
+
583
+ Consolidated Action Items: [12 items grouped by owner]
333
584
  ```
334
585
 
335
586
  ---
@@ -338,16 +589,19 @@ AI: → schedule_meeting_event(meetingUrl, scheduledAt: "2026-03-23T14:00:00Z")
338
589
 
339
590
  ### Authentication
340
591
 
341
- All requests require `x-speakai-key` (API key) and `x-access-token` (JWT) headers. Access tokens expire — refresh using `POST /v1/auth/refreshToken`.
592
+ 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`.
342
593
 
343
594
  ### Rate Limits
344
595
 
345
596
  - Implement exponential backoff on `429` responses
346
- - Cache stable data (folder lists, field definitions)
347
- - Use `export_multiple_media` over individual exports
597
+ - Cache stable data (folder lists, field definitions, supported languages)
598
+ - Use `export_multiple_media` over individual exports for batch operations
599
+ - Use `upload_and_analyze` instead of manual upload + poll + fetch loops
348
600
 
349
601
  ### Error Format
350
602
 
603
+ All tool errors follow this structure:
604
+
351
605
  ```json
352
606
  {
353
607
  "content": [{ "type": "text", "text": "Error: HTTP 401: {\"message\": \"Invalid API key\"}" }],
@@ -367,18 +621,22 @@ All requests require `x-speakai-key` (API key) and `x-access-token` (JWT) header
367
621
  ## Development
368
622
 
369
623
  ```sh
370
- git clone https://github.com/speakai/speak-mcp.git
371
- cd speak-mcp
624
+ git clone https://github.com/speakai/speakai-mcp.git
625
+ cd speakai-mcp
626
+
372
627
  npm install
373
628
  npm run dev # Run with hot reload
374
629
  npm run build # Production build
375
630
  ```
376
631
 
632
+ ---
633
+
377
634
  ## Resources
378
635
 
379
636
  - [Speak AI](https://speakai.co) — Platform
380
637
  - [API Documentation](https://docs.speakai.co) — Full API reference
381
638
  - [MCP Protocol](https://modelcontextprotocol.io) — Model Context Protocol spec
639
+ - [npm Package](https://www.npmjs.com/package/@speakai/mcp-server) — npm registry
382
640
  - [Support](mailto:accounts@speakai.co) — Email us
383
641
 
384
642
  ## License