sherpa-mcp 0.1.1 → 0.1.2

package/README.md

@@ -56,30 +56,71 @@ Prerequisites: Node.js ≥ 18, [ripgrep](https://github.com/BurntSushi/ripgrep#i
 (`rg`) on `PATH`, and a local backend running (Ollama, llama.cpp server,
 or LM Studio).
 
-**Register it in Claude Code.** This is the part most likely to trip
-people up: config goes in the MCP server's `env`, **not your shell** —
-`export SHERPA_MODEL=...` in a terminal does nothing, since the server
-runs in its own subprocess with its own environment. Add this to your
-`~/.claude.json` (or a project-level `.mcp.json`):
+### Main path: install the plugin
 
-Ollama:
+This gets you the MCP server, the skill, and `/sherpa-status` together,
+in one shot:
+
+```
+/plugin marketplace add Tongas/sherpa-mcp
+/plugin install sherpa@sherpa-mcp
+```
+
+**Configure the backend.** A plugin-provided MCP server inherits Claude
+Code's own process environment — there's no documented way to attach a
+per-plugin `env` block after a marketplace install. That makes shell
+exports fragile: if you launch Claude Code from a GUI launcher instead
+of a terminal, it doesn't inherit anything from `~/.bashrc`/`~/.zshrc`.
+
+**Recommended: a config file**, which sherpa reads regardless of how
+Claude Code was launched. Create `~/.claude/sherpa/config.json` (applies
+everywhere) or `./sherpa.config.json` in a specific project (same keys,
+camelCase):
 
 ```json
 {
-  "mcpServers": {
-    "sherpa": {
-      "command": "npx",
-      "args": ["-y", "sherpa-mcp"],
-      "env": {
-        "SHERPA_BASE_URL": "http://localhost:11434",
-        "SHERPA_MODEL": "qwen2.5-coder:14b"
-      }
-    }
-  }
+  "backend": "openai-compatible",
+  "baseUrl": "http://localhost:8080",
+  "model": "qwen2.5-coder-14b",
+  "contextWindowOverride": 32768,
+  "maxOutputTokensOverride": 8192
 }
 ```
 
-llama.cpp server (or any OpenAI-compatible server):
+(For Ollama, drop `backend`/`contextWindowOverride`/`maxOutputTokensOverride`
+— just `baseUrl` and `model` are enough; see
+[Configuration](#configuration) below for the full key list.)
+
+**Quick alternative:** if you're always launching Claude Code from a
+shell, exporting env vars works too:
+
+```bash
+export SHERPA_BASE_URL="http://localhost:11434"   # Ollama default
+export SHERPA_MODEL="qwen2.5-coder:14b"            # whatever you have pulled
+```
+
+For an `openai-compatible` backend (llama.cpp server, LM Studio), also
+export `SHERPA_BACKEND=openai-compatible` plus `SHERPA_CONTEXT_WINDOW`
+and `SHERPA_MAX_OUTPUT_TOKENS` set to your server's real values. There's
+no standard endpoint to discover the context window, so without one of
+these two config methods sherpa falls back to a conservative 4096/2048,
+which makes `delegate_transform` skip files over roughly 200 lines.
+
+**Verify:** open a new session and run `/sherpa-status`. It shows the
+active backend, the loaded model, and where each config value actually
+came from, so a typo doesn't go unnoticed.
+
+### Alternative: MCP server only, via npx
+
+Use this if you just want the tools — for example, wiring sherpa into
+something other than Claude Code. **You won't get the skill or
+`/sherpa-status`**, which means no automatic guidance on when delegating
+is worth it and no built-in way to check what's configured; you'll need
+to invoke the tools explicitly and know your own setup.
+
+Add this to `~/.claude.json` (or a project-level `.mcp.json`) — here the
+`env` block is explicit and does work, since you're registering the MCP
+server directly rather than through a plugin:
 
 ```json
 {
@@ -88,31 +129,22 @@ llama.cpp server (or any OpenAI-compatible server):
       "command": "npx",
       "args": ["-y", "sherpa-mcp"],
       "env": {
-        "SHERPA_BACKEND": "openai-compatible",
-        "SHERPA_BASE_URL": "http://localhost:8080",
-        "SHERPA_MODEL": "qwen2.5-coder-14b",
-        "SHERPA_CONTEXT_WINDOW": "32768",
-        "SHERPA_MAX_OUTPUT_TOKENS": "8192"
+        "SHERPA_BASE_URL": "http://localhost:11434",
+        "SHERPA_MODEL": "qwen2.5-coder:14b"
       }
     }
   }
 }
 ```
 
-On `openai-compatible` backends, set `SHERPA_CONTEXT_WINDOW` and
-`SHERPA_MAX_OUTPUT_TOKENS` to your server's real values. There's no
-standard endpoint to discover them, so without these sherpa falls back
-to a conservative 4096/2048 — which makes `delegate_transform` skip
-files over roughly 200 lines.
-
-**Verify:** run `/sherpa-status` in Claude Code. It shows the active
-backend, the loaded model, and — critically — where each config value
-actually came from, so a typo doesn't go unnoticed.
+For an `openai-compatible` backend, add `SHERPA_BACKEND`,
+`SHERPA_CONTEXT_WINDOW`, and `SHERPA_MAX_OUTPUT_TOKENS` to that same
+`env` block, same as above.
 
 Tested with llama.cpp server. Also supports Ollama and LM Studio through
 the same OpenAI-compatible interface.
 
-### Installing from a clone (development)
+#### Installing from a clone (development)
 
 If you're working on `sherpa` itself, build locally instead of using
 `npx`:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sherpa-mcp",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "MCP server that delegates high-volume file exploration, search, and transformation to a local LLM backend",
   "author": "Gastón Parravicini",
   "license": "MIT",