@plaud-ai/mcp 0.1.32 → 0.2.0

package/dist/{setup-3PYAGQRG.js → setup-7JTG3C2W.js}

@@ -1,58 +1,20 @@
 import {
-  SKILLS_COMBINED
-} from "./chunk-5JTZ7NKP.js";
+  copyToClipboard,
+  getMcpEntry,
+  removeSkillsFromClaudeCode,
+  writeSkillsToClaudeCode
+} from "./chunk-UPEENHCG.js";
+import {
+  skillsCombined
+} from "./chunk-4QBEOJPX.js";
 
 // src/setup.ts
 import { readFile, writeFile, mkdir, rm } from "fs/promises";
 import { join, dirname } from "path";
-import { homedir, platform } from "os";
-import { fileURLToPath } from "url";
-import { spawnSync } from "child_process";
-var SKILLS_MARKER_START = "<!-- plaud-skills:start -->";
-var SKILLS_MARKER_END = "<!-- plaud-skills:end -->";
-var SKILLS_BLOCK = `${SKILLS_MARKER_START}
-${SKILLS_COMBINED}
-${SKILLS_MARKER_END}`;
-async function removeSkillsFromClaudeCode() {
-  const claudeMdPath = join(homedir(), ".claude", "CLAUDE.md");
-  let existing = "";
-  try {
-    existing = await readFile(claudeMdPath, "utf-8");
-  } catch {
-    return;
-  }
-  if (!existing.includes(SKILLS_MARKER_START)) {
-    return;
-  }
-  const updated = existing.replace(new RegExp(`\\n?${SKILLS_MARKER_START}[\\s\\S]*?${SKILLS_MARKER_END}\\n?`), "").trimEnd();
-  await writeFile(claudeMdPath, updated ? updated + "\n" : "", "utf-8");
-}
-async function writeSkillsToClaudeCode() {
-  const claudeMdPath = join(homedir(), ".claude", "CLAUDE.md");
-  let existing = "";
-  try {
-    existing = await readFile(claudeMdPath, "utf-8");
-  } catch {
-  }
-  if (existing.includes(SKILLS_MARKER_START)) {
-    const updated = existing.replace(
-      new RegExp(`${SKILLS_MARKER_START}[\\s\\S]*?${SKILLS_MARKER_END}`),
-      SKILLS_BLOCK
-    );
-    await mkdir(dirname(claudeMdPath), { recursive: true });
-    await writeFile(claudeMdPath, updated, "utf-8");
-  } else {
-    await mkdir(dirname(claudeMdPath), { recursive: true });
-    await writeFile(claudeMdPath, existing + (existing.endsWith("\n") ? "" : "\n") + SKILLS_BLOCK + "\n", "utf-8");
-  }
-}
-function copyToClipboard(content) {
-  const cmd = platform() === "win32" ? "clip" : "pbcopy";
-  const result = spawnSync(cmd, [], { input: content });
-  return result.status === 0;
-}
-function printSkillsPasteGuide() {
-  const copied = copyToClipboard(SKILLS_COMBINED);
+import { homedir } from "os";
+async function printSkillsPasteGuide() {
+  const combined = await skillsCombined();
+  const copied = copyToClipboard(combined);
   console.log("");
   if (copied) {
     console.log("Plaud Skills copied to clipboard.");
@@ -63,13 +25,6 @@ function printSkillsPasteGuide() {
   console.log("  Claude Desktop: Settings \u2192 Profile \u2192 Custom Instructions");
   console.log("  Codex Desktop:  refer to client documentation");
 }
-function getMcpEntry() {
-  const __dirname = dirname(fileURLToPath(import.meta.url));
-  return {
-    command: process.execPath,
-    args: [join(__dirname, "index.js")]
-  };
-}
 function getConfigPath() {
   if (process.platform === "darwin") {
     return join(homedir(), "Library", "Application Support", "Claude", "claude_desktop_config.json");
@@ -105,10 +60,11 @@ async function runCleanPlugin() {
 async function runSetupCodex() {
   const configPath = join(homedir(), ".codex", "config.toml");
   const { command, args } = getMcpEntry();
+  const argsStr = args.map((a) => `"${a}"`).join(", ");
   const entry = `
 [mcp_servers.plaud]
 command = "${command}"
-args = ["${args[0]}"]
+args = [${argsStr}]
 `;
   let content = "";
   try {
@@ -126,7 +82,7 @@ args = ["${args[0]}"]
   console.log("Please restart Codex Desktop to complete the setup.");
   await writeSkillsToClaudeCode();
   console.log("Plaud Skills have been added to ~/.claude/CLAUDE.md for Claude Code.");
-  printSkillsPasteGuide();
+  await printSkillsPasteGuide();
   process.exit(0);
 }
 async function runUnsetupCodex() {
@@ -142,7 +98,7 @@ async function runUnsetupCodex() {
     console.log("Plaud is not configured in Codex Desktop. Nothing to remove.");
     return;
   }
-  const cleaned = content.replace(/\n*\[mcp_servers\.plaud\]\n(?:(?!\[)[^\n]*\n)*/g, "");
+  const cleaned = content.replace(/\[mcp_servers\.plaud\]\n(?:(?!\[)[^\n]*\n)*/g, "").replace(/\n{3,}/g, "\n\n");
   await writeFile(configPath, cleaned, "utf-8");
   await removeSkillsFromClaudeCode();
   console.log("Plaud has been removed from Codex Desktop.");
@@ -201,7 +157,7 @@ async function runSetup() {
   console.log("Please restart Claude Desktop to complete the setup.");
   await writeSkillsToClaudeCode();
   console.log("Plaud Skills have been added to ~/.claude/CLAUDE.md for Claude Code.");
-  printSkillsPasteGuide();
+  await printSkillsPasteGuide();
   process.exit(0);
 }
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plaud-ai/mcp",
-  "version": "0.1.32",
+  "version": "0.2.0",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
@@ -12,21 +12,28 @@
     ".mcp.json",
     "skills"
   ],
-  "scripts": {
-    "version:show": "node -p \"require('./package.json').version\"",
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "clean": "rm -rf dist",
-    "prepublishOnly": "node -e \"const fs=require('fs'),v=require('./package.json').version,p=JSON.parse(fs.readFileSync('./plugin.json','utf8'));p.version=v;fs.writeFileSync('./plugin.json',JSON.stringify(p,null,2)+'\\n');\""
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
+    "express": "^5.2.1",
     "open": "^10.2.0",
+    "pino": "^10.3.1",
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@plaud-ai/shared": "workspace:*",
+    "@types/express": "^5.0.6",
     "@types/node": "^25.5.0",
-    "typescript": "^5.7.0"
+    "typescript": "^5.7.0",
+    "@plaud-ai/shared": "0.1.0"
+  },
+  "scripts": {
+    "version:show": "node -p \"require('./package.json').version\"",
+    "prebuild": "node ../../scripts/sync-skills.mjs",
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "clean": "rm -rf dist skills"
   }
-}
+}

package/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "plaud",
-  "version": "0.1.32",
+  "version": "0.2.0",
   "description": "Access your Plaud recordings in Claude",
   "author": {
     "name": "Plaud AI"

package/skills/plaud-browse/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: plaud-browse
+version: 1.0.0
+description: "Browse, list, or paginate through Plaud recordings. Use when the user says 'what recordings do I have', 'show my recent recordings', 'list my recordings', or asks to see the most recent uploads."
+metadata:
+  requires:
+    bins: []
+---
+
+# plaud-browse
+
+**Read [`plaud-shared`](../plaud-shared/SKILL.md) first** for auth and output conventions.
+
+## When to use
+
+- User wants to see what is in their library without a specific target in mind.
+- User explicitly asks for a page, or says "next page", "more results".
+- User asks "what's the most recent recording" — fetch page 1 and return the top item.
+
+## Steps
+
+1. Call `list_files` with `page=1` and `page_size=20` (default). No `query` / `date_from` / `date_to` unless the user said something that matches `plaud-find`.
+2. Present results in a compact table: **ID**, **NAME**, **DATE** (`YYYY-MM-DD`), **DURATION** (`5m23s` style).
+3. If the page looks like the whole library (fewer than `page_size` returned), tell the user there is no next page.
+4. If the user asks for more, increment `page` by 1 and call again.
+
+## Anti-patterns
+
+- Do **not** fetch every page eagerly; pagination is lazy.
+- Do **not** call `get_note` or `get_transcript` during a browse — that belongs to `plaud-read` and burns tokens.
+- Do **not** expose raw timestamps or durations in milliseconds.
+
+## Example
+
+User: "show me my recordings"
+
+Agent:
+- `list_files(page=1, page_size=20)`
+- Render table, mention "page 1, say 'next page' for more"

package/skills/plaud-digest/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: plaud-digest
+version: 1.0.0
+description: "Summarize multiple Plaud recordings into a digest. Use when the user says 'weekly report', 'digest of this month', 'what meetings did I have this week', 'recap of last quarter', or asks to roll up multiple recordings into one overview."
+metadata:
+  requires:
+    bins: []
+---
+
+# plaud-digest
+
+**Read [`plaud-shared`](../plaud-shared/SKILL.md) first.**
+
+## When to use
+
+- User asks for a roll-up across multiple recordings.
+- Time window is explicit ("this week") or implicit ("recap of recent meetings").
+- Scope is "what happened", not "find one specific meeting" (that's `plaud-find`).
+
+## Steps
+
+1. **Resolve the window.** Use the date interpretation table in `plaud-find` for relative phrases.
+2. **List the corpus.** `list_files` with `date_from` / `date_to`. Cap at 50 recordings — if the window returns more, ask the user to narrow it.
+3. **Fetch notes in batch.** For each recording, call `get_note`. Do **not** call `get_transcript` unless a specific recording merits a deeper pull.
+4. **Synthesize.** Produce a structured digest:
+   - **Headline** — one-line theme of the window.
+   - **By recording** — one bullet per recording: `• name (date, duration) — one-sentence takeaway`.
+   - **Recurring themes** — topics that appeared in ≥ 2 recordings.
+   - **Open action items** — aggregated across recordings, deduplicated.
+5. **Cite sources.** Every non-trivial claim must reference the recording it came from, using the file name (not the raw ID unless the user asked).
+
+## Budget
+
+- Hard cap: 50 `get_note` calls per digest. If the window has more recordings, compress or ask user to narrow.
+- Skip recordings where `note_list` is empty — mention them at the end under "unsummarized".
+
+## Anti-patterns
+
+- Do not load transcripts just to pad the digest.
+- Do not synthesize across windows the user didn't ask for ("while we're at it, here's last month too").
+- Do not invent action items that aren't in the notes — only aggregate what's there.

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` |