@iistools/grove-mcp 0.1.0 → 0.2.2

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,15 +36,92 @@ 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
+
+Paste any of these into your AI once Grove is attached. The first time it reads
+your feeds, the server asks you to sign in. A longer list (16 prompts, with tips)
+is on the "More examples" page in Grove under Settings.
+
+1. **Morning briefing, no side effects.** "Give me a briefing of my unread Grove
+   articles: the ten most important stories, one line each with the source. Do
+   not open full articles and do not mark anything read; use the summaries only."
+2. **Match against my own reactions.** "Look at the articles I have liked and
+   bookmarked in Grove, describe my interests in three bullets, then go through
+   today's unread and tell me which five fit those interests best and why."
+3. **Back from a break.** "I was away for ten days. Page through all my unread
+   Grove articles (keep going until there are none left), drop duplicates covering
+   the same event, and give me: five things I must know, ten worth a glance, and
+   the rest as a count per source. Then ask me whether to mark the "rest" as read."
+4. **Find, preview, then follow.** "Find me five good feeds about woodworking in
+   German. For each, show the preview (latest titles, how often it posts). Do not
+   subscribe yet; I will pick."
+
+## 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.
+- **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
+  confirmations on and do not choose "always allow" for them. Reading tools can be
+  auto-allowed.
+- **Review the list before a bulk action.** "Mark 400 articles read" and
+  "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 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.0.
+This file lists the third-party software components used by @iistools/grove-mcp v0.2.2.
 Each component is listed with its license type. Full license texts follow below.
 
-Generated: 2026-10-18T13:45:06Z
+Generated: 2026-10-20T13:49:44Z
 
 ===============================================================================