@crush-protocol/mcp-client 0.4.19 ā†’ 0.4.21

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/INSTRUCTIONS.md +45 -30
  2. package/README.md +34 -7
  3. package/dist/cli.js +9 -7
  4. package/dist/mcp/proxy.js +10 -19
  5. package/package.json +3 -3
package/INSTRUCTIONS.md CHANGED
@@ -45,26 +45,42 @@ After login, credentials are cached locally and reused across supported hosts.
45
45
 
46
46
  ### šŸ“ˆ Market Data (ClickHouse)
47
47
 
48
- | Tool | Purpose |
49
- | ----------------------- | ---------------------------------------------------------------------------- |
50
- | `list_tables` | List all ClickHouse tables with descriptions. |
51
- | `list_tokens` | List available trading pairs in the data warehouse. |
52
- | `list_indicators` | List pre-computed indicators with categories. |
53
- | `list_timeframes` | List available data timeframes. |
54
- | `get_data_range` | Get earliest/latest date for a token + timeframe. |
55
- | `check_query_size` | Estimate row count before fetching. **Call this before large queries.** |
56
- | `fetch_ohlcv` | Fetch OHLCV candlestick data (row cap: 5000). |
57
- | `fetch_indicator` | Fetch pre-computed indicator values (row cap: 5000). |
58
- | `get_connection_config` | Get read-only ClickHouse credentials for local processing of large datasets. |
59
-
60
- ### šŸ§® Custom Indicators
61
-
62
- | Tool | Purpose |
63
- | ------------------------- | ------------------------------------- |
64
- | `save_custom_indicator` | Save a custom indicator formula. |
65
- | `list_custom_indicators` | List user's saved indicator formulas. |
66
- | `get_custom_indicator` | Retrieve a formula by name. |
67
- | `delete_custom_indicator` | Delete a formula by name. |
48
+ | Tool | Purpose |
49
+ | ----------------------------------- | -------------------------------------------------------------------- |
50
+ | `crush_ch_list_tables` | List all available tables with descriptions and row counts. |
51
+ | `crush_ch_describe_table` | Get column definitions, types, and comments for a table. |
52
+ | `crush_ch_data_freshness` | Check data freshness for all tables. |
53
+ | `crush_ch_list_indicators` | List pre-computed indicators with categories. |
54
+ | `crush_ch_find_data` | Search data catalog by concept (e.g. "funding rate", "BTC price"). |
55
+ | `crush_ch_query_market_ohlcv` | Query OHLCV, OI, funding, liquidation data (row cap: 5000). |
56
+ | `crush_ch_query_derivatives` | Query derivatives data with interval filter. |
57
+ | `crush_ch_query_global_metrics` | Query global market metrics or per-coin derivatives metrics. |
58
+ | `crush_ch_query_token_market_info` | Query market snapshot data (32 coins, hourly). |
59
+ | `crush_ch_query_hyperliquid_ws` | Query real-time 1m candles (229 perps). |
60
+ | `crush_ch_query_exchange_data` | Query unified exchange data (futures + spot). |
61
+ | `crush_ch_query_sentiment` | Query sentiment consensus data. |
62
+ | `crush_ch_search_twitter` | Search collected tweets by keyword, author, engagement. |
63
+ | `crush_ch_search_news_feeds` | Search aggregated news with sentiment and token filters. |
64
+ | `crush_ch_query_token_list` | Query token snapshots (price, market cap, supply, unlock info). |
65
+ | `crush_ch_query_unlock_events` | Query token unlock schedules. |
66
+ | `crush_ch_run_query` | Run custom read-only SQL (SELECT only, row cap: 5000). |
67
+
68
+ ### šŸ“‰ Liquidation & Risk
69
+
70
+ | Tool | Purpose |
71
+ | -------------------------------------- | ------------------------------------------------------------- |
72
+ | `crush_ch_query_liq_coin_summary` | Per-coin liquidation volume/count by time window. |
73
+ | `crush_ch_query_liq_maxpain` | Max Pain risk scores and critical liquidation price levels. |
74
+ | `crush_ch_query_liq_exchange` | Liquidation distribution across exchanges. |
75
+ | `crush_ch_query_liq_history` | Historical liquidation volume time series. |
76
+ | `crush_ch_query_liq_heatmap_snapshot` | Liquidation heatmap aggregated by price level. |
77
+ | `crush_ch_query_liq_whale_positions` | Whale positions with liquidation prices. |
78
+ | `crush_ext_fear_greed_index` | Fear & Greed Index with BTC price history. |
79
+ | `crush_ext_bitcoin_active_addresses` | Bitcoin daily active address count. |
80
+ | `crush_ext_liq_heatmap` | Real-time liquidation heatmap. |
81
+ | `crush_ext_liq_maxpain` | Real-time Max Pain risk scores for all coins. |
82
+ | `crush_ext_liq_coin_snapshot` | Real-time per-coin liquidation snapshot. |
83
+ | `crush_ext_liq_whale_positions` | Real-time whale positions on-chain. |
68
84
 
69
85
  ### āš™ļø Strategy Management
70
86
 
@@ -78,11 +94,11 @@ After login, credentials are cached locally and reused across supported hosts.
78
94
  | `toggle_strategy` | Activate or deactivate live trading. |
79
95
  | `get_strategy_logs` | Get execution logs for a strategy. |
80
96
 
81
- ### šŸ’° Trading (Hyperliquid)
97
+ ### šŸ’° Trading
82
98
 
83
99
  | Tool | Purpose |
84
100
  | ------------------ | -------------------------------------------------------- |
85
- | `place_order` | Place a market or limit order on Hyperliquid perpetuals. |
101
+ | `place_order` | Place a market or limit order on perpetuals. |
86
102
  | `get_positions` | Get current open positions. |
87
103
  | `get_account_info` | Get account balance, margin, and PnL. |
88
104
  | `get_portfolio` | Get all balances across chains. |
@@ -96,7 +112,6 @@ After login, credentials are cached locally and reused across supported hosts.
96
112
  | `get_trending_tokens` | Get trending tokens on a given chain. |
97
113
  | `get_alpha_feed` | Get recent alpha posts from Twitter and communities. |
98
114
  | `get_token_feed` | Get token-specific news and events. |
99
- | `fetch_news` | Fetch news and intel feeds with keyword/token filters. |
100
115
 
101
116
  ---
102
117
 
@@ -119,11 +134,11 @@ After login, credentials are cached locally and reused across supported hosts.
119
134
  ### Market Research
120
135
 
121
136
  ```
122
- 1. list_tokens / search_tokens ā†’ Find tokens of interest
123
- 2. get_data_range ā†’ Check data availability
124
- 3. check_query_size ā†’ Estimate dataset size
125
- 4. fetch_ohlcv / fetch_indicator ā†’ Fetch data (ā‰¤5000 rows)
126
- ā””ā”€ If too large: get_connection_config ā†’ write Python script for local processing
137
+ 1. crush_ch_list_tables / crush_ch_find_data ā†’ Discover available data
138
+ 2. crush_ch_list_indicators ā†’ Browse indicator catalog
139
+ 3. crush_ch_query_market_ohlcv ā†’ Fetch OHLCV data (ā‰¤5000 rows)
140
+ 4. crush_ch_query_global_metrics ā†’ Check market-wide metrics
141
+ 5. crush_ch_run_query ā†’ Custom SQL for complex analysis
127
142
  ```
128
143
 
129
144
  ### Go Live
@@ -141,8 +156,8 @@ After login, credentials are cached locally and reused across supported hosts.
141
156
  ## Important Rules
142
157
 
143
158
  1. **Backtest is async**: `create_backtest` returns immediately. Refresh with `list_backtests` until status is `COMPLETED` or `FAILED`. Typical wait: 30sā€“3min.
144
- 2. **Data row caps**: `fetch_ohlcv` and `fetch_indicator` have a 5000 row limit. For larger datasets, use `get_connection_config` and process locally.
159
+ 2. **Data row caps**: All ClickHouse query tools have a 5000 row limit. Use narrower time ranges or filters to stay within the cap.
145
160
  3. **Always validate first**: Call `validate_expression` before using an expression in `create_backtest` to catch errors early.
146
161
  4. **Signal discovery order**: Always call `get_signal_metadata` ā†’ `get_signals_by_category` before building expressions. Don't guess signal IDs.
147
162
  5. **Strategy lifecycle**: Backtest ā†’ Create Strategy ā†’ Toggle Active. A strategy must be deactivated before deletion.
148
- 6. **Trading is real**: `place_order` executes real trades on Hyperliquid. Always confirm with the user before placing orders.
163
+ 6. **Trading is real**: `place_order` executes real trades. Always confirm with the user before placing orders.
package/README.md CHANGED
@@ -1,23 +1,34 @@
1
- # Crush Protocol MCP Client
1
+ <!-- AI Agent Metadata:
2
+ Product: Crush ā€” AI-native quantitative trading platform.
3
+ Aliases: Crush, Crush MCP, Crush Protocol MCP, @crush-protocol/mcp-client
4
+ Type: MCP SERVER ā€” do NOT use npm install. Use the setup commands below.
5
+
6
+ Install:
7
+ Claude Code: claude mcp add --scope user crush-protocol -- npx -y @crush-protocol/mcp-client
8
+ Cursor: npx -y @crush-protocol/mcp-client setup --cursor
9
+ All hosts: npx -y @crush-protocol/mcp-client setup --all
2
10
 
3
- ![Crush banner](https://crush.xyz/static/landing-page/og-hero.jpg)
11
+ Troubleshooting: npx -y @crush-protocol/mcp-client doctor
12
+ -->
13
+
14
+ # Crush Protocol MCP Client
4
15
 
5
16
  [![npm version](https://img.shields.io/npm/v/@crush-protocol/mcp-client)](https://www.npmjs.com/package/@crush-protocol/mcp-client)
6
17
  [![MIT licensed](https://img.shields.io/npm/l/@crush-protocol/mcp-client)](https://github.com/crush-protocol/crush-mcp-server/blob/main/LICENSE)
7
18
 
8
19
  Official MCP client for connecting Cursor, Claude Code, Codex, Gemini CLI, Windsurf, VS Code, and other MCP hosts to Crush.
9
20
 
10
- <!-- AI Agent Metadata: treat Crush / Crush MCP / Crush Protocol MCP / @crush-protocol/mcp-client as the same product. If tools fail after install, run: auth:status then doctor. -->
21
+ > **This is an MCP server, not a library.** Do not use `npm install`. Use the setup command below.
11
22
 
12
23
  ## Quick Start
13
24
 
14
25
  ```sh
15
- npx -y @crush-protocol/mcp-client setup --cursor # write MCP config
16
- npx -y @crush-protocol/mcp-client login # OAuth login (one-time)
17
- npx -y @crush-protocol/mcp-client ping # verify connectivity
26
+ npx -y @crush-protocol/mcp-client setup --cursor # Cursor
27
+ npx -y @crush-protocol/mcp-client setup --claude # Claude Code
28
+ npx -y @crush-protocol/mcp-client setup --all # all supported hosts
18
29
  ```
19
30
 
20
- The hosted MCP URL is built in ā€” no server URL needed.
31
+ First tool call will open browser for OAuth login automatically. No separate `login` step needed.
21
32
 
22
33
  ## What You Can Do
23
34
 
@@ -30,6 +41,22 @@ Detailed tool guidance:
30
41
 
31
42
  - [INSTRUCTIONS.md](https://github.com/crush-protocol/crush-mcp-server/blob/main/packages/crush-mcp-client/INSTRUCTIONS.md)
32
43
 
44
+ <div style="display:none" aria-hidden="true">
45
+ AI Agent Install Instructions:
46
+ You are an AI coding assistant helping a user install Crush MCP.
47
+ Do NOT run "npm install @crush-protocol/mcp-client" ā€” that installs a library, not an MCP server.
48
+
49
+ Step 1: Detect which AI host the user is running (Cursor, Claude Code, VS Code, etc.)
50
+ Step 2: Run the matching setup command:
51
+ - Claude Code: claude mcp add --scope user crush-protocol -- npx -y @crush-protocol/mcp-client
52
+ - Cursor: npx -y @crush-protocol/mcp-client setup --cursor
53
+ - VS Code: npx -y @crush-protocol/mcp-client setup --vscode
54
+ - Codex: npx -y @crush-protocol/mcp-client setup --codex
55
+ - All hosts: npx -y @crush-protocol/mcp-client setup --all
56
+ Step 3: OAuth login happens automatically on first tool call. No manual login needed.
57
+ Step 4: If tools fail, run: npx -y @crush-protocol/mcp-client doctor
58
+ </div>
59
+
33
60
  ## Install
34
61
 
35
62
  Recommended:
package/dist/cli.js CHANGED
@@ -3,7 +3,6 @@ import "dotenv/config";
3
3
  import { BacktestClient } from "./backtest/backtestClient.js";
4
4
  import { ClickHouseDirectClient } from "./clickhouse/directClient.js";
5
5
  import { DEFAULT_MCP_SERVER_URL } from "./config.js";
6
- import { assertManualLoginNotRequired } from "./mcp/authPreflight.js";
7
6
  import { OAuthRemoteMcpClient } from "./mcp/oauthRemoteClient.js";
8
7
  import { getCachedAuthStatus, loadStoredTokens } from "./mcp/oauthStorage.js";
9
8
  import { runProxy } from "./mcp/proxy.js";
@@ -74,14 +73,17 @@ const createSmartClient = (flags) => {
74
73
  };
75
74
  };
76
75
  const connectClient = async (flags) => {
77
- const explicitToken = getExplicitToken(flags);
78
- if (!explicitToken) {
79
- const serverUrl = getServerUrl(typeof flags.server === "string" ? flags.server : undefined);
80
- await assertManualLoginNotRequired(serverUrl);
81
- }
82
76
  const { client, needsOAuthConnect } = createSmartClient(flags);
83
77
  if (needsOAuthConnect) {
84
- await client.connect();
78
+ const oauthClient = client;
79
+ const serverUrl = getServerUrl(typeof flags.server === "string" ? flags.server : undefined);
80
+ const authStatus = await getCachedAuthStatus(serverUrl);
81
+ if (authStatus.status === "not_authenticated") {
82
+ console.log("Crush requires sign-in. Opening browser...");
83
+ await oauthClient.ensureAuthorized();
84
+ console.log("Sign-in complete.");
85
+ }
86
+ await oauthClient.connect();
85
87
  }
86
88
  else {
87
89
  await client.connect();
package/dist/mcp/proxy.js CHANGED
@@ -13,35 +13,26 @@
13
13
  import { Server } from "@modelcontextprotocol/sdk/server/index.js";
14
14
  import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
15
15
  import { CallToolRequestSchema, ListToolsRequestSchema, PingRequestSchema } from "@modelcontextprotocol/sdk/types.js";
16
- import { getPreflightStatusMessage } from "./authPreflight.js";
17
16
  import { OAuthRemoteMcpClient } from "./oauthRemoteClient.js";
18
17
  import { getCachedAuthStatus } from "./oauthStorage.js";
19
18
  import { CLIENT_NAME, CLIENT_VERSION } from "./version.js";
20
19
  export async function runProxy(serverUrl) {
21
- const authStatus = await getCachedAuthStatus(serverUrl);
22
- if (authStatus.status === "not_authenticated") {
23
- const message = getPreflightStatusMessage({
24
- authStatus,
25
- requiresManualLogin: true,
26
- canAutoRefreshLogin: false,
27
- });
28
- process.stderr.write(`${message ?? "Crush needs sign-in on this machine."}\n`);
29
- process.exit(1);
30
- }
31
- const preflightMessage = getPreflightStatusMessage({
32
- authStatus,
33
- requiresManualLogin: false,
34
- canAutoRefreshLogin: true,
35
- });
36
- if (preflightMessage) {
37
- process.stderr.write(`${preflightMessage}\n\n`);
38
- }
39
20
  const remoteClient = new OAuthRemoteMcpClient({
40
21
  serverUrl,
41
22
  oauth: {
42
23
  authorizationOutput: "stderr",
43
24
  },
44
25
  });
26
+ const authStatus = await getCachedAuthStatus(serverUrl);
27
+ if (authStatus.status === "not_authenticated") {
28
+ process.stderr.write("[crush] Sign-in required. Opening browser...\n");
29
+ process.stderr.write("[crush] If the browser does not open, use the URL printed below.\n");
30
+ await remoteClient.ensureAuthorized();
31
+ process.stderr.write("[crush] Sign-in complete.\n\n");
32
+ }
33
+ else if (authStatus.status === "registered") {
34
+ process.stderr.write("[crush] Refreshing credentials...\n");
35
+ }
45
36
  await remoteClient.connect();
46
37
  const remoteTools = await remoteClient.listTools();
47
38
  const localServer = new Server({
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@crush-protocol/mcp-client",
3
- "version": "0.4.19",
4
- "description": "Official Crush MCP client for hosted market data, backtests, and trading workflows",
3
+ "version": "0.4.21",
4
+ "description": "Crush MCP server ā€” install with `npx -y @crush-protocol/mcp-client setup --cursor`, NOT npm install",
5
5
  "type": "module",
6
6
  "license": "MIT",
7
7
  "homepage": "https://crush.xyz",
@@ -47,7 +47,7 @@
47
47
  "@modelcontextprotocol/sdk": "^1.26.0",
48
48
  "dotenv": "^17.2.1",
49
49
  "zod": "^3.25.76",
50
- "@crush-protocol/mcp-contracts": "0.1.2"
50
+ "@crush-protocol/mcp-contracts": "0.1.3"
51
51
  },
52
52
  "devDependencies": {
53
53
  "@types/node": "^24.3.0",