@iistools/grove-mcp 0.1.1 → 0.3.0

package/README.md

@@ -6,7 +6,27 @@ news, manage your feeds, engage with articles and discover sources.
 
 ## Install
 
-Add one entry to your MCP host config (`mcp.json`, `claude_desktop_config.json`):
+Run this once in a terminal (Node 20 or newer):
+
+```bash
+npx -y @iistools/grove-mcp install
+```
+
+It finds the MCP apps on this computer (Claude Code in user scope, which its VS Code
+extension also reads; Claude Desktop; Cursor; VS Code) and adds a `grove` entry to each,
+with the absolute path of your `npx` and a `PATH` that holds `node`, so an app started
+from the Dock finds both. It repairs a broken `grove` entry, leaves every other server
+untouched, keeps a backup beside each file it changes (`<file>.bak-grove-mcp`, the first one is kept) and
+prints one line per app. Restart the apps afterwards.
+
+- `--dry-run` prints what it would change and writes nothing.
+- `--client <name>` limits it to `claude-code`, `claude-desktop`, `cursor` or `vscode`
+  (repeatable); it also creates that app's config file when the app was not found.
+- Re-run it after a Node upgrade or move: the entry names that Node's `npx`.
+  Under fnm it names fnm's version dir, not the per-shell link that is gone after logout.
+
+Manual fallback, one entry for Claude Desktop and Cursor (`claude_desktop_config.json`,
+`mcp.json`; VS Code uses `"servers"` instead of `"mcpServers"`):
 
 ```json
 {
@@ -16,13 +36,13 @@ Add one entry to your MCP host config (`mcp.json`, `claude_desktop_config.json`)
 }
 ```
 
-Claude Code, from a terminal:
+Claude Code, from a terminal (`-s user` makes it work in every project):
 
 ```bash
-claude mcp add grove -- npx -y @iistools/grove-mcp
+claude mcp add -s user grove -- npx -y @iistools/grove-mcp
 ```
 
-Node 20 or newer is required. There is no setup step: the first Grove tool call opens a
+There is no other setup step: the first Grove tool call opens a
 sign-in with your account, and the server keeps the session for later calls.
 
 ## Example prompts
@@ -47,8 +67,11 @@ is on the "More examples" page in Grove under Settings.
 
 ## Before you start
 
-- **Opening a full article marks it read.** Say "summaries only" to keep your
-  unread list intact, and ask for the full text only for the few that matter.
+- **Opening an article marks nothing read** unless you ask for it (the assistant
+  passes `markRead`). It may take up to a minute: when a feed carries only a
+  teaser, Grove fetches the publisher's page itself and keeps the text. Say
+  "summaries only" to skip that, and ask for the full text only for the few that
+  matter.
 - **Article text is third-party content.** A feed can carry text written to steer
   an assistant. Grove marks the tools that change things (follow, unfollow, group
   edits, reactions) so your host asks before running them: keep those
@@ -58,13 +81,50 @@ is on the "More examples" page in Grove under Settings.
   "unsubscribe these six" are one step each; have your AI show the list first.
 - **Reactions are your taste signal:** prompts like "match against my reactions"
   read them. Your AI should like, bookmark or mark read only when you ask.
-- **Open only sign-in links you just triggered.** The server opens the sign-in page
-  in your browser itself; when it cannot, the first call returns a link to open in a
-  browser on the computer running the server, and whoever opens it first within five
-  minutes decides which account the server is signed in as.
+- **Open only sign-in links you just asked for.** The server opens the sign-in page
+  in your browser itself; when it cannot, the first call returns a link you can open
+  on any device, a phone included, and whoever opens it first within five minutes
+  decides which account the server is signed in as. The first answer after a sign-in
+  names that account. If this is not your account, stop: run `grove auth logout` if
+  you have the Grove CLI, or delete the profile file the answer names
+  (`~/Library/Preferences/grove-cli-nodejs/config.json` on macOS,
+  `~/.config/grove-cli-nodejs/config.json` on Linux (`$XDG_CONFIG_HOME` if set),
+  `%APPDATA%\grove-cli-nodejs\Config\config.json` on Windows); the server signs out on its next call.
 - Downloading all your Grove data and deleting it stay in the `grove` command-line
   tool and the web app; your AI can do neither.
 
+## Troubleshooting
+
+- **`ENOENT … posix_spawn 'npx -y @iistools/grove-mcp'`**: the whole command line
+  ended up in `"command"` (a quoted `claude mcp add grove "npx -y …"`, or an app's
+  single command field). Run `npx -y @iistools/grove-mcp install`; it splits the
+  entry, also inside a single project's settings.
+- **`env: node: No such file or directory`** from an app opened from the Dock or
+  Start menu: the app's `PATH` has no `node`. `install` writes one into the entry;
+  re-run it after upgrading or moving Node.
+- **`npx` answers 404** on a machine whose `~/.npmrc` maps `@iistools` to a private
+  registry: run
+  `npx -y --@iistools:registry=https://registry.npmjs.org/ @iistools/grove-mcp install`;
+  `install` keeps that flag in the entry it writes.
+- **Windows:** `install` writes the path of `npx.cmd`. If an app cannot start it, set
+  `"command": "cmd"` and `"args": ["/c", "npx", "-y", "@iistools/grove-mcp"]`.
+- **Grove twice in one app.** Two routes can start Grove's tools: a standalone entry
+  (`grove`, or any other entry that runs `@iistools/grove-mcp`) and `iis mcp` with a
+  profile that lists `grove-mcp`. `install` never adds a second one: it prints
+  `skipped: grove already reaches <app> via iis mcp` or
+  `kept: grove reaches <app> via "<entry>"` and writes nothing, and where two routes
+  already exist it prints `double: …` with the entry to delete, exits 1 and deletes
+  nothing. `--force` writes `grove` anyway. Windows has no `iis mcp` mount of Grove today.
+- **`vscode … skipped: not valid JSON`:** VS Code allows comments and trailing commas in
+  `mcp.json`; `install` edits only strict JSON, so it leaves that file alone (exit 1, the
+  other apps are still set up). Add Grove there by hand, under `"servers"`:
+  `"grove": { "type": "stdio", "command": "npx", "args": ["-y", "@iistools/grove-mcp"] }`.
+- **Paths `install` does not know for sure:** Claude Desktop on Linux
+  (`~/.config/Claude/`), VS Code profiles other than the default
+  (`User/profiles/<id>/mcp.json`), VS Code Insiders (`Code - Insiders`) and the
+  Microsoft Store build of Claude Desktop. Use `--client` with the right app, or the
+  manual entry above.
+
 ## License
 
 MIT. Third-party licenses are in `THIRD_PARTY_NOTICES.txt`.

package/THIRD_PARTY_NOTICES.txt

@@ -1,9 +1,9 @@
 THIRD-PARTY SOFTWARE NOTICES AND INFORMATION
 
-This file lists the third-party software components used by @iistools/grove-mcp v0.1.1.
+This file lists the third-party software components used by @iistools/grove-mcp v0.3.0.
 Each component is listed with its license type. Full license texts follow below.
 
-Generated: 2026-10-19T14:51:29Z
+Generated: 2026-10-22T14:57:34Z
 
 ===============================================================================