@maind-dev/mcp-bridge 0.93.0 → 0.95.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/README.md +73 -19
- package/build/index.js +266 -262
- package/build/meta.json +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -105,39 +105,52 @@ again unless you re-pair).
|
|
|
105
105
|
|---|---|---|
|
|
106
106
|
| Claude Code (project) | `<project>/.mcp.json` | always |
|
|
107
107
|
| Claude Code (user) | `~/.claude.json` | always |
|
|
108
|
-
| Claude Desktop | `claude_desktop_config.json` (per-OS path) |
|
|
108
|
+
| Claude Desktop | `claude_desktop_config.json` (per-OS path) | Claude Desktop is installed, or `--client claude-desktop` |
|
|
109
109
|
| Cursor | `~/.cursor/mcp.json` | Cursor is installed, or `--client cursor` |
|
|
110
110
|
| Devin Desktop (formerly Windsurf) | Devin's own `mcp_config.json` — `~/.config/devin/` on macOS and Linux (`$XDG_CONFIG_HOME/devin/` when set), `%APPDATA%\devin\` on Windows; the Devin CLI reads it too | Devin Desktop is installed, or `--client windsurf` (alias `--client devin`) |
|
|
111
111
|
| Devin Desktop, legacy file | `~/.codeium/windsurf/mcp_config.json` — Devin imports it; an existing `maind` entry is kept current, the file is never created and never gets an entry | Devin Desktop is installed and the entry is already there |
|
|
112
112
|
| GitHub Copilot (VS Code) | user-profile `mcp.json` (per-OS path, `servers` shape) | VS Code is installed, or `--client copilot` |
|
|
113
113
|
| Cline | `~/.cline/data/settings/cline_mcp_settings.json` — one file for Cline in every editor, its CLI and Cline Desktop | Cline is installed, or `--client cline` |
|
|
114
114
|
| Continue | `~/.continue/mcpServers/maind.json` — a file of its own; `config.yaml` is never touched | Continue is installed, or `--client continue` |
|
|
115
|
-
| Codex CLI |
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
115
|
+
| Codex CLI | `config.toml` in Codex's home — `~/.codex/`, or `$CODEX_HOME` when set (absolute paths only); the Codex IDE extension and the ChatGPT desktop app share it | Codex is installed, or `--client codex`; `--skip-codex` leaves an installed Codex out |
|
|
116
|
+
|
|
117
|
+
Only Claude Code's two files are written on every machine. A client that is not
|
|
118
|
+
installed gets no file of ours (since **0.85.0** for Cursor and Windsurf,
|
|
119
|
+
**0.83.0** for VS Code, **0.87.0** for Cline and Continue, **0.95.0** for Claude
|
|
120
|
+
Desktop and Codex). Windsurf became Devin Desktop on 2026-06-02; since
|
|
121
|
+
**0.92.0** the bridge writes Devin's own file — the family id stays `windsurf`
|
|
122
|
+
in every config it writes. "Installed" means a trace only the client leaves,
|
|
123
|
+
never a file or directory the bridge writes itself (since **0.87.0** — bridges
|
|
124
|
+
up to 0.84.0 wrote `~/.cursor/mcp.json` and
|
|
125
|
+
`~/.codeium/windsurf/mcp_config.json` on every machine, bridges up to 0.94.0
|
|
126
|
+
Claude Desktop's and Codex's files):
|
|
125
127
|
|
|
126
128
|
| Client | Counts as installed when |
|
|
127
129
|
|---|---|
|
|
130
|
+
| Claude Desktop | its app data (`~/Library/Application Support/Claude`, `%APPDATA%\Claude`, `~/.config/Claude`) holds more than `claude_desktop_config.json`; on macOS also `/Applications/Claude.app` or `~/Applications/Claude.app`; on Windows also `%LOCALAPPDATA%\AnthropicClaude` (the .exe install) or `%LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc` (the MSIX install) |
|
|
128
131
|
| Cursor | its app data (`~/Library/Application Support/Cursor`, `%APPDATA%\Cursor`, `~/.config/Cursor`) holds more than `User/`, or `~/.cursor` holds more than `mcp.json` / `hooks.json` |
|
|
129
132
|
| Devin Desktop (formerly Windsurf) | its app data (`~/Library/Application Support/Devin`, `%APPDATA%\Devin`, `~/.config/Devin`) holds more than `User/` (and, on Windows, where it is the same directory as `%APPDATA%\devin`, more than our `mcp_config.json`), `~/.devin` exists, Devin's config dir holds more than `mcp_config.json`, Windsurf's app data (`…/Windsurf`) holds more than `User/`, or `~/.codeium/windsurf` holds more than `mcp_config.json` |
|
|
130
133
|
| VS Code | its app data (`…/Code`) holds more than `User/` |
|
|
131
|
-
| Cline | `~/.cline/data` holds more than `settings/`,
|
|
132
|
-
| Continue | `~/.continue` holds more than `mcpServers
|
|
134
|
+
| Cline | `~/.cline/data` holds more than `settings/`, an editor (Code, Code - Insiders, Cursor, VSCodium, Windsurf, Devin, AgentComposer) has Cline's `User/globalStorage/saoudrizwan.claude-dev`, or Cline's extension folder (`saoudrizwan.claude-dev-<version>`) is in an editor's extensions dir — see below |
|
|
135
|
+
| Continue | `~/.continue` holds more than `mcpServers/`, or Continue's extension folder (`continue.continue-<version>`) is in an editor's extensions dir — see below |
|
|
136
|
+
| Codex | its home (`$CODEX_HOME`, else `~/.codex`) holds more than `config.toml` — Codex keeps `auth.json`, `sessions/`, `history.jsonl`, … there; with `CODEX_HOME` set, a `~/.codex` beyond `config.toml` counts too |
|
|
137
|
+
|
|
138
|
+
An agent that ships as an editor extension counts as installed once its folder
|
|
139
|
+
is there, before it ever ran (since **0.95.0**): the editors' per-user
|
|
140
|
+
extensions dirs (`~/.vscode`, `~/.vscode-insiders`, `~/.cursor`, `~/.vscode-oss`,
|
|
141
|
+
`~/.windsurf`, `~/.devin`, `~/.agentcomposer`, each `/extensions`), the builtins
|
|
142
|
+
of the app bundle the bridge itself runs from (`<App>.app/Contents/Resources/app/extensions`),
|
|
143
|
+
and on macOS AgentComposer's builtins at `/Applications` or `~/Applications` —
|
|
144
|
+
AgentComposer ships Cline and Continue built in, and on its first start
|
|
145
|
+
neither has data of its own yet.
|
|
133
146
|
|
|
134
147
|
The report shows a skipped client as `skipped` with the reason (e.g. `Cursor
|
|
135
148
|
not found (no Cursor app data, nothing of Cursor's in ~/.cursor)`); when a
|
|
136
149
|
leftover file sits there, the row says so. The exit code stays 0.
|
|
137
150
|
Naming the family with `--client` is the explicit request that overrides the
|
|
138
|
-
probe. `CLINE_DIR`, `CLINE_DATA_DIR`, `CLINE_MCP_SETTINGS_PATH
|
|
139
|
-
`CONTINUE_GLOBAL_DIR` move the Cline and
|
|
140
|
-
resolve them (absolute paths only).
|
|
151
|
+
probe. `CLINE_DIR`, `CLINE_DATA_DIR`, `CLINE_MCP_SETTINGS_PATH`,
|
|
152
|
+
`CONTINUE_GLOBAL_DIR` and `CODEX_HOME` move the Cline, Continue and Codex files
|
|
153
|
+
the way the clients resolve them (absolute paths only).
|
|
141
154
|
|
|
142
155
|
### Leftover configs: `doctor --remove-phantoms`
|
|
143
156
|
|
|
@@ -146,7 +159,9 @@ as a **phantom** — nothing reads it. `doctor --remove-phantoms` lists what it
|
|
|
146
159
|
would do and changes nothing; `doctor --remove-phantoms --yes` applies the same
|
|
147
160
|
list. A file that holds only maind's entry is deleted; a file with anything
|
|
148
161
|
else in it (other servers, other keys, comments) loses only maind's entry,
|
|
149
|
-
every other byte stays.
|
|
162
|
+
every other byte stays. Codex's `config.toml` follows the same rules: only
|
|
163
|
+
`[mcp_servers.maind]` and its sub-tables are cut out, and an entry that is not
|
|
164
|
+
in tables of its own is listed for removal by hand, never touched.
|
|
150
165
|
|
|
151
166
|
### Claude Code hook subcommands
|
|
152
167
|
|
|
@@ -158,6 +173,7 @@ here; the standalone `maind-hook` binary they came from is retired (ADR-245).
|
|
|
158
173
|
|
|
159
174
|
| Subcommand | Hook event | Effect |
|
|
160
175
|
|---|---|---|
|
|
176
|
+
| `on-session-reminder` | `SessionStart` | Add `~/.claude/maind-session-start-reminder.md` (the consultation triggers) to the session context — what the `cat` hook before 0.94.0 printed, but only to a host that can take it (see "Other hosts") |
|
|
161
177
|
| `on-session-start` | `SessionStart` | Open a tracked session for the flat Tier-3 metrics |
|
|
162
178
|
| `on-session-briefing` | `SessionStart` | Add the session briefing and the project conventions to the session context (see below; never blocks) |
|
|
163
179
|
| `on-tool-use` | `PreToolUse` | Count tool calls; warn on stderr when token usage crosses your handoff thresholds (ADR-039) |
|
|
@@ -203,7 +219,8 @@ count what arrived. The index itself is built once by `codebase_index` (or
|
|
|
203
219
|
says when a wired context hook has no index or no SQLite backend to read it.
|
|
204
220
|
Under Cursor, which also runs the hooks in `~/.claude/settings.json`, both
|
|
205
221
|
print nothing (same detection as the session-start hook); a Cursor equivalent
|
|
206
|
-
is follow-up work.
|
|
222
|
+
is follow-up work. Devin Local gets the prompt context in its documented shape
|
|
223
|
+
and the read context not at all (see "Other hosts").
|
|
207
224
|
|
|
208
225
|
## Claude Code: conventions at session start
|
|
209
226
|
|
|
@@ -235,7 +252,8 @@ path and a 2,000-character preview.
|
|
|
235
252
|
(its third-party import, on by default) but expects JSON there, and every
|
|
236
253
|
extra session-start command slows a race in which Cursor drops injected
|
|
237
254
|
context. Under Cursor (`CURSOR_VERSION` set, or `cursor_version` in the
|
|
238
|
-
payload) this hook and `guard-inject` print nothing.
|
|
255
|
+
payload) this hook and `guard-inject` print nothing. Devin Local gets the
|
|
256
|
+
block as SessionStart `additionalContext` — see "Other hosts".
|
|
239
257
|
- **Existing installs.** `install` is append-only, so updating the bridge does
|
|
240
258
|
not wire the hook. `on-session-start` says so once per session, with the
|
|
241
259
|
exact command — `<bridge> install --hooks-only` —, and `doctor` reports the
|
|
@@ -279,6 +297,41 @@ conversation's initial system context" (cursor.com/docs/hooks). Since
|
|
|
279
297
|
block below is the reliable channel in Cursor. We claim nothing for Cursor
|
|
280
298
|
until the scan says `measured_*`.
|
|
281
299
|
|
|
300
|
+
## Other hosts: Cursor and Devin Local run these hooks too
|
|
301
|
+
|
|
302
|
+
The hooks `install` writes into `~/.claude/settings.json` are not only Claude
|
|
303
|
+
Code's. Cursor imports them (Settings → Agents → Third-Party Imports, on by
|
|
304
|
+
default) and maps `SessionStart`, `UserPromptSubmit`, `PreToolUse`,
|
|
305
|
+
`PostToolUse` and `Stop` onto its own events. Devin Local (Devin Desktop's
|
|
306
|
+
agent) loads them while `read_config_from.claude` is on, which is the default.
|
|
307
|
+
Neither reads stdout the way Claude Code does. Since **0.94.0** every hook
|
|
308
|
+
asks which host runs it: `cursor_version` in the payload, a transcript under
|
|
309
|
+
`~/.claude/projects/`, `CURSOR_VERSION`, `DEVIN_PROJECT_DIR`, in that order —
|
|
310
|
+
the payload first, because a hook inherits its parent's environment. It then
|
|
311
|
+
prints what that host can take:
|
|
312
|
+
|
|
313
|
+
| Host | What it gets |
|
|
314
|
+
|---|---|
|
|
315
|
+
| Claude Code (or a host we cannot identify) | Exactly what it got before — plain text at session start, `hookSpecificOutput` JSON elsewhere |
|
|
316
|
+
| Cursor | One JSON object in Cursor's own shape, or nothing — never plain text. A refused `Write` is `permission: "deny"` with the reason for you and the agent; session-start text and context stay out (Cursor's own `sessionStart` hook — see above — and `AGENTS.md` carry the briefing there) |
|
|
317
|
+
| Devin Local | Claude Code's JSON where Devin documents it: `additionalContext` at `SessionStart`, `UserPromptSubmit` and `PostToolUse`, `decision: "block"` for a refusal. Nothing at `PreToolUse`, never plain text |
|
|
318
|
+
|
|
319
|
+
Whether the context reaches the model in Devin Local is **not measured**. To
|
|
320
|
+
keep every hook silent there, set `MAIND_DEVIN_HOOK_OUTPUT=off`, or
|
|
321
|
+
`"devin_hook_output": false` in the bridge's `config.json`. The guard pack
|
|
322
|
+
(`guard install`) judges only in Claude Code: what it relies on — the briefing
|
|
323
|
+
stamp, maind consultations, Claude Code's tool names — cannot be observed
|
|
324
|
+
elsewhere, so it neither warns nor blocks there.
|
|
325
|
+
|
|
326
|
+
**The reminder hook.** Before 0.94.0 the SessionStart reminder was the shell
|
|
327
|
+
command `cat ~/.claude/maind-session-start-reminder.md`, plain text for every
|
|
328
|
+
host. It is now the subcommand `on-session-reminder`. `install` and
|
|
329
|
+
`install --hooks-only` replace a `cat` entry in the form an earlier install
|
|
330
|
+
wrote in place, after asking — the one entry they rewrite. A command of your
|
|
331
|
+
own on that file stays as it is and is named with its replacement. `doctor`
|
|
332
|
+
reports an old `cat` (`hook-hosts`, a warning when Cursor is installed), and
|
|
333
|
+
the session-start line names the command while Cursor is installed.
|
|
334
|
+
|
|
282
335
|
## AGENTS.md readers: conventions via AGENTS.md
|
|
283
336
|
|
|
284
337
|
Measured on 2026-09-30 over 76 Codex rollouts: the MCP `instructions` never
|
|
@@ -393,6 +446,7 @@ Rarely useful outside maind's own development environments:
|
|
|
393
446
|
| `MAIND_FUNCTIONS_ORIGIN` | maind's Supabase Edge Functions URL | Device-flow base URL |
|
|
394
447
|
| `MAIND_NO_AGENTS_MD_REFRESH` | unset | Set to `1` to stop the bridge from refreshing the conventions block in `AGENTS.md` for Codex sessions (see above) |
|
|
395
448
|
| `MAIND_DEBUG` | unset | Set to `1` for one diagnostic stderr line on the otherwise silent AGENTS.md skip (no file with the header inside the repository) |
|
|
449
|
+
| `MAIND_DEVIN_HOOK_OUTPUT` | `on` | `off` keeps every hook silent when Devin Local runs it (same as `"devin_hook_output": false` in `config.json`; see "Other hosts") |
|
|
396
450
|
| `XDG_CONFIG_HOME` | `~/.config` (Linux/BSD) | Parent of the `maind/` config dir |
|
|
397
451
|
|
|
398
452
|
## License
|