diff --git a/README.md b/README.md index dc6d491..e144737 100644 --- a/README.md +++ b/README.md @@ -153,10 +153,43 @@ claude mcp add blockrun -s user -- npx -y @blockrun/mcp@latest | **Cursor** | ๐Ÿ“ Documented | โœ… | `~/.cursor/mcp.json` โ€” JSON below | | **VS Code (Copilot)** | ๐Ÿ“ Documented | โœ… | `code --add-mcp '{"name":"blockrun","command":"npx","args":["-y","@blockrun/mcp@latest"]}'` | | **Gemini CLI** | ๐Ÿ“ Documented | โŒ | `gemini mcp add -s user blockrun npx -y @blockrun/mcp@latest` | +| **Grok** | ๐Ÿ“ Documented ยท see the timeout note | โŒ | `grok mcp add blockrun -- npx -y @blockrun/mcp@latest` โ€” **raise `startup_timeout_sec` first**, below | | **Windsurf** | ๐Ÿ“ Documented | โŒ | `~/.codeium/windsurf/mcp_config.json` โ€” JSON below | Any other MCP client that can spawn a stdio server works the same way: `command: npx`, `args: ["-y", "@blockrun/mcp@latest"]`. With nvm/Homebrew Node on a JSON-configured client, put the absolute path from `which npx` in `command`. Spend-dialog sources and what "proceeds without asking" means: [`docs/spend-confirmation.md`](docs/spend-confirmation.md). +**Grok โ€” raise the startup timeout before you install, or the first run looks broken.** +Grok waits `startup_timeout_sec` for an MCP server to answer, and it defaults to **30** +([xAI's MCP docs](https://docs.x.ai/build/features/mcp-servers)). A first `npx -y` run has +to download this package and its dependency tree before the server can say anything, and +that is a race: measured cold, with an empty npm cache, it took **17s on a fast connection +and 42-46s on a slower shared box**. Lose the race and `grok mcp doctor blockrun` says +`server timed out (no response within 30s)` and the UI shows `blockrun [unavailable]` โ€” an +install that is working, timing out, and indistinguishable from broken. + +Give it room in `~/.grok/config.toml` (or `.grok/config.toml` for one project): + +```toml +[mcp_servers.blockrun] +command = "npx" +args = ["-y", "@blockrun/mcp@latest"] +enabled = true +startup_timeout_sec = 120 +``` + +Or skip the cold download entirely, which is faster every run after the first: + +```bash +npm install -g @blockrun/mcp@latest +grok mcp add blockrun -- blockrun-mcp +``` + +Only the FIRST run pays this: npx caches by exact spec, so the next start is warm (~9s +here). The same trap exists on any client with a startup timeout โ€” if a fresh install +shows as unavailable and `npx -y @blockrun/mcp@latest` runs fine in a terminal, raise the +client's timeout or install globally before looking for anything else. Thanks to +[@0xCheetah1](https://github.com/BlockRunAI/blockrun-mcp/issues/144) for the report. + **OpenClaw:** the published `npx` package was verified end-to-end on 2026.8.2: all 20 tools were projected (19 since the Surf delisting), free calls worked, and paid x402 calls settled. Add a hard session cap while installing: ```bash diff --git a/skills/blockrun-debug/SKILL.md b/skills/blockrun-debug/SKILL.md index 756156a..c7feb6e 100644 --- a/skills/blockrun-debug/SKILL.md +++ b/skills/blockrun-debug/SKILL.md @@ -14,6 +14,9 @@ triggers: - "equity quotes are not served" - "sports markets 500" - "501 not implemented" + - "blockrun unavailable" + - "server timed out" + - "startup_timeout_sec" - "refusing to sign it" - "quoted a different price" - "polymarket buy failed" @@ -63,6 +66,7 @@ re-added at user scope leaves a duplicate. Then, in the session: `blockrun_walle | 401 from `api.blockrun.ai` | `BLOCKRUN_API_KEY` rejected. | Check the key at . | | "needs wallet mode" on Polymarket / wallet / realface list | Keypair-only capability while `BLOCKRUN_API_KEY` is set. | Unset `BLOCKRUN_API_KEY` and restart to use a wallet. | | Startup error "not a valid BlockRun API key" | `BLOCKRUN_API_KEY` is malformed. It deliberately fails loudly rather than silently spending USDC from a wallet instead. | Fix the value or unset it. | +| Grok (or any client with a startup timeout) shows `blockrun [unavailable]`, and `mcp doctor` says `server timed out (no response within 30s)` | NOT broken: a cold `npx -y` is still downloading the package and its dependency tree when the client gives up. Grok's `startup_timeout_sec` defaults to 30; the cold start measured 17s on a fast connection and 42-46s on a slower box. Nothing is charged โ€” the server never started. | Raise it in `~/.grok/config.toml` (`[mcp_servers.blockrun]` โ€ฆ `startup_timeout_sec = 120`), or `npm install -g @blockrun/mcp@latest` and point the client at `blockrun-mcp`. Confirm the package itself is fine first: `npx -y @blockrun/mcp@latest` in a terminal answers an `initialize` line. Only the first run is slow โ€” npx caches by exact spec. | | `fetch failed` / balance-check timeout | Base RPC blip; the tool rotates through 3 public RPCs | Wait 30 s, retry once. Persistent โ†’ a local proxy/firewall is blocking outbound RPC. | | `Video`/`Music generation timed out` | Upstream queue. **Not charged** โ€” payment settles on completion only. | Retry, or pick a faster model. Do not retry-loop; jobs take 60โ€“180 s. | | `blockrun_price` with `category:"stocks"` / `"usstock"` โ†’ `Equity quotes are not served (gateway 501 โ€ฆ)` | The gateway withdrew equity price/history on 2026-09-05 (licensing), and the tool answers before the wallet is consulted. Not an outage. **Not charged.** | Do not retry. `action:"list" category:"stocks" market:"us"` still returns the ticker catalog for free. Equity coverage: hello@blockrun.ai. | diff --git a/skills/blockrun-setup/SKILL.md b/skills/blockrun-setup/SKILL.md index 2a7fc16..1c28b23 100644 --- a/skills/blockrun-setup/SKILL.md +++ b/skills/blockrun-setup/SKILL.md @@ -1,12 +1,15 @@ --- name: blockrun-setup -description: "Use when asked to install, add, configure, or set up the BlockRun MCP server (@blockrun/mcp) in Claude Code, Claude Desktop, Cursor, Windsurf, Codex CLI or another MCP client โ€” including first-run wallet creation, funding with USDC, choosing a tool profile, and proving the install works. Also use when a fresh install 'doesn't show up' or a user asks how to pay for calls." +description: "Use when asked to install, add, configure, or set up the BlockRun MCP server (@blockrun/mcp) in Claude Code, Claude Desktop, Cursor, Windsurf, Codex CLI, Grok or another MCP client โ€” including first-run wallet creation, funding with USDC, choosing a tool profile, and proving the install works. Also use when a fresh install 'doesn't show up' or a user asks how to pay for calls." triggers: - "install blockrun" - "add blockrun mcp" - "set up blockrun" - "blockrun setup" - "claude mcp add blockrun" + - "grok mcp add blockrun" + - "blockrun unavailable" + - "mcp server timed out" - "@blockrun/mcp" - "fund my blockrun wallet" - "how do I pay for blockrun" @@ -62,6 +65,24 @@ codex mcp add blockrun --env PATH="$PATH" -- npx -y @blockrun/mcp@latest For a JSON client with nvm/Homebrew Node, put the absolute `npx` path (`which npx`) in `command` โ€” there is no `-e PATH` equivalent there. +**Grok** โ€” raise the startup timeout BEFORE the first run. Grok waits +`startup_timeout_sec` (default **30**) for the server to answer, and a cold `npx -y` has +to download this package and its dependencies first: measured 17s on a fast connection, +42-46s on a slower box. Lose that race and the UI says `blockrun [unavailable]` for an +install that is merely still downloading. In `~/.grok/config.toml`: + +```toml +[mcp_servers.blockrun] +command = "npx" +args = ["-y", "@blockrun/mcp@latest"] +enabled = true +startup_timeout_sec = 120 +``` + +Or sidestep it: `npm install -g @blockrun/mcp@latest` then +`grok mcp add blockrun -- blockrun-mcp`, which launches an already-installed binary. +Only the first run is slow either way โ€” npx caches by exact spec. + **Optional flags** (append after `@latest`): `--profile trading|research|media|chat` exposes a smaller tool set so the client loads fewer schemas. Omit for all 19 tools.