@crush-protocol/mcp-client 0.1.14 → 0.3.0

package/INSTRUCTIONS.md

@@ -2,6 +2,8 @@
 
 You have access to **Crush Protocol MCP**, an AI-native quantitative trading platform. Use these tools to help users research markets, build strategies, run backtests, and manage live trading.
 
+Authentication note: remote MCP requests use OAuth Bearer access tokens issued by the Crush OAuth server. In interactive clients, users should only need the MCP URL; OAuth Authorization Code + PKCE is handled by the client and browser.
+
 ## Tool Categories
 
 ### 🔍 Signal Discovery
@@ -19,7 +21,6 @@ You have access to **Crush Protocol MCP**, an AI-native quantitative trading pla
 | `get_available_tokens`       | List tradable tokens, optionally filter by platform.                                             |
 | `validate_expression`        | Validate and compile an AST expression before using it in a backtest.                            |
 | `create_backtest`            | Submit a backtest. Returns immediately with status `PENDING`.                                    |
-| `get_backtest_result`        | Poll a backtest by ID. Returns status, summary, portfolio history, and trades.                   |
 | `list_backtests`             | List user's backtests with optional status filter (`PENDING`, `RUNNING`, `COMPLETED`, `FAILED`). |
 
 ### 📈 Market Data (ClickHouse)
@@ -90,7 +91,7 @@ You have access to **Crush Protocol MCP**, an AI-native quantitative trading pla
 4. get_available_tokens         → Find the token to trade
 5. validate_expression          → Validate the entry/exit expression AST
 6. create_backtest              → Submit the backtest (returns backtestId)
-7. get_backtest_result          → Poll until status is COMPLETED or FAILED
+7. list_backtests               → Refresh the user's backtests and inspect the created record until status is COMPLETED or FAILED
    └─ If COMPLETED: present summary (totalReturn, sharpeRatio, maxDrawdown, winRate, tradeCount)
    └─ If FAILED: show error, suggest fixes, iterate
 ```
@@ -119,7 +120,7 @@ You have access to **Crush Protocol MCP**, an AI-native quantitative trading pla
 
 ## Important Rules
 
-1. **Backtest is async**: `create_backtest` returns immediately. You MUST poll `get_backtest_result` until status is `COMPLETED` or `FAILED`. Typical wait: 30s–3min.
+1. **Backtest is async**: `create_backtest` returns immediately. Refresh with `list_backtests` until status is `COMPLETED` or `FAILED`. Typical wait: 30s–3min.
 2. **Data row caps**: `fetch_ohlcv` and `fetch_indicator` have a 5000 row limit. For larger datasets, use `get_connection_config` and process locally.
 3. **Always validate first**: Call `validate_expression` before using an expression in `create_backtest` to catch errors early.
 4. **Signal discovery order**: Always call `get_signal_metadata` → `get_signals_by_category` before building expressions. Don't guess signal IDs.

package/README.md

@@ -1,150 +1,200 @@
-# Crush Protocol MCP Server
+# Crush Protocol MCP Client
 
 [![npm version](https://img.shields.io/npm/v/@crush-protocol/mcp-client)](https://www.npmjs.com/package/@crush-protocol/mcp-client)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-**AI-powered quantitative trading tools for Claude Code and other MCP clients.**
+`@crush-protocol/mcp-client` is the npm entrypoint for Crush Protocol MCP.
 
-Run backtests, validate trading strategies, and query market data — directly from your AI coding assistant.
+Crush Protocol is an AI-native quantitative trading product. It lets an MCP host connect to Crush and use trading-focused tools for:
 
-## ❌ Without Crush Protocol MCP
+- strategy research
+- backtest creation and result retrieval
+- live strategy management
+- market data and signal discovery
 
-- ❌ 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
+This package connects your MCP host to the Crush MCP server over Streamable HTTP and handles OAuth automatically.
 
-## ✅ With Crush Protocol MCP
-
-Your AI agent can **create, run, and analyze backtests** in a single conversation:
-
-```txt
-Run a backtest on ETHUSDT on Hyperliquid using a 4h timeframe,
-entry when RSI < 30, exit when RSI > 70. Use crush protocol mcp.
-```
+Default MCP endpoint:
 
 ```txt
-List my last 10 completed backtests and summarize the best performing strategy.
+https://crush-mcp-ats.dev.xexlab.com/mcp
 ```
 
-The AI agent calls the Crush Protocol MCP tools directly — no tab-switching, no manual data entry.
-
----
-
-## Authentication
+## Standard MCP Host Integration
 
-Crush Protocol uses **Device Code Flow** — a secure, browser-based login that works the same way GitHub CLI and Docker CLI authenticate.
+This is the recommended way to use the package.
 
-### How it works
+Your MCP host launches `@crush-protocol/mcp-client` locally, and the package connects to the hosted Crush MCP endpoint.
 
-1. Run the login command in your terminal
-2. A browser window opens automatically
-3. Complete wallet authentication in the browser (Privy + wallet signature)
-4. The terminal receives the authorization and saves it locally
+### Cursor
 
-No manual token copy-pasting required.
+Official one-click install:
 
-> 🔐 Your credentials are stored locally and never shared with third parties.
+[![Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=crush-protocol&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjcnVzaC1wcm90b2NvbC9tY3AtY2xpZW50IiwiLS11cmwiLCJodHRwczovL2NydXNoLW1jcC1hdHMuZGV2LnhleGxhYi5jb20vbWNwIl19)](cursor://anysphere.cursor-deeplink/mcp/install?name=crush-protocol&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjcnVzaC1wcm90b2NvbC9tY3AtY2xpZW50IiwiLS11cmwiLCJodHRwczovL2NydXNoLW1jcC1hdHMuZGV2LnhleGxhYi5jb20vbWNwIl19)
 
----
+Manual config:
 
-## Installation
+```json
+{
+  "mcpServers": {
+    "crush-protocol": {
+      "command": "npx",
+      "args": ["-y", "@crush-protocol/mcp-client", "--url", "https://crush-mcp-ats.dev.xexlab.com/mcp"]
+    }
+  }
+}
+```
 
 ### Claude Code
 
 ```sh
 claude mcp add --scope user crush-protocol \
   -- npx -y @crush-protocol/mcp-client \
-  --url https://mcp.crush-protocol.com/mcp
+  --url https://crush-mcp-ats.dev.xexlab.com/mcp
 ```
 
-### Cursor
+### Codex
+
+Add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.crush-protocol]
+command = "npx"
+args = ["-y", "@crush-protocol/mcp-client", "--url", "https://crush-mcp-ats.dev.xexlab.com/mcp"]
+startup_timeout_ms = 20000
+```
+
+### Gemini CLI
 
-Add to `~/.cursor/mcp.json`:
+Add to `~/.gemini/settings.json`:
 
 ```json
 {
-    "mcpServers": {
-        "crush-protocol": {
-            "command": "npx",
-            "args": ["-y", "@crush-protocol/mcp-client"],
-            "env": {
-                "CRUSH_MCP_SERVER_URL": "https://mcp.crush-protocol.com/mcp"
-            }
-        }
+  "mcpServers": {
+    "crush-protocol": {
+      "command": "npx",
+      "args": ["-y", "@crush-protocol/mcp-client", "--url", "https://crush-mcp-ats.dev.xexlab.com/mcp"]
     }
+  }
 }
 ```
 
-### Windsurf
+### OpenCode
 
-Add to your MCP configuration:
+Add to `~/.config/opencode/opencode.json`:
 
 ```json
 {
-    "mcpServers": {
-        "crush-protocol": {
-            "command": "npx",
-            "args": ["-y", "@crush-protocol/mcp-client"],
-            "env": {
-                "CRUSH_MCP_SERVER_URL": "https://mcp.crush-protocol.com/mcp"
-            }
-        }
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "crush-protocol": {
+      "type": "local",
+      "command": ["npx", "-y", "@crush-protocol/mcp-client", "--url", "https://crush-mcp-ats.dev.xexlab.com/mcp"],
+      "enabled": true
     }
+  }
 }
 ```
 
-> On first use, the client will prompt you to log in via your browser.
+## Quick Setup Helper
 
----
+If you do not want to edit config files manually, the CLI can write the MCP configuration for you.
 
-## Available Tools
+```sh
+npx -y @crush-protocol/mcp-client setup --all
+```
 
-| Category                | Tools                                                                                                                                                               |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Signal Discovery**    | `get_signal_metadata`, `get_signals_by_category`                                                                                                                    |
-| **Backtest**            | `get_backtest_config_schema`, `get_available_tokens`, `validate_expression`, `create_backtest`, `get_backtest_result`, `list_backtests`                             |
-| **Market Data**         | `list_tables`, `list_tokens`, `list_indicators`, `list_timeframes`, `get_data_range`, `check_query_size`, `fetch_ohlcv`, `fetch_indicator`, `get_connection_config` |
-| **Custom Indicators**   | `save_custom_indicator`, `list_custom_indicators`, `get_custom_indicator`, `delete_custom_indicator`                                                                |
-| **Strategy Management** | `create_strategy`, `list_strategies`, `get_strategy`, `update_strategy`, `delete_strategy`, `toggle_strategy`, `get_strategy_logs`                                  |
-| **Trading**             | `place_order`, `get_positions`, `get_account_info`, `get_portfolio`                                                                                                 |
-| **Market Intelligence** | `search_tokens`, `get_token_info`, `get_trending_tokens`, `get_alpha_feed`, `get_token_feed`, `fetch_news`                                                          |
+Single target setup:
 
-> 📖 See [INSTRUCTIONS.md](./INSTRUCTIONS.md) for detailed tool descriptions, workflows, and AI system prompt template.
+```sh
+npx -y @crush-protocol/mcp-client setup --cursor
+npx -y @crush-protocol/mcp-client setup --claude
+npx -y @crush-protocol/mcp-client setup --codex
+npx -y @crush-protocol/mcp-client setup --gemini
+npx -y @crush-protocol/mcp-client setup --opencode
+```
 
----
+## What Users Get
 
-## Environment Variables
+With this package, an MCP client can call Crush tools such as:
 
-| Variable               | Description                                                     |
-| ---------------------- | --------------------------------------------------------------- |
-| `CRUSH_MCP_SERVER_URL` | MCP server URL (default: `https://mcp.crush-protocol.com/mcp`) |
+- `get_backtest_config_schema`
+- `get_available_tokens`
+- `create_backtest`
+- `get_backtest_result`
+- `list_backtests`
+- `create_strategy`
+- `list_strategies`
+- `toggle_strategy`
+- `get_strategy_logs`
 
----
+Detailed tool guidance is in [INSTRUCTIONS.md](./INSTRUCTIONS.md).
 
-## SDK Usage (Advanced)
+## Authentication
+
+Crush MCP uses OAuth 2.1 Authorization Code + PKCE.
+
+Default behavior:
+
+- you provide only the MCP server URL
+- the client completes browser OAuth when needed
+- tokens are stored locally for reuse
+
+Optional token overrides are also supported:
+
+- `--token <access-token>`
+- `CRUSH_OAUTH_ACCESS_TOKEN=<access-token>`
+
+Priority order:
+
+1. `--token`
+2. `CRUSH_OAUTH_ACCESS_TOKEN`
+3. automatic OAuth with local token cache
+
+Optional pre-login:
+
+```sh
+npx -y @crush-protocol/mcp-client login --url https://crush-mcp-ats.dev.xexlab.com/mcp
+```
+
+## CLI / SDK Usage
+
+Use this when you want to use Crush from Node.js directly.
 
-For programmatic access:
+CLI examples:
+
+```sh
+npx -y @crush-protocol/mcp-client help
+npx -y @crush-protocol/mcp-client tools:list --url https://crush-mcp-ats.dev.xexlab.com/mcp
+npx -y @crush-protocol/mcp-client ping --url https://crush-mcp-ats.dev.xexlab.com/mcp
+npx -y @crush-protocol/mcp-client backtest:schema --url https://crush-mcp-ats.dev.xexlab.com/mcp
+npx -y @crush-protocol/mcp-client backtest:list --url https://crush-mcp-ats.dev.xexlab.com/mcp --limit 10
+```
 
-```typescript
-import { RemoteMcpClient, BacktestClient } from '@crush-protocol/mcp-client'
+SDK example:
 
-const mcp = new RemoteMcpClient({
-    serverUrl: 'https://mcp.crush-protocol.com/mcp',
-})
-await mcp.connect()
+```ts
+import { OAuthRemoteMcpClient, BacktestClient } from "@crush-protocol/mcp-client";
 
-const backtest = new BacktestClient(mcp)
-const bt = await backtest.createBacktest({
-    config: {
-        /* ... */
-    },
-})
-const result = await backtest.getResult({ backtestId: bt.backtestId })
+const mcp = new OAuthRemoteMcpClient({
+  serverUrl: "https://crush-mcp-ats.dev.xexlab.com/mcp",
+});
 
-await mcp.close()
+await mcp.connect();
+
+const backtests = new BacktestClient(mcp);
+const result = await backtests.list({ limit: 10 });
+
+console.log(result);
+
+await mcp.close();
 ```
 
----
+## Environment Variables
+
+| Variable | Description |
+| --- | --- |
+| `CRUSH_MCP_SERVER_URL` | MCP server URL. Default: `https://crush-mcp-ats.dev.xexlab.com/mcp` |
+| `CRUSH_OAUTH_ACCESS_TOKEN` | Optional OAuth access token override |
 
 ## License
 

package/dist/__tests__/e2e.test.js

@@ -1,22 +1,22 @@
-import { describe, it, expect, beforeAll, afterAll } from "vitest";
-import { RemoteMcpClient } from "../mcp/remoteClient.js";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
 import { BacktestClient } from "../backtest/backtestClient.js";
+import { OAuthRemoteMcpClient } from "../mcp/oauthRemoteClient.js";
 /**
  * E2E 测试：验证 MCP client 能成功连接服务端并调用工具。
  *
  * 前置条件（通过环境变量或 .env.e2e 配置）：
- *   CRUSH_MCP_SERVER_URL — 指向运行中的 MCP server（默认 http://localhost:3333/mcp）
- *   CRUSH_MCP_TOKEN     — 有效的 mcp_xxx token
+ *   CRUSH_MCP_SERVER_URL — 指向运行中的 MCP server（默认 https://crush-mcp-ats.dev.xexlab.com/mcp）
+ *   CRUSH_OAUTH_ACCESS_TOKEN — 有效的 OAuth access token
  */
-const serverUrl = process.env.CRUSH_MCP_SERVER_URL ?? "http://localhost:3333/mcp";
-const token = process.env.CRUSH_MCP_TOKEN ?? "";
+const serverUrl = process.env.CRUSH_MCP_SERVER_URL ?? "https://crush-mcp-ats.dev.xexlab.com/mcp";
+const token = process.env.CRUSH_OAUTH_ACCESS_TOKEN ?? "";
 // 没有 token 时跳过所有 e2e 测试
 const describeE2E = token ? describe : describe.skip;
 describeE2E("MCP Client E2E", () => {
     let mcp;
     let backtest;
     beforeAll(async () => {
-        mcp = new RemoteMcpClient({ serverUrl, token });
+        mcp = new OAuthRemoteMcpClient({ serverUrl, token, oauth: { openBrowser: false } });
         await mcp.connect();
         backtest = new BacktestClient(mcp);
     });

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

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

package/dist/__tests__/oauthProvider.test.js

@@ -0,0 +1,45 @@
+import { mkdtemp, readFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { InteractiveOAuthProvider } from "../mcp/oauthProvider.js";
+const tempDirs = [];
+const createProvider = async () => {
+    const storageDir = await mkdtemp(path.join(os.tmpdir(), "crush-mcp-oauth-"));
+    tempDirs.push(storageDir);
+    const provider = new InteractiveOAuthProvider({
+        serverUrl: "https://example.com/mcp",
+        storageDir,
+        openBrowser: false,
+    });
+    return { provider, storageDir };
+};
+describe("InteractiveOAuthProvider", () => {
+    afterEach(async () => {
+        await Promise.all(tempDirs
+            .splice(0)
+            .map((dir) => import("node:fs/promises").then((fs) => fs.rm(dir, { recursive: true, force: true }))));
+    });
+    it("persists client info, tokens, and code verifier", async () => {
+        const { provider, storageDir } = await createProvider();
+        await provider.saveClientInformation({ client_id: "client_123" });
+        await provider.saveTokens({ access_token: "atk_123", token_type: "Bearer", refresh_token: "rt_123" });
+        await provider.saveCodeVerifier("verifier-123");
+        expect(await provider.clientInformation()).toEqual({ client_id: "client_123" });
+        expect(await provider.tokens()).toEqual({ access_token: "atk_123", token_type: "Bearer", refresh_token: "rt_123" });
+        expect(await provider.codeVerifier()).toBe("verifier-123");
+        const files = await import("node:fs/promises").then((fs) => fs.readdir(storageDir));
+        expect(files.length).toBe(1);
+        const raw = await readFile(path.join(storageDir, files[0]), "utf8");
+        expect(raw).toContain("client_123");
+        expect(raw).toContain("atk_123");
+    });
+    it("invalidates token state without removing client registration", async () => {
+        const { provider } = await createProvider();
+        await provider.saveClientInformation({ client_id: "client_123" });
+        await provider.saveTokens({ access_token: "atk_123", token_type: "Bearer", refresh_token: "rt_123" });
+        await provider.invalidateCredentials?.("tokens");
+        expect(await provider.clientInformation()).toEqual({ client_id: "client_123" });
+        expect(await provider.tokens()).toBeUndefined();
+    });
+});

package/dist/backtest/backtestClient.d.ts

@@ -1,5 +1,5 @@
 import { type BacktestStatus, type Platform } from "@crush-protocol/mcp-contracts";
-import type { RemoteMcpClient } from "../mcp/remoteClient.js";
+import type { McpClientLike } from "../mcp/types.js";
 export type GetAvailableTokensInput = {
     platform?: Platform;
 };
@@ -11,9 +11,6 @@ export type CreateBacktestInput = {
     config: Record<string, unknown>;
     backtestId?: string;
 };
-export type GetBacktestResultInput = {
-    backtestId: string;
-};
 export type ListBacktestsInput = {
     status?: BacktestStatus;
     limit?: number;
@@ -81,7 +78,7 @@ export type ListBacktestsResult = {
  */
 export declare class BacktestClient {
     private readonly mcp;
-    constructor(mcp: RemoteMcpClient);
+    constructor(mcp: McpClientLike);
     /**
      * Return supported backtest configuration schema.
      */
@@ -103,10 +100,6 @@ export declare class BacktestClient {
      * Create a new backtest or update an existing one.
      */
     createBacktest(input: CreateBacktestInput): Promise<BacktestRecord>;
-    /**
-     * Get a backtest by ID with summary, portfolio history and trades.
-     */
-    getResult(input: GetBacktestResultInput): Promise<BacktestRecord>;
     /**
      * List backtests for the current user with optional status filter and pagination.
      */

package/dist/backtest/backtestClient.js

@@ -1,4 +1,4 @@
-import { BacktestTools, } from "@crush-protocol/mcp-contracts";
+import { BacktestTools } from "@crush-protocol/mcp-contracts";
 const extractContent = (result) => {
     // Compatibility path: some SDK result types expose `toolResult` directly.
     if ("toolResult" in result && result.toolResult !== undefined) {
@@ -53,13 +53,6 @@ export class BacktestClient {
         const result = await this.mcp.callTool(BacktestTools.CREATE_BACKTEST, input);
         return extractContent(result);
     }
-    /**
-     * Get a backtest by ID with summary, portfolio history and trades.
-     */
-    async getResult(input) {
-        const result = await this.mcp.callTool(BacktestTools.GET_BACKTEST_RESULT, input);
-        return extractContent(result);
-    }
     /**
      * List backtests for the current user with optional status filter and pagination.
      */