@maind-dev/mcp-bridge 0.86.0 → 0.88.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 +79 -13
- package/build/index.js +301 -225
- package/build/meta.json +1 -1
- package/package.json +1 -1
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, …) and forwards every request to `https://mcp.maind.dev/mcp`
|
|
5
|
+
Cursor, 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
|
|
|
@@ -93,7 +93,9 @@ 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 |
|
|
98
|
+
| `npx -y @maind-dev/mcp-bridge doctor` | Offline self-diagnosis with fix commands (`--json`; `--remove-phantoms [--yes]`, see below) |
|
|
97
99
|
| `npx -y @maind-dev/mcp-bridge --version` | Print the bridge version |
|
|
98
100
|
| `npx -y @maind-dev/mcp-bridge --help` | Show usage |
|
|
99
101
|
|
|
@@ -104,20 +106,44 @@ again unless you re-pair).
|
|
|
104
106
|
| Claude Code (project) | `<project>/.mcp.json` | always |
|
|
105
107
|
| Claude Code (user) | `~/.claude.json` | always |
|
|
106
108
|
| Claude Desktop | `claude_desktop_config.json` (per-OS path) | always |
|
|
107
|
-
| Cursor | `~/.cursor/mcp.json` |
|
|
108
|
-
| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
|
|
109
|
-
| GitHub Copilot (VS Code) | user-profile `mcp.json` (per-OS path, `servers` shape) | VS Code
|
|
109
|
+
| Cursor | `~/.cursor/mcp.json` | Cursor is installed, or `--client cursor` |
|
|
110
|
+
| Windsurf | `~/.codeium/windsurf/mcp_config.json` | Windsurf is installed, or `--client windsurf` |
|
|
111
|
+
| GitHub Copilot (VS Code) | user-profile `mcp.json` (per-OS path, `servers` shape) | VS Code is installed, or `--client copilot` |
|
|
112
|
+
| 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
|
+
| Continue | `~/.continue/mcpServers/maind.json` — a file of its own; `config.yaml` is never touched | Continue is installed, or `--client continue` |
|
|
110
114
|
| Codex CLI | `~/.codex/config.toml` | always, unless `--skip-codex` |
|
|
111
115
|
|
|
112
116
|
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
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
117
|
+
and Windsurf, **0.83.0** for VS Code, **0.87.0** for Cline and Continue).
|
|
118
|
+
"Installed" means a trace only the client leaves, never a file or directory the
|
|
119
|
+
bridge writes itself (since **0.87.0** — bridges up to 0.84.0 wrote
|
|
120
|
+
`~/.cursor/mcp.json` and `~/.codeium/windsurf/mcp_config.json` on every
|
|
121
|
+
machine):
|
|
122
|
+
|
|
123
|
+
| Client | Counts as installed when |
|
|
124
|
+
|---|---|
|
|
125
|
+
| 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` |
|
|
127
|
+
| 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` |
|
|
129
|
+
| Continue | `~/.continue` holds more than `mcpServers/` |
|
|
130
|
+
|
|
131
|
+
The report shows a skipped client as `skipped` with the reason (e.g. `Cursor
|
|
132
|
+
not found (no Cursor app data, nothing of Cursor's in ~/.cursor)`); when a
|
|
133
|
+
leftover file sits there, the row says so. The exit code stays 0.
|
|
134
|
+
Naming the family with `--client` is the explicit request that overrides the
|
|
135
|
+
probe. `CLINE_DIR`, `CLINE_DATA_DIR`, `CLINE_MCP_SETTINGS_PATH` and
|
|
136
|
+
`CONTINUE_GLOBAL_DIR` move the Cline and Continue files the way the clients
|
|
137
|
+
resolve them (absolute paths only).
|
|
138
|
+
|
|
139
|
+
### Leftover configs: `doctor --remove-phantoms`
|
|
140
|
+
|
|
141
|
+
`doctor` reports a config that names maind for a client that is not installed
|
|
142
|
+
as a **phantom** — nothing reads it. `doctor --remove-phantoms` lists what it
|
|
143
|
+
would do and changes nothing; `doctor --remove-phantoms --yes` applies the same
|
|
144
|
+
list. A file that holds only maind's entry is deleted; a file with anything
|
|
145
|
+
else in it (other servers, other keys, comments) loses only maind's entry,
|
|
146
|
+
every other byte stays.
|
|
121
147
|
|
|
122
148
|
### Claude Code hook subcommands
|
|
123
149
|
|
|
@@ -130,6 +156,7 @@ here; the standalone `maind-hook` binary they came from is retired (ADR-245).
|
|
|
130
156
|
| Subcommand | Hook event | Effect |
|
|
131
157
|
|---|---|---|
|
|
132
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) |
|
|
133
160
|
| `on-tool-use` | `PreToolUse` | Count tool calls; warn on stderr when token usage crosses your handoff thresholds (ADR-039) |
|
|
134
161
|
| `on-session-end` | `Stop` | Post session communication analytics; close and flush the tracked session |
|
|
135
162
|
| `sync-config` | — | Pull your context thresholds from the server |
|
|
@@ -141,6 +168,44 @@ Everything these post is gated server-side by Tier-3 consent
|
|
|
141
168
|
Thresholds are set at <https://app.maind.dev/settings>; run `sync-config`
|
|
142
169
|
afterwards on each machine.
|
|
143
170
|
|
|
171
|
+
## Claude Code: conventions at session start
|
|
172
|
+
|
|
173
|
+
Claude Code cuts the MCP `instructions` after about 2,000 characters
|
|
174
|
+
(measured 2026-10-04: 9 of 21 conventions visible). The channel that arrives
|
|
175
|
+
whole is a SessionStart hook whose output stays under Claude Code's
|
|
176
|
+
10,000-character hook limit — above it, Claude Code swaps the output for a file
|
|
177
|
+
path and a 2,000-character preview.
|
|
178
|
+
|
|
179
|
+
- **What.** `on-session-briefing` (since **0.88.0**) prints the project
|
|
180
|
+
conventions first, then your top lessons, skills and memory titles, rendered
|
|
181
|
+
compactly under a 9,000-byte budget; what does not fit is named (`+N more —
|
|
182
|
+
via …`), never cut silently. It runs on `startup`, `clear` and `compact` (a
|
|
183
|
+
compaction summarises the earlier block away); `resume` and `fork` keep the
|
|
184
|
+
earlier one.
|
|
185
|
+
- **Where it comes from.** The same cache-first ladder as the guard: the
|
|
186
|
+
local cache `~/.maind/guard/briefing-cache.json` (fresh for 12 h, for the
|
|
187
|
+
same project), else
|
|
188
|
+
one fetch from mcp.maind.dev with a 3-second budget (API key, device id,
|
|
189
|
+
project key, client family — never paths or file contents), else the stale
|
|
190
|
+
cache with a note. With nothing at all, one line tells the model to call
|
|
191
|
+
`get_session_briefing` itself.
|
|
192
|
+
- **Delivery, not enforcement.** It is a core hook: `install` offers it with
|
|
193
|
+
its own consent, `install --full` (the dashboard's One-Click path) wires it,
|
|
194
|
+
and it works with the guard off. The guard pack's `guard-inject` delivers
|
|
195
|
+
the same block; when both are wired, `guard-inject` stays silent, so the
|
|
196
|
+
briefing arrives once.
|
|
197
|
+
- **Not in Cursor.** Cursor also runs the hooks in `~/.claude/settings.json`
|
|
198
|
+
(its third-party import, on by default) but expects JSON there, and every
|
|
199
|
+
extra session-start command slows a race in which Cursor drops injected
|
|
200
|
+
context. Under Cursor (`CURSOR_VERSION` set, or `cursor_version` in the
|
|
201
|
+
payload) this hook and `guard-inject` print nothing.
|
|
202
|
+
- **Existing installs.** `install` is append-only, so updating the bridge does
|
|
203
|
+
not wire the hook. `on-session-start` says so once per session, with the
|
|
204
|
+
exact command — `<bridge> install --hooks-only` —, and `doctor` reports the
|
|
205
|
+
channel (`session-start`). A hook you declined at the prompt is remembered
|
|
206
|
+
(`declined_hooks` in the bridge config) and not nagged about;
|
|
207
|
+
`install --hooks-only` asks again.
|
|
208
|
+
|
|
144
209
|
## Codex: conventions via AGENTS.md
|
|
145
210
|
|
|
146
211
|
Measured on 2026-09-30 over 76 Codex rollouts: the MCP `instructions` never
|
|
@@ -199,6 +264,7 @@ appending it once and leaving it to age.
|
|
|
199
264
|
| `device-id`-sibling file `api-key` | API key returned by approve flow (mode 0600) |
|
|
200
265
|
| `~/.maind/state.json` | Hook subcommand state: tracked sessions, queued Tier-3 metrics, synced thresholds (mode 0600) |
|
|
201
266
|
| `~/.maind/guard/agents-md-refresh.json` | When the Codex `AGENTS.md` conventions block was last checked, per project (path hashed; mode 0600) |
|
|
267
|
+
| `~/.maind/guard/briefing-cache.json` | The last session briefing + conventions, for the session-start hook and the `AGENTS.md` block (12 h; mode 0600) |
|
|
202
268
|
|
|
203
269
|
To rebind the bridge to a different account: delete the directory above (or run
|
|
204
270
|
`--reauth`) and restart the bridge.
|
|
@@ -229,7 +295,7 @@ Rarely useful outside maind's own development environments:
|
|
|
229
295
|
| Variable | Default | Purpose |
|
|
230
296
|
|---|---|---|
|
|
231
297
|
| `MAIND_MCP_URL` | `https://mcp.maind.dev/mcp` | Streamable-HTTP endpoint to forward to |
|
|
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` |
|
|
298
|
+
| `MAIND_CLIENT_FAMILY` | unset | Forwards `X-Maind-Client-Family` (`claude-code`, `codex`, `copilot`, `cursor`, `windsurf`, `cline`, `continue`, …) so telemetry tracks the real upstream agent instead of generic `mcp-bridge` |
|
|
233
299
|
| `MAIND_CLIENT_VERSION` | unset | Forwards optional `X-Maind-Client-Version` marker (max 64 chars) |
|
|
234
300
|
| `MAIND_FUNCTIONS_ORIGIN` | maind's Supabase Edge Functions URL | Device-flow base URL |
|
|
235
301
|
| `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) |
|