@crush-protocol/mcp-client 0.1.3 → 0.1.4

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 (2) hide show
  1. package/README.md +91 -121
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,159 +1,87 @@
1
- # @crush-protocol/mcp-client
1
+ # Crush Protocol MCP Server
2
2
 
3
3
  [![npm version](https://badge.fury.io/js/%40crush-protocol%2Fmcp-client.svg)](https://www.npmjs.com/package/@crush-protocol/mcp-client)
4
4
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
5
5
 
6
- Crush Protocol MCP client — SDK + CLI for interacting with the Crush MCP Server.
6
+ **AI-powered quantitative trading tools for Claude Code and other MCP clients.**
7
7
 
8
- ## Features
8
+ Run backtests, validate trading strategies, and query market data — directly from your AI coding assistant.
9
9
 
10
- - **Remote MCP SDK** — Connect to the Crush MCP Server via Streamable HTTP, authenticated with `Bearer mcp_xxx` tokens.
11
- - **Backtest SDK** — Typed wrappers for all backtest tools (`getConfigSchema`, `createBacktest`, `getResult`, etc.).
12
- - **ClickHouse direct** _(optional)_ — Read-only direct ClickHouse access with a row cap safety limit.
13
- - **CLI** — Command-line tool for quick testing and scripting.
10
+ ## ❌ Without Crush Protocol MCP
14
11
 
15
- ## Requirements
12
+ - ❌ Manually switch between your IDE and trading dashboards
13
+ - ❌ Copy-paste backtest configs and wait for results separately
14
+ - ❌ No way for your AI agent to iterate on strategies automatically
16
15
 
17
- - Node.js >= 20
18
- - A valid `mcp_xxx` token (issued by the Crush MCP Server)
16
+ ## ✅ With Crush Protocol MCP
19
17
 
20
- ## Installation
18
+ Your AI agent can **create, run, and analyze backtests** in a single conversation:
21
19
 
22
- ```bash
23
- npm install @crush-protocol/mcp-client
20
+ ```txt
21
+ Run a backtest on ETHUSDT on Hyperliquid using a 4h timeframe,
22
+ entry when RSI < 30, exit when RSI > 70. Use crush protocol mcp.
24
23
  ```
25
24
 
26
- ## Quick Start
27
-
28
- ### Get a Token
29
-
30
- Tokens are issued by the Crush MCP Server's REST API. Use your Privy JWT to claim one:
31
-
32
- ```bash
33
- curl -X POST https://your-server/v1/mcp-tokens \
34
- -H "Authorization: Bearer <privy-jwt>" \
35
- -H "Content-Type: application/json" \
36
- -d '{"name": "my-token"}'
37
- # → {"data": {"token": "mcp_xxx", ...}}
25
+ ```txt
26
+ List my last 10 completed backtests and summarize the best performing strategy.
38
27
  ```
39
28
 
40
- Store the returned `mcp_xxx` token — it is shown only once.
29
+ The AI agent calls the Crush Protocol MCP tools directly — no tab-switching, no manual data entry.
41
30
 
42
31
  ---
43
32
 
44
- ## SDK Usage
45
-
46
- ```typescript
47
- import { RemoteMcpClient, BacktestClient } from '@crush-protocol/mcp-client'
48
-
49
- const mcp = new RemoteMcpClient({
50
- serverUrl: 'https://your-server/mcp',
51
- token: 'mcp_xxx',
52
- })
53
- await mcp.connect()
54
-
55
- const backtest = new BacktestClient(mcp)
56
-
57
- // Get supported configuration schema
58
- const schema = await backtest.getConfigSchema()
59
-
60
- // List available tokens for a platform
61
- const { tokens } = await backtest.getAvailableTokens({ platform: 'hyperliquid_perps' })
62
-
63
- // Validate an entry/exit expression
64
- const validation = await backtest.validateExpression({
65
- expression: { type: 'comparison', field: 'close', operator: '>', value: 100 },
66
- dataSource: 'kline',
67
- })
68
-
69
- // Create a backtest
70
- const bt = await backtest.createBacktest({
71
- config: {
72
- token: { symbol: 'ETHUSDT' },
73
- platform: 'hyperliquid_perps',
74
- timeframe: '240',
75
- entry: {
76
- /* AST expression */
77
- },
78
- },
79
- })
80
-
81
- // Poll for result
82
- const result = await backtest.getResult({ backtestId: bt.backtestId })
33
+ ## Getting a Token
83
34
 
84
- // List backtests
85
- const list = await backtest.list({ status: 'COMPLETED', limit: 10 })
86
-
87
- await mcp.close()
88
- ```
35
+ Tokens are issued from the Crush Protocol web app. After logging in, navigate to **Settings → API Tokens** to create an `mcp_xxx` token.
89
36
 
90
37
  ---
91
38
 
92
- ## CLI Usage
93
-
94
- ### General
95
-
96
- ```bash
97
- # Ping the MCP server
98
- crush-mcp-client ping --url https://your-server/mcp --token mcp_xxx
39
+ ## Installation
99
40
 
100
- # List available tools
101
- crush-mcp-client tools:list --url https://your-server/mcp --token mcp_xxx
41
+ ### Claude Code
102
42
 
103
- # Call any tool by name
104
- crush-mcp-client tool:call --name get_backtest_config_schema --args '{}' --token mcp_xxx
43
+ ```sh
44
+ claude mcp add --scope user crush-protocol -- npx -y @crush-protocol/mcp-client
105
45
  ```
106
46
 
107
- ### Backtest
47
+ Then set your credentials:
108
48
 
109
- ```bash
110
- crush-mcp-client backtest:schema --token mcp_xxx
111
- crush-mcp-client backtest:tokens --platform hyperliquid_perps --token mcp_xxx
112
- crush-mcp-client backtest:validate \
113
- --expression '{"type":"comparison","field":"close","operator":">","value":100}' \
114
- --token mcp_xxx
115
- crush-mcp-client backtest:create \
116
- --config '{"token":{"symbol":"ETHUSDT"},"platform":"hyperliquid_perps","timeframe":"240","entry":{}}' \
49
+ ```sh
50
+ claude mcp add --scope user crush-protocol \
51
+ -- npx -y @crush-protocol/mcp-client \
52
+ --url https://mcp.crush-protocol.com/mcp \
117
53
  --token mcp_xxx
118
- crush-mcp-client backtest:get --backtest-id <id> --token mcp_xxx
119
- crush-mcp-client backtest:list --status COMPLETED --limit 10 --token mcp_xxx
120
54
  ```
121
55
 
122
- ### ClickHouse Direct (read-only)
56
+ Or via environment variables in `~/.claude.json`:
123
57
 
124
- ```bash
125
- crush-mcp-client clickhouse:list-tables \
126
- --ch-host localhost --ch-port 8123 --ch-user default --ch-password "" --ch-database crush_ats
127
-
128
- crush-mcp-client clickhouse:query \
129
- --sql "SELECT * FROM system.tables LIMIT 10" --ch-database system
58
+ ```json
59
+ {
60
+ "mcpServers": {
61
+ "crush-protocol": {
62
+ "command": "npx",
63
+ "args": ["-y", "@crush-protocol/mcp-client"],
64
+ "env": {
65
+ "CRUSH_MCP_SERVER_URL": "https://mcp.crush-protocol.com/mcp",
66
+ "CRUSH_MCP_TOKEN": "mcp_xxx"
67
+ }
68
+ }
69
+ }
70
+ }
130
71
  ```
131
72
 
132
- ### Environment Variables
133
-
134
- Set these to avoid passing flags on every command:
135
-
136
- | Variable | Description |
137
- | ----------------------------------------------------------------- | ----------------------------------------------------- |
138
- | `CRUSH_MCP_SERVER_URL` | MCP server URL (default: `http://localhost:8080/mcp`) |
139
- | `CRUSH_MCP_TOKEN` | MCP auth token (`mcp_xxx`) |
140
- | `CH_HOST` / `CH_PORT` / `CH_USER` / `CH_PASSWORD` / `CH_DATABASE` | ClickHouse connection |
141
- | `CH_ROW_CAP` | Max rows returned (default: `5000`) |
142
-
143
- ---
144
-
145
- ## Configure Claude Code (MCP Integration)
73
+ ### Cursor
146
74
 
147
- Add to your Claude Code config (`~/.claude.json`):
75
+ Add to `~/.cursor/mcp.json`:
148
76
 
149
77
  ```json
150
78
  {
151
79
  "mcpServers": {
152
- "crush": {
80
+ "crush-protocol": {
153
81
  "command": "npx",
154
- "args": ["-y", "@crush-protocol/mcp-client", "tools:list"],
82
+ "args": ["-y", "@crush-protocol/mcp-client"],
155
83
  "env": {
156
- "CRUSH_MCP_SERVER_URL": "https://your-server/mcp",
84
+ "CRUSH_MCP_SERVER_URL": "https://mcp.crush-protocol.com/mcp",
157
85
  "CRUSH_MCP_TOKEN": "mcp_xxx"
158
86
  }
159
87
  }
@@ -163,11 +91,53 @@ Add to your Claude Code config (`~/.claude.json`):
163
91
 
164
92
  ---
165
93
 
166
- ## Security
94
+ ## Available Tools
95
+
96
+ | Tool | Description |
97
+ | ---------------------------- | --------------------------------------------------------------- |
98
+ | `get_backtest_config_schema` | Get supported platforms, timeframes, and strategy config schema |
99
+ | `get_available_tokens` | List tradable tokens, optionally filtered by platform |
100
+ | `validate_expression` | Validate and compile an entry/exit AST expression |
101
+ | `create_backtest` | Create or update a backtest with a strategy config |
102
+ | `get_backtest_result` | Fetch result, summary, portfolio history and trades |
103
+ | `list_backtests` | List your backtests with optional status filter and pagination |
104
+
105
+ ---
106
+
107
+ ## Environment Variables
108
+
109
+ | Variable | Description |
110
+ | ---------------------- | ----------------------------------------------------- |
111
+ | `CRUSH_MCP_SERVER_URL` | MCP server URL (default: `http://localhost:8080/mcp`) |
112
+ | `CRUSH_MCP_TOKEN` | MCP auth token (`mcp_xxx`) |
113
+
114
+ ---
115
+
116
+ ## SDK Usage (Advanced)
117
+
118
+ For programmatic access:
167
119
 
168
- - Tokens must be in the format `mcp_xxx`. Invalid formats are rejected immediately.
169
- - Tokens are transmitted via `Authorization: Bearer` header over HTTPS.
170
- - ClickHouse direct mode enforces `readonly=1` and a row cap to prevent abuse.
120
+ ```typescript
121
+ import { RemoteMcpClient, BacktestClient } from '@crush-protocol/mcp-client'
122
+
123
+ const mcp = new RemoteMcpClient({
124
+ serverUrl: 'https://mcp.crush-protocol.com/mcp',
125
+ token: 'mcp_xxx',
126
+ })
127
+ await mcp.connect()
128
+
129
+ const backtest = new BacktestClient(mcp)
130
+ const bt = await backtest.createBacktest({
131
+ config: {
132
+ /* ... */
133
+ },
134
+ })
135
+ const result = await backtest.getResult({ backtestId: bt.backtestId })
136
+
137
+ await mcp.close()
138
+ ```
139
+
140
+ ---
171
141
 
172
142
  ## License
173
143
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@crush-protocol/mcp-client",
3
- "version": "0.1.3",
3
+ "version": "0.1.4",
4
4
  "description": "Crush MCP npm client package (remote Streamable HTTP + optional ClickHouse direct)",
5
5
  "type": "module",
6
6
  "license": "MIT",