@joe-broadhead/opencode-wisprflow 0.0.0-stage → 0.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md ADDED
@@ -0,0 +1,28 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
4
+
5
+ ## [0.0.0] - 2026-11-05
6
+
7
+ ### Added
8
+
9
+ - Wispr Flow's official MCP server, registered under the name `wisprflow` at `https://api.wisprflow.ai/connect/mcp`.
10
+ OpenCode signs in with its own MCP OAuth: run `/connect` and choose Wispr Flow. The `/connect` entry is named
11
+ "Wispr Flow", and its account is marked "Sign in required" when the sign-in needs renewing.
12
+ - Your own `mcp.servers.wisprflow` at exactly that URL is adopted unchanged. Any other URL, the same one with a
13
+ trailing slash included, is a conflict, which status reports with its fix.
14
+ - Default permission rules after each agent's base allow: every Wispr Flow tool asks, and the 15 read tools Wispr
15
+ Flow lists for every account run without a prompt. `get_participant_contacts`, listed only for accounts with Wispr
16
+ Contacts, asks, because it returns other people's profiles. A tool Wispr Flow adds later asks.
17
+ - `/wisprflow-status`, and the `/wisprflow` dialog ("Wispr Flow: Status" in the command palette): connection,
18
+ account, access, skills, tools, agents without the default rules, the OpenCode check and one next step. Status
19
+ names a skill of yours that takes the place of the plugin's own, and says when Wispr Flow lists no tools for the
20
+ account. The status RPC `wisprflow.meetings` returns the same model.
21
+ - Two skills: `wisprflow`, for finding, reading and citing meetings, transcripts, Scratchpad notes and calendar events,
22
+ and for saying what the connection can't read; and `wisprflow-meeting-brief`, for a sourced brief before a meeting
23
+ or a recap of a period's meetings.
24
+ - The tools RPC `wisprflow.meetings.tools`: a script calls the 15 known reads with no model, as a session and its
25
+ agent.
26
+ - The option `allowUntestedHost`. The plugin starts on OpenCode `>=2.2.3 <2.3.0`, tested on 2.2.3, 2.2.4 and 2.2.5.
27
+ - A `jelly` declaration for Jelly: the 16 known tools, `get_participant_contacts` as an ask, the skills, the sign-in, a
28
+ summary and a neutral icon.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Joe Broadhead
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,208 @@
1
- # Temporary Holding Version
1
+ # Wispr Flow for OpenCode
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Search and read your Wispr Flow Notetaker meetings, transcripts, Scratchpad notes and calendar in OpenCode, through
4
+ Wispr Flow's official MCP server.
5
+
6
+ Unofficial; not affiliated with Wispr Flow.
7
+
8
+ ## Requirements
9
+
10
+ - OpenCode `>=2.2.3 <2.3.0`, tested on 2.2.3, 2.2.4 and 2.2.5. Outside that range the plugin does not start, unless
11
+ you set `allowUntestedHost`.
12
+ - macOS or Linux.
13
+ - A Wispr Flow account with Notetaker and MCP access; the free plan includes it. The Wispr Flow app on Mac or Windows
14
+ records the meetings, and OpenCode can run on another machine.
15
+ - **Cloud Sync** (Dictation cloud storage, in Wispr Flow's Settings → Data & Privacy) turned on, for meetings and the
16
+ calendar. Scratchpad works without it.
17
+ - Not available on accounts with a HIPAA agreement. Organisation admins can turn Wispr Flow's MCP, or Scratchpad, off.
18
+ - Wispr Flow processes your data in the United States.
19
+
20
+ What Wispr Flow's server can't read: dictation history, the dictionary, snippets, styles and usage. No tool takes
21
+ audio, and no tool changes anything in Wispr Flow. One tool, `get_participant_contacts`, asks before it runs: see
22
+ [Permissions](#permissions).
23
+
24
+ ## Install
25
+
26
+ ```sh
27
+ opencode plugin add @joe-broadhead/opencode-wisprflow
28
+ ```
29
+
30
+ Run `opencode reload`, or restart OpenCode. Then run `/wisprflow-status`: it shows `sign-in required` until you sign
31
+ in (see [Sign in](#sign-in)).
32
+
33
+ The plugin registers Wispr Flow's MCP server under the name `wisprflow`, adds default permission rules, the
34
+ `/wisprflow-status` command, the `/wisprflow` status view and two skills. Every tool is Wispr Flow's, and OpenCode
35
+ handles the connection, the sign-in and the stored credentials.
36
+
37
+ **Update** with `opencode plugin update @joe-broadhead/opencode-wisprflow`, then run `opencode reload`. An entry
38
+ pinned to a version does not update: remove the `@version` from its `plugins` entry first.
39
+
40
+ ## Sign in
41
+
42
+ Run `/connect` and choose **Wispr Flow** (it is listed under MCP). In the terminal UI, press `o` or Enter to open the
43
+ link to Wispr Flow's sign-in page in your browser. Sign in with the Wispr Flow account that holds the notes: personal
44
+ and work accounts are separate. With Google, Apple, Microsoft or single sign-on, finish within 5 minutes.
45
+
46
+ From a terminal, run `opencode mcp auth wisprflow` instead; it opens the link automatically. `/mcps` also offers the
47
+ same sign-in.
48
+
49
+ The sign-in covers every meeting, past ones included. There is nothing to configure, and Wispr Flow has no API key.
50
+
51
+ When the sign-in expires and cannot be renewed, `/connect` marks the Wispr Flow account as needing a new sign-in, and
52
+ OpenCode shows its "MCP server needs authentication" notice.
53
+
54
+ To sign out, or to switch account, run `opencode mcp logout wisprflow`, or remove the account in `/connect` →
55
+ Wispr Flow. Then sign in again. Wispr Flow itself has no disconnect control. To sign out before you remove the
56
+ plugin, see [Uninstall](#uninstall).
57
+
58
+ ## Use
59
+
60
+ Ask, for example:
61
+
62
+ - "In Wispr Flow, what did we decide in yesterday's pricing call?"
63
+ - "Prep me for my next meeting using Wispr Flow."
64
+ - "Find my Wispr Scratchpad note about the hiring plan and summarise it."
65
+ - "What's this meeting?" with a Google Calendar, Meet or Zoom link pasted, or a notes.wisprflow.ai share link.
66
+
67
+ | Command | What it does |
68
+ | --- | --- |
69
+ | `/wisprflow-status` | Posts the status report into the session: connection, account, access, skills, tools, agents without the default rules, the OpenCode check and the next step. The model can read it too. |
70
+ | `/wisprflow`, or "Wispr Flow: Status" in the command palette | Opens the same report in a dialog. Press `r` to refresh it and `Esc` to close it. It also refreshes when Wispr Flow's connection, the sign-in or the agents change. |
71
+
72
+ Two skills teach the model to use Wispr Flow well:
73
+
74
+ - `wisprflow`: which tool to use, local days turned into UTC windows, reading transcripts for what was said (search
75
+ finds meetings, not transcript words), paging, labelling Wispr Flow's summaries, citing share links, keeping
76
+ secrets and other people's details out of answers, and what the connection can't read.
77
+ - `wisprflow-meeting-brief`: a sourced brief before a meeting, from the upcoming event, its pre-read and earlier
78
+ meetings, or a recap of a period's meetings.
79
+
80
+ ### Scripts
81
+
82
+ A script or a cron job can call Wispr Flow's read tools with no model, through `opencode api`. It runs as a session
83
+ and its agent, under that agent's permission rules and the session's own:
84
+
85
+ ```sh
86
+ opencode api post /api/rpc/wisprflow.meetings.tools/search_meetings \
87
+ -d '{"input":{"sessionID":"ses_…","input":{"query":"pricing","since":"2026-03-01T00:00:00Z"}}}'
88
+ ```
89
+
90
+ See [Scripting](https://github.com/joe-broadhead/opencode-wisprflow/blob/HEAD/docs/scripting.md).
91
+
92
+ ## Permissions
93
+
94
+ The plugin adds these rules to every agent, directly after the agent's base rule that allows everything:
95
+
96
+ 1. `{ "action": "wisprflow_*", "resource": "*", "effect": "ask" }`: every Wispr Flow tool asks, including tools Wispr
97
+ Flow adds later.
98
+ 2. One `allow` rule for each of the 15 read tools Wispr Flow lists for every account, listed in
99
+ [`src/wisprflow-tools.ts`](https://github.com/joe-broadhead/opencode-wisprflow/blob/HEAD/src/wisprflow-tools.ts).
100
+ These run without a prompt.
101
+ 3. `{ "action": "wisprflow_get_participant_contacts", "resource": "*", "effect": "ask" }`: Wispr Flow lists this tool
102
+ only for accounts with Wispr Contacts. It returns other people's job titles, companies and LinkedIn profiles, so it
103
+ asks, although it only reads.
104
+
105
+ No Wispr Flow tool changes anything. A tool Wispr Flow adds later asks until the plugin knows it. Everything that comes later than these rules still wins: an agent's own stricter rules
106
+ (Explore cannot use Wispr Flow), your `permissions` in `opencode.json`, and your saved "Always allow" answers. To make
107
+ a read ask, add a later rule for it, such as `{ "action": "wisprflow_get_meeting", "resource": "*", "effect": "ask" }`.
108
+ In an unattended run such as `opencode run`, a tool that asks is refused.
109
+
110
+ Agents that exist only in your own config, and agents added by plugins that load later, are created after the plugin
111
+ adds its rules, so Wispr Flow tools run there without asking. `/wisprflow-status` and `/wisprflow` name those agents
112
+ and show the default rules to put first in each one's own `permissions`. Do not put them in the top-level
113
+ `permissions`, which would loosen Explore.
114
+ [Configuration](https://github.com/joe-broadhead/opencode-wisprflow/blob/HEAD/docs/configuration.md#permissions) has a
115
+ worked example and permission recipes.
116
+
117
+ ## Configure
118
+
119
+ Set options with the object form of the plugin entry:
120
+
121
+ ```json
122
+ {
123
+ "plugins": [{ "package": "@joe-broadhead/opencode-wisprflow", "options": { "allowUntestedHost": true } }]
124
+ }
125
+ ```
126
+
127
+ | Option | Values | Default | Effect |
128
+ | --- | --- | --- | --- |
129
+ | `allowUntestedHost` | `true` or `false` | `false` | Starts on an OpenCode version outside `>=2.2.3 <2.3.0`, with a warning in status. |
130
+
131
+ [docs/configuration.md](https://github.com/joe-broadhead/opencode-wisprflow/blob/HEAD/docs/configuration.md) has the
132
+ details, including your own `mcp.servers.wisprflow` entry, permission recipes and every error.
133
+
134
+ ## Organisation rollout
135
+
136
+ OpenCode registers itself with Wispr Flow's server automatically, so there is no client ID to distribute. Put the
137
+ plugin entry in the system config: `/Library/Application Support/opencode/opencode.json` on macOS, or
138
+ `/etc/opencode/opencode.json` on Linux.
139
+
140
+ ```json
141
+ {
142
+ "plugins": ["@joe-broadhead/opencode-wisprflow"]
143
+ }
144
+ ```
145
+
146
+ Members then only sign in: run `/connect` and choose Wispr Flow, then press `o` or Enter to open the link. To pin the
147
+ permissions, add your rules for `wisprflow_*` tools to the same file. Whether members may use Wispr Flow's MCP at
148
+ all, and Scratchpad through it, is set in Wispr Flow's admin portal.
149
+
150
+ ## Troubleshooting
151
+
152
+ Run `/wisprflow-status` first. Its last line is the next step.
153
+
154
+ | Status or error | What to do |
155
+ | --- | --- |
156
+ | Connection: sign-in required | Run `/connect` and choose Wispr Flow, then press `o` or Enter to open the link. In a terminal, `opencode mcp auth wisprflow` opens it automatically. |
157
+ | Connection: connecting | Wait a few seconds, then run `/wisprflow-status` again. |
158
+ | Connection: failed | Check your network, then run `/wisprflow-status` again. |
159
+ | Connection: disabled | Enable `wisprflow` in `/mcps`, or remove `"disabled": true` from `mcp.servers.wisprflow` in `opencode.json`. |
160
+ | Connection: not configured | An organisation policy (`mcp.use`) or another plugin removes the `wisprflow` server. Ask your administrator, then restart OpenCode. |
161
+ | Connection: conflict | Your config has an `mcp.servers.wisprflow` entry with a URL other than the plugin's, `https://api.wisprflow.ai/connect/mcp`. Point it there or remove it, then restart OpenCode. |
162
+ | Sign-in never starts | Your own `mcp.servers.wisprflow` URL ends with a slash. Wispr Flow's sign-in needs `https://api.wisprflow.ai/connect/mcp` exactly; status reports this as a conflict. |
163
+ | Wispr Flow's sign-in page doesn't return you to OpenCode | See Wispr Flow's help on [connecting an MCP client](https://docs.wisprflow.ai/articles/9551372685-connect-an-mcp-client-to-wispr-flow-remote-mcp-server), then run `/connect` and choose Wispr Flow again. |
164
+ | Tools: 0 available, while connected | Wispr Flow lists no tools for this account: an active HIPAA agreement, or an organisation policy, turns its MCP off. Check Wispr Flow's Settings → MCP, or ask your admin. |
165
+ | Tools: unknown | Your account lists tools the plugin hasn't classified, such as ones Wispr Flow added or lists only with a feature turned on. They ask before they run. |
166
+ | Skills: `wisprflow` is replaced by a path | A skill of yours with the id `wisprflow` or `wisprflow-meeting-brief`, for example in `~/.config/opencode/skills/` or a project's `.opencode/skills/`, loads instead of the plugin's own. Rename or move that file, as the next step says. |
167
+ | Agents without default rules | Put the default rules shown by `/wisprflow-status` first in each listed agent's own permissions, in `opencode.json` or the agent's Markdown file, followed by your top-level rules for Wispr Flow tools. |
168
+ | OpenCode: untested | OpenCode is not 2.2.3, 2.2.4 or 2.2.5. Inside `>=2.2.3 <2.3.0` the plugin runs normally; outside it, it runs only because `allowUntestedHost` is set. If Wispr Flow misbehaves, use a tested release. |
169
+ | "Cloud Sync must be enabled to use this feature." | Turn on Dictation cloud storage in Wispr Flow's Settings → Data & Privacy, or ask your admin. Meetings recorded while it was off never appear, even after you turn it on. |
170
+ | "This feature is not available for HIPAA-covered accounts." | Wispr Flow's MCP is not available on this account. |
171
+ | "MCP access has been disabled by your organization's administrator." or "Scratchpad access has been disabled…" | Ask your organisation's Wispr Flow admin. |
172
+ | "Too many requests" | Wait about a minute, then try again. |
173
+ | Meetings are missing | Check the account: `opencode mcp logout wisprflow`, then sign in with the other one. Meetings recorded with Cloud Sync off never appear, and a transcript removed by your retention setting is gone, while its summary remains. |
174
+ | A Wispr Flow tool is refused in `opencode run` | Nobody could answer its prompt. Add an `allow` rule for that tool. |
175
+ | `/wisprflow` is missing | The plugin did not start. Run `/plugins` to see the error. |
176
+ | `OPTIONS_INVALID` | An option is unknown or has a wrong value. The message names the option and the accepted values. |
177
+ | `HOST_UNTESTED` | Your OpenCode is outside `>=2.2.3 <2.3.0`, so the plugin did not start. Use OpenCode `>=2.2.3 <2.3.0`, or set `"allowUntestedHost": true` to run anyway. |
178
+ | `STATUS_UNAVAILABLE` | The status could not be read, or the plugin is not running. Follow the next step in the message. |
179
+ | `SKILLS_INVALID` | A skill file in the package is missing or broken. Reinstall the plugin. |
180
+ | `SERVER_NOT_REGISTERED` | The plugin could not register the `wisprflow` server. Restart OpenCode. |
181
+ | `RULES_NOT_ADDED` | The default permission rules could not be added, so Wispr Flow tools may run without asking. Restart OpenCode. |
182
+
183
+ A script's errors from the tools RPC have their own codes, listed in
184
+ [Scripting](https://github.com/joe-broadhead/opencode-wisprflow/blob/HEAD/docs/scripting.md#errors).
185
+
186
+ ## Uninstall
187
+
188
+ Sign out while the plugin is still installed: once it is removed, OpenCode no longer knows the `wisprflow` server, so
189
+ `opencode mcp logout wisprflow` fails with `MCP server not found: wisprflow` and the sign-in stays in OpenCode's
190
+ credential store.
191
+
192
+ 1. Sign out: `opencode mcp logout wisprflow`. Right after OpenCode starts or reloads, it can answer
193
+ `MCP server not found: wisprflow` for a few seconds; wait, then run it again.
194
+ 2. Check: `opencode auth list` no longer lists **Wispr Flow**.
195
+ 3. Remove the plugin: `opencode plugin remove @joe-broadhead/opencode-wisprflow`, then `opencode reload`.
196
+ `opencode mcp list` no longer lists `wisprflow`.
197
+ 4. Remove any Wispr Flow rules you copied into your agents' own `permissions`.
198
+
199
+ ## Links
200
+
201
+ - [Configuration](https://github.com/joe-broadhead/opencode-wisprflow/blob/HEAD/docs/configuration.md)
202
+ - [In Jelly](https://github.com/joe-broadhead/opencode-wisprflow/blob/HEAD/docs/jelly.md)
203
+ - [Architecture](https://github.com/joe-broadhead/opencode-wisprflow/blob/HEAD/docs/architecture.md)
204
+ - [Contributing](https://github.com/joe-broadhead/opencode-wisprflow/blob/HEAD/CONTRIBUTING.md)
205
+ - [Security](https://github.com/joe-broadhead/opencode-wisprflow/blob/HEAD/SECURITY.md)
206
+ - [Changelog](https://github.com/joe-broadhead/opencode-wisprflow/blob/HEAD/CHANGELOG.md)
207
+ - [MIT license](https://github.com/joe-broadhead/opencode-wisprflow/blob/HEAD/LICENSE)
208
+ - [Wispr Flow's MCP help](https://docs.wisprflow.ai/articles/9551372685-connect-an-mcp-client-to-wispr-flow-remote-mcp-server)
@@ -0,0 +1 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" width="32" height="32"><rect width="32" height="32" rx="7" fill="#4B5563"/><g fill="none" stroke="#FFFFFF" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"><rect x="6.5" y="5.5" width="14" height="20" rx="2"/><path d="M10 10.5h7"/><path d="M10 14.5h7"/><path d="M10 18.5h3.5"/><circle cx="21.5" cy="21.5" r="5" fill="#4B5563"/><path d="M21.5 19.2v2.5l1.7 1.1"/></g></svg>