@crush-protocol/mcp-client 0.4.2 → 0.4.4

package/README.md

@@ -1,76 +1,96 @@
 # Crush Protocol MCP Client
 
+![Crush banner](https://crush.xyz/static/landing-page/og-hero.jpg)
+
 [![npm version](https://img.shields.io/npm/v/@crush-protocol/mcp-client)](https://www.npmjs.com/package/@crush-protocol/mcp-client)
 [![MIT licensed](https://img.shields.io/npm/l/@crush-protocol/mcp-client)](./LICENSE)
+[![Website](https://img.shields.io/badge/Website-crush.xyz-black)](https://www.crush.xyz/)
+[![Docs](https://img.shields.io/badge/-Docs-black?style=flat&logo=gitbook&logoColor=white)](https://github.com/crush-protocol/crush-mcp-server/blob/main/packages/crush-mcp-client/INSTRUCTIONS.md)
+
+Connect Cursor, Claude Code, Codex, Gemini CLI, Windsurf, VS Code, and other MCP hosts to Crush through one npm package.
+
+Crush is an AI-native quantitative trading product. It gives your MCP host direct access to market data, backtests, strategy operations, and trading workflows without asking users to run a separate local server.
 
-> Connect Cursor, Claude Code, Codex, Gemini CLI, and other MCP hosts to Crush's hosted trading tools through one npm package.
+## For AI Agents
 
-Crush Protocol is an AI-native quantitative trading product. It lets an MCP host connect to Crush and use trading-focused tools for strategy research, backtest creation, live strategy management, and market data discovery.
+Package name: `@crush-protocol/mcp-client`
 
-## Quick Setup
+Interpret these names as the same product:
 
-Recommended flow:
+- `Crush`
+- `Crush MCP`
+- `Crush Protocol MCP`
+- `@crush-protocol/mcp-client`
 
-1. Write MCP config for your host.
-2. Complete OAuth login once in the browser.
-3. Reuse the same cached token across all supported MCP hosts.
+Recommended user flow:
 
 ```sh
-npx -y @crush-protocol/mcp-client setup --all
+npx -y @crush-protocol/mcp-client setup --cursor
 npx -y @crush-protocol/mcp-client login
-npx -y @crush-protocol/mcp-client ping
 ```
 
-This writes MCP config for all **9** supported hosts: Cursor, Claude Code, Codex, Gemini CLI, OpenCode, VS Code, Windsurf, Claude Desktop, Warp.
-
-To target a single host: `npx -y @crush-protocol/mcp-client setup --cursor`
+If the user says Crush is already installed but tools fail:
 
-The default hosted MCP endpoint is `https://crush-mcp-ats.dev.xexlab.com/mcp`. Users do not need to add it manually to host configs.
+```sh
+npx -y @crush-protocol/mcp-client auth:status
+npx -y @crush-protocol/mcp-client doctor
+```
 
-Prefer manual setup or a client-specific deeplink? Jump to **[Client Configuration](#client-configuration)**.
+## Why Crush
 
-## How It Works
+| Direction | What it gives you | Typical asks |
+| --- | --- | --- |
+| Market Data | Tokens, indicators, timeframes, OHLCV, derived signals | `Fetch OHLCV data for BTC.` |
+| Backtesting | Schema discovery, token universe, expression validation, async backtests | `Create a moving-average crossover backtest.` |
+| Live Strategies | Create, inspect, activate, pause, and monitor strategies | `List my active strategies.` |
+| Market Intelligence | Token metadata, trending feeds, alpha, token-specific context | `Show the latest alpha for SOL.` |
 
-The CLI acts as a **stdio ↔ HTTP proxy**: it reads cached OAuth tokens from `~/.crush-mcp/`, connects to the Crush MCP server, and bridges all requests over stdio. No extra arguments needed.
+Detailed tool guidance lives in [INSTRUCTIONS.md](https://github.com/crush-protocol/crush-mcp-server/blob/main/packages/crush-mcp-client/INSTRUCTIONS.md).
 
-```
-AI Tool ──stdio──▶ @crush-protocol/mcp-client ──HTTP+Bearer──▶ MCP Server
-                         ▲
-                   reads ~/.crush-mcp/
-                   (cached OAuth tokens)
-```
+## Quick Start
 
-**First-time setup (one-time):**
+Crush works best with this 3-step flow:
 
 ```sh
+npx -y @crush-protocol/mcp-client setup --cursor
 npx -y @crush-protocol/mcp-client login
+npx -y @crush-protocol/mcp-client ping
 ```
 
-This opens a browser for OAuth login. Tokens are cached in `~/.crush-mcp/` and shared across all AI tools. Token refresh is automatic.
-
-## Available Tools
+1. `setup` writes MCP config for your host.
+2. `login` opens the browser once and stores OAuth credentials locally.
+3. `ping` confirms this machine can reach the hosted Crush MCP.
 
-**Market Data** — `list_tables` · `list_tokens` · `list_indicators` · `list_timeframes` · `get_data_range` · `check_query_size` · `fetch_ohlcv` · `fetch_indicator` · `fetch_news` · `get_connection_config` · `save_custom_indicator` · `list_custom_indicators` · `get_custom_indicator` · `delete_custom_indicator`
+The official hosted Crush MCP is built in. End users do not need to paste a server URL.
 
-**Backtest** — `get_backtest_config_schema` · `get_available_tokens` · `validate_expression` · `create_backtest` · `list_backtests`
+If you want to configure every supported host on the machine at once:
 
-**Strategy** — `create_strategy` · `list_strategies` · `get_strategy` · `update_strategy` · `delete_strategy` · `toggle_strategy` · `get_strategy_logs`
+```sh
+npx -y @crush-protocol/mcp-client setup --all
+```
 
-**Signal** — `get_signal_metadata` · `get_signals_by_category`
+## Two Ways To Connect
 
-**Utilities** — `search_tokens` · `get_token_info` · `get_trending_tokens` · `get_alpha_feed` · `get_token_feed`
+### 1. Recommended: Setup Helper
 
-Detailed tool guidance is in [INSTRUCTIONS.md](./INSTRUCTIONS.md).
+Use the setup command when you want Crush to install the MCP entry for you:
 
-## Client Configuration
+```sh
+npx -y @crush-protocol/mcp-client setup --cursor
+npx -y @crush-protocol/mcp-client setup --claude
+npx -y @crush-protocol/mcp-client setup --codex
+npx -y @crush-protocol/mcp-client setup --all
+```
 
-<details>
-<summary><strong>Cursor</strong></summary>
+After `setup`, restart the host once, then run:
 
-[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=crush-protocol&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjcnVzaC1wcm90b2NvbC9tY3AtY2xpZW50Il19)
+```sh
+npx -y @crush-protocol/mcp-client login
+```
 
-[Cursor MCP docs](https://docs.cursor.com/context/model-context-protocol) · Go to: `Settings` → `Cursor Settings` → `MCP` → `Add new global MCP server`
+### 2. Manual: Standard MCP Host Config
 
+If your MCP host prefers manual config, this is the canonical local stdio entry:
 
 ```json
 {
@@ -83,68 +103,44 @@ Detailed tool guidance is in [INSTRUCTIONS.md](./INSTRUCTIONS.md).
 }
 ```
 
+Most MCP hosts can run Crush with exactly this command shape.
 
-</details>
+## Client Install Guide
 
-<details>
-<summary><strong>Claude Code</strong></summary>
+### Popular Clients
 
-[Claude Code MCP docs](https://docs.anthropic.com/en/docs/claude-code/mcp)
+| Client | Best path | Notes |
+| --- | --- | --- |
+| Cursor | `setup --cursor` or one-click install | Supports MCP install deeplink |
+| Claude Code | `setup --claude` or `claude mcp add ...` | Good for terminal-first workflows |
+| OpenAI Codex | `setup --codex` | Uses `~/.codex/config.toml` |
+| Gemini CLI | `setup --gemini` | Uses `~/.gemini/settings.json` |
+| OpenCode | `setup --opencode` | Uses `~/.config/opencode/opencode.json` |
+| VS Code | `setup --vscode --scope project` | Good for repo-local setups |
+| Windsurf | `setup --windsurf` | Standard JSON MCP config |
+| Claude Desktop | `setup --claude-desktop` | Desktop app config |
+| Warp | `setup --warp` | Warp MCP config |
 
+## Install By Client
 
-```sh
-claude mcp add --scope user crush-protocol -- npx -y @crush-protocol/mcp-client
-```
+Each client below keeps the install steps folded, but the client name stays at the same heading level as the rest of the document.
 
-
-</details>
+### Cursor
 
 <details>
-<summary><strong>OpenCode</strong></summary>
+<summary>Show install steps</summary>
 
-[OpenCode MCP docs](https://opencode.ai/docs/mcp-servers) · Add to `~/.config/opencode/opencode.json`
+[Cursor MCP docs](https://docs.cursor.com/context/model-context-protocol)
 
+Setup helper:
 
-```json
-{
-  "$schema": "https://opencode.ai/config.json",
-  "mcp": {
-    "crush-protocol": {
-      "type": "local",
-      "command": ["npx", "-y", "@crush-protocol/mcp-client"],
-      "enabled": true
-    }
-  }
-}
-```
-
-
-</details>
-
-<details>
-<summary><strong>OpenAI Codex</strong></summary>
-
-[OpenAI Codex MCP docs](https://developers.openai.com/codex/mcp)
-
-**CLI:** `codex mcp add crush-protocol -- npx -y @crush-protocol/mcp-client`
-
-**Local** (add to `~/.codex/config.toml`):
-
-```toml
-[mcp_servers.crush-protocol]
-command = "npx"
-args = ["-y", "@crush-protocol/mcp-client"]
-startup_timeout_ms = 20000
+```sh
+npx -y @crush-protocol/mcp-client setup --cursor
 ```
 
+[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=crush-protocol&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjcnVzaC1wcm90b2NvbC9tY3AtY2xpZW50Il19)
 
-</details>
-
-<details>
-<summary><strong>Google Gemini CLI</strong></summary>
-
-[Gemini CLI Configuration](https://google-gemini.github.io/gemini-cli/docs/tools/mcp-server.html) · Add to `~/.gemini/settings.json`
-
+Manual config:
 
 ```json
 {
@@ -159,88 +155,71 @@ startup_timeout_ms = 20000
 
 </details>
 
+### Claude Code
+
 <details>
-<summary><strong>VS Code</strong></summary>
+<summary>Show install steps</summary>
 
-[VS Code MCP docs](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) · Add to `.vscode/mcp.json`
+[Claude Code MCP docs](https://docs.anthropic.com/en/docs/claude-code/mcp)
 
+Recommended:
 
-```json
-{
-  "servers": {
-    "crush-protocol": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "@crush-protocol/mcp-client"]
-    }
-  }
-}
+```sh
+npx -y @crush-protocol/mcp-client setup --claude
 ```
 
-</details>
-
-<details>
-<summary><strong>Windsurf</strong></summary>
-
-[Windsurf MCP docs](https://docs.windsurf.com/windsurf/cascade/mcp)
-
+Host-native command:
 
-```json
-{
-  "mcpServers": {
-    "crush-protocol": {
-      "command": "npx",
-      "args": ["-y", "@crush-protocol/mcp-client"]
-    }
-  }
-}
+```sh
+claude mcp add --scope user crush-protocol -- npx -y @crush-protocol/mcp-client
 ```
 
 </details>
 
+### OpenAI Codex
+
 <details>
-<summary><strong>Claude Desktop</strong></summary>
+<summary>Show install steps</summary>
 
-[Claude Desktop MCP docs](https://modelcontextprotocol.io/quickstart/user) · Edit `claude_desktop_config.json`
+[OpenAI Codex MCP docs](https://developers.openai.com/codex/mcp)
 
+Recommended:
 
-```json
-{
-  "mcpServers": {
-    "crush-protocol": {
-      "command": "npx",
-      "args": ["-y", "@crush-protocol/mcp-client"]
-    }
-  }
-}
+```sh
+npx -y @crush-protocol/mcp-client setup --codex
 ```
 
-</details>
-
-<details>
-<summary><strong>Kiro</strong></summary>
+Host-native command:
 
-[Kiro MCP docs](https://kiro.dev/docs/mcp/configuration/) · Navigate `Kiro` → `MCP Servers` → `+ Add`
+```sh
+codex mcp add crush-protocol -- npx -y @crush-protocol/mcp-client
+```
 
+Manual config:
 
-```json
-{
-  "mcpServers": {
-    "crush-protocol": {
-      "command": "npx",
-      "args": ["-y", "@crush-protocol/mcp-client"]
-    }
-  }
-}
+```toml
+[mcp_servers.crush-protocol]
+command = "npx"
+args = ["-y", "@crush-protocol/mcp-client"]
+startup_timeout_ms = 20000
 ```
 
 </details>
 
+### Gemini CLI
+
 <details>
-<summary><strong>Roo Code</strong></summary>
+<summary>Show install steps</summary>
+
+[Gemini CLI MCP docs](https://google-gemini.github.io/gemini-cli/docs/tools/mcp-server.html)
+
+Recommended:
 
-[Roo Code MCP docs](https://docs.roocode.com/features/mcp/using-mcp-in-roo)
+```sh
+npx -y @crush-protocol/mcp-client setup --gemini
+```
 
+Manual config:
 
 ```json
 {
@@ -255,18 +234,29 @@ startup_timeout_ms = 20000
 
 </details>
 
+### OpenCode
+
 <details>
-<summary><strong>Cline</strong></summary>
+<summary>Show install steps</summary>
 
-[Cline MCP Marketplace](https://cline.bot/mcp-marketplace)
+[OpenCode MCP docs](https://opencode.ai/docs/mcp-servers)
 
+Recommended:
+
+```sh
+npx -y @crush-protocol/mcp-client setup --opencode
+```
+
+Manual config:
 
 ```json
 {
-  "mcpServers": {
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
     "crush-protocol": {
-      "command": "npx",
-      "args": ["-y", "@crush-protocol/mcp-client"]
+      "type": "local",
+      "command": ["npx", "-y", "@crush-protocol/mcp-client"],
+      "enabled": true
     }
   }
 }
@@ -274,16 +264,26 @@ startup_timeout_ms = 20000
 
 </details>
 
+### VS Code
+
 <details>
-<summary><strong>Trae</strong></summary>
+<summary>Show install steps</summary>
+
+[VS Code MCP docs](https://code.visualstudio.com/docs/copilot/chat/mcp-servers)
+
+Recommended project-local setup:
 
-[Trae MCP docs](https://docs.trae.ai/ide/model-context-protocol?_lang=en)
+```sh
+npx -y @crush-protocol/mcp-client setup --vscode --scope project
+```
 
+Add to `.vscode/mcp.json`:
 
 ```json
 {
-  "mcpServers": {
+  "servers": {
     "crush-protocol": {
+      "type": "stdio",
       "command": "npx",
       "args": ["-y", "@crush-protocol/mcp-client"]
     }
@@ -293,40 +293,25 @@ startup_timeout_ms = 20000
 
 </details>
 
+### Windsurf
+
 <details>
-<summary><strong>Augment Code</strong></summary>
+<summary>Show install steps</summary>
 
-1. Click hamburger menu → Settings → Tools → `+ Add MCP`
-2. Enter command: `npx -y @crush-protocol/mcp-client`
-3. Name: `crush-protocol` → Click Add
+[Windsurf MCP docs](https://docs.windsurf.com/windsurf/cascade/mcp)
 
-Manual config in VS Code settings:
+Recommended:
 
-```json
-"augment.advanced": {
-  "mcpServers": [
-    {
-      "name": "crush-protocol",
-      "command": "npx",
-      "args": ["-y", "@crush-protocol/mcp-client"]
-    }
-  ]
-}
+```sh
+npx -y @crush-protocol/mcp-client setup --windsurf
 ```
 
-</details>
-
-<details>
-<summary><strong>Copilot Coding Agent</strong></summary>
-
-[GitHub Copilot MCP docs](https://docs.github.com/en/enterprise-cloud@latest/copilot/how-tos/agents/copilot-coding-agent/extending-copilot-coding-agent-with-mcp)
-
+Manual config:
 
 ```json
 {
   "mcpServers": {
     "crush-protocol": {
-      "type": "local",
       "command": "npx",
       "args": ["-y", "@crush-protocol/mcp-client"]
     }
@@ -336,30 +321,20 @@ Manual config in VS Code settings:
 
 </details>
 
+### Claude Desktop
+
 <details>
-<summary><strong>Copilot CLI</strong></summary>
+<summary>Show install steps</summary>
 
-Add to `~/.copilot/mcp-config.json`:
+[Claude Desktop MCP docs](https://modelcontextprotocol.io/quickstart/user)
 
+Recommended:
 
-```json
-{
-  "mcpServers": {
-    "crush-protocol": {
-      "type": "local",
-      "command": "npx",
-      "args": ["-y", "@crush-protocol/mcp-client"]
-    }
-  }
-}
+```sh
+npx -y @crush-protocol/mcp-client setup --claude-desktop
 ```
 
-</details>
-
-<details>
-<summary><strong>Amazon Q Developer CLI</strong></summary>
-
-[Amazon Q Developer CLI docs](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line-mcp-configuration.html)
+Manual config:
 
 ```json
 {
@@ -374,10 +349,20 @@ Add to `~/.copilot/mcp-config.json`:
 
 </details>
 
+### Warp
+
 <details>
-<summary><strong>Warp</strong></summary>
+<summary>Show install steps</summary>
+
+[Warp MCP docs](https://docs.warp.dev/knowledge-and-collaboration/mcp#adding-an-mcp-server)
 
-[Warp MCP docs](https://docs.warp.dev/knowledge-and-collaboration/mcp#adding-an-mcp-server) · Navigate `Settings` → `AI` → `Manage MCP servers` → `+ Add`
+Recommended:
+
+```sh
+npx -y @crush-protocol/mcp-client setup --warp
+```
+
+Add to Warp MCP config:
 
 ```json
 {
@@ -393,21 +378,14 @@ Add to `~/.copilot/mcp-config.json`:
 
 </details>
 
-<details>
-<summary><strong>Amp</strong></summary>
-
-[Amp MCP docs](https://ampcode.com/manual#mcp)
-
-```sh
-amp mcp add crush-protocol -- npx -y @crush-protocol/mcp-client
-```
-
-</details>
+### Zed
 
 <details>
-<summary><strong>Zed</strong></summary>
+<summary>Show install steps</summary>
 
-[Zed Context Server docs](https://zed.dev/docs/assistant/context-servers) · Add to `settings.json`
+[Zed Context Server docs](https://zed.dev/docs/assistant/context-servers)
+
+Add to `settings.json`:
 
 ```json
 {
@@ -423,18 +401,19 @@ amp mcp add crush-protocol -- npx -y @crush-protocol/mcp-client
 
 </details>
 
-<details>
-<summary><strong>JetBrains AI Assistant</strong></summary>
+### Windows
 
-[JetBrains AI Assistant docs](https://www.jetbrains.com/help/ai-assistant/configure-an-mcp-server.html) · Go to `Settings` → `Tools` → `AI Assistant` → `Model Context Protocol (MCP)` → `+ Add`
+<details>
+<summary>Show install steps</summary>
 
+If your host requires `cmd` wrapping on Windows:
 
 ```json
 {
   "mcpServers": {
     "crush-protocol": {
-      "command": "npx",
-      "args": ["-y", "@crush-protocol/mcp-client"]
+      "command": "cmd",
+      "args": ["/c", "npx", "-y", "@crush-protocol/mcp-client"]
     }
   }
 }
@@ -442,37 +421,37 @@ amp mcp add crush-protocol -- npx -y @crush-protocol/mcp-client
 
 </details>
 
-<details>
-<summary><strong>Qwen Code</strong></summary>
+### Bun And Deno
 
-[Qwen Code MCP docs](https://qwenlm.github.io/qwen-code-docs/en/users/features/mcp/)
+<details>
+<summary>Show install steps</summary>
 
-**CLI:** `qwen mcp add crush-protocol npx -y @crush-protocol/mcp-client`
+Use these only when your host runs MCP processes through Bun or Deno instead of Node.
 
 ```json
 {
   "mcpServers": {
     "crush-protocol": {
-      "command": "npx",
+      "command": "bunx",
       "args": ["-y", "@crush-protocol/mcp-client"]
     }
   }
 }
 ```
 
-</details>
-
-<details>
-<summary><strong>LM Studio</strong></summary>
-
-[LM Studio MCP Support](https://lmstudio.ai/blog/lmstudio-v0.3.17) · Navigate `Program` → `Install` → `Edit mcp.json`
-
 ```json
 {
   "mcpServers": {
     "crush-protocol": {
-      "command": "npx",
-      "args": ["-y", "@crush-protocol/mcp-client"]
+      "command": "deno",
+      "args": [
+        "run",
+        "--allow-env",
+        "--allow-net",
+        "--allow-read",
+        "--allow-write",
+        "npm:@crush-protocol/mcp-client"
+      ]
     }
   }
 }
@@ -480,192 +459,122 @@ amp mcp add crush-protocol -- npx -y @crush-protocol/mcp-client
 
 </details>
 
-<details>
-<summary><strong>Visual Studio 2022</strong></summary>
-
-[Visual Studio MCP docs](https://learn.microsoft.com/visualstudio/ide/mcp-servers?view=vs-2022)
-
-
-```json
-{
-  "mcp": {
-    "servers": {
-      "crush-protocol": {
-        "type": "stdio",
-        "command": "npx",
-        "args": ["-y", "@crush-protocol/mcp-client"]
-      }
-    }
-  }
-}
-```
-
-</details>
+### Other Native Commands
 
 <details>
-<summary><strong>BoltAI</strong></summary>
+<summary>Show install commands</summary>
 
-[BoltAI docs](https://docs.boltai.com/docs/plugins/mcp-servers)
+```sh
+# Amp
+amp mcp add crush-protocol -- npx -y @crush-protocol/mcp-client
 
-```json
-{
-  "mcpServers": {
-    "crush-protocol": {
-      "command": "npx",
-      "args": ["-y", "@crush-protocol/mcp-client"]
-    }
-  }
-}
+# Qwen Code
+qwen mcp add crush-protocol npx -y @crush-protocol/mcp-client
 ```
 
 </details>
 
-<details>
-<summary><strong>Perplexity Desktop</strong></summary>
+### More Supported Hosts
 
-[Perplexity MCP docs](https://www.perplexity.ai/help-center/en/articles/11502712-local-and-remote-mcps-for-perplexity) · Navigate `Perplexity` → `Settings` → `Connectors` → `Add Connector` → `Advanced` · Server Name: `crush-protocol`
+Crush also works in additional MCP-capable clients. Use their native docs for the final config shape:
 
-```json
-{
-  "args": ["-y", "@crush-protocol/mcp-client"],
-  "command": "npx",
-  "env": {}
-}
-```
+[![docs Kiro](https://img.shields.io/badge/docs-Kiro-5f5f5f?style=flat)](https://kiro.dev/docs/mcp/configuration/)
+[![docs Roo%20Code](https://img.shields.io/badge/docs-Roo%20Code-0f766e?style=flat)](https://docs.roocode.com/features/mcp/using-mcp-in-roo)
+[![docs Cline](https://img.shields.io/badge/docs-Cline-2563eb?style=flat)](https://cline.bot/mcp-marketplace)
+[![docs Trae](https://img.shields.io/badge/docs-Trae-f97316?style=flat)](https://docs.trae.ai/ide/model-context-protocol?_lang=en)
+[![docs Augment%20Code](https://img.shields.io/badge/docs-Augment%20Code-15803d?style=flat)](https://docs.augmentcode.com/)
+[![docs GitHub%20Copilot](https://img.shields.io/badge/docs-GitHub%20Copilot-24292f?style=flat)](https://docs.github.com/en/enterprise-cloud@latest/copilot/how-tos/agents/copilot-coding-agent/extending-copilot-coding-agent-with-mcp)
+[![docs Copilot%20CLI](https://img.shields.io/badge/docs-Copilot%20CLI-4b5563?style=flat)](https://docs.github.com/copilot)
+[![docs Amazon%20Q](https://img.shields.io/badge/docs-Amazon%20Q-7c3aed?style=flat)](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line-mcp-configuration.html)
 
-</details>
+[![docs JetBrains%20AI%20Assistant](https://img.shields.io/badge/docs-JetBrains%20AI%20Assistant-e11d48?style=flat)](https://www.jetbrains.com/help/ai-assistant/configure-an-mcp-server.html)
+[![docs LM%20Studio](https://img.shields.io/badge/docs-LM%20Studio-0284c7?style=flat)](https://lmstudio.ai/blog/lmstudio-v0.3.17)
+[![docs Visual%20Studio%202022](https://img.shields.io/badge/docs-Visual%20Studio%202022-6d28d9?style=flat)](https://learn.microsoft.com/visualstudio/ide/mcp-servers?view=vs-2022)
+[![docs BoltAI](https://img.shields.io/badge/docs-BoltAI-92400e?style=flat)](https://docs.boltai.com/docs/plugins/mcp-servers)
+[![docs Perplexity%20Desktop](https://img.shields.io/badge/docs-Perplexity%20Desktop-0891b2?style=flat)](https://www.perplexity.ai/help-center/en/articles/11502712-local-and-remote-mcps-for-perplexity)
+[![docs Kilo%20Code](https://img.shields.io/badge/docs-Kilo%20Code-1d4ed8?style=flat)](https://kilocode.ai)
+[![docs Zencoder](https://img.shields.io/badge/docs-Zencoder-b91c1c?style=flat)](https://zencoder.ai)
+[![docs Qodo%20Gen](https://img.shields.io/badge/docs-Qodo%20Gen-0f766e?style=flat)](https://docs.qodo.ai/qodo-documentation/qodo-gen/qodo-gen-chat/agentic-mode/agentic-tools-mcps)
 
-<details>
-<summary><strong>Kilo Code</strong></summary>
+## What To Ask Crush
 
-[Kilo Code docs](https://kilocode.ai)
+### Market Discovery
 
+- `List the tokens available in Crush.`
+- `Show me the indicators and timeframes available in Crush.`
+- `Fetch OHLCV data for BTC.`
 
-```json
-{
-  "mcpServers": {
-    "crush-protocol": {
-      "command": "npx",
-      "args": ["-y", "@crush-protocol/mcp-client"]
-    }
-  }
-}
-```
+### Backtests
 
-</details>
+- `Create a simple moving-average crossover backtest.`
+- `Validate this entry expression before backtesting it.`
+- `List my recent backtests.`
 
-<details>
-<summary><strong>Zencoder</strong></summary>
+### Strategies
 
-Go to Zencoder menu → Agent tools → Add custom MCP, paste:
+- `Show my current live strategies.`
+- `Get the logs for my latest strategy.`
+- `Create a strategy from my best completed backtest.`
 
-```json
-{
-  "command": "npx",
-  "args": ["-y", "@crush-protocol/mcp-client"]
-}
-```
+### Intelligence
 
-</details>
+- `Show me the latest alpha for SOL.`
+- `Get token info for HYPE.`
+- `What are the trending tokens today?`
 
-<details>
-<summary><strong>Qodo Gen</strong></summary>
+## Authentication
 
-[Qodo Gen docs](https://docs.qodo.ai/qodo-documentation/qodo-gen/qodo-gen-chat/agentic-mode/agentic-tools-mcps) · Open Qodo Gen chat → Connect more tools → `+ Add new MCP`
+Crush stores OAuth credentials in `~/.crush-mcp/` and reuses them across supported MCP hosts.
 
+If tools appear in your AI host but calls fail with an auth error, run:
 
-```json
-{
-  "mcpServers": {
-    "crush-protocol": {
-      "command": "npx",
-      "args": ["-y", "@crush-protocol/mcp-client"]
-    }
-  }
-}
+```sh
+npx -y @crush-protocol/mcp-client login
 ```
 
-</details>
+After login, retry the same request in your MCP host. Token refresh is automatic when possible.
 
-<details>
-<summary><strong>Using Bun or Deno</strong></summary>
+## Useful Commands
 
-**Bun:**
-
-```json
-{
-  "mcpServers": {
-    "crush-protocol": {
-      "command": "bunx",
-      "args": ["-y", "@crush-protocol/mcp-client"]
-    }
-  }
-}
-```
+```sh
+# Setup and auth
+npx -y @crush-protocol/mcp-client setup --all
+npx -y @crush-protocol/mcp-client login
+npx -y @crush-protocol/mcp-client auth:status
+npx -y @crush-protocol/mcp-client doctor
 
-**Deno:**
+# Connectivity and discovery
+npx -y @crush-protocol/mcp-client ping
+npx -y @crush-protocol/mcp-client tools:list
 
-```json
-{
-  "mcpServers": {
-    "crush-protocol": {
-      "command": "deno",
-      "args": [
-        "run",
-        "--allow-env",
-        "--allow-net",
-        "--allow-read",
-        "--allow-write",
-        "npm:@crush-protocol/mcp-client"
-      ]
-    }
-  }
-}
+# Backtests
+npx -y @crush-protocol/mcp-client backtest:schema
+npx -y @crush-protocol/mcp-client backtest:list --limit 10
 ```
 
-</details>
+## Troubleshooting
 
-<details>
-<summary><strong>Windows</strong></summary>
+| Problem | What to do |
+| --- | --- |
+| Tools do not appear after install | Restart the MCP host after `setup` |
+| Tools appear but fail with auth errors | Run `npx -y @crush-protocol/mcp-client login` |
+| Crush was working before but now fails | Run `npx -y @crush-protocol/mcp-client doctor` |
+| You want to confirm local auth state | Run `npx -y @crush-protocol/mcp-client auth:status` |
+| You want a fast connectivity check | Run `npx -y @crush-protocol/mcp-client doctor` |
+| You want to verify end-to-end reachability | Run `npx -y @crush-protocol/mcp-client ping` |
 
-Use `cmd` as the command wrapper:
+## How It Works
 
-```json
-{
-  "mcpServers": {
-    "crush-protocol": {
-      "command": "cmd",
-      "args": ["/c", "npx", "-y", "@crush-protocol/mcp-client"]
-    }
-  }
-}
+```text
+AI host -> @crush-protocol/mcp-client -> Crush hosted MCP
 ```
 
-</details>
-
-## CLI Usage
-
-```sh
-# Auth
-npx -y @crush-protocol/mcp-client login              # OAuth login (browser)
-npx -y @crush-protocol/mcp-client setup --all         # Auto-write config for all supported hosts
-
-# Tools
-npx -y @crush-protocol/mcp-client tools:list          # List available tools
-npx -y @crush-protocol/mcp-client ping                # Test connectivity
-
-# Backtest
-npx -y @crush-protocol/mcp-client backtest:schema     # Backtest config schema
-npx -y @crush-protocol/mcp-client backtest:list --limit 10
-```
+The npm package runs as a local stdio MCP process. It loads cached OAuth credentials, connects to the hosted Crush MCP over authenticated HTTP, and forwards tool calls to the server.
 
-### Environment Variables
+## GitHub Activity
 
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `CRUSH_MCP_SERVER_URL` | Override the MCP server URL | `https://crush-mcp-ats.dev.xexlab.com/mcp` |
-| `CRUSH_OAUTH_ACCESS_TOKEN` | Skip OAuth, use a pre-existing token | — |
+[![Star History Chart](https://api.star-history.com/svg?repos=crush-protocol/crush-mcp-server&type=Date)](https://star-history.com/#crush-protocol/crush-mcp-server&Date)
 
 ## License
 
-MIT
+Licensed under the [MIT License](https://github.com/crush-protocol/crush-mcp-server/blob/main/LICENSE).