blockrun-upgrade

# Upgrading BlockRun MCP The server is run by `npx`, so "upgrading" means making npx fetch a newer version and the client restart into it. Which of those two is the problem depends on how it was installed. ## 1. Read how it was installed ```bash claude mcp get blockrun # registered command + args + env + scope npm view @blockrun/mcp version # what "latest" is on the registry right now ``` | Registered spec | What happens at each client start | |---|---| | `npx -y @blockrun/mcp@latest` | npx re-resolves `latest` against the registry and downloads if newer. **A client restart is the upgrade.** | | `npx -y @blockrun/mcp` (no tag) | npx reuses whatever is in `~/.npm/_npx` — the version from the day it was installed. Restarting changes nothing. | | `npx -y @blockrun/mcp@0.39.2` | Pinned on purpose. Only changes if you re-register. | The startup notice is the server telling you it is not on `latest`: ``` [BlockRun] Update available: v0.39.2 → v0.42.0 [BlockRun] Run: claude mcp add blockrun -s user -- npx -y @blockrun/mcp@latest ``` ## 2. Upgrade **Registered with `@latest`:** restart the client. Done. If the notice persists, the cache is stale or the registry was unreachable at start: ```bash rm -rf ~/.npm/_npx # safe — it is only a download cache ``` then restart again. **Registered without a tag, or pinned:** re-register with `@latest`. `claude mcp add` refuses a name that already exists, so remove first — at the scope `claude mcp get` reported — and carry every env var and flag it printed across, one `-e` each, flags after the package: ```bash claude mcp remove blockrun -s user claude mcp add blockrun -s user \ -e PATH="$PATH" -e BLOCKRUN_KEYCHAIN=auto -e BLOCKRUN_CONFIRM_SPEND=on \ -- npx -y @blockrun/mcp@latest --profile trading ``` Codex: `codex mcp remove blockrun` then `codex mcp add blockrun -- npx -y @blockrun/mcp@latest`. JSON clients (Claude Desktop / Cursor / Windsurf): edit `args` to `["-y", "@blockrun/mcp@latest"]`. Then quit and relaunch the client (Claude Code: `/mcp reconnect blockrun` respawns just this server). A running session keeps the old process until you do. ## 3. Prove the version ```bash npx -y @blockrun/mcp@latest --version # what npx would launch now, e.g. 0.42.0 ``` That proves what npx *would* launch. What the client *is* running is the server's startup line on stderr — `BlockRun MCP Server started (v0.42.0) — stdio transport — 20 tools` (Claude Code: `claude --debug` or the MCP log; `/mcp` shows connection status, not the version). If the two disagree, the client was not restarted; the stderr line wins. No `Update available` line after it = you are current. ## 4. What can break Read the **CHANGELOG** for the versions you are crossing: <https://github.com/BlockRunAI/blockrun-mcp/blob/main/CHANGELOG.md>. Each entry explains the behaviour change, not just the diff. Things that have changed across versions and are worth checking: - **Tool set / profiles** — `--profile` names and tool membership; a trimmed profile may gain or lose a tool. - **Env-var semantics** — the kind of change to look for: `BLOCKRUN_KEYCHAIN` arrived in 0.41; `BLOCKRUN_CONFIRM_SPEND` widened from one tool to all paid tools in 0.43. Read the entries for the versions *you* cross and re-check `claude mcp get blockrun` env against the README Configuration table. - **Wallet file precedence** — `BLOCKRUN_WALLET_KEY` → agent `wallet.json` → `~/.blockrun/.session`. An upgrade never moves or rewrites the key; if a balance "disappears", the signer changed, not the funds. `blockrun_wallet` prints the address. - **Polymarket approvals** — new adapter grants are added over time. After an upgrade, `blockrun_polymarket action:"setup" confirm:true` once before trading: idempotent and gasless, but it signs on-chain approvals, so say so to the user before running it. Your USDC and keys are in `~/.blockrun/`, not in the package. Upgrading cannot lose them. ## 5. Refresh copied skills Skills copied into a project or user directory do **not** update with the package. Marketplace-installed skills (`/plugin marketplace add BlockRunAI/blockrun-mcp`) refresh with `/plugin marketplace update blockrun-mcp` followed by `/reload-plugins` (or uninstall + `/plugin install <skill>@blockrun-mcp`). For copied ones, re-run the install with `--force` — it overwrites the files the package ships and leaves any other files in those directories alone: ```bash ls .claude/skills ~/.claude/skills 2>/dev/null # where were they copied? npx -y @blockrun/mcp@latest skills list # what this version ships npx -y @blockrun/mcp@latest skills install --force # ./.claude/skills npx -y @blockrun/mcp@latest skills install --global --force # ~/.claude/skills ``` `--force` replaces the shipped files. If the user edited their copies, diff before overwriting: `skills install --to /tmp/br-skills` and `diff -r /tmp/br-skills .claude/skills`. ## Rollback Pin the previous version and restart: ```bash claude mcp remove blockrun -s user claude mcp add blockrun -s user -e PATH="$PATH" -- npx -y @blockrun/mcp@0.41.1 ``` Versions: <https://www.npmjs.com/package/@blockrun/mcp?activeTab=versions>. Report what broke at <https://github.com/BlockRunAI/blockrun-mcp/issues> with the two version numbers. ## Common mistakes | Mistake | Reality | |---|---| | `npm install -g @blockrun/mcp` to upgrade | The client runs `npx`, which ignores the global install. Re-register instead. | | Editing `~/.npm/_npx/**/package.json` | It is a cache. Delete it, don't edit it. | | Restarting only the terminal | The MCP process belongs to the client session. Restart the client (or `/mcp` reconnect in Claude Code). | | Assuming the skills upgraded too | They are files you copied. `skills install --force`. |