@maind-dev/mcp-bridge 0.87.0 → 0.89.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 +76 -0
- package/build/index.js +254 -243
- package/build/meta.json +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -93,6 +93,7 @@ again unless you re-pair).
|
|
|
93
93
|
|---|---|
|
|
94
94
|
| `npx -y @maind-dev/mcp-bridge` | Run as MCP server (default; what your IDE invokes) |
|
|
95
95
|
| `npx -y @maind-dev/mcp-bridge install` | One-shot setup: MCP configs, preamble files, Claude Code hooks |
|
|
96
|
+
| `maind-mcp-bridge install --hooks-only` | Only the Claude Code hooks — adds what an existing install is missing (no pairing, no configs, no preamble) |
|
|
96
97
|
| `npx -y @maind-dev/mcp-bridge --reauth` | Drop the cached key and re-run the device flow |
|
|
97
98
|
| `npx -y @maind-dev/mcp-bridge doctor` | Offline self-diagnosis with fix commands (`--json`; `--remove-phantoms [--yes]`, see below) |
|
|
98
99
|
| `npx -y @maind-dev/mcp-bridge --version` | Print the bridge version |
|
|
@@ -155,7 +156,10 @@ here; the standalone `maind-hook` binary they came from is retired (ADR-245).
|
|
|
155
156
|
| Subcommand | Hook event | Effect |
|
|
156
157
|
|---|---|---|
|
|
157
158
|
| `on-session-start` | `SessionStart` | Open a tracked session for the flat Tier-3 metrics |
|
|
159
|
+
| `on-session-briefing` | `SessionStart` | Add the session briefing and the project conventions to the session context (see below; never blocks) |
|
|
158
160
|
| `on-tool-use` | `PreToolUse` | Count tool calls; warn on stderr when token usage crosses your handoff thresholds (ADR-039) |
|
|
161
|
+
| `on-prompt-context` | `UserPromptSubmit` | Context at the prompt: matching project conventions and the file:line of symbols the prompt names — matched locally (see below) |
|
|
162
|
+
| `on-read-context` | `PreToolUse` (`Read`) | Context at a file read: who calls the file's symbols from other files, who imports it, and an outline when the Read covers only part of it |
|
|
159
163
|
| `on-session-end` | `Stop` | Post session communication analytics; close and flush the tracked session |
|
|
160
164
|
| `sync-config` | — | Pull your context thresholds from the server |
|
|
161
165
|
| `flush` | — | Post queued Tier-3 metrics now |
|
|
@@ -166,6 +170,76 @@ Everything these post is gated server-side by Tier-3 consent
|
|
|
166
170
|
Thresholds are set at <https://app.maind.dev/settings>; run `sync-config`
|
|
167
171
|
afterwards on each machine.
|
|
168
172
|
|
|
173
|
+
### Context at the moment (since 0.89.0)
|
|
174
|
+
|
|
175
|
+
Two hooks deliver context when it matters instead of only at session start
|
|
176
|
+
(ADR-363). Each is consented separately at `install`, and both run entirely on
|
|
177
|
+
this machine — no network call, nothing uploaded, nothing stored but an empty
|
|
178
|
+
once-per-session marker file per delivered item under `~/.maind/context/`.
|
|
179
|
+
|
|
180
|
+
- **`on-prompt-context`** reads the prompt text **locally** and matches it
|
|
181
|
+
against the project conventions MAIND already cached
|
|
182
|
+
(`.maind/conventions-cache.json` in the repo, or the session-briefing cache
|
|
183
|
+
`~/.maind/guard/briefing-cache.json`) and against symbol names in the repo's
|
|
184
|
+
code index (`.maind/code-index.sqlite`). It adds at most ~2,000 characters:
|
|
185
|
+
conventions whose terms the prompt uses (full text via `get_conventions`),
|
|
186
|
+
and where the symbols it names are defined. Slash commands, generated turns
|
|
187
|
+
and compaction summaries get nothing.
|
|
188
|
+
- **`on-read-context`** reads the **path** of the file the agent is about to
|
|
189
|
+
read — never its contents — and adds at most ~1,500 characters from the
|
|
190
|
+
index: which symbols other files call and from where (the import-resolved
|
|
191
|
+
graph), which files import it, and, for a partial Read, an outline of the
|
|
192
|
+
whole file. A full Read of a file nobody else uses gets nothing.
|
|
193
|
+
|
|
194
|
+
Both stay silent whenever they cannot be sure: no index, an index older than
|
|
195
|
+
the file (`mtime` + size, the indexer's own rule), an interrupted index run, an
|
|
196
|
+
older index schema, any error. Every delivery starts with
|
|
197
|
+
`[maind context · prompt]` or `[maind context · read]`, so a transcript scan can
|
|
198
|
+
count what arrived. The index itself is built once by `codebase_index` (or
|
|
199
|
+
`maind index`) and kept fresh by the `on-index-refresh` Stop hook; `doctor`
|
|
200
|
+
says when a wired context hook has no index or no SQLite backend to read it.
|
|
201
|
+
Under Cursor, which also runs the hooks in `~/.claude/settings.json`, both
|
|
202
|
+
print nothing (same detection as the session-start hook); a Cursor equivalent
|
|
203
|
+
is follow-up work.
|
|
204
|
+
|
|
205
|
+
## Claude Code: conventions at session start
|
|
206
|
+
|
|
207
|
+
Claude Code cuts the MCP `instructions` after about 2,000 characters
|
|
208
|
+
(measured 2026-10-04: 9 of 21 conventions visible). The channel that arrives
|
|
209
|
+
whole is a SessionStart hook whose output stays under Claude Code's
|
|
210
|
+
10,000-character hook limit — above it, Claude Code swaps the output for a file
|
|
211
|
+
path and a 2,000-character preview.
|
|
212
|
+
|
|
213
|
+
- **What.** `on-session-briefing` (since **0.88.0**) prints the project
|
|
214
|
+
conventions first, then your top lessons, skills and memory titles, rendered
|
|
215
|
+
compactly under a 9,000-byte budget; what does not fit is named (`+N more —
|
|
216
|
+
via …`), never cut silently. It runs on `startup`, `clear` and `compact` (a
|
|
217
|
+
compaction summarises the earlier block away); `resume` and `fork` keep the
|
|
218
|
+
earlier one.
|
|
219
|
+
- **Where it comes from.** The same cache-first ladder as the guard: the
|
|
220
|
+
local cache `~/.maind/guard/briefing-cache.json` (fresh for 12 h, for the
|
|
221
|
+
same project), else
|
|
222
|
+
one fetch from mcp.maind.dev with a 3-second budget (API key, device id,
|
|
223
|
+
project key, client family — never paths or file contents), else the stale
|
|
224
|
+
cache with a note. With nothing at all, one line tells the model to call
|
|
225
|
+
`get_session_briefing` itself.
|
|
226
|
+
- **Delivery, not enforcement.** It is a core hook: `install` offers it with
|
|
227
|
+
its own consent, `install --full` (the dashboard's One-Click path) wires it,
|
|
228
|
+
and it works with the guard off. The guard pack's `guard-inject` delivers
|
|
229
|
+
the same block; when both are wired, `guard-inject` stays silent, so the
|
|
230
|
+
briefing arrives once.
|
|
231
|
+
- **Not in Cursor.** Cursor also runs the hooks in `~/.claude/settings.json`
|
|
232
|
+
(its third-party import, on by default) but expects JSON there, and every
|
|
233
|
+
extra session-start command slows a race in which Cursor drops injected
|
|
234
|
+
context. Under Cursor (`CURSOR_VERSION` set, or `cursor_version` in the
|
|
235
|
+
payload) this hook and `guard-inject` print nothing.
|
|
236
|
+
- **Existing installs.** `install` is append-only, so updating the bridge does
|
|
237
|
+
not wire the hook. `on-session-start` says so once per session, with the
|
|
238
|
+
exact command — `<bridge> install --hooks-only` —, and `doctor` reports the
|
|
239
|
+
channel (`session-start`). A hook you declined at the prompt is remembered
|
|
240
|
+
(`declined_hooks` in the bridge config) and not nagged about;
|
|
241
|
+
`install --hooks-only` asks again.
|
|
242
|
+
|
|
169
243
|
## Codex: conventions via AGENTS.md
|
|
170
244
|
|
|
171
245
|
Measured on 2026-09-30 over 76 Codex rollouts: the MCP `instructions` never
|
|
@@ -224,6 +298,8 @@ appending it once and leaving it to age.
|
|
|
224
298
|
| `device-id`-sibling file `api-key` | API key returned by approve flow (mode 0600) |
|
|
225
299
|
| `~/.maind/state.json` | Hook subcommand state: tracked sessions, queued Tier-3 metrics, synced thresholds (mode 0600) |
|
|
226
300
|
| `~/.maind/guard/agents-md-refresh.json` | When the Codex `AGENTS.md` conventions block was last checked, per project (path hashed; mode 0600) |
|
|
301
|
+
| `~/.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
|
+
| `~/.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 |
|
|
227
303
|
|
|
228
304
|
To rebind the bridge to a different account: delete the directory above (or run
|
|
229
305
|
`--reauth`) and restart the bridge.
|