@crush-protocol/mcp-client 0.1.2 → 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 +111 -77
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,110 +1,144 @@
1
- # @crush-protocol/mcp-client
1
+ # Crush Protocol MCP Server
2
2
 
3
- Crush MCP npm 客户端 — CLI + SDK。
3
+ [![npm version](https://badge.fury.io/js/%40crush-protocol%2Fmcp-client.svg)](https://www.npmjs.com/package/@crush-protocol/mcp-client)
4
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
4
5
 
5
- 提供三种能力：
6
+ **AI-powered quantitative trading tools for Claude Code and other MCP clients.**
6
7
 
7
- 1. **Remote MCP**（默认）：通过 Streamable HTTP 访问远程 `/mcp`，强制 `Bearer mcp_xxx` 鉴权。
8
- 2. **Backtest SDK**：类型化的回测工具封装（`client.backtest.*`），基于 Remote MCP。
9
- 3. **ClickHouse direct**（可选）：客户端只读直连 ClickHouse（仅 SELECT + 行数上限）。
8
+ Run backtests, validate trading strategies, and query market data — directly from your AI coding assistant.
10
9
 
11
- ## 安装
10
+ ## ❌ Without Crush Protocol MCP
12
11
 
13
- ```bash
14
- npm install @crush-protocol/mcp-client
15
- ```
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
- ## SDK 使用
16
+ ## ✅ With Crush Protocol MCP
18
17
 
19
- ```typescript
20
- import { RemoteMcpClient, BacktestClient } from "@crush-protocol/mcp-client";
18
+ Your AI agent can **create, run, and analyze backtests** in a single conversation:
21
19
 
22
- const mcp = new RemoteMcpClient({
23
- serverUrl: "https://your-host/mcp",
24
- token: "mcp_xxx",
25
- });
26
- await mcp.connect();
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.
23
+ ```
24
+
25
+ ```txt
26
+ List my last 10 completed backtests and summarize the best performing strategy.
27
+ ```
27
28
 
28
- const backtest = new BacktestClient(mcp);
29
+ The AI agent calls the Crush Protocol MCP tools directly — no tab-switching, no manual data entry.
29
30
 
30
- // 获取回测配置 schema
31
- const schema = await backtest.getConfigSchema();
31
+ ---
32
32
 
33
- // 获取可用交易对
34
- const { tokens } = await backtest.getAvailableTokens({ platform: "hyperliquid_perps" });
33
+ ## Getting a Token
35
34
 
36
- // 验证表达式
37
- const validation = await backtest.validateExpression({
38
- expression: { type: "comparison", field: "close", operator: ">", value: 100 },
39
- dataSource: "kline",
40
- });
35
+ Tokens are issued from the Crush Protocol web app. After logging in, navigate to **Settings → API Tokens** to create an `mcp_xxx` token.
41
36
 
42
- // 创建回测
43
- const bt = await backtest.createBacktest({
44
- config: {
45
- token: { symbol: "ETHUSDT" },
46
- platform: "hyperliquid_perps",
47
- timeframe: "240",
48
- entry: { /* ... */ },
49
- },
50
- });
37
+ ---
51
38
 
52
- // 获取回测结果
53
- const result = await backtest.getResult({ backtestId: bt.backtestId });
39
+ ## Installation
54
40
 
55
- // 列出回测
56
- const list = await backtest.list({ status: "COMPLETED", limit: 10 });
41
+ ### Claude Code
57
42
 
58
- await mcp.close();
43
+ ```sh
44
+ claude mcp add --scope user crush-protocol -- npx -y @crush-protocol/mcp-client
59
45
  ```
60
46
 
61
- ## CLI 使用
62
-
63
- ### General
47
+ Then set your credentials:
64
48
 
65
- ```bash
66
- crush-mcp-client tools:list --url https://your-host/mcp --token mcp_xxx
67
- crush-mcp-client tool:call --name list_tables --args '{}' --token mcp_xxx
68
- crush-mcp-client ping --token mcp_xxx
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 \
53
+ --token mcp_xxx
69
54
  ```
70
55
 
71
- ### Backtest
56
+ Or via environment variables in `~/.claude.json`:
57
+
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
+ }
71
+ ```
72
72
 
73
- ```bash
74
- crush-mcp-client backtest:schema --token mcp_xxx
75
- crush-mcp-client backtest:tokens --platform hyperliquid_perps --token mcp_xxx
76
- crush-mcp-client backtest:validate --expression '{"type":"comparison","field":"close","operator":">","value":100}' --token mcp_xxx
77
- crush-mcp-client backtest:create --config '{"token":{"symbol":"ETHUSDT"},"platform":"hyperliquid_perps","timeframe":"240","entry":{}}' --token mcp_xxx
78
- crush-mcp-client backtest:get --backtest-id 665a1b2c3d4e5f6a7b8c9d0e --token mcp_xxx
79
- crush-mcp-client backtest:list --status COMPLETED --limit 10 --token mcp_xxx
73
+ ### Cursor
74
+
75
+ Add to `~/.cursor/mcp.json`:
76
+
77
+ ```json
78
+ {
79
+ "mcpServers": {
80
+ "crush-protocol": {
81
+ "command": "npx",
82
+ "args": ["-y", "@crush-protocol/mcp-client"],
83
+ "env": {
84
+ "CRUSH_MCP_SERVER_URL": "https://mcp.crush-protocol.com/mcp",
85
+ "CRUSH_MCP_TOKEN": "mcp_xxx"
86
+ }
87
+ }
88
+ }
89
+ }
80
90
  ```
81
91
 
82
- ### ClickHouse 直连（只读）
92
+ ---
83
93
 
84
- ```bash
85
- crush-mcp-client clickhouse:list-tables --ch-host localhost --ch-port 8123 --ch-user default --ch-password '' --ch-database crush_ats
86
- crush-mcp-client clickhouse:query --sql 'SELECT * FROM system.tables LIMIT 10' --ch-database system
87
- ```
94
+ ## Available Tools
88
95
 
89
- ## 环境变量
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 |
90
104
 
91
- 可复制 `.env.example` 并设置：
105
+ ---
92
106
 
93
- - `CRUSH_MCP_SERVER_URL` — 远程 MCP 服务地址（默认 `http://localhost:8080/mcp`）
94
- - `CRUSH_MCP_TOKEN` — MCP 鉴权 token（`mcp_xxx`）
95
- - `CH_HOST` / `CH_PORT` / `CH_USER` / `CH_PASSWORD` / `CH_DATABASE` — ClickHouse 连接
96
- - `CH_ROW_CAP`（可选，默认 5000）
107
+ ## Environment Variables
97
108
 
98
- ## 安全说明
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`) |
99
113
 
100
- 1. 远程 MCP 模式要求 token 形如 `mcp_xxx`，通过 `Authorization: Bearer ...` 发送。
101
- 2. Token 缺失或格式错误时直接失败。
102
- 3. ClickHouse 直连模式仅允许 `SELECT`，强制 `readonly=1`，结果有行数上限。
114
+ ---
103
115
 
104
- ## 本地开发
116
+ ## SDK Usage (Advanced)
105
117
 
106
- ```bash
107
- pnpm install
108
- pnpm build
109
- pnpm dev -- help
118
+ For programmatic access:
119
+
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()
110
138
  ```
139
+
140
+ ---
141
+
142
+ ## License
143
+
144
+ MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@crush-protocol/mcp-client",
3
- "version": "0.1.2",
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",