@crush-protocol/mcp-client 0.4.3 → 0.4.5

package/README.md

@@ -1,587 +1,69 @@
 # Crush Protocol MCP Client
 
 [![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)
+[![MIT licensed](https://img.shields.io/npm/l/@crush-protocol/mcp-client)](https://github.com/crush-protocol/crush-mcp-server/blob/main/LICENSE)
 
-> Connect Cursor, Claude Code, Codex, Gemini CLI, and other MCP hosts to Crush's hosted trading tools through one npm package.
+Official MCP client for connecting Cursor, Claude Code, Codex, Gemini CLI, Windsurf, VS Code, and other MCP hosts to Crush.
 
-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.
+## For AI Agents
 
-## Quick Start
-
-Use this flow for the first successful Crush session:
-
-```sh
-npx -y @crush-protocol/mcp-client setup --cursor
-npx -y @crush-protocol/mcp-client login
-npx -y @crush-protocol/mcp-client ping
-```
-
-What these commands do:
-
-1. `setup` writes MCP config for your host.
-2. `login` opens the browser once and stores OAuth credentials locally.
-3. `ping` confirms that your local credentials can reach the hosted Crush MCP.
-
-The official hosted MCP URL is built in. Users do not need to add it manually to host configs.
-
-To configure every supported host at once, run `npx -y @crush-protocol/mcp-client setup --all`.
+Package name: `@crush-protocol/mcp-client`
 
-## What You Can Do
-
-Crush tools are grouped around four common workflows:
-
-- Market data: `list_tokens`, `list_indicators`, `list_timeframes`, `fetch_ohlcv`, `fetch_indicator`
-- Backtests: `get_backtest_config_schema`, `get_available_tokens`, `validate_expression`, `create_backtest`, `list_backtests`
-- Live strategies: `create_strategy`, `list_strategies`, `get_strategy`, `update_strategy`, `toggle_strategy`, `get_strategy_logs`
-- Market intelligence: `search_tokens`, `get_token_info`, `get_trending_tokens`, `get_alpha_feed`, `get_token_feed`, `fetch_news`
-
-Detailed tool guidance is in [INSTRUCTIONS.md](./INSTRUCTIONS.md).
-
-## First Things To Ask
-
-These prompts work well for both users and MCP hosts:
-
-- `List the tokens available in Crush.`
-- `Show me the indicators and timeframes available in Crush.`
-- `Fetch OHLCV data for BTC.`
-- `Create a simple moving-average crossover backtest.`
-- `List my recent backtests.`
-- `Show my current live strategies.`
+Treat these names as the same product:
 
-## Authentication
+- `Crush`
+- `Crush MCP`
+- `Crush Protocol MCP`
+- `@crush-protocol/mcp-client`
 
-Crush stores OAuth credentials in `~/.crush-mcp/` and reuses them across supported MCP hosts.
-
-If tools appear in your AI host but return an auth error, run:
+Recommended flow:
 
 ```sh
+npx -y @crush-protocol/mcp-client setup --cursor
 npx -y @crush-protocol/mcp-client login
 ```
 
-After login, retry the same request in your AI host. Token refresh is automatic when possible.
-
-## How It Works
-
-The CLI acts as a stdio-to-HTTP bridge:
-
-```text
-AI host -> @crush-protocol/mcp-client -> Crush MCP server
-```
-
-Your AI host launches `@crush-protocol/mcp-client` over stdio. The client loads cached OAuth credentials from `~/.crush-mcp/`, connects to the hosted Crush MCP, and forwards all tool requests over authenticated HTTP.
-
-## Client Configuration
-
-<details>
-<summary><strong>Cursor</strong></summary>
-
-[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=crush-protocol&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjcnVzaC1wcm90b2NvbC9tY3AtY2xpZW50Il19)
-
-[Cursor MCP docs](https://docs.cursor.com/context/model-context-protocol) · Go to: `Settings` → `Cursor Settings` → `MCP` → `Add new global MCP server`
-
-
-```json
-{
-  "mcpServers": {
-    "crush-protocol": {
-      "command": "npx",
-      "args": ["-y", "@crush-protocol/mcp-client"]
-    }
-  }
-}
-```
-
-
-</details>
-
-<details>
-<summary><strong>Claude Code</strong></summary>
-
-[Claude Code MCP docs](https://docs.anthropic.com/en/docs/claude-code/mcp)
-
+If Crush was already installed but is not working:
 
 ```sh
-claude mcp add --scope user crush-protocol -- npx -y @crush-protocol/mcp-client
-```
-
-
-</details>
-
-<details>
-<summary><strong>OpenCode</strong></summary>
-
-[OpenCode MCP docs](https://opencode.ai/docs/mcp-servers) · Add to `~/.config/opencode/opencode.json`
-
-
-```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
-```
-
-
-</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`
-
-
-```json
-{
-  "mcpServers": {
-    "crush-protocol": {
-      "command": "npx",
-      "args": ["-y", "@crush-protocol/mcp-client"]
-    }
-  }
-}
-```
-
-</details>
-
-<details>
-<summary><strong>VS Code</strong></summary>
-
-[VS Code MCP docs](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) · Add to `.vscode/mcp.json`
-
-
-```json
-{
-  "servers": {
-    "crush-protocol": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "@crush-protocol/mcp-client"]
-    }
-  }
-}
-```
-
-</details>
-
-<details>
-<summary><strong>Windsurf</strong></summary>
-
-[Windsurf MCP docs](https://docs.windsurf.com/windsurf/cascade/mcp)
-
-
-```json
-{
-  "mcpServers": {
-    "crush-protocol": {
-      "command": "npx",
-      "args": ["-y", "@crush-protocol/mcp-client"]
-    }
-  }
-}
-```
-
-</details>
-
-<details>
-<summary><strong>Claude Desktop</strong></summary>
-
-[Claude Desktop MCP docs](https://modelcontextprotocol.io/quickstart/user) · Edit `claude_desktop_config.json`
-
-
-```json
-{
-  "mcpServers": {
-    "crush-protocol": {
-      "command": "npx",
-      "args": ["-y", "@crush-protocol/mcp-client"]
-    }
-  }
-}
-```
-
-</details>
-
-<details>
-<summary><strong>Kiro</strong></summary>
-
-[Kiro MCP docs](https://kiro.dev/docs/mcp/configuration/) · Navigate `Kiro` → `MCP Servers` → `+ Add`
-
-
-```json
-{
-  "mcpServers": {
-    "crush-protocol": {
-      "command": "npx",
-      "args": ["-y", "@crush-protocol/mcp-client"]
-    }
-  }
-}
-```
-
-</details>
-
-<details>
-<summary><strong>Roo Code</strong></summary>
-
-[Roo Code MCP docs](https://docs.roocode.com/features/mcp/using-mcp-in-roo)
-
-
-```json
-{
-  "mcpServers": {
-    "crush-protocol": {
-      "command": "npx",
-      "args": ["-y", "@crush-protocol/mcp-client"]
-    }
-  }
-}
-```
-
-</details>
-
-<details>
-<summary><strong>Cline</strong></summary>
-
-[Cline MCP Marketplace](https://cline.bot/mcp-marketplace)
-
-
-```json
-{
-  "mcpServers": {
-    "crush-protocol": {
-      "command": "npx",
-      "args": ["-y", "@crush-protocol/mcp-client"]
-    }
-  }
-}
-```
-
-</details>
-
-<details>
-<summary><strong>Trae</strong></summary>
-
-[Trae MCP docs](https://docs.trae.ai/ide/model-context-protocol?_lang=en)
-
-
-```json
-{
-  "mcpServers": {
-    "crush-protocol": {
-      "command": "npx",
-      "args": ["-y", "@crush-protocol/mcp-client"]
-    }
-  }
-}
-```
-
-</details>
-
-<details>
-<summary><strong>Augment Code</strong></summary>
-
-1. Click hamburger menu → Settings → Tools → `+ Add MCP`
-2. Enter command: `npx -y @crush-protocol/mcp-client`
-3. Name: `crush-protocol` → Click Add
-
-Manual config in VS Code settings:
-
-```json
-"augment.advanced": {
-  "mcpServers": [
-    {
-      "name": "crush-protocol",
-      "command": "npx",
-      "args": ["-y", "@crush-protocol/mcp-client"]
-    }
-  ]
-}
-```
-
-</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)
-
-
-```json
-{
-  "mcpServers": {
-    "crush-protocol": {
-      "type": "local",
-      "command": "npx",
-      "args": ["-y", "@crush-protocol/mcp-client"]
-    }
-  }
-}
-```
-
-</details>
-
-<details>
-<summary><strong>Copilot CLI</strong></summary>
-
-Add to `~/.copilot/mcp-config.json`:
-
-
-```json
-{
-  "mcpServers": {
-    "crush-protocol": {
-      "type": "local",
-      "command": "npx",
-      "args": ["-y", "@crush-protocol/mcp-client"]
-    }
-  }
-}
-```
-
-</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)
-
-```json
-{
-  "mcpServers": {
-    "crush-protocol": {
-      "command": "npx",
-      "args": ["-y", "@crush-protocol/mcp-client"]
-    }
-  }
-}
-```
-
-</details>
-
-<details>
-<summary><strong>Warp</strong></summary>
-
-[Warp MCP docs](https://docs.warp.dev/knowledge-and-collaboration/mcp#adding-an-mcp-server) · Navigate `Settings` → `AI` → `Manage MCP servers` → `+ Add`
-
-```json
-{
-  "crush-protocol": {
-    "command": "npx",
-    "args": ["-y", "@crush-protocol/mcp-client"],
-    "env": {},
-    "working_directory": null,
-    "start_on_launch": true
-  }
-}
+npx -y @crush-protocol/mcp-client auth:status
+npx -y @crush-protocol/mcp-client doctor
 ```
 
-</details>
-
-<details>
-<summary><strong>Amp</strong></summary>
-
-[Amp MCP docs](https://ampcode.com/manual#mcp)
+## Quick Start
 
 ```sh
-amp mcp add crush-protocol -- npx -y @crush-protocol/mcp-client
-```
-
-</details>
-
-<details>
-<summary><strong>Zed</strong></summary>
-
-[Zed Context Server docs](https://zed.dev/docs/assistant/context-servers) · Add to `settings.json`
-
-```json
-{
-  "context_servers": {
-    "crush-protocol": {
-      "source": "custom",
-      "command": "npx",
-      "args": ["-y", "@crush-protocol/mcp-client"]
-    }
-  }
-}
-```
-
-</details>
-
-<details>
-<summary><strong>JetBrains AI Assistant</strong></summary>
-
-[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`
-
-
-```json
-{
-  "mcpServers": {
-    "crush-protocol": {
-      "command": "npx",
-      "args": ["-y", "@crush-protocol/mcp-client"]
-    }
-  }
-}
-```
-
-</details>
-
-<details>
-<summary><strong>Qwen Code</strong></summary>
-
-[Qwen Code MCP docs](https://qwenlm.github.io/qwen-code-docs/en/users/features/mcp/)
-
-**CLI:** `qwen mcp add crush-protocol npx -y @crush-protocol/mcp-client`
-
-```json
-{
-  "mcpServers": {
-    "crush-protocol": {
-      "command": "npx",
-      "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"]
-    }
-  }
-}
-```
-
-</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>
-
-<details>
-<summary><strong>BoltAI</strong></summary>
-
-[BoltAI docs](https://docs.boltai.com/docs/plugins/mcp-servers)
-
-```json
-{
-  "mcpServers": {
-    "crush-protocol": {
-      "command": "npx",
-      "args": ["-y", "@crush-protocol/mcp-client"]
-    }
-  }
-}
-```
-
-</details>
-
-<details>
-<summary><strong>Perplexity Desktop</strong></summary>
-
-[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`
-
-```json
-{
-  "args": ["-y", "@crush-protocol/mcp-client"],
-  "command": "npx",
-  "env": {}
-}
+npx -y @crush-protocol/mcp-client setup --cursor
+npx -y @crush-protocol/mcp-client login
+npx -y @crush-protocol/mcp-client ping
 ```
 
-</details>
+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.
 
-<details>
-<summary><strong>Kilo Code</strong></summary>
+The official hosted Crush MCP URL is built in. End users do not need to paste a server URL.
 
-[Kilo Code docs](https://kilocode.ai)
+## What You Can Do
 
+- Market data: tokens, indicators, timeframes, OHLCV
+- Backtests: schema discovery, token universe, expression validation, backtest execution
+- Live strategies: create, inspect, activate, pause, monitor
+- Market intelligence: token info, trending feeds, alpha context
 
-```json
-{
-  "mcpServers": {
-    "crush-protocol": {
-      "command": "npx",
-      "args": ["-y", "@crush-protocol/mcp-client"]
-    }
-  }
-}
-```
+Detailed tool guidance:
 
-</details>
+- [INSTRUCTIONS.md](https://github.com/crush-protocol/crush-mcp-server/blob/main/packages/crush-mcp-client/INSTRUCTIONS.md)
 
-<details>
-<summary><strong>Zencoder</strong></summary>
+## Install
 
-Go to Zencoder menu → Agent tools → Add custom MCP, paste:
+Recommended:
 
-```json
-{
-  "command": "npx",
-  "args": ["-y", "@crush-protocol/mcp-client"]
-}
+```sh
+npx -y @crush-protocol/mcp-client setup --cursor
 ```
 
-</details>
-
-<details>
-<summary><strong>Qodo Gen</strong></summary>
-
-[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`
-
+Manual MCP host config:
 
 ```json
 {
@@ -594,121 +76,26 @@ Go to Zencoder menu → Agent tools → Add custom MCP, paste:
 }
 ```
 
-</details>
-
-<details>
-<summary><strong>Using Bun or Deno</strong></summary>
-
-**Bun:**
-
-```json
-{
-  "mcpServers": {
-    "crush-protocol": {
-      "command": "bunx",
-      "args": ["-y", "@crush-protocol/mcp-client"]
-    }
-  }
-}
-```
-
-**Deno:**
-
-```json
-{
-  "mcpServers": {
-    "crush-protocol": {
-      "command": "deno",
-      "args": [
-        "run",
-        "--allow-env",
-        "--allow-net",
-        "--allow-read",
-        "--allow-write",
-        "npm:@crush-protocol/mcp-client"
-      ]
-    }
-  }
-}
-```
-
-</details>
-
-<details>
-<summary><strong>Windows</strong></summary>
-
-Use `cmd` as the command wrapper:
-
-```json
-{
-  "mcpServers": {
-    "crush-protocol": {
-      "command": "cmd",
-      "args": ["/c", "npx", "-y", "@crush-protocol/mcp-client"]
-    }
-  }
-}
-```
-
-</details>
-
-## CLI Usage
-
-```sh
-# Auth
-npx -y @crush-protocol/mcp-client login               # OAuth login (browser)
-npx -y @crush-protocol/mcp-client auth:status         # Show local Crush auth state
-npx -y @crush-protocol/mcp-client doctor              # Check auth state and connectivity
-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
-```
-
-## Troubleshooting
-
-### Tools appear, but calls fail with auth errors
-
-Run:
+## Common Commands
 
 ```sh
+npx -y @crush-protocol/mcp-client setup --all
 npx -y @crush-protocol/mcp-client login
-```
-
-Then retry the same request in your AI host.
-
-### I installed Crush but do not see tools yet
-
-Restart your AI host session after `setup`.
-
-### I want to confirm whether this machine is logged in
-
-Run:
-
-```sh
 npx -y @crush-protocol/mcp-client auth:status
-```
-
-### I want a quick connectivity check
-
-Run:
-
-```sh
 npx -y @crush-protocol/mcp-client doctor
+npx -y @crush-protocol/mcp-client ping
+npx -y @crush-protocol/mcp-client tools:list
 ```
 
-### Environment Variables
+## Troubleshooting
 
-| 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 | — |
+| 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` |
 
 ## License
 
-MIT
+Licensed under the [MIT License](https://github.com/crush-protocol/crush-mcp-server/blob/main/LICENSE).