@crush-protocol/mcp-client 0.1.0 → 0.1.3

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 +126 -62
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,71 +1,107 @@
1
1
  # @crush-protocol/mcp-client
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
+ Crush Protocol MCP client — SDK + CLI for interacting with the Crush MCP Server.
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
+ ## Features
10
9
 
11
- ## 安装
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.
14
+
15
+ ## Requirements
16
+
17
+ - Node.js >= 20
18
+ - A valid `mcp_xxx` token (issued by the Crush MCP Server)
19
+
20
+ ## Installation
12
21
 
13
22
  ```bash
14
23
  npm install @crush-protocol/mcp-client
15
24
  ```
16
25
 
17
- ## SDK 使用
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", ...}}
38
+ ```
39
+
40
+ Store the returned `mcp_xxx` token — it is shown only once.
41
+
42
+ ---
43
+
44
+ ## SDK Usage
18
45
 
19
46
  ```typescript
20
- import { RemoteMcpClient, BacktestClient } from "@crush-protocol/mcp-client";
47
+ import { RemoteMcpClient, BacktestClient } from '@crush-protocol/mcp-client'
21
48
 
22
49
  const mcp = new RemoteMcpClient({
23
- serverUrl: "https://your-host/mcp",
24
- token: "mcp_xxx",
25
- });
26
- await mcp.connect();
50
+ serverUrl: 'https://your-server/mcp',
51
+ token: 'mcp_xxx',
52
+ })
53
+ await mcp.connect()
27
54
 
28
- const backtest = new BacktestClient(mcp);
55
+ const backtest = new BacktestClient(mcp)
29
56
 
30
- // 获取回测配置 schema
31
- const schema = await backtest.getConfigSchema();
57
+ // Get supported configuration schema
58
+ const schema = await backtest.getConfigSchema()
32
59
 
33
- // 获取可用交易对
34
- const { tokens } = await backtest.getAvailableTokens({ platform: "hyperliquid_perps" });
60
+ // List available tokens for a platform
61
+ const { tokens } = await backtest.getAvailableTokens({ platform: 'hyperliquid_perps' })
35
62
 
36
- // 验证表达式
63
+ // Validate an entry/exit expression
37
64
  const validation = await backtest.validateExpression({
38
- expression: { type: "comparison", field: "close", operator: ">", value: 100 },
39
- dataSource: "kline",
40
- });
65
+ expression: { type: 'comparison', field: 'close', operator: '>', value: 100 },
66
+ dataSource: 'kline',
67
+ })
41
68
 
42
- // 创建回测
69
+ // Create a backtest
43
70
  const bt = await backtest.createBacktest({
44
- config: {
45
- token: { symbol: "ETHUSDT" },
46
- platform: "hyperliquid_perps",
47
- timeframe: "240",
48
- entry: { /* ... */ },
49
- },
50
- });
51
-
52
- // 获取回测结果
53
- const result = await backtest.getResult({ backtestId: bt.backtestId });
54
-
55
- // 列出回测
56
- const list = await backtest.list({ status: "COMPLETED", limit: 10 });
57
-
58
- await mcp.close();
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 })
83
+
84
+ // List backtests
85
+ const list = await backtest.list({ status: 'COMPLETED', limit: 10 })
86
+
87
+ await mcp.close()
59
88
  ```
60
89
 
61
- ## CLI 使用
90
+ ---
91
+
92
+ ## CLI Usage
62
93
 
63
94
  ### General
64
95
 
65
96
  ```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
97
+ # Ping the MCP server
98
+ crush-mcp-client ping --url https://your-server/mcp --token mcp_xxx
99
+
100
+ # List available tools
101
+ crush-mcp-client tools:list --url https://your-server/mcp --token mcp_xxx
102
+
103
+ # Call any tool by name
104
+ crush-mcp-client tool:call --name get_backtest_config_schema --args '{}' --token mcp_xxx
69
105
  ```
70
106
 
71
107
  ### Backtest
@@ -73,38 +109,66 @@ crush-mcp-client ping --token mcp_xxx
73
109
  ```bash
74
110
  crush-mcp-client backtest:schema --token mcp_xxx
75
111
  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
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":{}}' \
117
+ --token mcp_xxx
118
+ crush-mcp-client backtest:get --backtest-id <id> --token mcp_xxx
79
119
  crush-mcp-client backtest:list --status COMPLETED --limit 10 --token mcp_xxx
80
120
  ```
81
121
 
82
- ### ClickHouse 直连（只读）
122
+ ### ClickHouse Direct (read-only)
83
123
 
84
124
  ```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
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
87
130
  ```
88
131
 
89
- ## 环境变量
132
+ ### Environment Variables
90
133
 
91
- 可复制 `.env.example` 并设置：
134
+ Set these to avoid passing flags on every command:
92
135
 
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）
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`) |
97
142
 
98
- ## 安全说明
143
+ ---
99
144
 
100
- 1. 远程 MCP 模式要求 token 形如 `mcp_xxx`，通过 `Authorization: Bearer ...` 发送。
101
- 2. Token 缺失或格式错误时直接失败。
102
- 3. ClickHouse 直连模式仅允许 `SELECT`，强制 `readonly=1`，结果有行数上限。
145
+ ## Configure Claude Code (MCP Integration)
103
146
 
104
- ## 本地开发
147
+ Add to your Claude Code config (`~/.claude.json`):
105
148
 
106
- ```bash
107
- pnpm install
108
- pnpm build
109
- pnpm dev -- help
149
+ ```json
150
+ {
151
+ "mcpServers": {
152
+ "crush": {
153
+ "command": "npx",
154
+ "args": ["-y", "@crush-protocol/mcp-client", "tools:list"],
155
+ "env": {
156
+ "CRUSH_MCP_SERVER_URL": "https://your-server/mcp",
157
+ "CRUSH_MCP_TOKEN": "mcp_xxx"
158
+ }
159
+ }
160
+ }
161
+ }
110
162
  ```
163
+
164
+ ---
165
+
166
+ ## Security
167
+
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.
171
+
172
+ ## License
173
+
174
+ MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@crush-protocol/mcp-client",
3
- "version": "0.1.0",
3
+ "version": "0.1.3",
4
4
  "description": "Crush MCP npm client package (remote Streamable HTTP + optional ClickHouse direct)",
5
5
  "type": "module",
6
6
  "license": "MIT",