diff --git a/README.md b/README.md index f7abbca..5a93d14 100644 --- a/README.md +++ b/README.md @@ -1 +1,145 @@ -IyBwbGF1ZC1tcG0tcGx1Z2luCgpDb25uZWN0cyBDbGF1ZGUgdG8gUGxhdWQgcmVjb3JkaW5ncyDigJQgbGlzdCwgc2VhcmNoLCB0cmFuc2NyaXB0cywgc3VtbWFyaWVzLCBhbmQgQUkgbm90ZXMgZGlyZWN0bHkgaW4gQ29Xb3JrLgoKKipWZXJzaW9uOioqIDAuMS4yCioqQXV0aG9yOioqIE1lc3NhZ2UgUG9pbnQgTWVkaWEKKipSZXBvOioqIGh0dHBzOi8vZ2l0LmFsd2lzcC5jb20vamFzb24vcGxhdWQtbXBtLXBsdWdpbgoqKkNvV29yayBQcm9qZWN0OioqIENXLTAxMiDigJQgUGxhdWQgTUNQIFBsdWdpbgoKLS0tCgojIyBPdmVydmlldwoKVGhpcyBDb1dvcmsgcGx1Z2luIGdpdmVzIENsYXVkZSBkaXJlY3QgYWNjZXNzIHRvIEJyeWFuJ3MgUGxhdWQgdm9pY2UgcmVjb3JkaW5ncyB2aWEgdGhlIHVub2ZmaWNpYWwgUGxhdWQgQVBJLiBJdCBleHBvc2VzIDcgTUNQIHRvb2xzIGNvdmVyaW5nIGxpc3RpbmcsIHNlYXJjaGluZywgdHJhbnNjcmlwdHMsIHN1bW1hcmllcywgYW5kIEFJLWdlbmVyYXRlZCBub3Rlcy4gVGhlIHBsdWdpbiBydW5zIGFzIGEgUHl0aG9uIEZhc3RNQ1Agc3RkaW8gc2VydmVyIGxhdW5jaGVkIGJ5IGB1dmAg4oCUIG5vIGFkZGl0aW9uYWwgcnVudGltZSBkZXBlbmRlbmNpZXMgYmV5b25kIGBtY3BbY2xpXWAuCgpBdXRoZW50aWNhdGlvbiB1c2VzIHRoZSBQbGF1ZCBkZXNrdG9wIGFwcCdzIGxvbmctbGl2ZWQgYGF1dGhUb2tlbmAgSldUICh+NiBtb250aHMpLCBleHRyYWN0ZWQgZnJvbSBFbGVjdHJvbiBzYWZlU3RvcmFnZSB2aWEgYHBsYXVkX2RlY3J5cHRfdG9rZW5zLnB5YC4gTm8gbWFudWFsIHRva2VuIGh1bnRpbmcgaW4gYnJvd3NlciBEZXZUb29scyByZXF1aXJlZC4KCi0tLQoKIyMgQXV0aGVudGljYXRpb24KCiMjIyBIb3cgaXQgd29ya3MKClRoZSBQbGF1ZCBkZXNrdG9wIGFwcCBzdG9yZXMgdGhyZWUgdG9rZW4gdHlwZXMgaW4gQ2hyb21pdW0gdjEwIEVsZWN0cm9uIHNhZmVTdG9yYWdlIChgfi9MaWJyYXJ5L0FwcGxpY2F0aW9uIFN1cHBvcnQvUGxhdWQvZW5jcnlwdGlvbi5qc29uYCk6Cgp8IFRva2VuIHwgVHlwZSB8IExpZmV0aW1lIHwgVXNlZCBmb3IgfAp8LS0tfC0tLXwtLS18LS0tfAp8IGBhdXRoVG9rZW5gIHwgU3RhbmRhcmQgSldUIHwgKip+NiBtb250aHMqKiB8IOKchSBBUEkgY2FsbHMgKGBhcGkucGxhdWQuYWlgKSB8CnwgYHd0VG9rZW5gIHwgUGxhdWQgV0pUIHwgfjI0IGhvdXJzIHwgSW50ZXJuYWwgd2ViIHNlc3Npb25zIG9ubHkgfAp8IGB3cnRUb2tlbmAgfCBQbGF1ZCBXUlQgfCB+MzAgZGF5cyB8IFdvcmtzcGFjZSByZWZyZXNoIChub3QgT0F1dGgtY29tcGF0aWJsZSkgfAoKVGhlIE1DUCBzZXJ2ZXIgcmVhZHMgYGF1dGhUb2tlbmAg4oCUIHRoZSBvbmx5IHRva2VuIHRoYXQgd29ya3Mgd2l0aCB0aGUgQVBJIGxvbmctdGVybS4KCiMjIyBUb2tlbiByZXNvbHV0aW9uIG9yZGVyCgpgcGxhdWRfbWNwLnB5YCBjaGVja3MgY3JlZGVudGlhbHMgaW4gdGhpcyBwcmlvcml0eToKCjEuIGBQTEFVRF9UT0tFTmAgZW52aXJvbm1lbnQgdmFyaWFibGUgKG1hbnVhbCBvdmVycmlkZSkKMi4gYH4vLnBsYXVkL3Rva2Vucy1tY3AuanNvbmAg4oaSIGBhY2Nlc3NfdG9rZW5gIGZpZWxkIOKGkCAqKnByaW1hcnk7IH42LW1vbnRoIGxpZmV0aW1lKioKMy4gYH4vLnBsYXVkL2NvbmZpZy5qc29uYCDihpIgYHRva2VuLnRva2VuYCBmaWVsZCAobGVnYWN5IGZhbGxiYWNrKQoKIyMjIFNldHVwIOKAlCBvbmUtdGltZSB0b2tlbiBleHRyYWN0aW9uCgpgcGxhdWRfZGVjcnlwdF90b2tlbnMucHlgIChzYXZlZCBpbiB5b3VyIENsYXVkZSBDb1dvcmsgZm9sZGVyKSBkZWNyeXB0cyB0aGUgZGVza3RvcCBhcHAgdG9rZW5zIHVzaW5nIHRoZSBtYWNPUyBLZXljaGFpbiBwYXNzd29yZCBhbmQgc2F2ZXMgdGhlbSB0byBgfi8ucGxhdWQvdG9rZW5zLW1jcC5qc29uYC4KCioqUHJlcmVxdWlzaXRlczoqKiBQbGF1ZCBkZXNrdG9wIGFwcCBpbnN0YWxsZWQgYW5kIGxvZ2dlZCBpbi4gUHl0aG9uICsgYHB5Y3J5cHRvZG9tZWAuCgpgYGBiYXNoCiMgSW5zdGFsbCBjcnlwdG8gbGlicmFyeSAoZmlyc3QgdGltZSBvbmx5KQpwaXAgaW5zdGFsbCBweWNyeXB0b2RvbWUKCiMgUnVuIGZyb20gQ2xhdWRlIENvV29yayBmb2xkZXIKcHl0aG9uMyBwbGF1ZF9kZWNyeXB0X3Rva2Vucy5weQpgYGAKCkV4cGVjdGVkIG91dHB1dDoKYGBgCmF1dGhUb2tlbiBleHBpcmVzIDogMjAyNi0xMS0yNQrinJMgQVBJIHRlc3QgcGFzc2VkIOKAlCA1IHNlc3Npb25zIGZvdW5kLgrinJMgU2F2ZWQgdG8gL1VzZXJzLzx5b3U+Ly5wbGF1ZC90b2tlbnMtbWNwLmpzb24KICBOZXh0IHJlbmV3YWw6IDIwMjYtMTEtMjUKYGBgCgojIyMgVG9rZW4gcmVuZXdhbAoKKipOZXh0IHJlbmV3YWwgZGF0ZTogMjAyNi0xMS0yNSoqCgpXaGVuIHRoZSB0b2tlbiBleHBpcmVzLCByZS1ydW4gYHBsYXVkX2RlY3J5cHRfdG9rZW5zLnB5YCBmcm9tIHRoZSBDbGF1ZGUgQ29Xb3JrIGZvbGRlci4gVGhlIHNjcmlwdCB3aWxsIHJlLWRlY3J5cHQgdGhlIGRlc2t0b3AgYXBwJ3MgcmVmcmVzaGVkIHRva2VuIGFuZCBvdmVyd3JpdGUgYHRva2Vucy1tY3AuanNvbmAgYXV0b21hdGljYWxseS4KCiMjIyBIb3cgdGhlIGRlY3J5cHRpb24gd29ya3MgKHRlY2huaWNhbCkKCkVsZWN0cm9uIHNhZmVTdG9yYWdlIG9uIG1hY09TIHVzZXMgQ2hyb21pdW0ncyB2MTAgZm9ybWF0OgotIEVuY3J5cHRpb246IEFFUy0xMjgtQ0JDCi0gS2V5IGRlcml2YXRpb246IFBCS0RGMi1TSEExKGBrZXljaGFpbl9wYXNzd29yZGAsIHNhbHQ9YHNhbHR5c2FsdGAsIGl0ZXJhdGlvbnM9MTAwMywga2V5X2xlbj0xNikKLSBJVjogMTYgc3BhY2UgYnl0ZXMKLSBDaXBoZXJ0ZXh0OiBiYXNlNjQtZW5jb2RlZCwgcHJlZml4ZWQgd2l0aCBgdjEwYAotIEtleWNoYWluIHNlcnZpY2U6IGAiUGxhdWQgU2FmZSBTdG9yYWdlImAKClRoZSBgYXV0aFRva2VuYCBmaWVsZCBkZWNyeXB0cyB0byBhIHN0YW5kYXJkIGAiYmVhcmVyIGV5Si4uLiJgIEpXVC4gVGhlIHNjcmlwdCBzdHJpcHMgdGhlIHByZWZpeCBhbmQgc2F2ZXMgdGhlIHJhdyBKV1QgYXMgYGFjY2Vzc190b2tlbmAgaW4gYHRva2Vucy1tY3AuanNvbmAuCgojIyMgV2h5IG5vdCBPQXV0aD8KClRoZSBQbGF1ZCBDTEkncyBPQXV0aCBmbG93IChgcGxhdGZvcm0ucGxhdWQuYWkvZGV2ZWxvcGVyL2FwaS9vYXV0aGApIHJlcXVpcmVzIGEgY2xpZW50IHNlY3JldCB0aGF0IGlzIG5vdCBidW5kbGVkIGluIHRoZSBvcGVuLXNvdXJjZSBjb25uZWN0b3IgcGFja2FnZS4gTm9kZS5qcyBgZmV0Y2goKWAgaXMgYWxzbyBibG9ja2VkIGJ5IENsb3VkZmxhcmUgb24gYHBsYXRmb3JtLnBsYXVkLmFpYC4gVGhlIEVsZWN0cm9uIHNhZmVTdG9yYWdlIGFwcHJvYWNoIGlzIG1vcmUgcmVsaWFibGUgYW5kIGxvbmdlci1saXZlZC4KCi0tLQoKIyMgTUNQIFRvb2xzICg3KQoKfCBUb29sIHwgRGVzY3JpcHRpb24gfAp8LS0tfC0tLXwKfCBgcGxhdWRfbGlzdF9yZWNvcmRpbmdzYCB8IExpc3QgYWxsIHJlY29yZGluZ3MgbmV3ZXN0LWZpcnN0LiBQYXJhbXM6IGBsaW1pdGAsIGBvbmx5X3dpdGhfdHJhbnNjcmlwdGAuIHwKfCBgcGxhdWRfc2VhcmNoX3JlY29yZGluZ3NgIHwgRmlsdGVyIGJ5IGB0aXRsZV9jb250YWluc2AsIGBzdGFydF9kYXRlYCwgYGVuZF9kYXRlYCwgYG9ubHlfd2l0aF90cmFuc2NyaXB0YC4gfAp8IGBwbGF1ZF9nZXRfdHJhbnNjcmlwdGAgfCBGdWxsIHRyYW5zY3JpcHQgdGV4dCBmb3IgYSByZWNvcmRpbmcgSUQuIHwKfCBgcGxhdWRfZ2V0X3N1bW1hcnlgIHwgQUktZ2VuZXJhdGVkIHN1bW1hcnkgZm9yIGEgcmVjb3JkaW5nIElELiB8CnwgYHBsYXVkX2dldF9ub3Rlc2AgfCBBSSBub3RlcyBhbmQgYWN0aW9uIGl0ZW1zIChjb250ZW50X2xpc3QpIGZvciBhIHJlY29yZGluZyBJRC4gfAp8IGBwbGF1ZF9nZXRfcmVjb3JkaW5nX2RldGFpbGAgfCBGdWxsIG1ldGFkYXRhOiB0aXRsZSwgZGF0ZSwgZHVyYXRpb24sIGZsYWdzLCBkZXZpY2UsIHRhZ3MuIHwKfCBgcGxhdWRfdXNlcl9pbmZvYCB8IEFjY291bnQgaW5mbyBhbmQgY29ubmVjdGlvbiBzdGF0dXMuIHwKCi0tLQoKIyMgU2tpbGxzCgp8IFNraWxsIHwgVHJpZ2dlciBwaHJhc2VzIHwKfC0tLXwtLS18CnwgYHBsYXVkYCB8ICJwdWxsIHRoZSB0cmFuc2NyaXB0IiwgIndoYXQgd2FzIGRpc2N1c3NlZCBpbiBteSBsYXN0IG1lZXRpbmciLCAic2VhcmNoIG15IFBsYXVkIHJlY29yZGluZ3MiLCAic2hvdyBtZSBhY3Rpb24gaXRlbXMgZnJvbSBbbWVldGluZ10iLCAibWVldGluZyB0cmFuc2NyaXB0IiwgIm1lZXRpbmcgc3VtbWFyeSIsICJ2b2ljZSBub3RlcyIgfAoKLS0tCgojIyBEZXBlbmRlbmNpZXMKCi0gYG1jcFtjbGldYCAodmlhIGB1diBydW4gLS13aXRoIG1jcFtjbGldYCkg4oCUIEZhc3RNQ1Agc2VydmVyIGZyYW1ld29yawotIGBweWNyeXB0b2RvbWVgIOKAlCBmb3IgYHBsYXVkX2RlY3J5cHRfdG9rZW5zLnB5YCBvbmx5IChub3QgbmVlZGVkIGF0IHJ1bnRpbWUpCi0gUHl0aG9uIHN0ZGxpYiBvbmx5IGF0IHJ1bnRpbWUgKGB1cmxsaWJgLCBgZ3ppcGAsIGBzdWJwcm9jZXNzYCkKCi0tLQoKIyMgUmVnaW9uCgpVUyByZWdpb24gKGBhcGkucGxhdWQuYWlgKS4gU2V0IGBQTEFVRF9SRUdJT049ZXVgIGVudiB2YXIgdG8gc3dpdGNoIHRvIEVVIChgYXBpLnBsYXVkLmV1YCkuCgotLS0KCiMjIEZpbGUgU3RydWN0dXJlCgpgYGAKcGxhdWQtbXBtLXBsdWdpbi8K4pSc4pSA4pSAIC5jbGF1ZGUtcGx1Z2luLwrilIIgICDilJTilIDilIAgcGx1Z2luLmpzb24gICAgICAgICAgICAgICMgUGx1Z2luIG1ldGFkYXRhCuKUnOKUgOKUgCAubWNwLmpzb24gICAgICAgICAgICAgICAgICAgICMgTUNQIHNlcnZlciBjb25maWcgKHV2ICsgcGxhdWRfbWNwLnB5KQrilJzilIDilIAgc2VydmVyLwrilIIgICDilJTilIDilIAgcGxhdWRfbWNwLnB5ICAgICAgICAgICAgICMgRmFzdE1DUCBzZXJ2ZXIg4oCUIDcgdG9vbHMK4pSc4pSA4pSAIHNraWxscy8K4pSCICAgIuKUlOKUgOKUgCBwbGF1ZC8K4pSCICAgICAgIOKUlOKUgOKUgCBTS0lMTC5tZCAgICAgICAgICAgICMgU2tpbGwgZGVmaW5pdGlvbiBhbmQgd29ya2Zsb3cgZ3VpZGFuY2UK4pSc4pSA4pSAIGRvY3MvCuKUgiAgIOKUlOKUgOKUgCBQbGF1ZF9NQ1BfU2V0dXBfR3VpZGUuZG9jeCAgIyBGdWxsIHNldHVwIGd1aWRlIChXb3JkKQrilJTilIDilIAgUkVBRE1FLm1kCmBgYAoKKipSdW50aW1lIGZpbGVzIChvbiBob3N0IG1hY2hpbmUsIG5vdCBpbiByZXBvKToqKgpgYGAKfi8ucGxhdWQvdG9rZW5zLW1jcC5qc29uICAgICAgICAgIyBMb25nLWxpdmVkIHRva2VuICh+NiBtb250aHMpIOKAlCB3cml0dGVuIGJ5IGRlY3J5cHQgc2NyaXB0Cn4vQ2xhdWRlIENvV29yay8K4pSU4pSA4pSAIHBsYXVkX2RlY3J5cHRfdG9rZW5zLnB5ICAgICAgIyBUb2tlbiBleHRyYWN0aW9uIHNjcmlwdCDigJQgcnVuIHRvIHJlbmV3CmBgYAoKLS0tCgojIyBDaGFuZ2Vsb2cKCnwgVmVyc2lvbiB8IERhdGUgfCBDaGFuZ2UgfAp8LS0tfC0tLXwtLS18CnwgMC4xLjIgfCAyMDI2LTA1LTEyIHwgU3dpdGNoZWQgdG8gRWxlY3Ryb24gc2FmZVN0b3JhZ2UgYXV0aFRva2VuICh+Ni1tb250aCBsaWZldGltZSkuIEFkZGVkIHBsYXVkX2RlY3J5cHRfdG9rZW5zLnB5IHJlbmV3YWwgd29ya2Zsb3cuIHwKfCAwLjEuMSB8IDIwMjYtMDUtMTIgfCBBZGRlZCBwbGF1ZF9nZXRfcmVjb3JkaW5nX2RldGFpbCB0b29sLCBjdXJsLWJhc2VkIEhUVFAgdG8gYnlwYXNzIENsb3VkZmxhcmUuIHwKfCAwLjEuMCB8IDIwMjYtMDUtMTEgfCBJbml0aWFsIHJlbGVhc2Ug4oCUIDcgdG9vbHMsIEZhc3RNQ1Agc3RkaW8gc2VydmVyLiB8Cg== \ No newline at end of file +# Plaud MCP Plugin for MPM + +Connects Claude (CoWork / Claude desktop) to your Plaud recordings — list, search, transcripts, AI summaries, and meeting notes directly in CoWork. + +**Version:** 0.1.2 +**Author:** Message Point Media +**Repo:** [git.alwisp.com/jason/plaud-mpm-plugin](https://git.alwisp.com/jason/plaud-mpm-plugin) + +--- + +## How Authentication Works + +Plaud does not offer a public OAuth API. The plugin authenticates using the long-lived `authToken` JWT that the Plaud desktop app stores in Electron's encrypted `safeStorage` (Chromium v10 AES-128-CBC, key derived from the macOS login keychain). + +### Token types + +| Token | Lifetime | Source | Used by plugin | +|---|---|---|---| +| `authToken` | ~6 months | Electron safeStorage | ✅ Primary | +| `wrtToken` | ~30 days | Electron safeStorage | No | +| `wtToken` | ~24 hours | Plaud web browser | Legacy fallback | + +### Resolution order + +The server checks credentials in this order at every startup: + +1. `PLAUD_TOKEN` environment variable (override) +2. `~/.plaud/tokens-mcp.json` → `access_token` field ← **normal path** +3. `~/.plaud/config.json` → `token` field (legacy 24-hour web token) + +### How `tokens-mcp.json` gets written + +Run `plaud_decrypt_tokens.py` (in the Claude CoWork folder). It: + +1. Reads the Chromium encrypted token store from `~/Library/Application Support/Plaud/` +2. Derives the AES key from the macOS login keychain entry `Plaud Keys` +3. Decrypts the `authToken` JWT +4. Writes `~/.plaud/tokens-mcp.json` with `access_token` set to that JWT + +### Why not OAuth? + +Plaud's API sits behind Cloudflare with browser-fingerprint checks that block standard HTTP clients. The `authToken` from the desktop app bypasses this because it is a long-lived JWT accepted directly by `api.plaud.ai` without browser validation. + +--- + +## Token Renewal + +The `authToken` expires approximately every **6 months**. Current token expires: **~2026-11-25**. + +**To renew:** + +```bash +# From the Claude CoWork folder (or wherever plaud_decrypt_tokens.py lives): +cd ~/Library/CloudStorage/GoogleDrive-bryan@messagepoint.media/My\ Drive/Claude\ CoWork +python3 plaud_decrypt_tokens.py +``` + +This re-reads the Plaud desktop app's current token from Electron safeStorage and overwrites `~/.plaud/tokens-mcp.json`. The plugin picks it up automatically on next restart — no reinstall required. + +**Prerequisites for renewal:** +- Plaud desktop app must be installed and you must be logged in +- Run the script while the desktop app is not actively running (or has been closed long enough for the keychain to be accessible) +- macOS only (the decryption uses the macOS login keychain) + +**Verify the token is loaded:** + +Ask Claude: *"check plaud connection"* — or use the `plaud_user_info` tool directly. It returns `token_loaded: true` if the token was found. + +--- + +## Installation + +### Plugin file (Claude CoWork) + +The plugin ships as a `.plugin` zip archive. Install by dropping it into Claude CoWork's plugin manager: + +``` +Claude CoWork/plugins/plaud-mpm-v0.1.2.plugin +``` + +The `.dxt` extension (used by Claude desktop's extension system) is identical — same zip format, different extension. + +### First-time setup + +1. Install the Plaud desktop app and log in +2. Run `python3 plaud_decrypt_tokens.py` from the CoWork folder +3. Confirm `~/.plaud/tokens-mcp.json` was created +4. Install `plaud-mpm-v0.1.2.plugin` in Claude CoWork +5. Ask Claude *"list my recent Plaud recordings"* to verify + +--- + +## Available Tools + +| Tool | Description | +|---|---| +| `plaud_list_recordings` | List recordings newest-first (limit, transcript filter) | +| `plaud_search_recordings` | Search by title and/or date range | +| `plaud_get_transcript` | Full transcript (polished → raw fallback) | +| `plaud_get_summary` | AI summary (`auto_sum_note` → outline fallback) | +| `plaud_get_notes` | All AI-generated note types from `content_list` | +| `plaud_get_recording_detail` | Full metadata including available content types | +| `plaud_user_info` | Connection status and token check | + +### Summary content types + +`plaud_get_summary` returns a `summary_type` field: + +- `auto_sum_note` — rich AI meeting notes (Meeting Information, Meeting Notes, Next Arrangements, AI Suggestions). This is what appears in the Plaud web UI "Summary" tab. +- `outline` — timestamped topic list (fallback when AI summary is unavailable) +- `none` — no summary content available + +--- + +## File Structure + +``` +.claude-plugin/plugin.json Plugin metadata +.mcp.json MCP server registration (uv runner) +server/plaud_mcp.py MCP server (FastMCP, stdio) +skills/plaud/SKILL.md Skill trigger rules for Claude +docs/SETUP.md Full setup and renewal guide +dist/plaud-mpm-v0.1.2.plugin Installable plugin package +``` + +--- + +## Changelog + +### 0.1.2 — 2026-05-12 +- **Fix:** `plaud_get_summary` now checks `auto_sum_note` (rich AI meeting notes) before `outline`. Previously only returned the timestamped topic outline. +- **Fix:** Added `_fetch_s3_text()` helper — `auto_sum_note` content is HTML/Markdown, not JSON. The old `_fetch_s3_json()` call returned empty results. +- **Fix:** `plaud_get_recording_detail` `has_summary` now checks both `auto_sum_note` and `outline`. +- **Fix:** `plaud_get_notes` routes `auto_sum_note` through `_fetch_s3_text()` instead of `_fetch_s3_json()`. +- `plaud_get_summary` response now includes `summary_type` field. +- README and setup guide rewritten to reflect true auth process. + +### 0.1.1 — 2026-05-12 +- Added `_fetch_s3_text()` stub (incomplete — superseded by 0.1.2) +- README rewrite (first pass) + +### 0.1.0 — 2026-05-11 +- Initial release +- Token decryption via `plaud_decrypt_tokens.py` +- Tools: list, search, transcript, summary (outline only), notes, detail, user info