@maind-dev/mcp-bridge 0.82.0 → 0.84.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 +74 -1
- package/build/index.js +428 -402
- package/build/meta.json +1 -1
- package/package.json +3 -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, …) and forwards every request to `https://mcp.maind.dev/mcp`
|
|
5
|
+
Cursor, Windsurf, GitHub Copilot in VS Code, …) 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
|
|
|
@@ -61,6 +61,28 @@ using the bridge transport, add a client marker via env:
|
|
|
61
61
|
}
|
|
62
62
|
```
|
|
63
63
|
|
|
64
|
+
**VS Code (GitHub Copilot agent mode)** reads a different file in a different
|
|
65
|
+
shape: `servers` instead of `mcpServers`, with `"type": "stdio"` on every
|
|
66
|
+
entry — an `mcpServers` key is ignored without a word. `npx -y @maind-dev/mcp-bridge install --client copilot`
|
|
67
|
+
writes the user-profile `mcp.json` (`~/Library/Application Support/Code/User/mcp.json`,
|
|
68
|
+
`%APPDATA%\Code\User\mcp.json`, `$XDG_CONFIG_HOME/Code/User/mcp.json`) in that
|
|
69
|
+
shape, keeping your comments; for a workspace-level file, put this in
|
|
70
|
+
`.vscode/mcp.json` instead:
|
|
71
|
+
|
|
72
|
+
```json
|
|
73
|
+
{
|
|
74
|
+
"servers": {
|
|
75
|
+
"maind": {
|
|
76
|
+
"type": "stdio",
|
|
77
|
+
"command": "npx",
|
|
78
|
+
"args": ["-y", "@maind-dev/mcp-bridge"],
|
|
79
|
+
"env": {
|
|
80
|
+
"MAIND_CLIENT_FAMILY": "copilot"
|
|
81
|
+
}
|
|
82
|
+
}
|
|
83
|
+
}
|
|
84
|
+
}
|
|
85
|
+
```
|
|
64
86
|
Restart the MCP client. The first invocation walks you through the device
|
|
65
87
|
flow; subsequent ones are silent (you should never see the verification code
|
|
66
88
|
again unless you re-pair).
|
|
@@ -97,6 +119,54 @@ Everything these post is gated server-side by Tier-3 consent
|
|
|
97
119
|
Thresholds are set at <https://app.maind.dev/settings>; run `sync-config`
|
|
98
120
|
afterwards on each machine.
|
|
99
121
|
|
|
122
|
+
## Codex: conventions via AGENTS.md
|
|
123
|
+
|
|
124
|
+
Measured on 2026-09-30 over 76 Codex rollouts: the MCP `instructions` never
|
|
125
|
+
reach the model as an instruction (0/76), while the maind block in `AGENTS.md`
|
|
126
|
+
does (74/76). For Codex, `AGENTS.md` is therefore the always-on channel for
|
|
127
|
+
your project conventions — and the bridge keeps that block current instead of
|
|
128
|
+
appending it once and leaving it to age.
|
|
129
|
+
|
|
130
|
+
- **What.** A managed block between `<!-- maind:conventions v1 begin -->` and
|
|
131
|
+
`<!-- maind:conventions v1 end -->`, placed inside the `## maind MCP
|
|
132
|
+
integration` section of `AGENTS.md`. Its lead line reads `Project conventions
|
|
133
|
+
— always-on policies served by maind; updated <date> by mcp-bridge <version>.
|
|
134
|
+
Managed block: …`; below it is the same severity-sorted conventions text the
|
|
135
|
+
Claude Code SessionStart hook injects, from the same local cache
|
|
136
|
+
(`~/.maind/guard/briefing-cache.json`). Capped at 6 000 characters at a line
|
|
137
|
+
boundary; what does not fit is named: `… (N more via get_conventions)`.
|
|
138
|
+
- **When.** `install` fills the block as soon as the pairing yields
|
|
139
|
+
conventions (own report row `preamble:AGENTS.md#conventions`; `skipped (no
|
|
140
|
+
conventions yet)` otherwise; `--dry-run` reads the cache only and reports
|
|
141
|
+
`would insert`). Every Codex session start refreshes it: after the MCP
|
|
142
|
+
handshake, off the hot path, at most once per 12 hours per project. The
|
|
143
|
+
session is recognised as Codex via `MAIND_CLIENT_FAMILY=codex` (the installer
|
|
144
|
+
writes it into `~/.codex/config.toml`) or detected from the client's
|
|
145
|
+
`initialize` frame. The file is rewritten only when the conventions changed —
|
|
146
|
+
a committed `AGENTS.md` does not churn for a date — and Codex has already
|
|
147
|
+
loaded `AGENTS.md` when the bridge starts, so a refresh reaches the *next*
|
|
148
|
+
session. A refresh prints one stderr line: `maind: AGENTS.md conventions
|
|
149
|
+
block refreshed (<n> conventions)`.
|
|
150
|
+
- **Only where the bridge installed it, only inside the repository.** The
|
|
151
|
+
block goes into the closest `AGENTS.md` between the session's working
|
|
152
|
+
directory and the root of its git repository (`git rev-parse
|
|
153
|
+
--show-toplevel`) that exists *and* carries the `## maind MCP integration`
|
|
154
|
+
header. The bridge never walks above the repository root — Codex reads
|
|
155
|
+
`AGENTS.md` from the repository root down to the working directory, so a
|
|
156
|
+
parent repository's file above a nested checkout is not this session's file
|
|
157
|
+
— never creates `AGENTS.md`, and never touches a file without the header.
|
|
158
|
+
Outside a git repository nothing is written. `MAIND_DEBUG=1` prints one line
|
|
159
|
+
when the repository has no such file. `CLAUDE.md`, `.cursorrules`,
|
|
160
|
+
`.windsurfrules` and `copilot-instructions.md` stay as they are — Claude Code
|
|
161
|
+
has the hook, and the readers of the others are not measured.
|
|
162
|
+
- **Opt-out.** `MAIND_NO_AGENTS_MD_REFRESH=1` in the bridge's environment (the
|
|
163
|
+
`env` table of the `maind` entry in `~/.codex/config.toml`). To get rid of
|
|
164
|
+
the block, set the opt-out and delete the two marker lines with everything
|
|
165
|
+
between them; without the opt-out the next refresh re-inserts it.
|
|
166
|
+
- **Measure, don't assume.** `maind sessions scan-conventions --client codex`
|
|
167
|
+
counts the Codex rollouts in which `=== Project Conventions` arrived as an
|
|
168
|
+
instruction.
|
|
169
|
+
|
|
100
170
|
## Where things live
|
|
101
171
|
|
|
102
172
|
| Path | Purpose |
|
|
@@ -106,6 +176,7 @@ afterwards on each machine.
|
|
|
106
176
|
| `%APPDATA%\maind\device-id` (Windows) | Same, on Windows |
|
|
107
177
|
| `device-id`-sibling file `api-key` | API key returned by approve flow (mode 0600) |
|
|
108
178
|
| `~/.maind/state.json` | Hook subcommand state: tracked sessions, queued Tier-3 metrics, synced thresholds (mode 0600) |
|
|
179
|
+
| `~/.maind/guard/agents-md-refresh.json` | When the Codex `AGENTS.md` conventions block was last checked, per project (path hashed; mode 0600) |
|
|
109
180
|
|
|
110
181
|
To rebind the bridge to a different account: delete the directory above (or run
|
|
111
182
|
`--reauth`) and restart the bridge.
|
|
@@ -139,6 +210,8 @@ Rarely useful outside maind's own development environments:
|
|
|
139
210
|
| `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` |
|
|
140
211
|
| `MAIND_CLIENT_VERSION` | unset | Forwards optional `X-Maind-Client-Version` marker (max 64 chars) |
|
|
141
212
|
| `MAIND_FUNCTIONS_ORIGIN` | maind's Supabase Edge Functions URL | Device-flow base URL |
|
|
213
|
+
| `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) |
|
|
214
|
+
| `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) |
|
|
142
215
|
| `XDG_CONFIG_HOME` | `~/.config` (Linux/BSD) | Parent of the `maind/` config dir |
|
|
143
216
|
|
|
144
217
|
## License
|