@maind-dev/mcp-bridge 0.90.0 → 0.92.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 +48 -27
- package/build/index.js +235 -230
- package/build/meta.json +1 -1
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
A tiny local MCP wrapper that pins your [maind](https://maind.dev) API key to
|
|
4
4
|
a single device. The bridge speaks MCP over stdio to your IDE (Claude Code,
|
|
5
|
-
Cursor, Windsurf, GitHub Copilot in VS Code, Cline, Continue, …) and forwards every request to `https://mcp.maind.dev/mcp`
|
|
5
|
+
Cursor, Devin Desktop (formerly Windsurf), GitHub Copilot in VS Code, Cline, Continue, …) and forwards every request to `https://mcp.maind.dev/mcp`
|
|
6
6
|
with an `X-Maind-Device-Id` header, so the server can refuse calls from any
|
|
7
7
|
other machine that tries to reuse the same key.
|
|
8
8
|
|
|
@@ -107,7 +107,8 @@ again unless you re-pair).
|
|
|
107
107
|
| Claude Code (user) | `~/.claude.json` | always |
|
|
108
108
|
| Claude Desktop | `claude_desktop_config.json` (per-OS path) | always |
|
|
109
109
|
| Cursor | `~/.cursor/mcp.json` | Cursor is installed, or `--client cursor` |
|
|
110
|
-
| Windsurf |
|
|
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
|
+
| 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 |
|
|
111
112
|
| GitHub Copilot (VS Code) | user-profile `mcp.json` (per-OS path, `servers` shape) | VS Code is installed, or `--client copilot` |
|
|
112
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` |
|
|
113
114
|
| Continue | `~/.continue/mcpServers/maind.json` — a file of its own; `config.yaml` is never touched | Continue is installed, or `--client continue` |
|
|
@@ -115,6 +116,8 @@ again unless you re-pair).
|
|
|
115
116
|
|
|
116
117
|
A client that is not installed gets no file of ours (since **0.85.0** for Cursor
|
|
117
118
|
and Windsurf, **0.83.0** for VS Code, **0.87.0** for Cline and Continue).
|
|
119
|
+
Windsurf became Devin Desktop on 2026-06-02; since **0.92.0** the bridge writes
|
|
120
|
+
Devin's own file — the family id stays `windsurf` in every config it writes.
|
|
118
121
|
"Installed" means a trace only the client leaves, never a file or directory the
|
|
119
122
|
bridge writes itself (since **0.87.0** — bridges up to 0.84.0 wrote
|
|
120
123
|
`~/.cursor/mcp.json` and `~/.codeium/windsurf/mcp_config.json` on every
|
|
@@ -123,9 +126,9 @@ machine):
|
|
|
123
126
|
| Client | Counts as installed when |
|
|
124
127
|
|---|---|
|
|
125
128
|
| 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` |
|
|
126
|
-
| Windsurf | its app data (`…/Windsurf`) holds more than `User/`, or `~/.codeium/windsurf` holds more than `mcp_config.json` |
|
|
129
|
+
| 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` |
|
|
127
130
|
| VS Code | its app data (`…/Code`) holds more than `User/` |
|
|
128
|
-
| Cline | `~/.cline/data` holds more than `settings/`, or an editor (Code, Code - Insiders, Cursor, VSCodium, Windsurf, AgentComposer) has Cline's `User/globalStorage/saoudrizwan.claude-dev` |
|
|
131
|
+
| Cline | `~/.cline/data` holds more than `settings/`, or an editor (Code, Code - Insiders, Cursor, VSCodium, Windsurf, Devin, AgentComposer) has Cline's `User/globalStorage/saoudrizwan.claude-dev` |
|
|
129
132
|
| Continue | `~/.continue` holds more than `mcpServers/` |
|
|
130
133
|
|
|
131
134
|
The report shows a skipped client as `skipped` with the reason (e.g. `Cursor
|
|
@@ -240,13 +243,22 @@ path and a 2,000-character preview.
|
|
|
240
243
|
(`declined_hooks` in the bridge config) and not nagged about;
|
|
241
244
|
`install --hooks-only` asks again.
|
|
242
245
|
|
|
243
|
-
##
|
|
246
|
+
## AGENTS.md readers: conventions via AGENTS.md
|
|
244
247
|
|
|
245
248
|
Measured on 2026-09-30 over 76 Codex rollouts: the MCP `instructions` never
|
|
246
249
|
reach the model as an instruction (0/76), while the maind block in `AGENTS.md`
|
|
247
250
|
does (74/76). For Codex, `AGENTS.md` is therefore the always-on channel for
|
|
248
251
|
your project conventions — and the bridge keeps that block current instead of
|
|
249
|
-
appending it once and leaving it to age.
|
|
252
|
+
appending it once and leaving it to age. Since **0.91.0** it does so for every
|
|
253
|
+
client that reads `AGENTS.md` per the vendor's own documentation (checked
|
|
254
|
+
2026-10-04): **Cursor** ("supports AGENTS.md in the project root and
|
|
255
|
+
subdirectories") and **VS Code Copilot** (`chat.useAgentsMdFile`, on by
|
|
256
|
+
default). For both the channel is documented, not yet measured here — we claim
|
|
257
|
+
nothing until it is. **Devin Desktop** (formerly Windsurf) sessions get the
|
|
258
|
+
same refresh, and per its docs its agent, Devin Local, reads `AGENTS.md` too —
|
|
259
|
+
at the project root, as an always-on rule (docs.devin.ai
|
|
260
|
+
`cli/extensibility/rules`, checked 2026-10-04); documented, not measured here
|
|
261
|
+
either.
|
|
250
262
|
|
|
251
263
|
- **What.** A managed block between `<!-- maind:conventions v1 begin -->` and
|
|
252
264
|
`<!-- maind:conventions v1 end -->`, placed inside the `## maind MCP
|
|
@@ -257,33 +269,42 @@ appending it once and leaving it to age.
|
|
|
257
269
|
(`~/.maind/guard/briefing-cache.json`). Capped at 6 000 characters at a line
|
|
258
270
|
boundary; what does not fit is named: `… (N more via get_conventions)`.
|
|
259
271
|
- **When.** `install` fills the block as soon as the pairing yields
|
|
260
|
-
conventions
|
|
261
|
-
|
|
262
|
-
`
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
272
|
+
conventions — if the run sets up at least one client the refresh serves
|
|
273
|
+
(Codex, Cursor, Devin Desktop, Copilot; own report row
|
|
274
|
+
`preamble:AGENTS.md#conventions`, `skipped (no selected client uses
|
|
275
|
+
the AGENTS.md block …)` otherwise; `skipped (no conventions yet)` without conventions;
|
|
276
|
+
`--dry-run` reads the cache only and reports `would insert`). Every session
|
|
277
|
+
start of such a client refreshes it: after the MCP handshake, off the hot
|
|
278
|
+
path, at most once per 12 hours per project. The client is recognised via
|
|
279
|
+
`MAIND_CLIENT_FAMILY` (the installer writes it into each client's config) or
|
|
280
|
+
detected from the client's `initialize` frame. The file is rewritten only
|
|
281
|
+
when the conventions changed — a committed `AGENTS.md` does not churn for a
|
|
282
|
+
date — and the client has usually loaded `AGENTS.md` when the bridge starts,
|
|
283
|
+
so a refresh reaches the *next* session. A refresh prints one stderr line:
|
|
284
|
+
`maind: AGENTS.md conventions block refreshed (<n> conventions)`.
|
|
271
285
|
- **Only where the bridge installed it, only inside the repository.** The
|
|
272
|
-
block goes into the closest `AGENTS.md` between the
|
|
286
|
+
block goes into the closest `AGENTS.md` between the bridge's working
|
|
273
287
|
directory and the root of its git repository (`git rev-parse
|
|
274
288
|
--show-toplevel`) that exists *and* carries the `## maind MCP integration`
|
|
275
|
-
header. The bridge never walks above the repository root —
|
|
289
|
+
header. The bridge never walks above the repository root — the readers take
|
|
276
290
|
`AGENTS.md` from the repository root down to the working directory, so a
|
|
277
291
|
parent repository's file above a nested checkout is not this session's file
|
|
278
292
|
— never creates `AGENTS.md`, and never touches a file without the header.
|
|
279
|
-
Outside a git repository nothing is written.
|
|
280
|
-
when
|
|
281
|
-
|
|
282
|
-
|
|
293
|
+
Outside a git repository nothing is written. Where the bridge runs is the
|
|
294
|
+
MCP client's choice; when its working directory leads to no repository or
|
|
295
|
+
to no such `AGENTS.md`, the bridge asks the client for its workspace folders
|
|
296
|
+
over MCP `roots/list` (only a client that declared the `roots` capability,
|
|
297
|
+
only after its `notifications/initialized`, within 8 seconds) and tries each
|
|
298
|
+
of them (at most 8). The answer never leaves the bridge. `MAIND_DEBUG=1`
|
|
299
|
+
prints one line per skip with its reason. `CLAUDE.md`, `.cursorrules`,
|
|
300
|
+
`.windsurfrules` and `copilot-instructions.md` stay as they are. Claude Code
|
|
301
|
+
is not on the list: it reads `AGENTS.md` only when a repository has no
|
|
302
|
+
`CLAUDE.md` (v2.1.277+), and its channel is the SessionStart hook.
|
|
283
303
|
- **Opt-out.** `MAIND_NO_AGENTS_MD_REFRESH=1` in the bridge's environment (the
|
|
284
|
-
`env`
|
|
285
|
-
the block, set the opt-out and
|
|
286
|
-
|
|
304
|
+
`env` of the `maind` entry in the client's MCP config, e.g. the `env` table
|
|
305
|
+
in `~/.codex/config.toml`). To get rid of the block, set the opt-out and
|
|
306
|
+
delete the two marker lines with everything between them; without the
|
|
307
|
+
opt-out the next refresh re-inserts it.
|
|
287
308
|
- **Measure, don't assume.** `maind sessions scan-conventions --client codex`
|
|
288
309
|
counts the Codex rollouts in which `=== Project Conventions` arrived as an
|
|
289
310
|
instruction.
|
|
@@ -297,7 +318,7 @@ appending it once and leaving it to age.
|
|
|
297
318
|
| `%APPDATA%\maind\device-id` (Windows) | Same, on Windows |
|
|
298
319
|
| `device-id`-sibling file `api-key` | API key returned by approve flow (mode 0600) |
|
|
299
320
|
| `~/.maind/state.json` | Hook subcommand state: tracked sessions, queued Tier-3 metrics, synced thresholds (mode 0600) |
|
|
300
|
-
| `~/.maind/guard/agents-md-refresh.json` | When the
|
|
321
|
+
| `~/.maind/guard/agents-md-refresh.json` | When the `AGENTS.md` conventions block was last checked, per project (path hashed; mode 0600) |
|
|
301
322
|
| `~/.maind/guard/briefing-cache.json` | The last session briefing + conventions, for the session-start hook and the `AGENTS.md` block (12 h; mode 0600) |
|
|
302
323
|
| `~/.maind/context/<session>/` | Once-per-session markers of the context hooks: one empty file per delivered item, named by a hash; swept after 7 days |
|
|
303
324
|
|