From 8aab0c6a47f03fa482c00b0a3bdabfeef5834578 Mon Sep 17 00:00:00 2001 From: jason Date: Tue, 12 May 2026 18:50:34 -0500 Subject: [PATCH] =?UTF-8?q?docs:=20add=20SETUP.md=20=E2=80=94=20true=206-m?= =?UTF-8?q?onth=20token=20process,=20renewal=20commands,=20troubleshooting?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/SETUP.md | 185 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 185 insertions(+) create mode 100644 docs/SETUP.md diff --git a/docs/SETUP.md b/docs/SETUP.md new file mode 100644 index 0000000..53f5f4e --- /dev/null +++ b/docs/SETUP.md @@ -0,0 +1,185 @@ +# Plaud MCP Plugin — Setup & Renewal Guide + +**Version:** 0.1.2 +**Last updated:** 2026-05-12 + +This guide covers everything needed to set up the Plaud MCP plugin and keep it running. The old docx guide is superseded by this file. + +--- + +## Prerequisites + +- macOS (token decryption uses the macOS login keychain) +- [Plaud desktop app](https://www.plaud.ai/download) installed and logged in +- Python 3.10+ +- `uv` installed (`brew install uv` or `pip install uv`) +- Access to the Claude CoWork folder + +--- + +## How the Token Works + +The Plaud desktop app (Electron) stores a long-lived `authToken` JWT in the macOS keychain via Chromium's `safeStorage` API. This token is valid for approximately **6 months** and is the only reliable way to authenticate with the Plaud API from a script. + +There is no public OAuth flow. Web-based tokens (`wtToken`) expire in 24 hours and are not practical for an MCP server. + +**Token file:** `~/.plaud/tokens-mcp.json` +**Field used:** `access_token` +**Current expiry:** approximately 2026-11-25 + +--- + +## First-Time Setup + +### Step 1 — Ensure Plaud desktop app is installed and logged in + +Download from [plaud.ai/download](https://www.plaud.ai/download). Log in with your Plaud account. Let the app sync at least once so the token is written to the keychain. + +### Step 2 — Run the token extraction script + +From the Claude CoWork folder: + +```bash +cd ~/Library/CloudStorage/GoogleDrive-bryan@messagepoint.media/My\ Drive/Claude\ CoWork +python3 plaud_decrypt_tokens.py +``` + +Expected output: +``` +✅ Token written to /Users//.plaud/tokens-mcp.json + access_token: eyJ... (truncated) + Expires: ~2026-11-25 (estimated) +``` + +If you see an error about the keychain, make sure the Plaud desktop app has been run at least once while logged in, then try again. + +### Step 3 — Verify the token file + +```bash +cat ~/.plaud/tokens-mcp.json +``` + +Should contain: +```json +{ + "access_token": "eyJ..." +} +``` + +### Step 4 — Install the plugin in Claude CoWork + +Drop `plaud-mpm-v0.1.2.plugin` into Claude CoWork's plugin manager (Settings → Plugins → Install from file). The `.plugin` and `.dxt` files are identical zip archives — use whichever extension your Claude version accepts. + +### Step 5 — Verify the connection + +In Claude CoWork, ask: *"check my Plaud connection"* + +Or trigger `plaud_user_info` directly. You should see: +```json +{ + "region": "us", + "api_base": "https://api.plaud.ai", + "token_loaded": true +} +``` + +--- + +## Token Renewal + +Renew the token when it expires (~every 6 months) or if you see `token_loaded: false` or API auth errors. + +### Renewal steps + +1. **Open the Plaud desktop app** and make sure you are logged in. The app refreshes its internal token on login. + +2. **Close the Plaud desktop app** (quit it fully — not just minimize). This ensures the keychain entry is accessible. + +3. **Run the decryption script:** + +```bash +cd ~/Library/CloudStorage/GoogleDrive-bryan@messagepoint.media/My\ Drive/Claude\ CoWork +python3 plaud_decrypt_tokens.py +``` + +4. **Verify** the new token was written: + +```bash +cat ~/.plaud/tokens-mcp.json +``` + +5. **Restart Claude** (or reload the plugin) so the MCP server picks up the new token. + +No reinstall of the plugin is required — the server reads `tokens-mcp.json` fresh on every startup. + +--- + +## Environment Variable Override + +If you need to use a specific token without running the decryption script: + +```bash +export PLAUD_TOKEN="eyJ..." +``` + +Set this in `~/.zshrc` or your shell profile if you want it to persist. The environment variable takes priority over `tokens-mcp.json`. + +--- + +## Region Configuration + +The plugin defaults to the US API (`api.plaud.ai`). For EU accounts: + +```bash +export PLAUD_REGION=eu +``` + +This switches the base URL to `api.plaud.eu`. Set in the `.mcp.json` `env` block if you want it permanent: + +```json +{ + "mcpServers": { + "plaud-mpm": { + "command": "uv", + "args": ["run", "--with", "mcp[cli]", "${CLAUDE_PLUGIN_ROOT}/server/plaud_mcp.py"], + "env": { + "PLAUD_REGION": "eu" + } + } + } +} +``` + +--- + +## Troubleshooting + +### `token_loaded: false` +The token file is missing or empty. Run `plaud_decrypt_tokens.py` to regenerate it. + +### `invalid auth header` / API returning status -3900 +The token has expired. Follow the renewal steps above. + +### `Plaud Keys` not found in keychain +The Plaud desktop app hasn't been run on this machine, or was installed under a different user account. Log in to the desktop app, let it sync, then try the script again. + +### `curl exit 22` errors when fetching recordings +Usually an auth issue — verify `token_loaded: true` first. If token is loaded but you still get 22, the API may have rate-limited the request; wait 30 seconds and retry. + +### Plugin shows as `Plaud_MCP` vs `plaud-mpm` +Two registrations exist: the `.dxt` extension installs as `Plaud_MCP`; the `.plugin` file installs as `plaud-mpm`. Both use the same `plaud_mcp.py` server. Use whichever is currently active — they are functionally identical once running v0.1.2. + +--- + +## Uninstall / Clean Up + +```bash +# Remove token files +rm -rf ~/.plaud + +# Remove plugin from CoWork via Settings → Plugins → Remove +``` + +--- + +*Setup guide for Plaud MCP Plugin v0.1.2 — Message Point Media*