@maind-dev/mcp-bridge 0.83.0 → 0.85.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 CHANGED
@@ -97,6 +97,28 @@ again unless you re-pair).
97
97
  | `npx -y @maind-dev/mcp-bridge --version` | Print the bridge version |
98
98
  | `npx -y @maind-dev/mcp-bridge --help` | Show usage |
99
99
 
100
+ ### What `install` writes, and when
101
+
102
+ | Client | File | Written when |
103
+ |---|---|---|
104
+ | Claude Code (project) | `<project>/.mcp.json` | always |
105
+ | Claude Code (user) | `~/.claude.json` | always |
106
+ | Claude Desktop | `claude_desktop_config.json` (per-OS path) | always |
107
+ | Cursor | `~/.cursor/mcp.json` | `~/.cursor` exists, or `--client cursor` |
108
+ | Windsurf | `~/.codeium/windsurf/mcp_config.json` | `~/.codeium/windsurf` exists, or `--client windsurf` |
109
+ | GitHub Copilot (VS Code) | user-profile `mcp.json` (per-OS path, `servers` shape) | VS Code's `Code/User` profile dir exists, or `--client copilot` |
110
+ | Codex CLI | `~/.codex/config.toml` | always, unless `--skip-codex` |
111
+
112
+ A client that is not installed gets no file of ours (since **0.85.0** for Cursor
113
+ and Windsurf, **0.83.0** for VS Code): each of these directories is created by
114
+ the client itself on first run, and the bridge never creates them. The report
115
+ shows such a row as `skipped` with the reason — `Cursor not found (no
116
+ ~/.cursor)`, `Windsurf not found (no ~/.codeium/windsurf)`, `VS Code not found
117
+ (no User profile dir)` —, the exit code stays 0, and `doctor` does not count
118
+ the missing file as a configured client. Naming the family with `--client` is
119
+ the explicit request that overrides the probe. A file the bridge wrote earlier
120
+ is always merged again: the probe asks for the directory the file lives in.
121
+
100
122
  ### Claude Code hook subcommands
101
123
 
102
124
  `install` wires these into `~/.claude/settings.json` for you (consent is asked
@@ -119,6 +141,54 @@ Everything these post is gated server-side by Tier-3 consent
119
141
  Thresholds are set at <https://app.maind.dev/settings>; run `sync-config`
120
142
  afterwards on each machine.
121
143
 
144
+ ## Codex: conventions via AGENTS.md
145
+
146
+ Measured on 2026-09-30 over 76 Codex rollouts: the MCP `instructions` never
147
+ reach the model as an instruction (0/76), while the maind block in `AGENTS.md`
148
+ does (74/76). For Codex, `AGENTS.md` is therefore the always-on channel for
149
+ your project conventions — and the bridge keeps that block current instead of
150
+ appending it once and leaving it to age.
151
+
152
+ - **What.** A managed block between `<!-- maind:conventions v1 begin -->` and
153
+ `<!-- maind:conventions v1 end -->`, placed inside the `## maind MCP
154
+ integration` section of `AGENTS.md`. Its lead line reads `Project conventions
155
+ — always-on policies served by maind; updated <date> by mcp-bridge <version>.
156
+ Managed block: …`; below it is the same severity-sorted conventions text the
157
+ Claude Code SessionStart hook injects, from the same local cache
158
+ (`~/.maind/guard/briefing-cache.json`). Capped at 6 000 characters at a line
159
+ boundary; what does not fit is named: `… (N more via get_conventions)`.
160
+ - **When.** `install` fills the block as soon as the pairing yields
161
+ conventions (own report row `preamble:AGENTS.md#conventions`; `skipped (no
162
+ conventions yet)` otherwise; `--dry-run` reads the cache only and reports
163
+ `would insert`). Every Codex session start refreshes it: after the MCP
164
+ handshake, off the hot path, at most once per 12 hours per project. The
165
+ session is recognised as Codex via `MAIND_CLIENT_FAMILY=codex` (the installer
166
+ writes it into `~/.codex/config.toml`) or detected from the client's
167
+ `initialize` frame. The file is rewritten only when the conventions changed —
168
+ a committed `AGENTS.md` does not churn for a date — and Codex has already
169
+ loaded `AGENTS.md` when the bridge starts, so a refresh reaches the *next*
170
+ session. A refresh prints one stderr line: `maind: AGENTS.md conventions
171
+ block refreshed (<n> conventions)`.
172
+ - **Only where the bridge installed it, only inside the repository.** The
173
+ block goes into the closest `AGENTS.md` between the session's working
174
+ directory and the root of its git repository (`git rev-parse
175
+ --show-toplevel`) that exists *and* carries the `## maind MCP integration`
176
+ header. The bridge never walks above the repository root — Codex reads
177
+ `AGENTS.md` from the repository root down to the working directory, so a
178
+ parent repository's file above a nested checkout is not this session's file
179
+ — never creates `AGENTS.md`, and never touches a file without the header.
180
+ Outside a git repository nothing is written. `MAIND_DEBUG=1` prints one line
181
+ when the repository has no such file. `CLAUDE.md`, `.cursorrules`,
182
+ `.windsurfrules` and `copilot-instructions.md` stay as they are — Claude Code
183
+ has the hook, and the readers of the others are not measured.
184
+ - **Opt-out.** `MAIND_NO_AGENTS_MD_REFRESH=1` in the bridge's environment (the
185
+ `env` table of the `maind` entry in `~/.codex/config.toml`). To get rid of
186
+ the block, set the opt-out and delete the two marker lines with everything
187
+ between them; without the opt-out the next refresh re-inserts it.
188
+ - **Measure, don't assume.** `maind sessions scan-conventions --client codex`
189
+ counts the Codex rollouts in which `=== Project Conventions` arrived as an
190
+ instruction.
191
+
122
192
  ## Where things live
123
193
 
124
194
  | Path | Purpose |
@@ -128,6 +198,7 @@ afterwards on each machine.
128
198
  | `%APPDATA%\maind\device-id` (Windows) | Same, on Windows |
129
199
  | `device-id`-sibling file `api-key` | API key returned by approve flow (mode 0600) |
130
200
  | `~/.maind/state.json` | Hook subcommand state: tracked sessions, queued Tier-3 metrics, synced thresholds (mode 0600) |
201
+ | `~/.maind/guard/agents-md-refresh.json` | When the Codex `AGENTS.md` conventions block was last checked, per project (path hashed; mode 0600) |
131
202
 
132
203
  To rebind the bridge to a different account: delete the directory above (or run
133
204
  `--reauth`) and restart the bridge.
@@ -161,6 +232,8 @@ Rarely useful outside maind's own development environments:
161
232
  | `MAIND_CLIENT_FAMILY` | unset | Forwards `X-Maind-Client-Family` (`claude-code`, `codex`, `copilot`, `cursor`, `windsurf`, …) so telemetry tracks the real upstream agent instead of generic `mcp-bridge` |
162
233
  | `MAIND_CLIENT_VERSION` | unset | Forwards optional `X-Maind-Client-Version` marker (max 64 chars) |
163
234
  | `MAIND_FUNCTIONS_ORIGIN` | maind's Supabase Edge Functions URL | Device-flow base URL |
235
+ | `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) |
236
+ | `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) |
164
237
  | `XDG_CONFIG_HOME` | `~/.config` (Linux/BSD) | Parent of the `maind/` config dir |
165
238
 
166
239
  ## License