@crush-protocol/mcp-client 0.1.3 → 0.1.5

package/README.md

@@ -1,159 +1,87 @@
-# @crush-protocol/mcp-client
+# Crush Protocol MCP Server
 
 [![npm version](https://badge.fury.io/js/%40crush-protocol%2Fmcp-client.svg)](https://www.npmjs.com/package/@crush-protocol/mcp-client)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-Crush Protocol MCP client — SDK + CLI for interacting with the Crush MCP Server.
+**AI-powered quantitative trading tools for Claude Code and other MCP clients.**
 
-## Features
+Run backtests, validate trading strategies, and query market data — directly from your AI coding assistant.
 
-- **Remote MCP SDK** — Connect to the Crush MCP Server via Streamable HTTP, authenticated with `Bearer mcp_xxx` tokens.
-- **Backtest SDK** — Typed wrappers for all backtest tools (`getConfigSchema`, `createBacktest`, `getResult`, etc.).
-- **ClickHouse direct** _(optional)_ — Read-only direct ClickHouse access with a row cap safety limit.
-- **CLI** — Command-line tool for quick testing and scripting.
+## ❌ Without Crush Protocol MCP
 
-## Requirements
+- ❌ Manually switch between your IDE and trading dashboards
+- ❌ Copy-paste backtest configs and wait for results separately
+- ❌ No way for your AI agent to iterate on strategies automatically
 
-- Node.js >= 20
-- A valid `mcp_xxx` token (issued by the Crush MCP Server)
+## ✅ With Crush Protocol MCP
 
-## Installation
+Your AI agent can **create, run, and analyze backtests** in a single conversation:
 
-```bash
-npm install @crush-protocol/mcp-client
+```txt
+Run a backtest on ETHUSDT on Hyperliquid using a 4h timeframe,
+entry when RSI < 30, exit when RSI > 70. Use crush protocol mcp.
 ```
 
-## Quick Start
-
-### Get a Token
-
-Tokens are issued by the Crush MCP Server's REST API. Use your Privy JWT to claim one:
-
-```bash
-curl -X POST https://your-server/v1/mcp-tokens \
-  -H "Authorization: Bearer <privy-jwt>" \
-  -H "Content-Type: application/json" \
-  -d '{"name": "my-token"}'
-# → {"data": {"token": "mcp_xxx", ...}}
+```txt
+List my last 10 completed backtests and summarize the best performing strategy.
 ```
 
-Store the returned `mcp_xxx` token — it is shown only once.
+The AI agent calls the Crush Protocol MCP tools directly — no tab-switching, no manual data entry.
 
 ---
 
-## SDK Usage
-
-```typescript
-import { RemoteMcpClient, BacktestClient } from '@crush-protocol/mcp-client'
-
-const mcp = new RemoteMcpClient({
-    serverUrl: 'https://your-server/mcp',
-    token: 'mcp_xxx',
-})
-await mcp.connect()
-
-const backtest = new BacktestClient(mcp)
-
-// Get supported configuration schema
-const schema = await backtest.getConfigSchema()
-
-// List available tokens for a platform
-const { tokens } = await backtest.getAvailableTokens({ platform: 'hyperliquid_perps' })
-
-// Validate an entry/exit expression
-const validation = await backtest.validateExpression({
-    expression: { type: 'comparison', field: 'close', operator: '>', value: 100 },
-    dataSource: 'kline',
-})
-
-// Create a backtest
-const bt = await backtest.createBacktest({
-    config: {
-        token: { symbol: 'ETHUSDT' },
-        platform: 'hyperliquid_perps',
-        timeframe: '240',
-        entry: {
-            /* AST expression */
-        },
-    },
-})
-
-// Poll for result
-const result = await backtest.getResult({ backtestId: bt.backtestId })
+## Getting a Token
 
-// List backtests
-const list = await backtest.list({ status: 'COMPLETED', limit: 10 })
-
-await mcp.close()
-```
+Tokens are issued from the Crush Protocol web app. After logging in, navigate to **Settings → API Tokens** to create an `mcp_xxx` token.
 
 ---
 
-## CLI Usage
-
-### General
-
-```bash
-# Ping the MCP server
-crush-mcp-client ping --url https://your-server/mcp --token mcp_xxx
+## Installation
 
-# List available tools
-crush-mcp-client tools:list --url https://your-server/mcp --token mcp_xxx
+### Claude Code
 
-# Call any tool by name
-crush-mcp-client tool:call --name get_backtest_config_schema --args '{}' --token mcp_xxx
+```sh
+claude mcp add --scope user crush-protocol -- npx -y @crush-protocol/mcp-client
 ```
 
-### Backtest
+Then set your credentials:
 
-```bash
-crush-mcp-client backtest:schema --token mcp_xxx
-crush-mcp-client backtest:tokens --platform hyperliquid_perps --token mcp_xxx
-crush-mcp-client backtest:validate \
-  --expression '{"type":"comparison","field":"close","operator":">","value":100}' \
-  --token mcp_xxx
-crush-mcp-client backtest:create \
-  --config '{"token":{"symbol":"ETHUSDT"},"platform":"hyperliquid_perps","timeframe":"240","entry":{}}' \
+```sh
+claude mcp add --scope user crush-protocol \
+  -- npx -y @crush-protocol/mcp-client \
+  --url https://mcp.crush-protocol.com/mcp \
   --token mcp_xxx
-crush-mcp-client backtest:get --backtest-id <id> --token mcp_xxx
-crush-mcp-client backtest:list --status COMPLETED --limit 10 --token mcp_xxx
 ```
 
-### ClickHouse Direct (read-only)
+Or via environment variables in `~/.claude.json`:
 
-```bash
-crush-mcp-client clickhouse:list-tables \
-  --ch-host localhost --ch-port 8123 --ch-user default --ch-password "" --ch-database crush_ats
-
-crush-mcp-client clickhouse:query \
-  --sql "SELECT * FROM system.tables LIMIT 10" --ch-database system
+```json
+{
+    "mcpServers": {
+        "crush-protocol": {
+            "command": "npx",
+            "args": ["-y", "@crush-protocol/mcp-client"],
+            "env": {
+                "CRUSH_MCP_SERVER_URL": "https://mcp.crush-protocol.com/mcp",
+                "CRUSH_MCP_TOKEN": "mcp_xxx"
+            }
+        }
+    }
+}
 ```
 
-### Environment Variables
-
-Set these to avoid passing flags on every command:
-
-| Variable                                                          | Description                                           |
-| ----------------------------------------------------------------- | ----------------------------------------------------- |
-| `CRUSH_MCP_SERVER_URL`                                            | MCP server URL (default: `http://localhost:8080/mcp`) |
-| `CRUSH_MCP_TOKEN`                                                 | MCP auth token (`mcp_xxx`)                            |
-| `CH_HOST` / `CH_PORT` / `CH_USER` / `CH_PASSWORD` / `CH_DATABASE` | ClickHouse connection                                 |
-| `CH_ROW_CAP`                                                      | Max rows returned (default: `5000`)                   |
-
----
-
-## Configure Claude Code (MCP Integration)
+### Cursor
 
-Add to your Claude Code config (`~/.claude.json`):
+Add to `~/.cursor/mcp.json`:
 
 ```json
 {
     "mcpServers": {
-        "crush": {
+        "crush-protocol": {
             "command": "npx",
-            "args": ["-y", "@crush-protocol/mcp-client", "tools:list"],
+            "args": ["-y", "@crush-protocol/mcp-client"],
             "env": {
-                "CRUSH_MCP_SERVER_URL": "https://your-server/mcp",
+                "CRUSH_MCP_SERVER_URL": "https://mcp.crush-protocol.com/mcp",
                 "CRUSH_MCP_TOKEN": "mcp_xxx"
             }
         }
@@ -163,11 +91,53 @@ Add to your Claude Code config (`~/.claude.json`):
 
 ---
 
-## Security
+## Available Tools
+
+| Tool                         | Description                                                     |
+| ---------------------------- | --------------------------------------------------------------- |
+| `get_backtest_config_schema` | Get supported platforms, timeframes, and strategy config schema |
+| `get_available_tokens`       | List tradable tokens, optionally filtered by platform           |
+| `validate_expression`        | Validate and compile an entry/exit AST expression               |
+| `create_backtest`            | Create or update a backtest with a strategy config              |
+| `get_backtest_result`        | Fetch result, summary, portfolio history and trades             |
+| `list_backtests`             | List your backtests with optional status filter and pagination  |
+
+---
+
+## Environment Variables
+
+| Variable               | Description                                                          |
+| ---------------------- | -------------------------------------------------------------------- |
+| `CRUSH_MCP_SERVER_URL` | MCP server URL (default: `https://crush-mcp-ats.dev.xexlab.com/mcp`) |
+| `CRUSH_MCP_TOKEN`      | MCP auth token (`mcp_xxx`)                                           |
+
+---
+
+## SDK Usage (Advanced)
+
+For programmatic access:
 
-- Tokens must be in the format `mcp_xxx`. Invalid formats are rejected immediately.
-- Tokens are transmitted via `Authorization: Bearer` header over HTTPS.
-- ClickHouse direct mode enforces `readonly=1` and a row cap to prevent abuse.
+```typescript
+import { RemoteMcpClient, BacktestClient } from '@crush-protocol/mcp-client'
+
+const mcp = new RemoteMcpClient({
+    serverUrl: 'https://mcp.crush-protocol.com/mcp',
+    token: 'mcp_xxx',
+})
+await mcp.connect()
+
+const backtest = new BacktestClient(mcp)
+const bt = await backtest.createBacktest({
+    config: {
+        /* ... */
+    },
+})
+const result = await backtest.getResult({ backtestId: bt.backtestId })
+
+await mcp.close()
+```
+
+---
 
 ## License
 

package/dist/__tests__/e2e.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/e2e.test.js

@@ -0,0 +1,50 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { RemoteMcpClient } from "../mcp/remoteClient.js";
+import { BacktestClient } from "../backtest/backtestClient.js";
+/**
+ * E2E 测试：验证 MCP client 能成功连接服务端并调用工具。
+ *
+ * 前置条件（通过环境变量或 .env.e2e 配置）：
+ *   CRUSH_MCP_SERVER_URL — 指向运行中的 MCP server（默认 http://localhost:3333/mcp）
+ *   CRUSH_MCP_TOKEN     — 有效的 mcp_xxx token
+ */
+const serverUrl = process.env.CRUSH_MCP_SERVER_URL ?? "http://localhost:3333/mcp";
+const token = process.env.CRUSH_MCP_TOKEN ?? "";
+// 没有 token 时跳过所有 e2e 测试
+const describeE2E = token ? describe : describe.skip;
+describeE2E("MCP Client E2E", () => {
+    let mcp;
+    let backtest;
+    beforeAll(async () => {
+        mcp = new RemoteMcpClient({ serverUrl, token });
+        await mcp.connect();
+        backtest = new BacktestClient(mcp);
+    });
+    afterAll(async () => {
+        await mcp.close();
+    });
+    it("ping — 服务端可达", async () => {
+        const result = await mcp.ping();
+        expect(result).toBeDefined();
+    });
+    it("listTools — 返回至少一个工具", async () => {
+        const { tools } = await mcp.listTools();
+        expect(tools.length).toBeGreaterThan(0);
+    });
+    it("backtest:schema — 返回支持的配置 schema", async () => {
+        const schema = await backtest.getConfigSchema();
+        expect(schema).toHaveProperty("platforms");
+        expect(schema).toHaveProperty("timeframes");
+        expect(Array.isArray(schema.platforms)).toBe(true);
+    });
+    it("backtest:tokens — 返回可用交易对列表", async () => {
+        const result = await backtest.getAvailableTokens();
+        expect(result).toHaveProperty("tokens");
+        expect(Array.isArray(result.tokens)).toBe(true);
+    });
+    it("backtest:list — 返回当前用户的回测列表", async () => {
+        const result = await backtest.list({ limit: 5 });
+        expect(result).toHaveProperty("backtests");
+        expect(typeof result.total).toBe("number");
+    });
+});

package/dist/cli.js

@@ -32,7 +32,7 @@ const requireString = (value, message) => {
 const createRemoteClient = (flags) => {
     const serverUrl = typeof flags.url === "string"
         ? flags.url
-        : (process.env.CRUSH_MCP_SERVER_URL ?? "http://localhost:8080/mcp");
+        : (process.env.CRUSH_MCP_SERVER_URL ?? "https://crush-mcp-ats.dev.xexlab.com/mcp");
     const token = typeof flags.token === "string"
         ? flags.token
         : requireString(process.env.CRUSH_MCP_TOKEN, "Missing token. Use --token or CRUSH_MCP_TOKEN");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crush-protocol/mcp-client",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Crush MCP npm client package (remote Streamable HTTP + optional ClickHouse direct)",
   "type": "module",
   "license": "MIT",
@@ -18,22 +18,26 @@
       "default": "./dist/index.js"
     }
   },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/cli.ts",
+    "test:e2e": "dotenv -e .env.e2e vitest run src/__tests__/e2e.test.ts",
+    "prepublishOnly": "pnpm run build"
+  },
   "dependencies": {
+    "@crush-protocol/mcp-contracts": "workspace:*",
     "@modelcontextprotocol/sdk": "^1.26.0",
     "dotenv": "^17.2.1",
-    "zod": "^3.25.76",
-    "@crush-protocol/mcp-contracts": "0.1.0"
+    "zod": "^3.25.76"
   },
   "devDependencies": {
     "@types/node": "^24.3.0",
+    "dotenv-cli": "^8.0.0",
     "tsx": "^4.20.4",
-    "typescript": "^5.9.2"
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
   },
   "engines": {
     "node": ">=20"
-  },
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "dev": "tsx src/cli.ts"
   }
-}
+}

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2025 Edwin Hernandez
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.