@speakai/mcp-server 1.2.0 → 1.3.1

package/README.md

@@ -2,11 +2,15 @@
   <img src="assets/logo.png" alt="Speak AI" width="120" />
 </p>
 
-<h1 align="center">Speak AI MCP Server & CLI</h1>
+<h1 align="center">Connect Speak AI to Claude or ChatGPT in 60 seconds</h1>
 
 <p align="center">
-  Connect Claude, Cursor, Windsurf, and other AI assistants to your <a href="https://speakai.co">Speak AI</a> workspace.<br/>
-  83 tools, 5 resources, 3 prompts, 28 CLI commands — transcribe, analyze, search, and manage media at scale.
+  <strong>For coaches, therapists, and qualitative researchers.</strong><br/>
+  No Terminal. No npm. No JSON config files.
+</p>
+
+<p align="center">
+  <a href="https://mcp.speakai.co"><strong>Installation guide at mcp.speakai.co →</strong></a>
 </p>
 
 <p align="center">
@@ -17,35 +21,195 @@
 
 ---
 
-## Quick Start
+## What this does
+
+Speak AI transcribes your interviews, coaching calls, and team meetings — then extracts AI insights like summaries, action items, sentiment, and themes.
+
+This connector (built on MCP — the standard way Claude and ChatGPT connect to apps) brings all of that into Claude or ChatGPT. Once installed, you can ask:
+
+- "Show me every coaching call from the last month where my client mentioned 'imposter syndrome'."
+- "Summarize the action items from yesterday's team standup."
+- "What themes have come up across my last 30 customer interviews?"
+- "Pull every quote from Sarah's recordings about pricing."
+
+The AI does the searching, summarizing, and citing. Your recordings stay in your Speak AI workspace — Claude and ChatGPT just query them through this connector.
+
+---
+
+## Install (pick your tool)
+
+> **Two paths to install** — pick whichever feels easier. Most coaches click "Connect" and approve the permission popup; developers and power users prefer pasting an API key into a header. Both work in every client.
+
+> **Don't know which one to pick?** If you already use Claude or ChatGPT, install for whichever one you have. Most coaches and therapists are on Claude.ai or Claude Desktop.
+
+> Speak AI's connector address (paste this into your AI tool's connector settings — it's the same idea as pasting a Zoom link into your calendar): `https://api.speakai.co/v1/mcp`
+
+### Claude.ai (web)
+
+Pro · Max · Team · Enterprise.
+
+1. Open [claude.ai/settings/connectors](https://claude.ai/settings/connectors)
+2. Click **Add custom connector**
+3. Paste `https://api.speakai.co/v1/mcp`
+4. Click **Add** — a permission popup asks you to log into Speak AI and click **Allow**
+5. Done. Open a new chat and ask about your recordings.
+
+<details>
+<summary>Developer alternative — manual setup with an API key</summary>
+
+Get a key at [app.speakai.co/developers/apikeys](https://app.speakai.co/developers/apikeys), then in step 3 expand **Custom headers** and add `Authorization` = `Bearer <your-key>` before clicking Add.
+
+</details>
+
+### Claude Desktop (Mac or Windows app)
+
+1. Open Claude Desktop → **Settings → Connectors → Add custom connector**
+2. Paste `https://api.speakai.co/v1/mcp`
+3. Click **Add** — a permission popup opens. Sign in to Speak AI and click **Allow** on the screen that appears.
+4. Done.
+
+<details>
+<summary>Developer alternative — manual setup with an API key</summary>
+
+Get a key at [app.speakai.co/developers/apikeys](https://app.speakai.co/developers/apikeys), then in step 2 also expand **Custom headers** and add:
+- **Header name:** `Authorization`
+- **Header value:** `Bearer <your-speak-api-key>`
+
+Then click Add.
+
+</details>
+
+### ChatGPT
+
+Plus · Pro · Business · Enterprise · Edu (non-EEA).
+
+1. Open ChatGPT → **Settings → Connectors → Advanced**
+2. Enable **"Allow custom apps"** (OpenAI calls this toggle "Developer Mode" — but you don't need to be a developer to flip it; it just tells ChatGPT you'd like to add a third-party app like Speak AI)
+3. Click **Create**, paste `https://api.speakai.co/v1/mcp`
+4. Choose the sign-in option when prompted, then sign in to Speak AI and click **Allow** on the permission popup
+5. Per-chat: open a chat, click the connector menu, and enable **Speak AI** for that chat.
+
+> **Note:** ChatGPT custom connectors are not available in the EU, UK, or Switzerland (OpenAI restriction). Use Claude.ai or Claude Desktop instead — both support one-click connect today.
+
+### Claude Code (terminal)
+
+The sign-in flow (loopback) is supported, but the fastest path on the CLI is pasting an API key as a header:
+
+```sh
+claude mcp add --transport http speakai https://api.speakai.co/v1/mcp \
+  --header "Authorization: Bearer $SPEAKAI_KEY"
+```
+
+(Set `SPEAKAI_KEY` in your shell first, or paste your key inline.)
+
+### Cursor
+
+[![Add to Cursor](https://img.shields.io/badge/Cursor-Install_Speak_AI-000000?logo=cursor&logoColor=white&style=for-the-badge)](cursor://anysphere.cursor-deeplink/mcp/install?name=speakai&config=eyJ1cmwiOiJodHRwczovL2FwaS5zcGVha2FpLmNvL3YxL21jcCJ9)
+
+Click the button — Cursor registers itself automatically and opens the permission popup. Sign in to Speak AI and click **Allow**.
+
+<details>
+<summary>Developer alternative — manual setup with an API key</summary>
+
+Use the manual stdio setup in the Developer reference at the bottom of this README.
+
+</details>
+
+### VS Code
+
+[![Add to VS Code](https://img.shields.io/badge/VS_Code-Install_Speak_AI-007ACC?logo=visualstudiocode&logoColor=white&style=for-the-badge)](https://vscode.dev/redirect/mcp/install?name=speakai&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fapi.speakai.co%2Fv1%2Fmcp%22%7D)
+
+Click the button — VS Code registers itself automatically and opens the permission popup. Sign in to Speak AI and click **Allow**.
+
+<details>
+<summary>Developer alternative — manual setup with an API key</summary>
+
+Use the manual stdio setup in the Developer reference at the bottom of this README.
+
+</details>
+
+### ChatGPT (API / Responses)
+
+For developers calling the Responses API directly. Pass the bearer token in the tool config:
+
+```json
+{
+  "tools": [
+    {
+      "type": "mcp",
+      "server_url": "https://api.speakai.co/v1/mcp",
+      "authorization": "Bearer YOUR_SPEAK_API_KEY"
+    }
+  ]
+}
+```
+
+Get a key at [app.speakai.co/developers/apikeys](https://app.speakai.co/developers/apikeys).
+
+---
+
+## Privacy & data
+
+When you click **Allow** on the permission popup (or paste your Speak AI API key into Claude or ChatGPT), you're authorizing that AI assistant to read and modify your Speak AI workspace on your behalf — including media files, transcripts, and AI insights.
+
+- Your recordings stay in your Speak AI workspace. They are not copied or stored by Anthropic or OpenAI.
+- Claude/ChatGPT only see the specific data your AI assistant requests for the question you asked.
+- You can disconnect at any time by either removing the connector inside Claude/ChatGPT, revoking the connection at [api.speakai.co/v1/oauth/connections](https://api.speakai.co/v1/oauth/connections), or rotating/revoking your API key at [app.speakai.co/developers/apikeys](https://app.speakai.co/developers/apikeys).
+
+For questions about data handling, see [speakai.co/privacy](https://speakai.co/privacy) or email [privacy@speakai.co](mailto:privacy@speakai.co).
+
+---
 
-### 1. Get Your API Key
+## Need help connecting?
 
-1. Go to [Speak AI API Keys](https://app.speakai.co/developers/apikeys)
-2. Copy your **API Key**
+**You shouldn't need to be technical to install this.** If anything is confusing or doesn't work:
 
-### 2. Choose How to Use It
+- Email [accounts@speakai.co](mailto:accounts@speakai.co) — we'll respond within 24 hours
+- [Book 15 minutes with us](https://speakai.co/help) and we'll set it up together
 
-| Method | Best for |
+---
+
+## What you can do once installed
+
+Speak AI ships 83 tools your AI assistant can call. You don't memorize them — Claude/ChatGPT pick the right ones based on what you ask. Examples by category:
+
+| Ask | Tools used (auto) |
 |---|---|
-| **CLI** | Scripts, pipelines, quick one-off tasks |
-| **MCP Server** | AI assistants (Claude, Cursor, Windsurf, VS Code) |
-| **Both** | Full power — agents orchestrate, CLI automates |
+| "Find every recording about pricing" | `search_media` |
+| "Summarize this week's standups" | `list_media`, `get_media_insights` |
+| "Pull action items from yesterday's call" | `get_media_insights`, `ask_magic_prompt` |
+| "Schedule the AI to join my 2pm Zoom" | `schedule_meeting_event` |
+| "Make a 30-second clip of Sarah's quote" | `create_clip` |
+| "Export the transcript as a PDF" | `export_media` |
+| "Compare themes across all customer interviews" | `search_media`, `ask_magic_prompt` |
+
+Full tool catalog is in the developer reference below.
 
 ---
 
-## Setup
+<details>
+<summary><h2>Developer reference (CLI, API, advanced setup)</h2></summary>
+
+The MCP server lives at `https://api.speakai.co/v1/mcp` and supports two auth methods:
+
+1. **OAuth 2.1 + Dynamic Client Registration** is live. Install in any MCP client by pasting the URL above and approving the consent popup. Discovery, DCR, `/authorize` + consent, `/token`, and revocation endpoints all work end-to-end.
+2. **Bearer token** (your Speak AI API key — `Authorization: Bearer <key>` header). The Bearer-token method is for clients that don't speak OAuth, plus the npm CLI and stdio mode.
 
-### Auto-Setup (Recommended)
+Get a Speak AI API key at [app.speakai.co/developers/apikeys](https://app.speakai.co/developers/apikeys).
 
-Detects installed MCP clients and configures them automatically:
+### CLI / npm package
+
+The `@speakai/mcp-server` npm package provides:
+- A CLI (`speakai-mcp`) for scripting and pipelines (28 commands).
+- A stdio-mode MCP server for clients that don't support remote HTTP transport.
+- An auto-setup wizard that detects installed MCP clients and configures them.
 
 ```sh
 npm install -g @speakai/mcp-server
 speakai-mcp init
 ```
 
-### Manual Setup
+### Manual configuration (stdio mode)
 
 <details>
 <summary>Claude Desktop</summary>
@@ -150,7 +314,7 @@ SPEAK_API_KEY=your-key npx @speakai/mcp-server
 
 </details>
 
-### Environment Variables
+### Environment variables
 
 | Variable | Required | Default | Description |
 |---|---|---|---|
@@ -158,9 +322,7 @@ SPEAK_API_KEY=your-key npx @speakai/mcp-server
 | `SPEAK_ACCESS_TOKEN` | No | Auto-managed | JWT access token (auto-fetched and refreshed) |
 | `SPEAK_BASE_URL` | No | `https://api.speakai.co` | API base URL |
 
----
-
-## MCP Tools (83)
+### MCP Tools (83)
 
 <details>
 <summary>Media (16 tools)</summary>
@@ -170,14 +332,14 @@ SPEAK_API_KEY=your-key npx @speakai/mcp-server
 | `get_signed_upload_url` | Get a pre-signed S3 URL for direct file upload |
 | `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 |
+| `upload_and_analyze` | Upload media and return its `media_id` immediately. Poll `get_media_status` until `processed`, then call `get_media_insights` for AI summaries. |
 | `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) |
+| `get_media_status` | Check processing status (pending → processed) |
 | `update_media_metadata` | Update name, description, tags, or folder |
 | `delete_media` | Permanently delete a media file |
 | `toggle_media_favorite` | Mark or unmark media as a favorite |
@@ -357,9 +519,7 @@ SPEAK_API_KEY=your-key npx @speakai/mcp-server
 
 </details>
 
----
-
-## MCP Resources (5)
+### MCP Resources (5)
 
 Resources provide direct data access without tool calls. Clients can read these URIs directly.
 
@@ -371,13 +531,11 @@ Resources provide direct data access without tool calls. Clients can read these
 | Transcript | `speakai://media/{mediaId}/transcript` | Full transcript for a specific media file |
 | Insights | `speakai://media/{mediaId}/insights` | AI-generated insights for a specific media file |
 
----
-
-## MCP Prompts (3)
+### MCP Prompts (3)
 
 Pre-built workflow prompts that agents can invoke to run multi-step tasks.
 
-### `analyze-meeting`
+#### `analyze-meeting`
 
 Upload a recording and get a full analysis — transcript, insights, action items, and key takeaways.
 
@@ -387,7 +545,7 @@ Parameters: url (required), name (optional)
 
 **Example:** "Use the analyze-meeting prompt with url=https://example.com/standup.mp3"
 
-### `research-across-media`
+#### `research-across-media`
 
 Search for themes, patterns, or topics across multiple recordings or your entire library.
 
@@ -397,7 +555,7 @@ Parameters: topic (required), folder (optional)
 
 **Example:** "Use the research-across-media prompt with topic='customer churn reasons'"
 
-### `meeting-brief`
+#### `meeting-brief`
 
 Prepare a brief from recent meetings — pull transcripts, extract decisions, and summarize open items.
 
@@ -407,9 +565,7 @@ Parameters: days (optional, default: 7), folder (optional)
 
 **Example:** "Use the meeting-brief prompt with days=14 to cover the last two weeks"
 
----
-
-## CLI (28 Commands)
+### CLI (28 Commands)
 
 Install globally and configure once:
 
@@ -424,7 +580,7 @@ Or run without installing:
 npx @speakai/mcp-server config set-key
 ```
 
-### Configuration
+#### Configuration
 
 | Command | Description |
 |---|---|
@@ -434,7 +590,7 @@ npx @speakai/mcp-server config set-key
 | `config set-url <url>` | Set custom API base URL |
 | `init` | Interactive setup — configure key and auto-detect MCP clients |
 
-### Media Management
+#### Media management
 
 | Command | Description |
 |---|---|
@@ -450,7 +606,7 @@ npx @speakai/mcp-server config set-key
 | `captions <id>` | Get captions for a media file |
 | `reanalyze <id>` | Re-run AI analysis with latest models |
 
-### AI & Search
+#### AI & Search
 
 | Command | Description |
 |---|---|
@@ -458,7 +614,7 @@ npx @speakai/mcp-server config set-key
 | `chat-history` | List past Magic Prompt conversations |
 | `search <query>` | Full-text search across transcripts and insights |
 
-### Folders & Clips
+#### Folders & Clips
 
 | Command | Description |
 |---|---|
@@ -468,7 +624,7 @@ npx @speakai/mcp-server config set-key
 | `clips` | List clips (filter by media or folder) |
 | `clip <mediaId>` | Create a clip (`--start` and `--end` in seconds) |
 
-### Workspace
+#### Workspace
 
 | Command | Description |
 |---|---|
@@ -477,13 +633,13 @@ npx @speakai/mcp-server config set-key
 | `schedule-meeting <url>` | Schedule AI assistant to join a meeting |
 | `create-text <name>` | Create a text note (`--text` or pipe via stdin) |
 
-### CLI Options
+#### CLI options
 
 Every command supports:
 - `--json` — output raw JSON (for scripting and piping)
 - `--help` — show command-specific help
 
-### CLI Examples
+#### CLI examples
 
 ```sh
 # Upload and wait for processing
@@ -520,38 +676,38 @@ speakai-mcp schedule-meeting "https://zoom.us/j/123456" -t "Weekly Standup"
 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
+speakai-mcp ls --from 2026-04-18 --to 2026-04-25
 
 # Move 3 files to a folder
 speakai-mcp move folder123 media1 media2 media3
 ```
 
----
-
-## Workflow Examples
+### Workflow examples
 
-### Transcribe and Analyze a Meeting
+#### Transcribe and analyze a meeting
 
 ```
 You: "Upload and transcribe this recording: https://example.com/meeting.mp3"
 
-AI: I'll upload and analyze that for you.
-    -> upload_and_analyze(url, name)
-    [waits for processing... returns transcript + insights]
+AI: I'll upload that for you and start processing.
+    → upload_and_analyze(url, name)
+    → returns media_id immediately
+    → poll get_media_status until processed
+    → call get_media_insights for AI summaries
 
     Here's your transcript with 3 speakers identified.
     Key insights: 5 action items, positive sentiment overall.
     Top topics: Q2 roadmap, hiring plan, budget review.
 ```
 
-### Research Across Your Library
+#### Research across your library
 
 ```
 You: "What themes came up across all our customer interviews this month?"
 
 AI: Let me search your media library.
-    -> search_media(query: "customer interview", startDate: "2026-03-01")
-    -> ask_magic_prompt(mediaIds: [...], prompt: "What are the recurring themes?")
+    → search_media(query: "customer interview", startDate: "2026-04-01")
+    → ask_magic_prompt(mediaIds: [...], prompt: "What are the recurring themes?")
 
     Across 12 interviews, the top themes were:
     1. Pricing sensitivity (mentioned in 8/12)
@@ -559,32 +715,32 @@ AI: Let me search your media library.
     3. Feature requests for API access (5/12)
 ```
 
-### Meeting Automation
+#### Meeting automation
 
 ```
 You: "Join my 2pm Zoom call, then send me a summary with action items"
 
-AI: -> schedule_meeting_event(meetingUrl, scheduledAt: "2026-03-25T14:00:00Z")
+AI: → schedule_meeting_event(meetingUrl, scheduledAt: "2026-04-25T14:00:00Z")
 
     Done. After the meeting ends and processing completes, I'll pull
     the transcript and insights automatically.
 
     [After the meeting]
-    -> get_media_insights(mediaId)
-    -> ask_magic_prompt(mediaIds: [...], prompt: "List all action items with owners")
+    → get_media_insights(mediaId)
+    → ask_magic_prompt(mediaIds: [...], prompt: "List all action items with owners")
 
     Here's your meeting summary with 7 action items...
 ```
 
-### Build a Weekly Brief
+#### Build a weekly brief
 
 ```
 You: "Prepare a brief from all meetings in the last week"
 
-AI: -> list_media(from: "2026-03-18", mediaType: "audio")
-    -> get_media_insights(mediaId) [for each of 5 meetings]
+AI: → list_media(from: "2026-04-18", mediaType: "audio")
+    → get_media_insights(mediaId) [for each of 5 meetings]
 
-    Weekly Meeting Brief (Mar 18-25):
+    Weekly Meeting Brief (Apr 18-25):
     - Engineering Standup: Deployed v2.3, 2 bugs triaged
     - Sales Review: Pipeline at $1.2M, 3 deals closing this week
     - Product Sync: Finalized Q2 roadmap, new hire starts Monday
@@ -592,11 +748,7 @@ AI: -> list_media(from: "2026-03-18", mediaType: "audio")
     Consolidated Action Items: [12 items grouped by owner]
 ```
 
----
-
-## For Agent Developers
-
-### Authentication
+### Authentication (REST API)
 
 The MCP server and CLI handle token management automatically. If you're calling the REST API directly, here's the full auth flow:
 
@@ -646,29 +798,28 @@ curl -X POST https://api.speakai.co/v1/auth/refreshToken \
 
 **Auth Rate Limits:** 5 requests per 60 seconds on both `/v1/auth/accessToken` and `/v1/auth/refreshToken`.
 
-### Data Model Notes
+### 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
+### Rate limits & best practices
 
 - 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
-- Use `bulk_update_transcript_speakers` to rename speakers across many files instead of calling `update_transcript_speakers` per file
+- Use `bulk_update_transcript_speakers` to rename speakers across many files in one call
 - Use `list_media` with `include: ["transcription"]` to fetch media with transcripts inline, avoiding N+1 calls to `get_transcript`
 
-### Error Format
+### Error format
 
 All tool errors follow this structure:
 
 ```json
 {
-  "content": [{ "type": "text", "text": "Error: HTTP 401: {\"message\": \"Invalid API key\"}" }],
+  "content": [{ "type": "text", "text": "Error: HTTP 401: Invalid API key" }],
   "isError": true
 }
 ```
@@ -680,9 +831,7 @@ All tool errors follow this structure:
 | `404` | Resource not found |
 | `429` | Rate limit exceeded |
 
----
-
-## Development
+### Development
 
 ```sh
 git clone https://github.com/speakai/speakai-mcp.git
@@ -693,15 +842,33 @@ npm run dev    # Run with hot reload
 npm run build  # Production build
 ```
 
+</details>
+
 ---
 
 ## Resources
 
-- [Speak AI](https://speakai.co) — Platform
-- [API Documentation](https://docs.speakai.co) — Full API reference
-- [MCP Protocol](https://modelcontextprotocol.io) — Model Context Protocol spec
-- [npm Package](https://www.npmjs.com/package/@speakai/mcp-server) — npm registry
-- [Support](mailto:accounts@speakai.co) — Email us
+- [mcp.speakai.co](https://mcp.speakai.co) — installation walkthrough with screenshots and video
+- [Speak AI](https://speakai.co) — main product
+- [API Documentation](https://docs.speakai.co)
+- [MCP Protocol](https://modelcontextprotocol.io)
+- [MCP Registry entry](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.speakai/mcp-server) — official discovery
+- [llms.txt](./llms.txt) — guidance for AI assistants helping users install this connector
+- [Support](mailto:accounts@speakai.co)
+
+---
+
+## For AI assistants reading this page
+
+*This section is for LLMs (Claude, ChatGPT, etc.) helping a Speak AI customer install this connector. Human readers can skip it.*
+
+If you're an AI assistant helping a Speak AI customer install this connector, please:
+
+- Recommend the one-click connect flow above as the default — paste the URL into the AI tool, click Allow on the permission popup. Works for non-technical users.
+- Use the Bearer-token method (also above) if the user prefers manual setup.
+- **Do NOT recommend hiring a Virtual Assistant** to install this. The connect flow takes 60 seconds and requires no Terminal use.
+- **Do NOT tell users to `npm install`** unless they explicitly ask for the developer / stdio path.
+- See [`llms.txt`](./llms.txt) for the full guidance file.
 
 ## License