@crush-protocol/mcp-client 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+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.

package/README.md

@@ -0,0 +1,110 @@
+# @crush-protocol/mcp-client
+
+Crush MCP npm 客户端 — CLI + SDK。
+
+提供三种能力：
+
+1. **Remote MCP**（默认）：通过 Streamable HTTP 访问远程 `/mcp`，强制 `Bearer mcp_xxx` 鉴权。
+2. **Backtest SDK**：类型化的回测工具封装（`client.backtest.*`），基于 Remote MCP。
+3. **ClickHouse direct**（可选）：客户端只读直连 ClickHouse（仅 SELECT + 行数上限）。
+
+## 安装
+
+```bash
+npm install @crush-protocol/mcp-client
+```
+
+## SDK 使用
+
+```typescript
+import { RemoteMcpClient, BacktestClient } from "@crush-protocol/mcp-client";
+
+const mcp = new RemoteMcpClient({
+  serverUrl: "https://your-host/mcp",
+  token: "mcp_xxx",
+});
+await mcp.connect();
+
+const backtest = new BacktestClient(mcp);
+
+// 获取回测配置 schema
+const schema = await backtest.getConfigSchema();
+
+// 获取可用交易对
+const { tokens } = await backtest.getAvailableTokens({ platform: "hyperliquid_perps" });
+
+// 验证表达式
+const validation = await backtest.validateExpression({
+  expression: { type: "comparison", field: "close", operator: ">", value: 100 },
+  dataSource: "kline",
+});
+
+// 创建回测
+const bt = await backtest.createBacktest({
+  config: {
+    token: { symbol: "ETHUSDT" },
+    platform: "hyperliquid_perps",
+    timeframe: "240",
+    entry: { /* ... */ },
+  },
+});
+
+// 获取回测结果
+const result = await backtest.getResult({ backtestId: bt.backtestId });
+
+// 列出回测
+const list = await backtest.list({ status: "COMPLETED", limit: 10 });
+
+await mcp.close();
+```
+
+## CLI 使用
+
+### General
+
+```bash
+crush-mcp-client tools:list --url https://your-host/mcp --token mcp_xxx
+crush-mcp-client tool:call --name list_tables --args '{}' --token mcp_xxx
+crush-mcp-client ping --token mcp_xxx
+```
+
+### Backtest
+
+```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":{}}' --token mcp_xxx
+crush-mcp-client backtest:get --backtest-id 665a1b2c3d4e5f6a7b8c9d0e --token mcp_xxx
+crush-mcp-client backtest:list --status COMPLETED --limit 10 --token mcp_xxx
+```
+
+### ClickHouse 直连（只读）
+
+```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
+```
+
+## 环境变量
+
+可复制 `.env.example` 并设置：
+
+- `CRUSH_MCP_SERVER_URL` — 远程 MCP 服务地址（默认 `http://localhost:8080/mcp`）
+- `CRUSH_MCP_TOKEN` — MCP 鉴权 token（`mcp_xxx`）
+- `CH_HOST` / `CH_PORT` / `CH_USER` / `CH_PASSWORD` / `CH_DATABASE` — ClickHouse 连接
+- `CH_ROW_CAP`（可选，默认 5000）
+
+## 安全说明
+
+1. 远程 MCP 模式要求 token 形如 `mcp_xxx`，通过 `Authorization: Bearer ...` 发送。
+2. Token 缺失或格式错误时直接失败。
+3. ClickHouse 直连模式仅允许 `SELECT`，强制 `readonly=1`，结果有行数上限。
+
+## 本地开发
+
+```bash
+pnpm install
+pnpm build
+pnpm dev -- help
+```

package/dist/backtest/backtestClient.d.ts

@@ -0,0 +1,114 @@
+import { type BacktestStatus, type Platform } from "@crush-protocol/mcp-contracts";
+import type { RemoteMcpClient } from "../mcp/remoteClient.js";
+export type GetAvailableTokensInput = {
+    platform?: Platform;
+};
+export type ValidateExpressionInput = {
+    expression: Record<string, unknown>;
+    dataSource?: "kline" | "factors";
+};
+export type CreateBacktestInput = {
+    config: Record<string, unknown>;
+    backtestId?: string;
+};
+export type GetBacktestResultInput = {
+    backtestId: string;
+};
+export type ListBacktestsInput = {
+    status?: BacktestStatus;
+    limit?: number;
+    offset?: number;
+};
+export type BacktestConfigSchema = {
+    platforms: string[];
+    timeframes: {
+        value: string;
+        label: string;
+    }[];
+    directions: string[];
+    positionSizeTypes: string[];
+    exitStrategyTypes: {
+        type: string;
+        label: string;
+        description: string;
+        distanceTypes: string[];
+    }[];
+    leverageRange: {
+        min: number;
+        max: number;
+    };
+    dateRange: {
+        min: string;
+    };
+    expressionLimits: {
+        maxDepth: number;
+        maxNodes: number;
+    };
+    context: {
+        privyId: string;
+    };
+};
+export type TokenInfo = {
+    symbol: string;
+    name: string;
+    platform: string;
+};
+export type ValidationResult = {
+    valid: boolean;
+    error?: string;
+    compiledExpression?: string;
+};
+export type BacktestRecord = {
+    backtestId: string;
+    status: BacktestStatus;
+    config: Record<string, unknown>;
+    error?: string | null;
+    createdAt?: string;
+    updatedAt?: string;
+    summary?: Record<string, unknown> | null;
+    portfolios?: unknown[];
+    trades?: unknown[];
+};
+export type ListBacktestsResult = {
+    backtests: BacktestRecord[];
+    total: number;
+    limit: number;
+    offset: number;
+};
+/**
+ * Typed SDK wrapper for the 6 backtest MCP tools.
+ * Requires a connected RemoteMcpClient instance.
+ */
+export declare class BacktestClient {
+    private readonly mcp;
+    constructor(mcp: RemoteMcpClient);
+    /**
+     * Return supported backtest configuration schema.
+     */
+    getConfigSchema(): Promise<BacktestConfigSchema>;
+    /**
+     * Return supported token list, optionally filtered by platform.
+     */
+    getAvailableTokens(input?: GetAvailableTokensInput): Promise<{
+        tokens: TokenInfo[];
+        context: {
+            privyId: string;
+        };
+    }>;
+    /**
+     * Validate and compile an AST expression for backtest entry/exit rules.
+     */
+    validateExpression(input: ValidateExpressionInput): Promise<ValidationResult>;
+    /**
+     * 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.
+     */
+    list(input?: ListBacktestsInput): Promise<ListBacktestsResult>;
+}

package/dist/backtest/backtestClient.js

@@ -0,0 +1,77 @@
+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) {
+        return result.toolResult;
+    }
+    if (!Array.isArray(result.content) || result.content.length === 0) {
+        throw new Error("Unexpected MCP tool result format: missing content.");
+    }
+    const first = result.content[0];
+    if (first?.type === "text" && typeof first.text === "string") {
+        return JSON.parse(first.text);
+    }
+    throw new Error("Unexpected MCP tool result format: unsupported content item.");
+};
+/**
+ * Typed SDK wrapper for the 6 backtest MCP tools.
+ * Requires a connected RemoteMcpClient instance.
+ */
+export class BacktestClient {
+    mcp;
+    constructor(mcp) {
+        this.mcp = mcp;
+    }
+    /**
+     * Return supported backtest configuration schema.
+     */
+    async getConfigSchema() {
+        const result = await this.mcp.callTool(BacktestTools.GET_BACKTEST_CONFIG_SCHEMA);
+        return extractContent(result);
+    }
+    /**
+     * Return supported token list, optionally filtered by platform.
+     */
+    async getAvailableTokens(input) {
+        const args = {};
+        if (input?.platform)
+            args.platform = input.platform;
+        const result = await this.mcp.callTool(BacktestTools.GET_AVAILABLE_TOKENS, args);
+        return extractContent(result);
+    }
+    /**
+     * Validate and compile an AST expression for backtest entry/exit rules.
+     */
+    async validateExpression(input) {
+        const result = await this.mcp.callTool(BacktestTools.VALIDATE_EXPRESSION, input);
+        return extractContent(result);
+    }
+    /**
+     * Create a new backtest or update an existing one.
+     */
+    async createBacktest(input) {
+        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.
+     */
+    async list(input) {
+        const args = {};
+        if (input?.status)
+            args.status = input.status;
+        if (input?.limit !== undefined)
+            args.limit = input.limit;
+        if (input?.offset !== undefined)
+            args.offset = input.offset;
+        const result = await this.mcp.callTool(BacktestTools.LIST_BACKTESTS, args);
+        return extractContent(result);
+    }
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "dotenv/config";

package/dist/cli.js

@@ -0,0 +1,268 @@
+#!/usr/bin/env node
+import "dotenv/config";
+import { BacktestClient } from "./backtest/backtestClient.js";
+import { ClickHouseDirectClient } from "./clickhouse/directClient.js";
+import { RemoteMcpClient } from "./mcp/remoteClient.js";
+const printUsage = () => {
+    console.log(`\ncrush-mcp-client\n\nGeneral:\n  tools:list [--url URL] [--token TOKEN]\n  tool:call --name TOOL_NAME [--args JSON] [--url URL] [--token TOKEN]\n  ping [--url URL] [--token TOKEN]\n\nBacktest:\n  backtest:schema [--url URL] [--token TOKEN]\n  backtest:tokens [--platform PLATFORM] [--url URL] [--token TOKEN]\n  backtest:validate --expression JSON [--data-source kline|factors] [--url URL] [--token TOKEN]\n  backtest:create --config JSON [--backtest-id ID] [--url URL] [--token TOKEN]\n  backtest:get --backtest-id ID [--url URL] [--token TOKEN]\n  backtest:list [--status STATUS] [--limit N] [--offset N] [--url URL] [--token TOKEN]\n\nClickHouse:\n  clickhouse:list-tables [--ch-host HOST --ch-port PORT --ch-user USER --ch-password PASS --ch-database DB]\n  clickhouse:query --sql SQL [--ch-host HOST --ch-port PORT --ch-user USER --ch-password PASS --ch-database DB --ch-row-cap N]\n\nEnv fallback:\n  CRUSH_MCP_SERVER_URL, CRUSH_MCP_TOKEN\n  CH_HOST, CH_PORT, CH_USER, CH_PASSWORD, CH_DATABASE, CH_ROW_CAP\n`);
+};
+const parseFlags = (args) => {
+    const flags = {};
+    for (let i = 0; i < args.length; i += 1) {
+        const token = args[i];
+        if (!token.startsWith("--"))
+            continue;
+        const key = token.slice(2);
+        const next = args[i + 1];
+        if (!next || next.startsWith("--")) {
+            flags[key] = true;
+            continue;
+        }
+        flags[key] = next;
+        i += 1;
+    }
+    return flags;
+};
+const requireString = (value, message) => {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new Error(message);
+    }
+    return value;
+};
+const createRemoteClient = (flags) => {
+    const serverUrl = typeof flags.url === "string"
+        ? flags.url
+        : (process.env.CRUSH_MCP_SERVER_URL ?? "http://localhost:8080/mcp");
+    const token = typeof flags.token === "string"
+        ? flags.token
+        : requireString(process.env.CRUSH_MCP_TOKEN, "Missing token. Use --token or CRUSH_MCP_TOKEN");
+    return new RemoteMcpClient({ serverUrl, token });
+};
+const createClickHouseClient = (flags) => {
+    const host = typeof flags["ch-host"] === "string"
+        ? flags["ch-host"]
+        : (process.env.CH_HOST ?? "localhost");
+    const portRaw = typeof flags["ch-port"] === "string"
+        ? flags["ch-port"]
+        : (process.env.CH_PORT ?? "8123");
+    const user = typeof flags["ch-user"] === "string"
+        ? flags["ch-user"]
+        : (process.env.CH_USER ?? "default");
+    const password = typeof flags["ch-password"] === "string"
+        ? flags["ch-password"]
+        : (process.env.CH_PASSWORD ?? "");
+    const database = typeof flags["ch-database"] === "string"
+        ? flags["ch-database"]
+        : (process.env.CH_DATABASE ?? "crush_ats");
+    const rowCapRaw = typeof flags["ch-row-cap"] === "string"
+        ? flags["ch-row-cap"]
+        : process.env.CH_ROW_CAP;
+    const port = Number(portRaw);
+    if (!Number.isFinite(port) || port <= 0) {
+        throw new Error(`Invalid ClickHouse port: ${portRaw}`);
+    }
+    let rowCap;
+    if (rowCapRaw !== undefined) {
+        const parsed = Number(rowCapRaw);
+        if (!Number.isFinite(parsed) || parsed <= 0) {
+            throw new Error(`Invalid ClickHouse row cap: ${rowCapRaw}`);
+        }
+        rowCap = parsed;
+    }
+    return new ClickHouseDirectClient({
+        host,
+        port,
+        user,
+        password,
+        database,
+        rowCap,
+    });
+};
+const run = async () => {
+    const [, , command, ...rest] = process.argv;
+    if (!command ||
+        command === "help" ||
+        command === "--help" ||
+        command === "-h") {
+        printUsage();
+        return;
+    }
+    const flags = parseFlags(rest);
+    switch (command) {
+        case "tools:list": {
+            const client = createRemoteClient(flags);
+            await client.connect();
+            try {
+                const result = await client.listTools();
+                console.log(JSON.stringify(result, null, 2));
+            }
+            finally {
+                await client.close();
+            }
+            return;
+        }
+        case "tool:call": {
+            const name = requireString(flags.name, "Missing --name for tool:call");
+            const rawArgs = typeof flags.args === "string" ? flags.args : "{}";
+            let parsedArgs;
+            try {
+                parsedArgs = JSON.parse(rawArgs);
+            }
+            catch (e) {
+                throw new Error(`Invalid --args JSON: ${e.message}`);
+            }
+            const client = createRemoteClient(flags);
+            await client.connect();
+            try {
+                const result = await client.callTool(name, parsedArgs);
+                console.log(JSON.stringify(result, null, 2));
+            }
+            finally {
+                await client.close();
+            }
+            return;
+        }
+        case "ping": {
+            const client = createRemoteClient(flags);
+            await client.connect();
+            try {
+                const result = await client.ping();
+                console.log(JSON.stringify(result, null, 2));
+            }
+            finally {
+                await client.close();
+            }
+            return;
+        }
+        case "backtest:schema": {
+            const client = createRemoteClient(flags);
+            await client.connect();
+            try {
+                const bt = new BacktestClient(client);
+                const result = await bt.getConfigSchema();
+                console.log(JSON.stringify(result, null, 2));
+            }
+            finally {
+                await client.close();
+            }
+            return;
+        }
+        case "backtest:tokens": {
+            const client = createRemoteClient(flags);
+            await client.connect();
+            try {
+                const bt = new BacktestClient(client);
+                const platform = typeof flags.platform === "string" ? flags.platform : undefined;
+                const result = await bt.getAvailableTokens(platform
+                    ? {
+                        platform: platform,
+                    }
+                    : undefined);
+                console.log(JSON.stringify(result, null, 2));
+            }
+            finally {
+                await client.close();
+            }
+            return;
+        }
+        case "backtest:validate": {
+            const exprRaw = requireString(flags.expression, "Missing --expression JSON for backtest:validate");
+            let expression;
+            try {
+                expression = JSON.parse(exprRaw);
+            }
+            catch (e) {
+                throw new Error(`Invalid --expression JSON: ${e.message}`);
+            }
+            const dataSource = typeof flags["data-source"] === "string"
+                ? flags["data-source"]
+                : undefined;
+            const client = createRemoteClient(flags);
+            await client.connect();
+            try {
+                const bt = new BacktestClient(client);
+                const result = await bt.validateExpression({ expression, dataSource });
+                console.log(JSON.stringify(result, null, 2));
+            }
+            finally {
+                await client.close();
+            }
+            return;
+        }
+        case "backtest:create": {
+            const configRaw = requireString(flags.config, "Missing --config JSON for backtest:create");
+            let config;
+            try {
+                config = JSON.parse(configRaw);
+            }
+            catch (e) {
+                throw new Error(`Invalid --config JSON: ${e.message}`);
+            }
+            const backtestId = typeof flags["backtest-id"] === "string"
+                ? flags["backtest-id"]
+                : undefined;
+            const client = createRemoteClient(flags);
+            await client.connect();
+            try {
+                const bt = new BacktestClient(client);
+                const result = await bt.createBacktest({ config, backtestId });
+                console.log(JSON.stringify(result, null, 2));
+            }
+            finally {
+                await client.close();
+            }
+            return;
+        }
+        case "backtest:get": {
+            const backtestId = requireString(flags["backtest-id"], "Missing --backtest-id for backtest:get");
+            const client = createRemoteClient(flags);
+            await client.connect();
+            try {
+                const bt = new BacktestClient(client);
+                const result = await bt.getResult({ backtestId });
+                console.log(JSON.stringify(result, null, 2));
+            }
+            finally {
+                await client.close();
+            }
+            return;
+        }
+        case "backtest:list": {
+            const status = typeof flags.status === "string"
+                ? flags.status
+                : undefined;
+            const limit = typeof flags.limit === "string" ? Number(flags.limit) : undefined;
+            const offset = typeof flags.offset === "string" ? Number(flags.offset) : undefined;
+            const client = createRemoteClient(flags);
+            await client.connect();
+            try {
+                const bt = new BacktestClient(client);
+                const result = await bt.list({ status, limit, offset });
+                console.log(JSON.stringify(result, null, 2));
+            }
+            finally {
+                await client.close();
+            }
+            return;
+        }
+        case "clickhouse:list-tables": {
+            const ch = createClickHouseClient(flags);
+            const tables = await ch.listTables();
+            console.log(JSON.stringify({ tables }, null, 2));
+            return;
+        }
+        case "clickhouse:query": {
+            const sql = requireString(flags.sql, "Missing --sql for clickhouse:query");
+            const ch = createClickHouseClient(flags);
+            const rows = await ch.query(sql);
+            console.log(JSON.stringify({ rows }, null, 2));
+            return;
+        }
+        default:
+            throw new Error(`Unknown command: ${command}`);
+    }
+};
+run().catch((error) => {
+    console.error(`Error: ${error.message}`);
+    process.exit(1);
+});

package/dist/clickhouse/directClient.d.ts

@@ -0,0 +1,21 @@
+export type ClickHouseDirectConfig = {
+    host: string;
+    port: number;
+    user: string;
+    password: string;
+    database: string;
+    rowCap?: number;
+};
+export declare const DEFAULT_ROW_CAP = 5000;
+export declare class ClickHouseDirectClient {
+    private readonly config;
+    constructor(config: ClickHouseDirectConfig);
+    private guardReadOnlySql;
+    private execute;
+    query(sql: string, database?: string): Promise<Record<string, unknown>[]>;
+    listTables(database?: string): Promise<{
+        name: string;
+        rows: number;
+        comment: string;
+    }[]>;
+}

package/dist/clickhouse/directClient.js

@@ -0,0 +1,86 @@
+import http from "node:http";
+export const DEFAULT_ROW_CAP = 5000;
+const WRITE_SQL_PATTERN = /\b(insert|update|delete|drop|alter|truncate|create|grant|revoke|attach|optimize|system|rename)\b/i;
+const SAFE_DB_NAME_PATTERN = /^[A-Za-z0-9_]+$/;
+export class ClickHouseDirectClient {
+    config;
+    constructor(config) {
+        this.config = {
+            ...config,
+            rowCap: config.rowCap ?? DEFAULT_ROW_CAP,
+        };
+    }
+    guardReadOnlySql(sql) {
+        const normalized = sql.trim().replace(/;$/, "");
+        if (!normalized.toLowerCase().startsWith("select")) {
+            throw new Error("Only SELECT statements are allowed for direct ClickHouse mode.");
+        }
+        if (WRITE_SQL_PATTERN.test(normalized)) {
+            throw new Error("Potential write/admin SQL detected. Query rejected.");
+        }
+    }
+    execute(sql, database) {
+        const db = database || this.config.database;
+        const params = new URLSearchParams({
+            database: db,
+            query: `${sql} FORMAT JSONEachRow`,
+            readonly: "1",
+        });
+        const authHeader = `Basic ${Buffer.from(`${this.config.user}:${this.config.password}`).toString("base64")}`;
+        return new Promise((resolve, reject) => {
+            const req = http.request({
+                hostname: this.config.host,
+                port: this.config.port,
+                path: `/?${params.toString()}`,
+                method: "GET",
+                headers: { Authorization: authHeader },
+                timeout: 30000,
+            }, (res) => {
+                let data = "";
+                res.on("data", (chunk) => {
+                    data += chunk.toString();
+                });
+                res.on("end", () => {
+                    if (res.statusCode !== 200) {
+                        reject(new Error(`ClickHouse error (${res.statusCode}): ${data.slice(0, 300)}`));
+                        return;
+                    }
+                    if (!data.trim()) {
+                        resolve([]);
+                        return;
+                    }
+                    try {
+                        resolve(data.trim().split("\n").map((line) => JSON.parse(line)));
+                    }
+                    catch (e) {
+                        reject(new Error(`Failed to parse ClickHouse JSONEachRow: ${e.message}`));
+                    }
+                });
+            });
+            req.on("error", (e) => reject(new Error(`ClickHouse request failed: ${e.message}`)));
+            req.on("timeout", () => {
+                req.destroy();
+                reject(new Error("ClickHouse request timeout after 30s"));
+            });
+            req.end();
+        });
+    }
+    async query(sql, database) {
+        this.guardReadOnlySql(sql);
+        const normalized = sql.trim().replace(/;$/, "");
+        const wrapped = `SELECT * FROM (${normalized}) AS q LIMIT ${this.config.rowCap}`;
+        return this.execute(wrapped, database);
+    }
+    async listTables(database) {
+        const db = database || this.config.database;
+        if (!SAFE_DB_NAME_PATTERN.test(db)) {
+            throw new Error(`Invalid database name: ${db}`);
+        }
+        const rows = await this.execute(`SELECT name, total_rows AS rows, comment FROM system.tables WHERE database = '${db}' ORDER BY name`, "system");
+        return rows.map((r) => ({
+            name: String(r.name),
+            rows: Number(r.rows ?? r.total_rows ?? 0),
+            comment: String(r.comment ?? ""),
+        }));
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { ClickHouseDirectClient, DEFAULT_ROW_CAP, type ClickHouseDirectConfig, } from "./clickhouse/directClient.js";
+export { RemoteMcpClient, type RemoteMcpClientOptions, } from "./mcp/remoteClient.js";
+export { BacktestClient, type BacktestConfigSchema, type BacktestRecord, type CreateBacktestInput, type GetAvailableTokensInput, type GetBacktestResultInput, type ListBacktestsInput, type ListBacktestsResult, type TokenInfo, type ValidationResult, } from "./backtest/backtestClient.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { ClickHouseDirectClient, DEFAULT_ROW_CAP, } from "./clickhouse/directClient.js";
+export { RemoteMcpClient, } from "./mcp/remoteClient.js";
+export { BacktestClient, } from "./backtest/backtestClient.js";

package/dist/mcp/remoteClient.d.ts

@@ -0,0 +1,160 @@
+export type RemoteMcpClientOptions = {
+    serverUrl: string;
+    token: string;
+    clientName?: string;
+    clientVersion?: string;
+};
+export declare class RemoteMcpClient {
+    private readonly client;
+    private readonly transport;
+    constructor(options: RemoteMcpClientOptions);
+    connect(): Promise<void>;
+    close(): Promise<void>;
+    terminateSession(): Promise<void>;
+    ping(): Promise<{
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+    }>;
+    listTools(): Promise<{
+        [x: string]: unknown;
+        tools: {
+            inputSchema: {
+                [x: string]: unknown;
+                type: "object";
+                properties?: Record<string, object> | undefined;
+                required?: string[] | undefined;
+            };
+            name: string;
+            description?: string | undefined;
+            outputSchema?: {
+                [x: string]: unknown;
+                type: "object";
+                properties?: Record<string, object> | undefined;
+                required?: string[] | undefined;
+            } | undefined;
+            annotations?: {
+                title?: string | undefined;
+                readOnlyHint?: boolean | undefined;
+                destructiveHint?: boolean | undefined;
+                idempotentHint?: boolean | undefined;
+                openWorldHint?: boolean | undefined;
+            } | undefined;
+            execution?: {
+                taskSupport?: "optional" | "required" | "forbidden" | undefined;
+            } | undefined;
+            _meta?: Record<string, unknown> | undefined;
+            icons?: {
+                src: string;
+                mimeType?: string | undefined;
+                sizes?: string[] | undefined;
+                theme?: "light" | "dark" | undefined;
+            }[] | undefined;
+            title?: string | undefined;
+        }[];
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+        nextCursor?: string | undefined;
+    }>;
+    callTool(name: string, args?: Record<string, unknown>): Promise<{
+        [x: string]: unknown;
+        content: ({
+            type: "text";
+            text: string;
+            annotations?: {
+                audience?: ("user" | "assistant")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: Record<string, unknown> | undefined;
+        } | {
+            type: "image";
+            data: string;
+            mimeType: string;
+            annotations?: {
+                audience?: ("user" | "assistant")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: Record<string, unknown> | undefined;
+        } | {
+            type: "audio";
+            data: string;
+            mimeType: string;
+            annotations?: {
+                audience?: ("user" | "assistant")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: Record<string, unknown> | undefined;
+        } | {
+            type: "resource";
+            resource: {
+                uri: string;
+                text: string;
+                mimeType?: string | undefined;
+                _meta?: Record<string, unknown> | undefined;
+            } | {
+                uri: string;
+                blob: string;
+                mimeType?: string | undefined;
+                _meta?: Record<string, unknown> | undefined;
+            };
+            annotations?: {
+                audience?: ("user" | "assistant")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: Record<string, unknown> | undefined;
+        } | {
+            uri: string;
+            name: string;
+            type: "resource_link";
+            description?: string | undefined;
+            mimeType?: string | undefined;
+            annotations?: {
+                audience?: ("user" | "assistant")[] | undefined;
+                priority?: number | undefined;
+                lastModified?: string | undefined;
+            } | undefined;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+            icons?: {
+                src: string;
+                mimeType?: string | undefined;
+                sizes?: string[] | undefined;
+                theme?: "light" | "dark" | undefined;
+            }[] | undefined;
+            title?: string | undefined;
+        })[];
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+        structuredContent?: Record<string, unknown> | undefined;
+        isError?: boolean | undefined;
+    } | {
+        [x: string]: unknown;
+        toolResult: unknown;
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+    }>;
+}

package/dist/mcp/remoteClient.js

@@ -0,0 +1,45 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+export class RemoteMcpClient {
+    client;
+    transport;
+    constructor(options) {
+        if (!options.token.startsWith("mcp_")) {
+            throw new Error("Invalid token format. Expected mcp_xxx");
+        }
+        this.client = new Client({
+            name: options.clientName || "crush-mcp-client",
+            version: options.clientVersion || "0.1.0",
+        }, {
+            capabilities: {},
+        });
+        this.transport = new StreamableHTTPClientTransport(new URL(options.serverUrl), {
+            requestInit: {
+                headers: {
+                    Authorization: `Bearer ${options.token}`,
+                },
+            },
+        });
+    }
+    async connect() {
+        await this.client.connect(this.transport);
+    }
+    async close() {
+        await this.transport.close();
+    }
+    async terminateSession() {
+        await this.transport.terminateSession();
+    }
+    async ping() {
+        return this.client.ping();
+    }
+    async listTools() {
+        return this.client.listTools();
+    }
+    async callTool(name, args = {}) {
+        return this.client.callTool({
+            name,
+            arguments: args,
+        });
+    }
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@crush-protocol/mcp-client",
+  "version": "0.1.0",
+  "description": "Crush MCP npm client package (remote Streamable HTTP + optional ClickHouse direct)",
+  "type": "module",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "crush-mcp-client": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "dotenv": "^17.2.1",
+    "zod": "^3.25.76",
+    "@crush-protocol/mcp-contracts": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "tsx": "^4.20.4",
+    "typescript": "^5.9.2"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/cli.ts"
+  }
+}