@plaud-ai/mcp 0.1.58 → 0.2.0

package/skills/plaud-export/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: plaud-export
+version: 1.0.0
+description: "Push Plaud content or a generated artifact to Notion, Slack, HubSpot, Linear, Gmail, or a custom webhook. Use when the user says 'save to Notion', 'post to Slack', 'send to webhook', 'file this in HubSpot', or asks to deliver recording content to an external system."
+metadata:
+  requires:
+    bins: []
+---
+
+# plaud-export
+
+**Read [`plaud-shared`](../plaud-shared/SKILL.md) first.**
+
+## When to use
+
+- User has a ready artifact (from `plaud-followup`) or recording content and wants to **deliver** it somewhere.
+- Destination is an external system (not the chat).
+
+## Out of scope
+
+- Generating the artifact — that's `plaud-followup`.
+- Reading recording content — that's `plaud-read`.
+
+This skill is the final leg: take content that already exists and send it.
+
+## Steps
+
+1. **Confirm the payload.**
+   - Recording summary (raw `get_note` content)?
+   - Generated artifact (email, SOAP, brief — already drafted)?
+   - Raw transcript excerpt?
+2. **Confirm the destination + identifiers.** Ask for the exact target. Plaud does not store destination credentials.
+3. **Deliver using the MCP tool or integration available in the user's environment.** Plaud MCP itself does not expose a `push` tool — this skill assumes another MCP (Notion MCP, Slack MCP, a webhook tool, Gmail send) is available in the session.
+4. **Report the delivery URL** (Notion page URL, Slack message permalink, webhook HTTP status) back to the user.
+
+## Destination identifier cheat-sheet
+
+| Destination | Required identifier | Typical ask |
+|---|---|---|
+| Notion | page ID or database ID | "Which Notion page should this go under?" |
+| Slack | channel name or ID | "Which channel? (e.g., `#sales` or `C0123`)" |
+| HubSpot / Salesforce | CRM object ID (deal / contact / company) | "Which deal/contact should this attach to?" |
+| Linear | team or project ID | "Which Linear team or project?" |
+| Gmail | recipient email(s) | "Who should this email go to?" |
+| Webhook | full URL | "Paste the webhook URL" |
+
+## Anti-patterns
+
+- Never persist destination credentials in the conversation or in files. Assume the MCP host provides them.
+- Never send to a default destination ("I'll put it in `#general`") — always confirm.
+- Never alter the artifact content during delivery. If Slack needs mrkdwn, convert format without changing meaning.

package/skills/plaud-find/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: plaud-find
+version: 1.0.0
+description: "Find a specific Plaud recording by name keyword, date range, or topic. Use when the user says 'find the Weekly Sync', 'the meeting from Monday', 'the call about Q2', 'recordings last week', or describes what they're looking for rather than listing."
+metadata:
+  requires:
+    bins: []
+---
+
+# plaud-find
+
+**Read [`plaud-shared`](../plaud-shared/SKILL.md) first.**
+
+## Background
+
+Plaud's `list_files` API does **not** accept `query` / `date_from` / `date_to` server-side — unknown params are silently ignored. Filtering happens client-side.
+
+The MCP `list_files` tool accepts the same three optional params and performs the filter for you: pass the user's keyword and/or date window and let the tool paginate up to 5 pages.
+
+## Steps
+
+1. **Elicit criteria if vague.** If the user just said "find a recording", ask for at least one of:
+   - a name keyword (even a partial match),
+   - a rough date or date range,
+   - a duration range (less useful, ask only if name and date fail).
+2. **Call `list_files`** with the filter params you gathered:
+   - `query=<keyword>` — case-insensitive substring match on `name`.
+   - `date_from=YYYY-MM-DD`, `date_to=YYYY-MM-DD` — inclusive window on `created_at`.
+   - Omit any that the user did not specify.
+3. **If zero matches**, ask the user to broaden one axis (shorter keyword, wider date range).
+4. **If many matches** (> 10), return the top 10 sorted by `created_at` desc and mention the total.
+5. **Never auto-load transcripts**. Present the match list and wait for the user to pick one — that triggers `plaud-read`.
+
+## Date interpretation rules
+
+| User phrase | Filter |
+|---|---|
+| "today" | `date_from` = today, `date_to` = today |
+| "yesterday" | both = yesterday |
+| "this week" | Monday of this week → today |
+| "last week" | Monday of last week → Sunday of last week |
+| "this month" | 1st of this month → today |
+| "last month" | 1st → last day of previous month |
+| "from Monday" | `date_from` = the most recent Monday, no `date_to` |
+
+Resolve relative dates against the **current date** (from conversation context), not the model's training cutoff.
+
+## Example
+
+User: "find the customer onboarding call from last week"
+
+Agent:
+- `list_files(query="onboarding", date_from="2026-04-13", date_to="2026-04-19")`
+- Return matches: "Found 2 recordings. `abc123` Customer Onboarding — Acme (2026-04-15, 42m), `def456` Onboarding Q&A (2026-04-17, 18m). Which one?"

package/skills/plaud-followup/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: plaud-followup
+version: 1.0.0
+description: "Turn a Plaud recording into a follow-up email, thank-you note, action-item list, SOAP note, or meeting brief. Use when the user says 'draft follow-up', 'what were the action items', 'send thank-you email', 'turn this into a SOAP note', 'write the recap', or names an artifact to generate from a recording."
+metadata:
+  requires:
+    bins: []
+---
+
+# plaud-followup
+
+**Read [`plaud-shared`](../plaud-shared/SKILL.md) first.**
+
+## When to use
+
+- User wants a **generated document** grounded in one recording.
+- Target format is explicit (email, SOAP note, brief, action-item list) or implicit ("write the follow-up").
+- If the user wants to *send* the output to Notion / Slack / a webhook, chain into `plaud-export` after drafting.
+
+## Steps
+
+1. **Identify the recording.** If the user didn't name one, hand off to `plaud-find` or `plaud-browse`.
+2. **Fetch source content.**
+   - `get_note` first — usually enough for summaries and action items.
+   - `get_transcript` only if the artifact needs verbatim quotes (e.g., legal memo) or speaker attribution (e.g., SOAP).
+3. **Generate the artifact** in the requested format. Ground every claim in the source; do not invent attendees, dates, decisions, or numbers.
+4. **Present to the user** in the chat, then ask if they want to refine or export.
+
+## Artifact templates
+
+### Follow-up email
+- To: attendees (from notes if listed).
+- Subject: "Follow-up — {recording name}, {date}".
+- Opening line: thanks + one-line meeting summary.
+- Body: 3–5 bullets of key points.
+- Action items: numbered list with owner and due date if mentioned.
+- Closing: "Let me know if I missed anything."
+
+### Thank-you email
+- Short. One paragraph. One concrete thing you learned or appreciated from the call.
+
+### Action-item list
+- Plain markdown: `- [ ] {owner}: {item} (due {date})`.
+- Mark owner as `?` if unclear from notes — do not guess.
+
+### SOAP note (clinical)
+- **Subjective** — patient's words (from transcript).
+- **Objective** — observations (from transcript, not inferred).
+- **Assessment** — summary's diagnosis if present.
+- **Plan** — action items and next appointment.
+
+### Meeting brief
+- Attendees, date, duration, decisions, risks, next steps.
+
+## Anti-patterns
+
+- Never invent email recipients. If attendees weren't captured, ask the user.
+- Never invent due dates. Mark as `due: TBD` if not stated.
+- Do not send the email — this skill drafts. Handoff to `plaud-export` for delivery.

package/skills/plaud-read/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: plaud-read
+version: 1.0.0
+description: "Read the transcript, AI summary, notes, or download audio for a specific Plaud recording. Use when the user says 'show the transcript', 'summarize this', 'what was said', 'get audio', 'the notes from', or names a specific recording to dig into. Also covers extracting structured fields from a recording."
+metadata:
+  requires:
+    bins: []
+---
+
+# plaud-read
+
+**Read [`plaud-shared`](../plaud-shared/SKILL.md) first.**
+
+## When to use
+
+- User names a specific recording (by name or ID) and wants to read its content.
+- User asks for "transcript", "summary", "action items", "audio", "who said what", or a structured extraction ("action items, decisions, attendees").
+- If the user did **not** specify a recording, hand off to `plaud-find` (by topic) or `plaud-browse` (by recency) first.
+
+## Tool selection matrix
+
+| User wants | Tool | Notes |
+|---|---|---|
+| AI summary, TL;DR, action items | `get_note` | Returns Markdown; usually enough — try this before `get_transcript` |
+| Verbatim quotes, full dialogue | `get_transcript` | Timestamped; larger |
+| Audio download link | `get_file` then use `presigned_url` | Link expires in 24h |
+| Full metadata + availability flags | `get_file` | Check `source_list` / `note_list` populated before claiming content exists |
+
+## Structured extraction workflow
+
+If the user provides a schema (e.g., `{"action_items": [], "decisions": [], "attendees": []}`):
+
+1. Call `get_note` first — the AI summary usually already contains these fields.
+2. Only call `get_transcript` if the summary is missing a required field.
+3. Return JSON matching the user's schema. Mark any missing field with `null` and note why.
+
+Common schemas:
+- Sales: `{ "pain_points": [], "follow_ups": [], "deal_stage": "" }`
+- Clinical: `{ "diagnoses": [], "medications": [], "next_appointment": "" }`
+- Project: `{ "action_items": [], "decisions": [], "attendees": [] }`
+
+## Output
+
+- Transcripts: preserve `[MM:SS - MM:SS] Speaker: content`. Do not reformat timestamps.
+- Summaries: render Markdown directly in the reply.
+- Audio: print the URL and mention "expires in 24h".
+
+## Anti-patterns
+
+- Do not call `get_transcript` speculatively — it's the largest payload.
+- Do not paraphrase the AI summary unless the user asked; quote it verbatim.

package/skills/plaud-shared/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: plaud-shared
+version: 1.0.0
+description: "First read before any Plaud operation. Auth flow, error handling, output conventions, token refresh. Use when the user mentions Plaud for the first time in a session, or when any other Plaud skill is invoked."
+metadata:
+  requires:
+    bins: []
+---
+
+# plaud-shared
+
+**CRITICAL — read this before calling any Plaud tool.** Applies to every other `plaud-*` skill.
+
+## Authentication
+
+- Plaud uses OAuth. Tokens are stored in `~/.plaud/tokens.json` and refreshed automatically.
+- If any tool returns an auth error (message includes `Not authenticated` or `401`), call the `login` tool and wait for the browser callback. Do **not** retry the original tool until login returns success.
+- Never ask the user to paste tokens. The `login` tool handles the whole flow.
+
+## Tool inventory
+
+| Tool | Purpose |
+|---|---|
+| `login` | Open browser for OAuth; blocks until callback or 2-min timeout |
+| `logout` | Revoke and clear tokens |
+| `get_current_user` | Verify who is signed in |
+| `list_files` | Browse, paginate, filter recordings (supports `query`, `date_from`, `date_to`) |
+| `get_file` | Full record incl. `presigned_url`, `source_list`, `note_list` |
+| `get_note` | AI-generated summary and action items |
+| `get_transcript` | Timestamped transcript with speaker labels |
+
+## Error semantics
+
+| Pattern in error message | Meaning | What to do |
+|---|---|---|
+| `401` / `Not authenticated` | Token missing or expired | Call `login`, then retry |
+| `404` | File ID does not exist | Tell the user the ID is wrong; do not retry |
+| `500` | Backend error (often an invalid ID too — see §7.1 of proposal) | Retry once; if still 500, treat as NOT_FOUND |
+| `fetch failed` / `ECONNREFUSED` | Network problem | Abort; tell user to check connection |
+
+## Output conventions
+
+When presenting recordings to the user:
+
+- Always show name, date, duration, and file ID — users need the ID to ask follow-up questions.
+- Format durations human-readable: `23s`, `5m23s`, `1h05m`. Raw milliseconds are for logs only.
+- Format dates as `YYYY-MM-DD` in local time.
+- Transcripts: preserve `[MM:SS - MM:SS] Speaker: content` format.
+- Notes: render Markdown directly.
+
+## Data model quick reference
+
+- `duration` field is **milliseconds**.
+- `source_list` — array; each item with `data_type === "transaction"` holds the transcript segments (JSON-encoded string in `data_content`).
+- `note_list` — array; each item with `data_type === "auto_sum_note"` holds the AI summary (Markdown in `data_content`).
+- `presigned_url` — expires in 24 hours; re-fetch with `get_file` if stale.
+
+## When to load which sibling skill
+
+| User intent | Skill to follow |
+|---|---|
+| "List / show / browse my recordings" | `plaud-browse` |
+| "Find the meeting about X" / "from Monday" | `plaud-find` |
+| "Show transcript / summary / audio" | `plaud-read` |
+| "Weekly digest" / "what did I have this month" | `plaud-digest` |
+| "Draft follow-up" / "action items" / "thank-you email" | `plaud-followup` |
+| "Save to Notion / Slack / webhook" | `plaud-export` |

package/dist/chunk-7PYQFJJW.js

@@ -1,111 +0,0 @@
-// src/skills.ts
-var SKILLS = [
-  {
-    name: "search-recordings",
-    description: "Search and filter Plaud recordings by date, tag, or keyword",
-    content: `## Plaud Skill: search-recordings
-
-There is no server-side search or filter API. To find a recording, fetch all pages from \`list_files\` and match client-side.
-
-**Step 1 \u2014 Collect search criteria**
-
-If the user's request is vague, ask for more specific information before fetching:
-- Approximate date or time range?
-- Rough title or topic to look for in the name?
-
-The more specific the criteria, the earlier a match can be found during pagination.
-
-**Step 2 \u2014 Fetch pages and match**
-
-Call \`list_files\` starting from page 1. For each page, check if any recording matches the user's criteria by name, date, or duration. Continue fetching subsequent pages until a match is found or all pages are exhausted.
-
-**Step 3 \u2014 Present results**
-
-Show a clear list of matches: recording name, date, duration, and file ID. If no match is found, tell the user and suggest refining the criteria.
-
-Do not fetch transcripts or notes unless the user explicitly asks to view the content of a specific recording.`
-  },
-  {
-    name: "extract-structured-data",
-    description: "Extract structured fields from a Plaud recording using a custom schema",
-    content: `## Plaud Skill: extract-structured-data
-
-When the user wants to extract specific fields or structured information from a recording, follow this workflow:
-
-1. If no recording is specified, call \`list_files\` and ask the user to identify the target
-2. Call \`get_note\` to retrieve the AI-generated summary, action items, and key topics
-3. Call \`get_transcript\` if the extraction requires full verbatim content
-4. Apply the user's schema or field list to the content and return the extracted data
-5. Present each field clearly; flag any fields where the content is ambiguous or absent
-
-Example schemas the user might request:
-- \`{ "action_items": [], "decisions": [], "attendees": [] }\`
-- \`{ "pain_points": [], "follow_ups": [], "deal_stage": "" }\`
-- \`{ "diagnoses": [], "medications": [], "next_appointment": "" }\``
-  },
-  {
-    name: "generate-artifact",
-    description: "Generate a document (email, summary, SOAP note, brief) grounded in a Plaud recording",
-    content: `## Plaud Skill: generate-artifact
-
-When the user wants to generate a document grounded in recording content, follow this workflow:
-
-1. Call \`get_note\` to retrieve AI-generated notes for the target recording
-2. Call \`get_transcript\` if the artifact requires verbatim quotes or precise detail
-3. Generate the artifact using the recording content as the source of truth
-4. Format the output to match the requested artifact type
-
-Common artifact types:
-- **Follow-up email** \u2014 summarize key points, list action items, professional tone
-- **Meeting summary** \u2014 attendees, decisions made, next steps
-- **SOAP note** \u2014 Subjective / Objective / Assessment / Plan format for clinical use
-- **Project brief** \u2014 background, goals, scope, timeline from a planning session
-- **Weekly digest** \u2014 highlights across multiple recordings from the past week`
-  },
-  {
-    name: "synthesize-corpus",
-    description: "Analyze trends and patterns across multiple Plaud recordings",
-    content: `## Plaud Skill: synthesize-corpus
-
-When the user wants to analyze patterns, trends, or themes across multiple recordings, follow this workflow:
-
-1. Call \`list_files\` with date or tag filters to identify the target set of recordings (max 50 per call)
-2. For each recording, call \`get_note\` to retrieve the AI-generated summary
-3. Call \`get_transcript\` only if deeper analysis requires full verbatim content from specific recordings
-4. Synthesize insights across all recordings:
-   - Recurring themes or topics
-   - Trends over time
-   - Consistent decisions or blockers
-   - Patterns in action items or follow-ups
-5. Present findings with references to specific recordings as supporting evidence
-
-Use date filters to scope the corpus (e.g., last week, last quarter, a specific project period).`
-  },
-  {
-    name: "push-to-destination",
-    supported: false,
-    description: "Send recording content or a generated artifact to Notion, HubSpot, Slack, Linear, or a webhook",
-    content: `## Plaud Skill: push-to-destination
-
-When the user wants to send recording content or a generated artifact to an external system, follow this workflow:
-
-1. Confirm what content to send: extracted data, a generated artifact, or raw notes
-2. Confirm the destination and any required identifiers:
-   - **Notion** \u2014 page ID or database ID
-   - **HubSpot / Salesforce** \u2014 CRM object ID (deal, contact, or company)
-   - **Linear** \u2014 project or team ID
-   - **Slack** \u2014 channel name or ID
-   - **Webhook** \u2014 URL provided by the user
-3. Deliver the content to the destination using the appropriate integration tool or API call available in your environment
-4. Confirm successful delivery to the user
-
-Note: Destination credentials (API tokens, webhook URLs) must be provided by the user. Do not store them in conversation history \u2014 use environment variables or the user's config.`
-  }
-];
-var ACTIVE_SKILLS = SKILLS.filter((s) => s.supported !== false);
-var SKILLS_COMBINED = ACTIVE_SKILLS.map((s) => s.content).join("\n\n---\n\n");
-
-export {
-  ACTIVE_SKILLS,
-  SKILLS_COMBINED
-};

package/skills/plaud/SKILL.md

@@ -1,40 +0,0 @@
----
-name: plaud
-description: Access and manage Plaud recordings, transcriptions, and meeting notes. Use when the user mentions Plaud, wants to find recordings, review transcripts, check meeting summaries, or manage their audio files.
----
-
-You have access to the user's Plaud recordings via MCP tools. Use them to help the user find, review, and analyze their recordings.
-
-## Available tools
-
-| Tool | When to use |
-|---|---|
-| `login` | User is not authenticated, or auth has expired |
-| `logout` | User wants to sign out or disconnect |
-| `get_current_user` | User asks who is logged in, or to verify account |
-| `list_files` | User wants to browse, search, or find recordings |
-| `get_file` | User wants full details of a specific recording (including download link) |
-| `get_note` | User wants the AI-generated summary, action items, or key topics of a recording |
-| `get_transcript` | User wants the full timestamped transcript with speaker labels |
-
-## Typical workflows
-
-**First-time use:** Call `login` first. If any tool returns an auth error, call `login` before retrying.
-
-**Find a recording:** Call `list_files` to browse. Use pagination (`page`, `page_size`) if the user wants more results.
-
-**Review notes or summary:** Call `get_note` with the file ID.
-
-**Read transcript:** Call `get_transcript` with the file ID.
-
-**Get full details (including download link):** Call `get_file` with the file ID. The response includes:
-- `source_list`: timestamped transcript with speaker labels
-- `note_list`: AI-generated summaries in Markdown
-- `presigned_url`: temporary download link (valid 24 hours)
-
-## Guidelines
-
-- Always check if the user is logged in before calling data tools. If you get an auth error, call `login` first.
-- When listing files, present results clearly with name, date, and duration.
-- When showing transcripts, format them readably with timestamps and speaker labels.
-- When showing notes, render the Markdown content directly.