@crush-protocol/mcp-client 0.3.0 → 0.3.2

package/README.md

@@ -1,200 +1,885 @@
 # 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)
 
 `@crush-protocol/mcp-client` is the npm entrypoint for Crush Protocol MCP.
 
-Crush Protocol is an AI-native quantitative trading product. It lets an MCP host connect to Crush and use trading-focused tools for:
+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.
 
-- strategy research
-- backtest creation and result retrieval
-- live strategy management
-- market data and signal discovery
+## Quick Setup
 
-This package connects your MCP host to the Crush MCP server over Streamable HTTP and handles OAuth automatically.
+```sh
+npx -y @crush-protocol/mcp-client setup --all
+```
+
+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`
+
+**[All Client Configurations →](#client-configuration)**
+
+## Connection Modes
+
+| Mode | Transport | Auth | Best For |
+|------|-----------|------|----------|
+| **Local** | stdio (npx) | OAuth — browser opens automatically | Most MCP clients |
+| **Remote** | Streamable HTTP | OAuth — browser opens automatically | Clients with native HTTP support |
 
-Default MCP endpoint:
+**Remote Server URL:** `https://crush-mcp-ats.dev.xexlab.com/mcp`
 
-```txt
-https://crush-mcp-ats.dev.xexlab.com/mcp
+Authentication is automatic (OAuth 2.1 Authorization Code + PKCE). On first use, a browser window opens for login; tokens are cached locally for reuse.
+
+For hosts that support URL-only MCP (Remote mode), the full flow is:
+
+1. Host connects to the MCP URL
+2. Server returns `401` with `WWW-Authenticate` header
+3. Host performs OAuth discovery and dynamic client registration
+4. Completes Authorization Code + PKCE via browser
+5. Persists tokens locally and reconnects
+
+If a host cannot complete OAuth automatically, pre-authorize with:
+
+```sh
+npx -y @crush-protocol/mcp-client login
 ```
 
-## Standard MCP Host Integration
+## Available Tools
+
+**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`
+
+**Backtest** — `get_backtest_config_schema` · `get_available_tokens` · `validate_expression` · `create_backtest` · `list_backtests`
+
+**Strategy** — `create_strategy` · `list_strategies` · `get_strategy` · `update_strategy` · `delete_strategy` · `toggle_strategy` · `get_strategy_logs`
 
-This is the recommended way to use the package.
+**Signal** — `get_signal_metadata` · `get_signals_by_category`
 
-Your MCP host launches `@crush-protocol/mcp-client` locally, and the package connects to the hosted Crush MCP endpoint.
+**Utilities** — `search_tokens` · `get_token_info` · `get_trending_tokens` · `get_alpha_feed` · `get_token_feed`
 
-### Cursor
+Detailed tool guidance is in [INSTRUCTIONS.md](./INSTRUCTIONS.md).
+
+## Client Configuration
 
-Official one-click install:
+<details>
+<summary><strong>Cursor</strong></summary>
 
-[![Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=crush-protocol&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjcnVzaC1wcm90b2NvbC9tY3AtY2xpZW50IiwiLS11cmwiLCJodHRwczovL2NydXNoLW1jcC1hdHMuZGV2LnhleGxhYi5jb20vbWNwIl19)](cursor://anysphere.cursor-deeplink/mcp/install?name=crush-protocol&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjcnVzaC1wcm90b2NvbC9tY3AtY2xpZW50IiwiLS11cmwiLCJodHRwczovL2NydXNoLW1jcC1hdHMuZGV2LnhleGxhYi5jb20vbWNwIl19)
+[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=crush-protocol&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjcnVzaC1wcm90b2NvbC9tY3AtY2xpZW50Il19)
 
-Manual config:
+[Cursor MCP docs](https://docs.cursor.com/context/model-context-protocol) · Go to: `Settings` → `Cursor Settings` → `MCP` → `Add new global MCP server`
+
+**Local:**
 
 ```json
 {
   "mcpServers": {
     "crush-protocol": {
       "command": "npx",
-      "args": ["-y", "@crush-protocol/mcp-client", "--url", "https://crush-mcp-ats.dev.xexlab.com/mcp"]
+      "args": ["-y", "@crush-protocol/mcp-client"]
+    }
+  }
+}
+```
+
+**Remote:**
+
+```json
+{
+  "mcpServers": {
+    "crush-protocol": {
+      "url": "https://crush-mcp-ats.dev.xexlab.com/mcp"
     }
   }
 }
 ```
 
-### Claude Code
+</details>
+
+<details>
+<summary><strong>Claude Code</strong></summary>
+
+[Claude Code MCP docs](https://docs.anthropic.com/en/docs/claude-code/mcp)
+
+**Local:**
 
 ```sh
-claude mcp add --scope user crush-protocol \
-  -- npx -y @crush-protocol/mcp-client \
-  --url https://crush-mcp-ats.dev.xexlab.com/mcp
+claude mcp add --scope user crush-protocol -- npx -y @crush-protocol/mcp-client
 ```
 
-### Codex
+**Remote:**
+
+```sh
+claude mcp add --scope user --transport http crush-protocol https://crush-mcp-ats.dev.xexlab.com/mcp
+```
+
+</details>
+
+<details>
+<summary><strong>OpenCode</strong></summary>
+
+[OpenCode MCP docs](https://opencode.ai/docs/mcp-servers) · Add to `~/.config/opencode/opencode.json`
+
+**Local:**
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "crush-protocol": {
+      "type": "local",
+      "command": ["npx", "-y", "@crush-protocol/mcp-client"],
+      "enabled": true
+    }
+  }
+}
+```
+
+**Remote:**
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "crush-protocol": {
+      "type": "remote",
+      "url": "https://crush-mcp-ats.dev.xexlab.com/mcp",
+      "enabled": true
+    }
+  }
+}
+```
 
-Add to `~/.codex/config.toml`:
+</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", "--url", "https://crush-mcp-ats.dev.xexlab.com/mcp"]
+args = ["-y", "@crush-protocol/mcp-client"]
 startup_timeout_ms = 20000
 ```
 
-### Gemini CLI
+**Remote:**
+
+```toml
+[mcp_servers.crush-protocol]
+url = "https://crush-mcp-ats.dev.xexlab.com/mcp"
+```
+
+</details>
+
+<details>
+<summary><strong>Google Gemini CLI</strong></summary>
 
-Add to `~/.gemini/settings.json`:
+[Gemini CLI Configuration](https://google-gemini.github.io/gemini-cli/docs/tools/mcp-server.html) · Add to `~/.gemini/settings.json`
+
+**Remote:**
+
+```json
+{
+  "mcpServers": {
+    "crush-protocol": {
+      "httpUrl": "https://crush-mcp-ats.dev.xexlab.com/mcp"
+    }
+  }
+}
+```
+
+**Local:**
 
 ```json
 {
   "mcpServers": {
     "crush-protocol": {
       "command": "npx",
-      "args": ["-y", "@crush-protocol/mcp-client", "--url", "https://crush-mcp-ats.dev.xexlab.com/mcp"]
+      "args": ["-y", "@crush-protocol/mcp-client"]
     }
   }
 }
 ```
 
-### OpenCode
+</details>
+
+<details>
+<summary><strong>VS Code</strong></summary>
 
-Add to `~/.config/opencode/opencode.json`:
+[VS Code MCP docs](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) · Add to `.vscode/mcp.json`
+
+**Remote:**
 
 ```json
 {
-  "$schema": "https://opencode.ai/config.json",
-  "mcp": {
+  "servers": {
+    "crush-protocol": {
+      "type": "http",
+      "url": "https://crush-mcp-ats.dev.xexlab.com/mcp"
+    }
+  }
+}
+```
+
+**Local:**
+
+```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)
+
+**Remote:**
+
+```json
+{
+  "mcpServers": {
+    "crush-protocol": {
+      "serverUrl": "https://crush-mcp-ats.dev.xexlab.com/mcp"
+    }
+  }
+}
+```
+
+**Local:**
+
+```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`
+
+**Local:**
+
+```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`
+
+**Remote:**
+
+```json
+{
+  "mcpServers": {
+    "crush-protocol": {
+      "url": "https://crush-mcp-ats.dev.xexlab.com/mcp"
+    }
+  }
+}
+```
+
+**Local:**
+
+```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)
+
+**Remote:**
+
+```json
+{
+  "mcpServers": {
+    "crush-protocol": {
+      "type": "streamable-http",
+      "url": "https://crush-mcp-ats.dev.xexlab.com/mcp"
+    }
+  }
+}
+```
+
+**Local:**
+
+```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)
+
+**Remote:**
+
+```json
+{
+  "mcpServers": {
+    "crush-protocol": {
+      "url": "https://crush-mcp-ats.dev.xexlab.com/mcp",
+      "type": "streamableHttp"
+    }
+  }
+}
+```
+
+**Local:**
+
+```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)
+
+**Remote:**
+
+```json
+{
+  "mcpServers": {
+    "crush-protocol": {
+      "url": "https://crush-mcp-ats.dev.xexlab.com/mcp"
+    }
+  }
+}
+```
+
+**Local:**
+
+```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)
+
+**Remote:**
+
+```json
+{
+  "mcpServers": {
+    "crush-protocol": {
+      "type": "http",
+      "url": "https://crush-mcp-ats.dev.xexlab.com/mcp"
+    }
+  }
+}
+```
+
+**Local:**
+
+```json
+{
+  "mcpServers": {
     "crush-protocol": {
       "type": "local",
-      "command": ["npx", "-y", "@crush-protocol/mcp-client", "--url", "https://crush-mcp-ats.dev.xexlab.com/mcp"],
-      "enabled": true
+      "command": "npx",
+      "args": ["-y", "@crush-protocol/mcp-client"]
     }
   }
 }
 ```
 
-## Quick Setup Helper
+</details>
 
-If you do not want to edit config files manually, the CLI can write the MCP configuration for you.
+<details>
+<summary><strong>Copilot CLI</strong></summary>
 
-```sh
-npx -y @crush-protocol/mcp-client setup --all
+Add to `~/.copilot/mcp-config.json`:
+
+**Remote:**
+
+```json
+{
+  "mcpServers": {
+    "crush-protocol": {
+      "type": "http",
+      "url": "https://crush-mcp-ats.dev.xexlab.com/mcp"
+    }
+  }
+}
+```
+
+**Local:**
+
+```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
+  }
+}
 ```
 
-Single target setup:
+</details>
+
+<details>
+<summary><strong>Amp</strong></summary>
+
+[Amp MCP docs](https://ampcode.com/manual#mcp)
 
 ```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 --gemini
-npx -y @crush-protocol/mcp-client setup --opencode
+amp mcp add crush-protocol https://crush-mcp-ats.dev.xexlab.com/mcp
 ```
 
-## What Users Get
+</details>
 
-With this package, an MCP client can call Crush tools such as:
+<details>
+<summary><strong>Zed</strong></summary>
 
-- `get_backtest_config_schema`
-- `get_available_tokens`
-- `create_backtest`
-- `get_backtest_result`
-- `list_backtests`
-- `create_strategy`
-- `list_strategies`
-- `toggle_strategy`
-- `get_strategy_logs`
+[Zed Context Server docs](https://zed.dev/docs/assistant/context-servers) · Add to `settings.json`
 
-Detailed tool guidance is in [INSTRUCTIONS.md](./INSTRUCTIONS.md).
+```json
+{
+  "context_servers": {
+    "crush-protocol": {
+      "source": "custom",
+      "command": "npx",
+      "args": ["-y", "@crush-protocol/mcp-client"]
+    }
+  }
+}
+```
 
-## Authentication
+</details>
 
-Crush MCP uses OAuth 2.1 Authorization Code + PKCE.
+<details>
+<summary><strong>JetBrains AI Assistant</strong></summary>
 
-Default behavior:
+[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`
 
-- you provide only the MCP server URL
-- the client completes browser OAuth when needed
-- tokens are stored locally for reuse
+**Remote:**
 
-Optional token overrides are also supported:
+```json
+{
+  "mcpServers": {
+    "crush-protocol": {
+      "url": "https://crush-mcp-ats.dev.xexlab.com/mcp"
+    }
+  }
+}
+```
 
-- `--token <access-token>`
-- `CRUSH_OAUTH_ACCESS_TOKEN=<access-token>`
+**Local:**
 
-Priority order:
+```json
+{
+  "mcpServers": {
+    "crush-protocol": {
+      "command": "npx",
+      "args": ["-y", "@crush-protocol/mcp-client"]
+    }
+  }
+}
+```
 
-1. `--token`
-2. `CRUSH_OAUTH_ACCESS_TOKEN`
-3. automatic OAuth with local token cache
+</details>
 
-Optional pre-login:
+<details>
+<summary><strong>Qwen Code</strong></summary>
 
-```sh
-npx -y @crush-protocol/mcp-client login --url https://crush-mcp-ats.dev.xexlab.com/mcp
+[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`
+
+**Remote** (add to `~/.qwen/settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "crush-protocol": {
+      "httpUrl": "https://crush-mcp-ats.dev.xexlab.com/mcp"
+    }
+  }
+}
 ```
 
-## CLI / SDK Usage
+**Local:**
 
-Use this when you want to use Crush from Node.js directly.
+```json
+{
+  "mcpServers": {
+    "crush-protocol": {
+      "command": "npx",
+      "args": ["-y", "@crush-protocol/mcp-client"]
+    }
+  }
+}
+```
 
-CLI examples:
+</details>
 
-```sh
-npx -y @crush-protocol/mcp-client help
-npx -y @crush-protocol/mcp-client tools:list --url https://crush-mcp-ats.dev.xexlab.com/mcp
-npx -y @crush-protocol/mcp-client ping --url https://crush-mcp-ats.dev.xexlab.com/mcp
-npx -y @crush-protocol/mcp-client backtest:schema --url https://crush-mcp-ats.dev.xexlab.com/mcp
-npx -y @crush-protocol/mcp-client backtest:list --url https://crush-mcp-ats.dev.xexlab.com/mcp --limit 10
+<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"]
+    }
+  }
+}
 ```
 
-SDK example:
+</details>
 
-```ts
-import { OAuthRemoteMcpClient, BacktestClient } from "@crush-protocol/mcp-client";
+<details>
+<summary><strong>Visual Studio 2022</strong></summary>
 
-const mcp = new OAuthRemoteMcpClient({
-  serverUrl: "https://crush-mcp-ats.dev.xexlab.com/mcp",
-});
+[Visual Studio MCP docs](https://learn.microsoft.com/visualstudio/ide/mcp-servers?view=vs-2022)
 
-await mcp.connect();
+**Remote:**
 
-const backtests = new BacktestClient(mcp);
-const result = await backtests.list({ limit: 10 });
+```json
+{
+  "inputs": [],
+  "servers": {
+    "crush-protocol": {
+      "type": "http",
+      "url": "https://crush-mcp-ats.dev.xexlab.com/mcp"
+    }
+  }
+}
+```
+
+**Local:**
+
+```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": {}
+}
+```
+
+</details>
+
+<details>
+<summary><strong>Kilo Code</strong></summary>
+
+[Kilo Code docs](https://kilocode.ai)
+
+**Remote:**
+
+```json
+{
+  "mcpServers": {
+    "crush-protocol": {
+      "type": "streamable-http",
+      "url": "https://crush-mcp-ats.dev.xexlab.com/mcp"
+    }
+  }
+}
+```
+
+**Local:**
+
+```json
+{
+  "mcpServers": {
+    "crush-protocol": {
+      "command": "npx",
+      "args": ["-y", "@crush-protocol/mcp-client"]
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><strong>Zencoder</strong></summary>
+
+Go to Zencoder menu → Agent tools → Add custom MCP, paste:
+
+```json
+{
+  "command": "npx",
+  "args": ["-y", "@crush-protocol/mcp-client"]
+}
+```
+
+</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`
+
+**Remote:**
+
+```json
+{
+  "mcpServers": {
+    "crush-protocol": {
+      "url": "https://crush-mcp-ats.dev.xexlab.com/mcp"
+    }
+  }
+}
+```
+
+**Local:**
+
+```json
+{
+  "mcpServers": {
+    "crush-protocol": {
+      "command": "npx",
+      "args": ["-y", "@crush-protocol/mcp-client"]
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><strong>Using Bun or Deno</strong></summary>
+
+**Bun:**
 
-console.log(result);
+```json
+{
+  "mcpServers": {
+    "crush-protocol": {
+      "command": "bunx",
+      "args": ["-y", "@crush-protocol/mcp-client"]
+    }
+  }
+}
+```
 
-await mcp.close();
+**Deno:**
+
+```json
+{
+  "mcpServers": {
+    "crush-protocol": {
+      "command": "deno",
+      "args": [
+        "run",
+        "--allow-env",
+        "--allow-net",
+        "--allow-read",
+        "--allow-write",
+        "npm:@crush-protocol/mcp-client"
+      ]
+    }
+  }
+}
 ```
 
-## Environment Variables
+</details>
 
-| Variable | Description |
-| --- | --- |
-| `CRUSH_MCP_SERVER_URL` | MCP server URL. Default: `https://crush-mcp-ats.dev.xexlab.com/mcp` |
-| `CRUSH_OAUTH_ACCESS_TOKEN` | Optional OAuth access token override |
+<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
+npx -y @crush-protocol/mcp-client login              # 预授权 OAuth（浏览器登录）
+npx -y @crush-protocol/mcp-client setup --all         # 写入所有客户端配置
+npx -y @crush-protocol/mcp-client tools:list          # 列出可用工具
+npx -y @crush-protocol/mcp-client ping                # 测试连通性
+npx -y @crush-protocol/mcp-client backtest:schema     # 获取回测配置 schema
+npx -y @crush-protocol/mcp-client backtest:list --limit 10
+```
 
 ## License
 

package/dist/cli.js

@@ -4,10 +4,10 @@ import { BacktestClient } from "./backtest/backtestClient.js";
 import { ClickHouseDirectClient } from "./clickhouse/directClient.js";
 import { OAuthRemoteMcpClient } from "./mcp/oauthRemoteClient.js";
 import { RemoteMcpClient } from "./mcp/remoteClient.js";
-import { installClientConfig } from "./setup/setupClients.js";
-const DEFAULT_MCP_SERVER_URL = "https://crush-mcp-ats.dev.xexlab.com/mcp";
+import { ALL_TARGETS, installClientConfig } from "./setup/setupClients.js";
+const MCP_SERVER_URL = "https://crush-mcp-ats.dev.xexlab.com/mcp";
 const printUsage = () => {
-    console.log(`\ncrush-mcp-client\n\nGeneral:\n  login [--url URL]\n  setup [--cursor] [--claude] [--codex] [--gemini] [--opencode] [--all] [--scope user|project] [--url URL]\n  tools:list [--url URL] [--token TOKEN]\n  tool:call --name TOOL_NAME [--args JSON] [--url URL] [--token TOKEN]\n  ping [--url URL] [--token TOKEN]\n\nBacktest:\n  backtest:schema [--url URL] [--token TOKEN]\n  backtest:tokens [--platform PLATFORM] [--url URL] [--token TOKEN]\n  backtest:validate --expression JSON [--data-source kline|factors] [--url URL] [--token TOKEN]\n  backtest:create --config JSON [--backtest-id ID] [--url URL] [--token TOKEN]\n  backtest:list [--status STATUS] [--limit N] [--offset N] [--url URL] [--token TOKEN]\n\nClickHouse:\n  clickhouse:list-tables [--ch-host HOST --ch-port PORT --ch-user USER --ch-password PASS --ch-database DB]\n  clickhouse:query --sql SQL [--ch-host HOST --ch-port PORT --ch-user USER --ch-password PASS --ch-database DB --ch-row-cap N]\n\nAuth:\n  --token TOKEN uses a provided OAuth access token.\n  Without --token, OAuth runs automatically in the browser when needed.\n\nEnv:\n  CRUSH_MCP_SERVER_URL, CRUSH_OAUTH_ACCESS_TOKEN\n  CH_HOST, CH_PORT, CH_USER, CH_PASSWORD, CH_DATABASE, CH_ROW_CAP\n`);
+    console.log(`\ncrush-mcp-client\n\nGeneral:\n  login\n  setup [--cursor] [--claude] [--codex] [--gemini] [--opencode] [--all] [--scope user|project]\n  tools:list [--token TOKEN]\n  tool:call --name TOOL_NAME [--args JSON] [--token TOKEN]\n  ping [--token TOKEN]\n\nBacktest:\n  backtest:schema [--token TOKEN]\n  backtest:tokens [--platform PLATFORM] [--token TOKEN]\n  backtest:validate --expression JSON [--data-source kline|factors] [--token TOKEN]\n  backtest:create --config JSON [--backtest-id ID] [--token TOKEN]\n  backtest:list [--status STATUS] [--limit N] [--offset N] [--token TOKEN]\n\nClickHouse:\n  clickhouse:list-tables [--ch-host HOST --ch-port PORT --ch-user USER --ch-password PASS --ch-database DB]\n  clickhouse:query --sql SQL [--ch-host HOST --ch-port PORT --ch-user USER --ch-password PASS --ch-database DB --ch-row-cap N]\n\nAuth:\n  --token TOKEN uses a provided OAuth access token.\n  Without --token, OAuth runs automatically in the browser when needed.\n\nEnv:\n  CRUSH_OAUTH_ACCESS_TOKEN\n  CH_HOST, CH_PORT, CH_USER, CH_PASSWORD, CH_DATABASE, CH_ROW_CAP\n`);
 };
 const parseFlags = (args) => {
     const flags = {};
@@ -32,15 +32,12 @@ const requireString = (value, message) => {
     }
     return value;
 };
-const getServerUrl = (flags) => typeof flags.url === "string"
-    ? flags.url
-    : (process.env.CRUSH_MCP_SERVER_URL ?? DEFAULT_MCP_SERVER_URL);
+const getServerUrl = () => MCP_SERVER_URL;
 const getSetupTargets = (flags) => {
-    const explicitTargets = ["cursor", "claude", "codex", "gemini", "opencode"].filter((target) => flags[target] === true);
     if (flags.all === true) {
-        return ["cursor", "claude", "codex", "gemini", "opencode"];
+        return [...ALL_TARGETS];
     }
-    return explicitTargets;
+    return ALL_TARGETS.filter((target) => flags[target] === true);
 };
 /**
  * 创建 MCP 客户端（统一认证入口）
@@ -54,7 +51,7 @@ const getSetupTargets = (flags) => {
  *    - 无 token → 自动拉起浏览器登录
  */
 const createSmartClient = (flags) => {
-    const serverUrl = getServerUrl(flags);
+    const serverUrl = getServerUrl();
     // 显式传了 token → 用简单客户端
     const explicitToken = typeof flags.token === "string" ? flags.token : process.env.CRUSH_OAUTH_ACCESS_TOKEN || "";
     if (explicitToken) {
@@ -116,7 +113,7 @@ const run = async () => {
     const flags = parseFlags(rest);
     switch (command) {
         case "login": {
-            const serverUrl = getServerUrl(flags);
+            const serverUrl = getServerUrl();
             const client = new OAuthRemoteMcpClient({ serverUrl });
             try {
                 await client.ensureAuthorized();
@@ -130,16 +127,15 @@ const run = async () => {
         case "setup": {
             const targets = getSetupTargets(flags);
             if (targets.length === 0) {
-                throw new Error("Specify at least one setup target: --cursor, --claude, --codex, --gemini, --opencode, or --all");
+                throw new Error(`Specify at least one setup target: ${ALL_TARGETS.map((t) => "--" + t).join(", ")}, or --all`);
             }
             const rawScope = typeof flags.scope === "string" ? flags.scope : "user";
             if (rawScope !== "user" && rawScope !== "project") {
                 throw new Error("Invalid --scope. Expected 'user' or 'project'.");
             }
             const scope = rawScope;
-            const serverUrl = getServerUrl(flags);
             for (const target of targets) {
-                const location = installClientConfig(target, serverUrl, scope);
+                const location = installClientConfig(target, scope);
                 console.log(`[setup] ${target}: configured (${location})`);
             }
             return;

package/dist/setup/setupClients.d.ts

@@ -1,3 +1,4 @@
-export type SetupTarget = "cursor" | "claude" | "codex" | "gemini" | "opencode";
+export type SetupTarget = "cursor" | "claude" | "codex" | "gemini" | "opencode" | "vscode" | "windsurf" | "claude-desktop" | "warp";
 export type SetupScope = "user" | "project";
-export declare const installClientConfig: (target: SetupTarget, serverUrl: string, scope: SetupScope) => string;
+export declare const ALL_TARGETS: readonly SetupTarget[];
+export declare const installClientConfig: (target: SetupTarget, scope: SetupScope) => string;

package/dist/setup/setupClients.js

@@ -4,6 +4,18 @@ import os from "node:os";
 import path from "node:path";
 const SERVER_NAME = "crush-protocol";
 const PACKAGE_NAME = "@crush-protocol/mcp-client";
+const REMOTE_URL = "https://crush-mcp-ats.dev.xexlab.com/mcp";
+export const ALL_TARGETS = [
+    "cursor",
+    "claude",
+    "codex",
+    "gemini",
+    "opencode",
+    "vscode",
+    "windsurf",
+    "claude-desktop",
+    "warp",
+];
 const ensureDir = (filePath) => {
     fs.mkdirSync(path.dirname(filePath), { recursive: true });
 };
@@ -21,37 +33,39 @@ const writeJson = (filePath, value) => {
     ensureDir(filePath);
     fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
 };
-const createNpxConfig = (serverUrl) => ({
+const createNpxConfig = () => ({
     command: "npx",
-    args: ["-y", PACKAGE_NAME, "--url", serverUrl],
+    args: ["-y", PACKAGE_NAME],
 });
+// ─── Cursor ─────────────────────────────────────────────
 const getCursorConfigPath = (scope) => scope === "project"
     ? path.join(process.cwd(), ".cursor", "mcp.json")
     : path.join(os.homedir(), ".cursor", "mcp.json");
-const getGeminiConfigPath = () => path.join(os.homedir(), ".gemini", "settings.json");
-const getOpenCodeConfigPath = (scope) => scope === "project"
-    ? path.join(process.cwd(), "opencode.json")
-    : path.join(os.homedir(), ".config", "opencode", "opencode.json");
-const getCodexConfigPath = () => path.join(os.homedir(), ".codex", "config.toml");
-const installCursor = (serverUrl, scope) => {
+const installCursor = (scope) => {
     const filePath = getCursorConfigPath(scope);
     const config = readJson(filePath);
     const mcpServers = (config.mcpServers ?? {});
-    mcpServers[SERVER_NAME] = createNpxConfig(serverUrl);
+    mcpServers[SERVER_NAME] = createNpxConfig();
     config.mcpServers = mcpServers;
     writeJson(filePath, config);
     return filePath;
 };
-const installGemini = (serverUrl) => {
+// ─── Gemini CLI ─────────────────────────────────────────
+const getGeminiConfigPath = () => path.join(os.homedir(), ".gemini", "settings.json");
+const installGemini = () => {
     const filePath = getGeminiConfigPath();
     const config = readJson(filePath);
     const mcpServers = (config.mcpServers ?? {});
-    mcpServers[SERVER_NAME] = createNpxConfig(serverUrl);
+    mcpServers[SERVER_NAME] = createNpxConfig();
     config.mcpServers = mcpServers;
     writeJson(filePath, config);
     return filePath;
 };
-const installOpenCode = (serverUrl, scope) => {
+// ─── OpenCode ───────────────────────────────────────────
+const getOpenCodeConfigPath = (scope) => scope === "project"
+    ? path.join(process.cwd(), "opencode.json")
+    : path.join(os.homedir(), ".config", "opencode", "opencode.json");
+const installOpenCode = (scope) => {
     const filePath = getOpenCodeConfigPath(scope);
     const config = readJson(filePath);
     const mcp = (config.mcp ?? {});
@@ -60,18 +74,20 @@ const installOpenCode = (serverUrl, scope) => {
     }
     mcp[SERVER_NAME] = {
         type: "local",
-        command: ["npx", "-y", PACKAGE_NAME, "--url", serverUrl],
+        command: ["npx", "-y", PACKAGE_NAME],
         enabled: true,
     };
     config.mcp = mcp;
     writeJson(filePath, config);
     return filePath;
 };
-const installCodex = (serverUrl) => {
+// ─── OpenAI Codex ───────────────────────────────────────
+const getCodexConfigPath = () => path.join(os.homedir(), ".codex", "config.toml");
+const installCodex = () => {
     const filePath = getCodexConfigPath();
     const section = `[mcp_servers.${SERVER_NAME}]
 command = "npx"
-args = ["-y", "${PACKAGE_NAME}", "--url", "${serverUrl}"]
+args = ["-y", "${PACKAGE_NAME}"]
 startup_timeout_ms = 20000
 `;
     ensureDir(filePath);
@@ -82,11 +98,12 @@ startup_timeout_ms = 20000
     }
     return filePath;
 };
-const installClaude = (serverUrl, scope) => {
+// ─── Claude Code CLI ────────────────────────────────────
+const installClaude = (scope) => {
     const configJson = JSON.stringify({
         type: "stdio",
         command: "npx",
-        args: ["-y", PACKAGE_NAME, "--url", serverUrl],
+        args: ["-y", PACKAGE_NAME],
     });
     const result = spawnSync("claude", ["mcp", "add-json", "--scope", scope, SERVER_NAME, configJson], {
         stdio: "pipe",
@@ -101,18 +118,91 @@ const installClaude = (serverUrl, scope) => {
     }
     return "claude-managed-config";
 };
-export const installClientConfig = (target, serverUrl, scope) => {
+// ─── VS Code ────────────────────────────────────────────
+const getVSCodeConfigPath = (scope) => scope === "project"
+    ? path.join(process.cwd(), ".vscode", "mcp.json")
+    : path.join(os.homedir(), ".vscode", "mcp.json");
+const installVSCode = (scope) => {
+    const filePath = getVSCodeConfigPath(scope);
+    const config = readJson(filePath);
+    const servers = (config.servers ?? {});
+    servers[SERVER_NAME] = {
+        type: "stdio",
+        command: "npx",
+        args: ["-y", PACKAGE_NAME],
+    };
+    config.servers = servers;
+    writeJson(filePath, config);
+    return filePath;
+};
+// ─── Windsurf ───────────────────────────────────────────
+const getWindsurfConfigPath = () => path.join(os.homedir(), ".codeium", "windsurf", "mcp_config.json");
+const installWindsurf = () => {
+    const filePath = getWindsurfConfigPath();
+    const config = readJson(filePath);
+    const mcpServers = (config.mcpServers ?? {});
+    mcpServers[SERVER_NAME] = createNpxConfig();
+    config.mcpServers = mcpServers;
+    writeJson(filePath, config);
+    return filePath;
+};
+// ─── Claude Desktop ─────────────────────────────────────
+const getClaudeDesktopConfigPath = () => {
+    const platform = os.platform();
+    if (platform === "darwin") {
+        return path.join(os.homedir(), "Library", "Application Support", "Claude", "claude_desktop_config.json");
+    }
+    if (platform === "win32") {
+        return path.join(process.env.APPDATA ?? path.join(os.homedir(), "AppData", "Roaming"), "Claude", "claude_desktop_config.json");
+    }
+    // Linux
+    return path.join(os.homedir(), ".config", "Claude", "claude_desktop_config.json");
+};
+const installClaudeDesktop = () => {
+    const filePath = getClaudeDesktopConfigPath();
+    const config = readJson(filePath);
+    const mcpServers = (config.mcpServers ?? {});
+    mcpServers[SERVER_NAME] = createNpxConfig();
+    config.mcpServers = mcpServers;
+    writeJson(filePath, config);
+    return filePath;
+};
+// ─── Warp ───────────────────────────────────────────────
+const getWarpConfigPath = () => path.join(os.homedir(), ".warp", "mcp_config.json");
+const installWarp = () => {
+    const filePath = getWarpConfigPath();
+    const config = readJson(filePath);
+    config[SERVER_NAME] = {
+        command: "npx",
+        args: ["-y", PACKAGE_NAME],
+        env: {},
+        working_directory: null,
+        start_on_launch: true,
+    };
+    writeJson(filePath, config);
+    return filePath;
+};
+// ─── Router ─────────────────────────────────────────────
+export const installClientConfig = (target, scope) => {
     switch (target) {
         case "cursor":
-            return installCursor(serverUrl, scope);
+            return installCursor(scope);
         case "claude":
-            return installClaude(serverUrl, scope);
+            return installClaude(scope);
         case "codex":
-            return installCodex(serverUrl);
+            return installCodex();
         case "gemini":
-            return installGemini(serverUrl);
+            return installGemini();
         case "opencode":
-            return installOpenCode(serverUrl, scope);
+            return installOpenCode(scope);
+        case "vscode":
+            return installVSCode(scope);
+        case "windsurf":
+            return installWindsurf();
+        case "claude-desktop":
+            return installClaudeDesktop();
+        case "warp":
+            return installWarp();
         default:
             throw new Error(`Unsupported setup target: ${target}`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crush-protocol/mcp-client",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Crush MCP npm client package (remote Streamable HTTP + optional ClickHouse direct)",
   "type": "module",
   "license": "MIT",