@crush-protocol/mcp-client 0.1.13 → 0.2.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

@@ -30,30 +30,101 @@ The AI agent calls the Crush Protocol MCP tools directly — no tab-switching, n
 
 ---
 
-## Getting a Token
+## Authentication
 
-Tokens are issued from the Crush Protocol web app. After logging in, navigate to **Settings → API Tokens** to create an `mcp_xxx` token.
+Crush Protocol MCP uses **OAuth 2.1 Authorization Code + PKCE**.
+
+For a standards-based MCP experience, configure only the MCP server URL. The client can complete browser authorization automatically and persist tokens locally.
+
+This means the published CLI and the URL-only MCP setup now follow the same auth model:
+
+- `npx -y @crush-protocol/mcp-client --url <mcp-url>` uses automatic OAuth on first use
+- host integrations such as Claude Code / Cursor / Windsurf can also provide only the MCP URL
+- both paths ultimately use the same OAuth access tokens against `/mcp`
+
+Non-interactive OAuth overrides are still available for scripts and already-published client workflows:
+
+1. `crush-mcp-client login --url <mcp-url>` to pre-authorize locally
+2. `--token <access-token>` for debugging
+3. `CRUSH_OAUTH_ACCESS_TOKEN=<access-token>` for non-interactive automation
 
 ---
 
-## Installation
+## CLI Usage
 
-### Claude Code
+The CLI is now an OAuth-aware MCP client, not a separate legacy auth path.
+
+### Common commands
 
 ```sh
-claude mcp add --scope user crush-protocol -- npx -y @crush-protocol/mcp-client
+# Show help
+npx -y @crush-protocol/mcp-client help
+
+# Pre-authorize locally (optional)
+npx -y @crush-protocol/mcp-client login --url https://mcp.crush-protocol.com/mcp
+
+# List tools
+npx -y @crush-protocol/mcp-client tools:list --url https://mcp.crush-protocol.com/mcp
+
+# Ping MCP server
+npx -y @crush-protocol/mcp-client ping --url https://mcp.crush-protocol.com/mcp
+
+# Call a tool directly
+npx -y @crush-protocol/mcp-client tool:call \
+  --url https://mcp.crush-protocol.com/mcp \
+  --name get_backtest_config_schema
 ```
 
-Then set your credentials:
+### Backtest commands
+
+```sh
+# Read backtest schema
+npx -y @crush-protocol/mcp-client backtest:schema --url https://mcp.crush-protocol.com/mcp
+
+# List available tokens
+npx -y @crush-protocol/mcp-client backtest:tokens --url https://mcp.crush-protocol.com/mcp
+
+# List backtests
+npx -y @crush-protocol/mcp-client backtest:list --url https://mcp.crush-protocol.com/mcp --limit 10
+```
+
+### How auth behaves
+
+```sh
+# Recommended: URL only, browser OAuth happens automatically if needed
+npx -y @crush-protocol/mcp-client tools:list --url https://mcp.crush-protocol.com/mcp
+
+# Optional: inject a pre-issued OAuth access token
+npx -y @crush-protocol/mcp-client tools:list \
+  --url https://mcp.crush-protocol.com/mcp \
+  --token <oauth-access-token>
+```
+
+Behavior priority is:
+
+1. `--token`
+2. `CRUSH_OAUTH_ACCESS_TOKEN`
+3. automatic OAuth with local token cache
+
+So the CLI remains compatible with script usage, but the default interactive path is the same URL-only OAuth flow used by MCP hosts.
+
+---
+
+## Installation
+
+### Claude Code
 
 ```sh
 claude mcp add --scope user crush-protocol \
   -- npx -y @crush-protocol/mcp-client \
-  --url https://mcp.crush-protocol.com/mcp \
-  --token mcp_xxx
+  --url https://mcp.crush-protocol.com/mcp
 ```
 
-Or via environment variables in `~/.claude.json`:
+On first use, Claude-compatible hosts should open the browser and complete OAuth automatically.
+
+### Cursor
+
+Add to `~/.cursor/mcp.json`:
 
 ```json
 {
@@ -62,17 +133,16 @@ Or via environment variables in `~/.claude.json`:
             "command": "npx",
             "args": ["-y", "@crush-protocol/mcp-client"],
             "env": {
-                "CRUSH_MCP_SERVER_URL": "https://mcp.crush-protocol.com/mcp",
-                "CRUSH_MCP_TOKEN": "mcp_xxx"
+                "CRUSH_MCP_SERVER_URL": "https://mcp.crush-protocol.com/mcp"
             }
         }
     }
 }
 ```
 
-### Cursor
+### Windsurf
 
-Add to `~/.cursor/mcp.json`:
+Add to your MCP configuration:
 
 ```json
 {
@@ -81,14 +151,44 @@ Add to `~/.cursor/mcp.json`:
             "command": "npx",
             "args": ["-y", "@crush-protocol/mcp-client"],
             "env": {
-                "CRUSH_MCP_SERVER_URL": "https://mcp.crush-protocol.com/mcp",
-                "CRUSH_MCP_TOKEN": "mcp_xxx"
+                "CRUSH_MCP_SERVER_URL": "https://mcp.crush-protocol.com/mcp"
             }
         }
     }
 }
 ```
 
+> On first use, the client will prompt you to log in via your browser and persist OAuth tokens under `~/.crush-mcp/`.
+
+### Host Integration Notes
+
+For Scheme C hosts, the recommended integration is:
+
+1. Configure only the MCP URL
+2. Let the client attempt `/mcp`
+3. When the server returns `401` with `WWW-Authenticate`, start OAuth discovery
+4. Complete Authorization Code + PKCE in the browser
+5. Persist tokens locally and reconnect
+
+If a host cannot yet complete this flow automatically, run:
+
+```sh
+crush-mcp-client login --url https://mcp.crush-protocol.com/mcp
+```
+
+This pre-authorizes the local client cache without requiring manual token copying.
+
+### Unified Production Architecture
+
+Crush MCP now uses one production auth path for remote access:
+
+1. The host knows only the MCP URL
+2. The MCP server returns OAuth discovery hints when auth is required
+3. The client dynamically registers, runs Authorization Code + PKCE, and persists credentials locally
+4. Authorization codes, access tokens, and refresh tokens are all managed server-side under the OAuth data model
+
+There is no separate legacy MCP token service in the production path.
+
 ---
 
 ## Available Tools
@@ -96,7 +196,7 @@ Add to `~/.cursor/mcp.json`:
 | 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`                             |
+| **Backtest**            | `get_backtest_config_schema`, `get_available_tokens`, `validate_expression`, `create_backtest`, `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`                                  |
@@ -109,10 +209,10 @@ Add to `~/.cursor/mcp.json`:
 
 ## Environment Variables
 
-| Variable               | Description                                                    |
-| ---------------------- | -------------------------------------------------------------- |
-| `CRUSH_MCP_SERVER_URL` | MCP server URL (default: `https://mcp.crush-protocol.com/mcp`) |
-| `CRUSH_MCP_TOKEN`      | MCP auth token (`mcp_xxx`)                                     |
+| Variable                    | Description                                                     |
+| --------------------------- | --------------------------------------------------------------- |
+| `CRUSH_MCP_SERVER_URL`      | MCP server URL (default: `https://mcp.crush-protocol.com/mcp`) |
+| `CRUSH_OAUTH_ACCESS_TOKEN`  | Optional override for a pre-issued OAuth access token           |
 
 ---
 
@@ -121,11 +221,10 @@ Add to `~/.cursor/mcp.json`:
 For programmatic access:
 
 ```typescript
-import { RemoteMcpClient, BacktestClient } from '@crush-protocol/mcp-client'
+import { OAuthRemoteMcpClient, BacktestClient } from '@crush-protocol/mcp-client'
 
-const mcp = new RemoteMcpClient({
+const mcp = new OAuthRemoteMcpClient({
     serverUrl: 'https://mcp.crush-protocol.com/mcp',
-    token: 'mcp_xxx',
 })
 await mcp.connect()
 
@@ -135,7 +234,7 @@ const bt = await backtest.createBacktest({
         /* ... */
     },
 })
-const result = await backtest.getResult({ backtestId: bt.backtestId })
+const result = await backtest.list({ limit: 10 })
 
 await mcp.close()
 ```

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_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 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.
      */

package/dist/cli.js

@@ -2,9 +2,10 @@
 import "dotenv/config";
 import { BacktestClient } from "./backtest/backtestClient.js";
 import { ClickHouseDirectClient } from "./clickhouse/directClient.js";
+import { OAuthRemoteMcpClient } from "./mcp/oauthRemoteClient.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`);
+    console.log(`\ncrush-mcp-client\n\nGeneral:\n  login [--url URL]\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: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\nAuth:\n  --token TOKEN overrides auto OAuth (for CI/scripts).\n  Without --token, OAuth flow runs automatically (browser login on first use).\n\nEnv fallback:\n  CRUSH_MCP_SERVER_URL, CRUSH_OAUTH_ACCESS_TOKEN\n  CH_HOST, CH_PORT, CH_USER, CH_PASSWORD, CH_DATABASE, CH_ROW_CAP\n`);
 };
 const parseFlags = (args) => {
     const flags = {};
@@ -29,34 +30,53 @@ const requireString = (value, message) => {
     }
     return value;
 };
-const createRemoteClient = (flags) => {
-    const serverUrl = typeof flags.url === "string"
-        ? flags.url
-        : (process.env.CRUSH_MCP_SERVER_URL ?? "https://mcp.crush-protocol.com/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 getServerUrl = (flags) => typeof flags.url === "string"
+    ? flags.url
+    : (process.env.CRUSH_MCP_SERVER_URL ?? "https://mcp.crush-protocol.com/mcp");
+/**
+ * 创建 MCP 客户端（统一认证入口）
+ *
+ * 优先级：
+ * 1. --token 参数 → 直接使用（适用于 CI/脚本）
+ * 2. CRUSH_OAUTH_ACCESS_TOKEN 环境变量 → 直接使用
+ * 3. 以上都没有 → 走 OAuthRemoteMcpClient 自动 OAuth 流程
+ *    - 本地有缓存 token → 直接用
+ *    - token 过期 → 自动 refresh
+ *    - 无 token → 自动拉起浏览器登录
+ */
+const createSmartClient = (flags) => {
+    const serverUrl = getServerUrl(flags);
+    // 显式传了 token → 用简单客户端
+    const explicitToken = typeof flags.token === "string" ? flags.token : process.env.CRUSH_OAUTH_ACCESS_TOKEN || "";
+    if (explicitToken) {
+        return {
+            client: new RemoteMcpClient({ serverUrl, token: explicitToken }),
+            needsOAuthConnect: false,
+        };
+    }
+    // 否则走 OAuth 自动流程
+    return {
+        client: new OAuthRemoteMcpClient({ serverUrl }),
+        needsOAuthConnect: true,
+    };
+};
+const connectClient = async (flags) => {
+    const { client, needsOAuthConnect } = createSmartClient(flags);
+    if (needsOAuthConnect) {
+        await client.connect();
+    }
+    else {
+        await client.connect();
+    }
+    return client;
 };
 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 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}`);
@@ -80,18 +100,26 @@ const createClickHouseClient = (flags) => {
 };
 const run = async () => {
     const [, , command, ...rest] = process.argv;
-    if (!command ||
-        command === "help" ||
-        command === "--help" ||
-        command === "-h") {
+    if (!command || command === "help" || command === "--help" || command === "-h") {
         printUsage();
         return;
     }
     const flags = parseFlags(rest);
     switch (command) {
+        case "login": {
+            const serverUrl = getServerUrl(flags);
+            const client = new OAuthRemoteMcpClient({ serverUrl });
+            try {
+                await client.ensureAuthorized();
+                console.log("OAuth authorization is ready. Tokens are stored locally.");
+            }
+            finally {
+                await client.close();
+            }
+            return;
+        }
         case "tools:list": {
-            const client = createRemoteClient(flags);
-            await client.connect();
+            const client = await connectClient(flags);
             try {
                 const result = await client.listTools();
                 console.log(JSON.stringify(result, null, 2));
@@ -111,8 +139,7 @@ const run = async () => {
             catch (e) {
                 throw new Error(`Invalid --args JSON: ${e.message}`);
             }
-            const client = createRemoteClient(flags);
-            await client.connect();
+            const client = await connectClient(flags);
             try {
                 const result = await client.callTool(name, parsedArgs);
                 console.log(JSON.stringify(result, null, 2));
@@ -123,8 +150,7 @@ const run = async () => {
             return;
         }
         case "ping": {
-            const client = createRemoteClient(flags);
-            await client.connect();
+            const client = await connectClient(flags);
             try {
                 const result = await client.ping();
                 console.log(JSON.stringify(result, null, 2));
@@ -135,8 +161,7 @@ const run = async () => {
             return;
         }
         case "backtest:schema": {
-            const client = createRemoteClient(flags);
-            await client.connect();
+            const client = await connectClient(flags);
             try {
                 const bt = new BacktestClient(client);
                 const result = await bt.getConfigSchema();
@@ -148,8 +173,7 @@ const run = async () => {
             return;
         }
         case "backtest:tokens": {
-            const client = createRemoteClient(flags);
-            await client.connect();
+            const client = await connectClient(flags);
             try {
                 const bt = new BacktestClient(client);
                 const platform = typeof flags.platform === "string" ? flags.platform : undefined;
@@ -174,11 +198,8 @@ const run = async () => {
             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();
+            const dataSource = typeof flags["data-source"] === "string" ? flags["data-source"] : undefined;
+            const client = await connectClient(flags);
             try {
                 const bt = new BacktestClient(client);
                 const result = await bt.validateExpression({ expression, dataSource });
@@ -198,11 +219,8 @@ const run = async () => {
             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();
+            const backtestId = typeof flags["backtest-id"] === "string" ? flags["backtest-id"] : undefined;
+            const client = await connectClient(flags);
             try {
                 const bt = new BacktestClient(client);
                 const result = await bt.createBacktest({ config, backtestId });
@@ -213,28 +231,11 @@ const run = async () => {
             }
             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 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();
+            const client = await connectClient(flags);
             try {
                 const bt = new BacktestClient(client);
                 const result = await bt.list({ status, limit, offset });

package/dist/index.d.ts

@@ -1,3 +1,6 @@
-export { ClickHouseDirectClient, DEFAULT_ROW_CAP, type ClickHouseDirectConfig, } from "./clickhouse/directClient.js";
+export { BacktestClient, type BacktestConfigSchema, type BacktestRecord, type CreateBacktestInput, type GetAvailableTokensInput, type ListBacktestsInput, type ListBacktestsResult, type TokenInfo, type ValidationResult, } from "./backtest/backtestClient.js";
+export { ClickHouseDirectClient, type ClickHouseDirectConfig, DEFAULT_ROW_CAP, } from "./clickhouse/directClient.js";
+export { InteractiveOAuthProvider, type InteractiveOAuthProviderOptions, } from "./mcp/oauthProvider.js";
+export { OAuthRemoteMcpClient, type OAuthRemoteMcpClientOptions, } from "./mcp/oauthRemoteClient.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";
+export type { McpClientLike } from "./mcp/types.js";

package/dist/index.js

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

package/dist/mcp/oauthProvider.d.ts

@@ -0,0 +1,42 @@
+import type { OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.js";
+import type { OAuthClientInformationMixed, OAuthClientMetadata, OAuthTokens } from "@modelcontextprotocol/sdk/shared/auth.js";
+export type InteractiveOAuthProviderOptions = {
+    serverUrl: string;
+    clientName?: string;
+    clientVersion?: string;
+    scope?: string;
+    redirectPort?: number;
+    redirectPath?: string;
+    storageDir?: string;
+    openBrowser?: boolean;
+    onAuthorizationUrl?: (authorizationUrl: URL) => void | Promise<void>;
+};
+export declare class InteractiveOAuthProvider implements OAuthClientProvider {
+    private readonly options;
+    readonly redirectUrl: URL;
+    private readonly storageFile;
+    private readonly scope;
+    private readonly openBrowserByDefault;
+    private readonly onAuthorizationUrl?;
+    private callbackServer?;
+    private pendingAuthorization?;
+    constructor(options: InteractiveOAuthProviderOptions);
+    get clientMetadata(): OAuthClientMetadata;
+    state(): Promise<string>;
+    clientInformation(): Promise<OAuthClientInformationMixed | undefined>;
+    saveClientInformation(clientInformation: OAuthClientInformationMixed): Promise<void>;
+    tokens(): Promise<OAuthTokens | undefined>;
+    saveTokens(tokens: OAuthTokens): Promise<void>;
+    redirectToAuthorization(authorizationUrl: URL): Promise<void>;
+    saveCodeVerifier(codeVerifier: string): Promise<void>;
+    codeVerifier(): Promise<string>;
+    invalidateCredentials(scope: "all" | "client" | "tokens" | "verifier"): Promise<void>;
+    waitForAuthorizationCode(): Promise<string>;
+    close(): Promise<void>;
+    private loadState;
+    private saveState;
+    private createPendingAuthorization;
+    private ensureCallbackServer;
+    private closeCallbackServer;
+    private handleCallbackRequest;
+}

package/dist/mcp/oauthProvider.js

@@ -0,0 +1,264 @@
+import { spawn } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { createServer } from "node:http";
+import os from "node:os";
+import path from "node:path";
+const DEFAULT_SCOPE = "mcp:tools";
+const DEFAULT_REDIRECT_PORT = 8787;
+const DEFAULT_REDIRECT_PATH = "/oauth/callback";
+const renderCallbackHtml = (title, message) => `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${title}</title>
+  <style>
+    body {
+      margin: 0;
+      min-height: 100vh;
+      display: grid;
+      place-items: center;
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+      background: linear-gradient(135deg, #f6f7fb, #eef2ff);
+      color: #0f172a;
+    }
+    main {
+      max-width: 560px;
+      padding: 32px;
+      border-radius: 20px;
+      background: rgba(255, 255, 255, 0.96);
+      box-shadow: 0 20px 45px rgba(15, 23, 42, 0.14);
+      text-align: center;
+    }
+    h1 {
+      margin: 0 0 12px;
+      font-size: 28px;
+    }
+    p {
+      margin: 0;
+      line-height: 1.6;
+      color: #334155;
+    }
+  </style>
+</head>
+<body>
+  <main>
+    <h1>${title}</h1>
+    <p>${message}</p>
+  </main>
+</body>
+</html>`;
+const defaultStorageDir = () => path.join(os.homedir(), ".crush-mcp");
+const hashServerUrl = (serverUrl) => createHash("sha256").update(serverUrl).digest("hex").slice(0, 16);
+const openBrowser = async (authorizationUrl) => {
+    const url = authorizationUrl.toString();
+    if (process.env.BROWSER) {
+        spawn(process.env.BROWSER, [url], { stdio: "ignore", detached: true }).unref();
+        return;
+    }
+    if (process.platform === "darwin") {
+        spawn("open", [url], { stdio: "ignore", detached: true }).unref();
+        return;
+    }
+    if (process.platform === "win32") {
+        spawn("cmd", ["/c", "start", "", url], { stdio: "ignore", detached: true }).unref();
+        return;
+    }
+    spawn("xdg-open", [url], { stdio: "ignore", detached: true }).unref();
+};
+export class InteractiveOAuthProvider {
+    options;
+    redirectUrl;
+    storageFile;
+    scope;
+    openBrowserByDefault;
+    onAuthorizationUrl;
+    callbackServer;
+    pendingAuthorization;
+    constructor(options) {
+        this.options = options;
+        const redirectPort = options.redirectPort ?? DEFAULT_REDIRECT_PORT;
+        const redirectPath = options.redirectPath ?? DEFAULT_REDIRECT_PATH;
+        this.redirectUrl = new URL(`http://127.0.0.1:${redirectPort}${redirectPath}`);
+        this.scope = options.scope ?? DEFAULT_SCOPE;
+        this.openBrowserByDefault = options.openBrowser ?? true;
+        const storageDir = options.storageDir ?? defaultStorageDir();
+        this.storageFile = path.join(storageDir, `oauth-${hashServerUrl(options.serverUrl)}.json`);
+        this.onAuthorizationUrl = options.onAuthorizationUrl;
+    }
+    get clientMetadata() {
+        return {
+            client_name: this.options.clientName ?? "Crush MCP Client",
+            grant_types: ["authorization_code", "refresh_token"],
+            redirect_uris: [this.redirectUrl.toString()],
+            response_types: ["code"],
+            scope: this.scope,
+            software_version: this.options.clientVersion,
+            token_endpoint_auth_method: "none",
+        };
+    }
+    async state() {
+        return randomBytes(16).toString("hex");
+    }
+    async clientInformation() {
+        const data = await this.loadState();
+        return data.clientInformation;
+    }
+    async saveClientInformation(clientInformation) {
+        const data = await this.loadState();
+        data.clientInformation = clientInformation;
+        await this.saveState(data);
+    }
+    async tokens() {
+        const data = await this.loadState();
+        return data.tokens;
+    }
+    async saveTokens(tokens) {
+        const data = await this.loadState();
+        data.tokens = tokens;
+        await this.saveState(data);
+    }
+    async redirectToAuthorization(authorizationUrl) {
+        this.createPendingAuthorization();
+        await this.ensureCallbackServer();
+        if (this.onAuthorizationUrl) {
+            await this.onAuthorizationUrl(authorizationUrl);
+        }
+        if (this.openBrowserByDefault) {
+            try {
+                await openBrowser(authorizationUrl);
+            }
+            catch {
+                // Fall back to printing the URL when no browser launcher is available.
+            }
+        }
+        process.stdout.write(`\nOpen this URL to authorize Crush MCP:\n${authorizationUrl.toString()}\n\n`);
+    }
+    async saveCodeVerifier(codeVerifier) {
+        const data = await this.loadState();
+        data.codeVerifier = codeVerifier;
+        await this.saveState(data);
+    }
+    async codeVerifier() {
+        const data = await this.loadState();
+        if (!data.codeVerifier) {
+            throw new Error("Missing PKCE code verifier. Restart the OAuth flow.");
+        }
+        return data.codeVerifier;
+    }
+    async invalidateCredentials(scope) {
+        const data = await this.loadState();
+        if (scope === "all") {
+            await rm(this.storageFile, { force: true });
+            return;
+        }
+        if (scope === "client") {
+            delete data.clientInformation;
+        }
+        if (scope === "tokens") {
+            delete data.tokens;
+        }
+        if (scope === "verifier") {
+            delete data.codeVerifier;
+        }
+        await this.saveState(data);
+    }
+    async waitForAuthorizationCode() {
+        if (!this.pendingAuthorization) {
+            this.createPendingAuthorization();
+        }
+        return this.pendingAuthorization.promise;
+    }
+    async close() {
+        await this.closeCallbackServer();
+    }
+    async loadState() {
+        try {
+            const raw = await readFile(this.storageFile, "utf8");
+            return JSON.parse(raw);
+        }
+        catch (error) {
+            const err = error;
+            if (err.code === "ENOENT") {
+                return {};
+            }
+            throw error;
+        }
+    }
+    async saveState(data) {
+        await mkdir(path.dirname(this.storageFile), { recursive: true });
+        await writeFile(this.storageFile, JSON.stringify(data, null, 2), "utf8");
+    }
+    createPendingAuthorization() {
+        let resolve;
+        let reject;
+        const promise = new Promise((innerResolve, innerReject) => {
+            resolve = innerResolve;
+            reject = innerReject;
+        });
+        this.pendingAuthorization = { promise, resolve, reject };
+        return this.pendingAuthorization;
+    }
+    async ensureCallbackServer() {
+        if (this.callbackServer) {
+            return;
+        }
+        this.callbackServer = createServer((req, res) => {
+            void this.handleCallbackRequest(req, res);
+        });
+        await new Promise((resolve, reject) => {
+            this.callbackServer.once("error", (error) => reject(error));
+            this.callbackServer.listen(Number(this.redirectUrl.port), this.redirectUrl.hostname, () => resolve());
+        });
+    }
+    async closeCallbackServer() {
+        if (!this.callbackServer) {
+            return;
+        }
+        const server = this.callbackServer;
+        this.callbackServer = undefined;
+        await new Promise((resolve, reject) => {
+            server.close((error) => {
+                if (error) {
+                    reject(error);
+                    return;
+                }
+                resolve();
+            });
+        });
+    }
+    async handleCallbackRequest(req, res) {
+        const requestUrl = new URL(req.url || "/", this.redirectUrl);
+        if (requestUrl.pathname !== this.redirectUrl.pathname) {
+            res.statusCode = 404;
+            res.end("Not found");
+            return;
+        }
+        const error = requestUrl.searchParams.get("error");
+        const errorDescription = requestUrl.searchParams.get("error_description");
+        const code = requestUrl.searchParams.get("code");
+        res.setHeader("Content-Type", "text/html; charset=utf-8");
+        if (error) {
+            res.statusCode = 400;
+            res.end(renderCallbackHtml("Authorization failed", errorDescription || error));
+            this.pendingAuthorization?.reject(new Error(errorDescription || error));
+            this.pendingAuthorization = undefined;
+            await this.closeCallbackServer();
+            return;
+        }
+        if (!code) {
+            res.statusCode = 400;
+            res.end(renderCallbackHtml("Authorization failed", "Missing authorization code."));
+            this.pendingAuthorization?.reject(new Error("Missing authorization code in callback."));
+            this.pendingAuthorization = undefined;
+            await this.closeCallbackServer();
+            return;
+        }
+        res.statusCode = 200;
+        res.end(renderCallbackHtml("Authorization complete", "You can close this tab and return to your MCP client."));
+        this.pendingAuthorization?.resolve(code);
+        this.pendingAuthorization = undefined;
+        await this.closeCallbackServer();
+    }
+}

package/dist/mcp/oauthRemoteClient.d.ts

@@ -0,0 +1,171 @@
+import { type AuthResult } from "@modelcontextprotocol/sdk/client/auth.js";
+import { type InteractiveOAuthProviderOptions } from "./oauthProvider.js";
+import type { McpClientLike } from "./types.js";
+export type OAuthRemoteMcpClientOptions = {
+    serverUrl: string;
+    clientName?: string;
+    clientVersion?: string;
+    scope?: string;
+    token?: string;
+    fetch?: typeof fetch;
+    oauth?: Omit<InteractiveOAuthProviderOptions, "serverUrl" | "clientName" | "clientVersion" | "scope">;
+};
+export declare class OAuthRemoteMcpClient implements McpClientLike {
+    private readonly options;
+    private readonly client;
+    private readonly transport;
+    private readonly authProvider;
+    constructor(options: OAuthRemoteMcpClientOptions);
+    connect(): Promise<void>;
+    ensureAuthorized(): Promise<void>;
+    runAuthFlow(): Promise<AuthResult>;
+    completeAuthorization(): 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/oauthRemoteClient.js

@@ -0,0 +1,95 @@
+import { auth, UnauthorizedError } from "@modelcontextprotocol/sdk/client/auth.js";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { InteractiveOAuthProvider } from "./oauthProvider.js";
+export class OAuthRemoteMcpClient {
+    options;
+    client;
+    transport;
+    authProvider;
+    constructor(options) {
+        this.options = options;
+        this.client = new Client({
+            name: options.clientName ?? "crush-mcp-client",
+            version: options.clientVersion ?? "0.2.0",
+        }, {
+            capabilities: {},
+        });
+        this.authProvider = new InteractiveOAuthProvider({
+            serverUrl: options.serverUrl,
+            clientName: options.clientName,
+            clientVersion: options.clientVersion,
+            scope: options.scope,
+            ...options.oauth,
+        });
+        this.transport = new StreamableHTTPClientTransport(new URL(options.serverUrl), {
+            authProvider: this.authProvider,
+            requestInit: options.token
+                ? {
+                    headers: {
+                        Authorization: `Bearer ${options.token}`,
+                    },
+                }
+                : undefined,
+            fetch: options.fetch,
+        });
+    }
+    async connect() {
+        try {
+            await this.client.connect(this.transport);
+        }
+        catch (error) {
+            if (!(error instanceof UnauthorizedError)) {
+                throw error;
+            }
+            const authResult = await auth(this.authProvider, {
+                serverUrl: this.options.serverUrl,
+                scope: this.options.scope,
+                fetchFn: this.options.fetch,
+            });
+            if (authResult !== "REDIRECT") {
+                await this.client.connect(this.transport);
+                return;
+            }
+            const authorizationCode = await this.authProvider.waitForAuthorizationCode();
+            await this.transport.finishAuth(authorizationCode);
+            await this.client.connect(this.transport);
+        }
+    }
+    async ensureAuthorized() {
+        const authResult = await this.runAuthFlow();
+        if (authResult === "REDIRECT") {
+            await this.completeAuthorization();
+        }
+    }
+    async runAuthFlow() {
+        return auth(this.authProvider, {
+            serverUrl: this.options.serverUrl,
+            scope: this.options.scope,
+            fetchFn: this.options.fetch,
+        });
+    }
+    async completeAuthorization() {
+        const authorizationCode = await this.authProvider.waitForAuthorizationCode();
+        await this.transport.finishAuth(authorizationCode);
+    }
+    async close() {
+        await this.authProvider.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/dist/mcp/remoteClient.d.ts

@@ -1,10 +1,11 @@
+import type { McpClientLike } from "./types.js";
 export type RemoteMcpClientOptions = {
     serverUrl: string;
     token: string;
     clientName?: string;
     clientVersion?: string;
 };
-export declare class RemoteMcpClient {
+export declare class RemoteMcpClient implements McpClientLike {
     private readonly client;
     private readonly transport;
     constructor(options: RemoteMcpClientOptions);

package/dist/mcp/remoteClient.js

@@ -4,8 +4,8 @@ export class RemoteMcpClient {
     client;
     transport;
     constructor(options) {
-        if (!options.token.startsWith("mcp_")) {
-            throw new Error("Invalid token format. Expected mcp_xxx");
+        if (typeof options.token !== "string" || options.token.trim().length === 0) {
+            throw new Error("Invalid token. Expected a non-empty OAuth access token");
         }
         this.client = new Client({
             name: options.clientName || "crush-mcp-client",

package/dist/mcp/types.d.ts

@@ -0,0 +1,8 @@
+export interface McpClientLike {
+    connect(): Promise<void>;
+    close(): Promise<void>;
+    terminateSession(): Promise<void>;
+    ping(): Promise<unknown>;
+    listTools(): Promise<unknown>;
+    callTool(name: string, args?: Record<string, unknown>): Promise<unknown>;
+}

package/dist/mcp/types.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crush-protocol/mcp-client",
-  "version": "0.1.13",
+  "version": "0.2.0",
   "description": "Crush MCP npm client package (remote Streamable HTTP + optional ClickHouse direct)",
   "type": "module",
   "license": "MIT",
@@ -13,6 +13,9 @@
     "dist",
     "INSTRUCTIONS.md"
   ],
+  "publishConfig": {
+    "access": "public"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -23,7 +26,7 @@
     "@modelcontextprotocol/sdk": "^1.26.0",
     "dotenv": "^17.2.1",
     "zod": "^3.25.76",
-    "@crush-protocol/mcp-contracts": "0.1.0"
+    "@crush-protocol/mcp-contracts": "0.1.1"
   },
   "devDependencies": {
     "@types/node": "^24.3.0",
@@ -38,6 +41,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "dev": "tsx src/cli.ts",
+    "test": "vitest run",
     "test:e2e": "dotenv -e .env.e2e vitest run src/__tests__/e2e.test.ts"
   }
 }