@maind-dev/mcp-bridge 0.132.0 → 0.133.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
@@ -10,7 +10,7 @@ Required for Pro and higher tiers; optional for Free.
10
10
 
11
11
  ## How it works
12
12
 
13
- 1. **First run** opens your browser at `https://maind.dev/devices?code=…` and
13
+ 1. **First run** opens your browser at `https://app.maind.dev/devices?code=…` and
14
14
  prints a short verification code. You sign in (if needed) and click
15
15
  **Approve** — the bridge receives an API key and stores it locally under
16
16
  `~/.config/maind/` (or platform equivalent). A stable device-id is created
@@ -29,8 +29,26 @@ pairings.
29
29
 
30
30
  ## Install / configure
31
31
 
32
+ **Requires Node.js 20 or later.** `npx` is part of Node.js; without it on the
33
+ `PATH` the commands below end in `command not found`.
34
+
32
35
  You normally don't install anything — `npx` fetches the bridge on first run.
33
36
 
37
+ **No Node.js, or the agent's shell does not find it?** On macOS and Linux
38
+
39
+ ```bash
40
+ curl -fsSL https://maind.dev/install.sh | sh
41
+ ```
42
+
43
+ finds a Node.js 20+ on this machine — on the `PATH`, in the usual version
44
+ managers (nvm, Volta, fnm, asdf, mise, nodenv), in Homebrew — or downloads the
45
+ official LTS build from nodejs.org (SHA-256 checked, into
46
+ `~/.local/share/maind/node`, no sudo). It then installs the bridge into
47
+ `~/.local/share/maind/bridge` and runs `install` with the arguments you pass
48
+ (`… | sh -s -- --client cursor`). The client configs name absolute paths, so
49
+ they keep working in clients whose `PATH` has no Node.js. Running it again
50
+ updates the bridge; `rm -rf ~/.local/share/maind` removes what it installed.
51
+
34
52
  Add this to your MCP client's config (`.mcp.json` or equivalent):
35
53
 
36
54
  ```json
@@ -696,6 +714,34 @@ Switch it off with `maind-mcp-bridge activity off`, per session with
696
714
  `MAIND_AGENT_ACTIVITY=off`. `install` asks once (default No); `--agent-activity`
697
715
  enables it without asking.
698
716
 
717
+ ## Local branch state on work objects
718
+
719
+ On by default. A server sees a branch once it is pushed; until then, commits
720
+ and edits exist on one machine only. For every branch that is bound to a work
721
+ object (`branch.<name>.maindObject`, set by `maind feature start` or
722
+ `maind object bind`), the bridge reports with its presence announce:
723
+
724
+ - the branch name and the work object it is bound to,
725
+ - the short hash of its head and the date of its last commit,
726
+ - how many commits no remote-tracking branch reaches (as of the last fetch),
727
+ - how many files are uncommitted — only where the branch is checked out.
728
+
729
+ Nothing else: no file contents, no commit titles, no file names, no paths. The
730
+ machine is not part of the report; MAIND names it by the paired device of the
731
+ key, or by the `machine_label` you set in `config.json`.
732
+
733
+ **When.** Once per session for all bound branches of the repository the agent
734
+ works in, right after the session became visible; after that only the session's
735
+ own branch, and only when one of the facts changed. The counting runs in the
736
+ background with `git --no-optional-locks` and never delays a tool call.
737
+
738
+ **Who sees it.** You, on the work object. Members of your organization only if
739
+ it enabled coordination visibility. An organization can switch the reports off
740
+ for everyone (Planning policy, "Local work reports"); then nothing is stored.
741
+
742
+ Switch it off on this machine with `"local_branch_report": false` in the
743
+ bridge's `config.json`, per session with `MAIND_LOCAL_BRANCH_REPORT=off`.
744
+
699
745
  ## Where things live
700
746
 
701
747
  | Path | Purpose |
@@ -719,7 +765,7 @@ To rebind the bridge to a different account: delete the directory above (or run
719
765
 
720
766
  **"device_mismatch" on every call.** Another machine has bound this key —
721
767
  the server is doing the right thing by refusing yours. Either unpair the
722
- other device from `https://maind.dev/devices`, or `--reauth` here to bind
768
+ other device from `https://app.maind.dev/devices`, or `--reauth` here to bind
723
769
  this machine and revoke the other.
724
770
 
725
771
  **Browser doesn't open.** The bridge falls back to printing the URL +
@@ -730,6 +776,13 @@ the page, click Approve.
730
776
  launching your MCP client. The bridge uses Node's built-in `fetch`, which
731
777
  respects the proxy env vars on Node 22+.
732
778
 
779
+ **`npx: command not found`, or `npm`/`node` not found.** Node.js 20 or later
780
+ is missing from the `PATH` of the shell that ran the command. That also
781
+ happens with Node.js installed: nvm and Homebrew put it on the `PATH` in the
782
+ shell profile, and an agent's shell does not always read that. Run
783
+ `curl -fsSL https://maind.dev/install.sh | sh` (macOS, Linux) — see
784
+ [Install / configure](#install--configure).
785
+
733
786
  **`npx` can't reach `registry.npmjs.org`.** Install the bridge globally
734
787
  (`npm install -g @maind-dev/mcp-bridge`) and point your `.mcp.json` at
735
788
  `"command": "maind-mcp-bridge"` instead of `npx`.
@@ -749,6 +802,7 @@ Rarely useful outside maind's own development environments:
749
802
  | `MAIND_CLAUDE_PLUGIN` | unset | Set by the Claude Code plugin's launcher to the plugin's version for every bridge it starts; the bridge then counts its Claude Code hooks as the plugin's (see "Claude Code plugin `maind`"). Not for setting by hand |
750
803
  | `MAIND_DEBUG` | unset | Set to `1` for one diagnostic stderr line on the otherwise silent team-block skip (no `AGENTS.md` with a team block inside the repository) |
751
804
  | `MAIND_AGENT_ACTIVITY` | unset | `on`/`off` overrides `activity on\|off` for one session (see "Agent activity from Claude Code sessions") |
805
+ | `MAIND_LOCAL_BRANCH_REPORT` | `on` | `off` stops the report of local branch state for one session (same as `"local_branch_report": false` in `config.json`; see "Local branch state on work objects") |
752
806
  | `MAIND_DEVIN_HOOK_OUTPUT` | `on` | `off` keeps every hook silent when Devin Local runs it (same as `"devin_hook_output": false` in `config.json`; see "Other hosts") |
753
807
  | `XDG_CONFIG_HOME` | `~/.config` (Linux/BSD) | Parent of the `maind/` config dir |
754
808