@maind-dev/mcp-bridge 0.89.0 → 0.91.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 +38 -23
- package/build/index.js +239 -237
- package/build/meta.json +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -240,13 +240,19 @@ path and a 2,000-character preview.
|
|
|
240
240
|
(`declined_hooks` in the bridge config) and not nagged about;
|
|
241
241
|
`install --hooks-only` asks again.
|
|
242
242
|
|
|
243
|
-
##
|
|
243
|
+
## AGENTS.md readers: conventions via AGENTS.md
|
|
244
244
|
|
|
245
245
|
Measured on 2026-09-30 over 76 Codex rollouts: the MCP `instructions` never
|
|
246
246
|
reach the model as an instruction (0/76), while the maind block in `AGENTS.md`
|
|
247
247
|
does (74/76). For Codex, `AGENTS.md` is therefore the always-on channel for
|
|
248
248
|
your project conventions — and the bridge keeps that block current instead of
|
|
249
|
-
appending it once and leaving it to age.
|
|
249
|
+
appending it once and leaving it to age. Since **0.91.0** it does so for every
|
|
250
|
+
client that reads `AGENTS.md` per the vendor's own documentation (checked
|
|
251
|
+
2026-10-04): **Cursor** ("supports AGENTS.md in the project root and
|
|
252
|
+
subdirectories") and **VS Code Copilot** (`chat.useAgentsMdFile`, on by
|
|
253
|
+
default). For both the channel is documented, not yet measured here — we claim
|
|
254
|
+
nothing until it is. Windsurf sessions get the same refresh; whether Windsurf
|
|
255
|
+
(now Devin Desktop) reads `AGENTS.md` is not established here.
|
|
250
256
|
|
|
251
257
|
- **What.** A managed block between `<!-- maind:conventions v1 begin -->` and
|
|
252
258
|
`<!-- maind:conventions v1 end -->`, placed inside the `## maind MCP
|
|
@@ -257,33 +263,42 @@ appending it once and leaving it to age.
|
|
|
257
263
|
(`~/.maind/guard/briefing-cache.json`). Capped at 6 000 characters at a line
|
|
258
264
|
boundary; what does not fit is named: `… (N more via get_conventions)`.
|
|
259
265
|
- **When.** `install` fills the block as soon as the pairing yields
|
|
260
|
-
conventions
|
|
261
|
-
|
|
262
|
-
`
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
266
|
+
conventions — if the run sets up at least one client the refresh serves
|
|
267
|
+
(Codex, Cursor, Windsurf, Copilot; own report row
|
|
268
|
+
`preamble:AGENTS.md#conventions`, `skipped (no selected client uses
|
|
269
|
+
the AGENTS.md block …)` otherwise; `skipped (no conventions yet)` without conventions;
|
|
270
|
+
`--dry-run` reads the cache only and reports `would insert`). Every session
|
|
271
|
+
start of such a client refreshes it: after the MCP handshake, off the hot
|
|
272
|
+
path, at most once per 12 hours per project. The client is recognised via
|
|
273
|
+
`MAIND_CLIENT_FAMILY` (the installer writes it into each client's config) or
|
|
274
|
+
detected from the client's `initialize` frame. The file is rewritten only
|
|
275
|
+
when the conventions changed — a committed `AGENTS.md` does not churn for a
|
|
276
|
+
date — and the client has usually loaded `AGENTS.md` when the bridge starts,
|
|
277
|
+
so a refresh reaches the *next* session. A refresh prints one stderr line:
|
|
278
|
+
`maind: AGENTS.md conventions block refreshed (<n> conventions)`.
|
|
271
279
|
- **Only where the bridge installed it, only inside the repository.** The
|
|
272
|
-
block goes into the closest `AGENTS.md` between the
|
|
280
|
+
block goes into the closest `AGENTS.md` between the bridge's working
|
|
273
281
|
directory and the root of its git repository (`git rev-parse
|
|
274
282
|
--show-toplevel`) that exists *and* carries the `## maind MCP integration`
|
|
275
|
-
header. The bridge never walks above the repository root —
|
|
283
|
+
header. The bridge never walks above the repository root — the readers take
|
|
276
284
|
`AGENTS.md` from the repository root down to the working directory, so a
|
|
277
285
|
parent repository's file above a nested checkout is not this session's file
|
|
278
286
|
— never creates `AGENTS.md`, and never touches a file without the header.
|
|
279
|
-
Outside a git repository nothing is written.
|
|
280
|
-
when
|
|
281
|
-
|
|
282
|
-
|
|
287
|
+
Outside a git repository nothing is written. Where the bridge runs is the
|
|
288
|
+
MCP client's choice; when its working directory leads to no repository or
|
|
289
|
+
to no such `AGENTS.md`, the bridge asks the client for its workspace folders
|
|
290
|
+
over MCP `roots/list` (only a client that declared the `roots` capability,
|
|
291
|
+
only after its `notifications/initialized`, within 8 seconds) and tries each
|
|
292
|
+
of them (at most 8). The answer never leaves the bridge. `MAIND_DEBUG=1`
|
|
293
|
+
prints one line per skip with its reason. `CLAUDE.md`, `.cursorrules`,
|
|
294
|
+
`.windsurfrules` and `copilot-instructions.md` stay as they are. Claude Code
|
|
295
|
+
is not on the list: it reads `AGENTS.md` only when a repository has no
|
|
296
|
+
`CLAUDE.md` (v2.1.277+), and its channel is the SessionStart hook.
|
|
283
297
|
- **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
|
-
|
|
298
|
+
`env` of the `maind` entry in the client's MCP config, e.g. the `env` table
|
|
299
|
+
in `~/.codex/config.toml`). To get rid of the block, set the opt-out and
|
|
300
|
+
delete the two marker lines with everything between them; without the
|
|
301
|
+
opt-out the next refresh re-inserts it.
|
|
287
302
|
- **Measure, don't assume.** `maind sessions scan-conventions --client codex`
|
|
288
303
|
counts the Codex rollouts in which `=== Project Conventions` arrived as an
|
|
289
304
|
instruction.
|
|
@@ -297,7 +312,7 @@ appending it once and leaving it to age.
|
|
|
297
312
|
| `%APPDATA%\maind\device-id` (Windows) | Same, on Windows |
|
|
298
313
|
| `device-id`-sibling file `api-key` | API key returned by approve flow (mode 0600) |
|
|
299
314
|
| `~/.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
|
|
315
|
+
| `~/.maind/guard/agents-md-refresh.json` | When the `AGENTS.md` conventions block was last checked, per project (path hashed; mode 0600) |
|
|
301
316
|
| `~/.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
317
|
| `~/.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
318
|
|