@crush-protocol/mcp-client 0.4.1 → 0.4.3

package/INSTRUCTIONS.md

@@ -2,7 +2,11 @@
 
 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.
+Authentication note: remote MCP requests use OAuth Bearer access tokens issued by the Crush OAuth server. In supported MCP hosts, users typically authenticate once with:
+
+`npx -y @crush-protocol/mcp-client login`
+
+After login, credentials are cached locally and reused across supported hosts.
 
 ## Tool Categories
 

package/README.md

@@ -3,56 +3,73 @@
 [![npm version](https://img.shields.io/npm/v/@crush-protocol/mcp-client)](https://www.npmjs.com/package/@crush-protocol/mcp-client)
 [![MIT licensed](https://img.shields.io/npm/l/@crush-protocol/mcp-client)](./LICENSE)
 
-`@crush-protocol/mcp-client` is the npm entrypoint for Crush Protocol MCP.
+> Connect Cursor, Claude Code, Codex, Gemini CLI, and other MCP hosts to Crush's hosted trading tools through one npm package.
 
 Crush Protocol is an AI-native quantitative trading product. It lets an MCP host connect to Crush and use trading-focused tools for strategy research, backtest creation, live strategy management, and market data discovery.
 
-## Quick Setup
+## Quick Start
+
+Use this flow for the first successful Crush session:
 
 ```sh
-npx -y @crush-protocol/mcp-client setup --all
+npx -y @crush-protocol/mcp-client setup --cursor
+npx -y @crush-protocol/mcp-client login
+npx -y @crush-protocol/mcp-client ping
 ```
 
-This writes MCP config for all **9** supported hosts: Cursor, Claude Code, Codex, Gemini CLI, OpenCode, VS Code, Windsurf, Claude Desktop, Warp.
+What these commands do:
 
-To target a single host: `npx -y @crush-protocol/mcp-client setup --cursor`
+1. `setup` writes MCP config for your host.
+2. `login` opens the browser once and stores OAuth credentials locally.
+3. `ping` confirms that your local credentials can reach the hosted Crush MCP.
 
-The default hosted MCP endpoint is `https://crush-mcp-ats.dev.xexlab.com/mcp`.
+The official hosted MCP URL is built in. Users do not need to add it manually to host configs.
 
-**[All Client Configurations →](#client-configuration)**
+To configure every supported host at once, run `npx -y @crush-protocol/mcp-client setup --all`.
 
-## How It Works
+## What You Can Do
 
-The CLI acts as a **stdio ↔ HTTP proxy**: it reads cached OAuth tokens from `~/.crush-mcp/`, connects to the Crush MCP server, and bridges all requests over stdio. No extra arguments needed.
+Crush tools are grouped around four common workflows:
 
-```
-AI Tool ──stdio──▶ @crush-protocol/mcp-client ──HTTP+Bearer──▶ MCP Server
-                         ▲
-                   reads ~/.crush-mcp/
-                   (cached OAuth tokens)
-```
+- Market data: `list_tokens`, `list_indicators`, `list_timeframes`, `fetch_ohlcv`, `fetch_indicator`
+- Backtests: `get_backtest_config_schema`, `get_available_tokens`, `validate_expression`, `create_backtest`, `list_backtests`
+- Live strategies: `create_strategy`, `list_strategies`, `get_strategy`, `update_strategy`, `toggle_strategy`, `get_strategy_logs`
+- Market intelligence: `search_tokens`, `get_token_info`, `get_trending_tokens`, `get_alpha_feed`, `get_token_feed`, `fetch_news`
 
-**First-time setup (one-time):**
+Detailed tool guidance is in [INSTRUCTIONS.md](./INSTRUCTIONS.md).
 
-```sh
-npx -y @crush-protocol/mcp-client login
-```
+## First Things To Ask
 
-This opens a browser for OAuth login. Tokens are cached in `~/.crush-mcp/` and shared across all AI tools. Token refresh is automatic.
+These prompts work well for both users and MCP hosts:
 
-## Available Tools
+- `List the tokens available in Crush.`
+- `Show me the indicators and timeframes available in Crush.`
+- `Fetch OHLCV data for BTC.`
+- `Create a simple moving-average crossover backtest.`
+- `List my recent backtests.`
+- `Show my current live strategies.`
 
-**Market Data** — `list_tables` · `list_tokens` · `list_indicators` · `list_timeframes` · `get_data_range` · `check_query_size` · `fetch_ohlcv` · `fetch_indicator` · `fetch_news` · `get_connection_config` · `save_custom_indicator` · `list_custom_indicators` · `get_custom_indicator` · `delete_custom_indicator`
+## Authentication
 
-**Backtest** — `get_backtest_config_schema` · `get_available_tokens` · `validate_expression` · `create_backtest` · `list_backtests`
+Crush stores OAuth credentials in `~/.crush-mcp/` and reuses them across supported MCP hosts.
 
-**Strategy** — `create_strategy` · `list_strategies` · `get_strategy` · `update_strategy` · `delete_strategy` · `toggle_strategy` · `get_strategy_logs`
+If tools appear in your AI host but return an auth error, run:
 
-**Signal** — `get_signal_metadata` · `get_signals_by_category`
+```sh
+npx -y @crush-protocol/mcp-client login
+```
 
-**Utilities** — `search_tokens` · `get_token_info` · `get_trending_tokens` · `get_alpha_feed` · `get_token_feed`
+After login, retry the same request in your AI host. Token refresh is automatic when possible.
 
-Detailed tool guidance is in [INSTRUCTIONS.md](./INSTRUCTIONS.md).
+## How It Works
+
+The CLI acts as a stdio-to-HTTP bridge:
+
+```text
+AI host -> @crush-protocol/mcp-client -> Crush MCP server
+```
+
+Your AI host launches `@crush-protocol/mcp-client` over stdio. The client loads cached OAuth credentials from `~/.crush-mcp/`, connects to the hosted Crush MCP, and forwards all tool requests over authenticated HTTP.
 
 ## Client Configuration
 
@@ -639,7 +656,9 @@ Use `cmd` as the command wrapper:
 
 ```sh
 # Auth
-npx -y @crush-protocol/mcp-client login              # OAuth login (browser)
+npx -y @crush-protocol/mcp-client login               # OAuth login (browser)
+npx -y @crush-protocol/mcp-client auth:status         # Show local Crush auth state
+npx -y @crush-protocol/mcp-client doctor              # Check auth state and connectivity
 npx -y @crush-protocol/mcp-client setup --all         # Auto-write config for all supported hosts
 
 # Tools
@@ -651,6 +670,38 @@ npx -y @crush-protocol/mcp-client backtest:schema     # Backtest config schema
 npx -y @crush-protocol/mcp-client backtest:list --limit 10
 ```
 
+## Troubleshooting
+
+### Tools appear, but calls fail with auth errors
+
+Run:
+
+```sh
+npx -y @crush-protocol/mcp-client login
+```
+
+Then retry the same request in your AI host.
+
+### I installed Crush but do not see tools yet
+
+Restart your AI host session after `setup`.
+
+### I want to confirm whether this machine is logged in
+
+Run:
+
+```sh
+npx -y @crush-protocol/mcp-client auth:status
+```
+
+### I want a quick connectivity check
+
+Run:
+
+```sh
+npx -y @crush-protocol/mcp-client doctor
+```
+
 ### Environment Variables
 
 | Variable | Description | Default |

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

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

package/dist/__tests__/cliOutput.test.js

@@ -0,0 +1,34 @@
+import { describe, expect, it } from "vitest";
+import { formatAuthStatus, formatSetupSummary, getLoginCommand } from "../onboarding/cliOutput.js";
+describe("cliOutput", () => {
+    it("renders setup summary with next steps", () => {
+        const results = [
+            {
+                target: "cursor",
+                scope: "user",
+                status: "created",
+                location: "/tmp/.cursor/mcp.json",
+            },
+        ];
+        const output = formatSetupSummary(results, "user");
+        expect(output).toContain("Crush MCP configured for Cursor.");
+        expect(output).toContain("Restart Cursor");
+        expect(output).toContain("npx -y @crush-protocol/mcp-client login");
+    });
+    it("renders auth status with login guidance when missing", () => {
+        const output = formatAuthStatus({
+            serverUrl: "https://crush-mcp-ats.dev.xexlab.com/mcp",
+            status: "not_authenticated",
+            hasClientInformation: false,
+            hasAccessToken: false,
+            hasRefreshToken: false,
+            hasCodeVerifier: false,
+        });
+        expect(output).toContain("Status: Not authenticated");
+        expect(output).toContain("Run:");
+        expect(output).toContain("npx -y @crush-protocol/mcp-client login");
+    });
+    it("renders custom login command for non-default server URLs", () => {
+        expect(getLoginCommand("https://example.com/mcp")).toBe('CRUSH_MCP_SERVER_URL="https://example.com/mcp" npx -y @crush-protocol/mcp-client login');
+    });
+});

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

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

package/dist/__tests__/oauthStorage.test.js

@@ -0,0 +1,52 @@
+import { mkdtemp, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { defaultStorageDir, getCachedAuthStatus, getStorageFileForServer, loadStoredTokens, } from "../mcp/oauthStorage.js";
+const tempDirs = [];
+describe("oauthStorage", () => {
+    afterEach(async () => {
+        await Promise.all(tempDirs
+            .splice(0)
+            .map((dir) => import("node:fs/promises").then((fs) => fs.rm(dir, { recursive: true, force: true }))));
+    });
+    it("reports authenticated state when tokens are present", async () => {
+        const storageDir = await mkdtemp(path.join(os.tmpdir(), "crush-mcp-storage-"));
+        tempDirs.push(storageDir);
+        const storageFile = getStorageFileForServer("https://example.com/mcp", storageDir);
+        await writeFile(storageFile, JSON.stringify({
+            clientInformation: { client_id: "client_123" },
+            tokens: { access_token: "atk_123", refresh_token: "rt_123", token_type: "Bearer", scope: "mcp:tools" },
+        }), "utf8");
+        const status = await getCachedAuthStatus("https://example.com/mcp", storageDir);
+        expect(status.status).toBe("authenticated");
+        expect(status.hasRefreshToken).toBe(true);
+        expect(status.storageFile).toBe(storageFile);
+    });
+    it("falls back between /mcp and base URL variants", async () => {
+        const storageDir = await mkdtemp(path.join(os.tmpdir(), "crush-mcp-storage-"));
+        tempDirs.push(storageDir);
+        const storageFile = getStorageFileForServer("https://example.com", storageDir);
+        await writeFile(storageFile, JSON.stringify({
+            clientInformation: { client_id: "client_123" },
+            tokens: { access_token: "atk_123", token_type: "Bearer" },
+        }), "utf8");
+        const tokens = await loadStoredTokens("https://example.com/mcp", storageDir);
+        expect(tokens?.access_token).toBe("atk_123");
+    });
+    it("reports registered state when only client metadata exists", async () => {
+        const storageDir = await mkdtemp(path.join(os.tmpdir(), "crush-mcp-storage-"));
+        tempDirs.push(storageDir);
+        const storageFile = getStorageFileForServer("https://example.com/mcp", storageDir);
+        await writeFile(storageFile, JSON.stringify({
+            clientInformation: { client_id: "client_123" },
+            codeVerifier: "verifier_123",
+        }), "utf8");
+        const status = await getCachedAuthStatus("https://example.com/mcp", storageDir);
+        expect(status.status).toBe("registered");
+        expect(status.hasCodeVerifier).toBe(true);
+    });
+    it("uses the default storage directory helper", () => {
+        expect(defaultStorageDir()).toContain(".crush-mcp");
+    });
+});

package/dist/cli.js

@@ -2,13 +2,17 @@
 import "dotenv/config";
 import { BacktestClient } from "./backtest/backtestClient.js";
 import { ClickHouseDirectClient } from "./clickhouse/directClient.js";
+import { DEFAULT_MCP_SERVER_URL } from "./config.js";
 import { OAuthRemoteMcpClient } from "./mcp/oauthRemoteClient.js";
+import { getCachedAuthStatus, loadStoredTokens } from "./mcp/oauthStorage.js";
 import { runProxy } from "./mcp/proxy.js";
 import { RemoteMcpClient } from "./mcp/remoteClient.js";
+import { CLIENT_VERSION } from "./mcp/version.js";
+import { formatAuthStatus, formatDoctorReport, formatSetupSummary, getLoginCommand, } from "./onboarding/cliOutput.js";
 import { ALL_TARGETS, installClientConfig } from "./setup/setupClients.js";
-const MCP_SERVER_URL = process.env.CRUSH_MCP_SERVER_URL || "https://crush-mcp-ats.dev.xexlab.com/mcp";
+const MCP_SERVER_URL = process.env.CRUSH_MCP_SERVER_URL || DEFAULT_MCP_SERVER_URL;
 const printUsage = () => {
-    console.log(`\ncrush-mcp-client\n\nGeneral:\n  login [SERVER_URL]\n  proxy [SERVER_URL]            — stdio proxy (login once, use everywhere)\n  setup [--cursor] [--claude] [--codex] [--gemini] [--opencode] [--all] [--scope user|project]\n  tools:list [--token TOKEN]\n  tool:call --name TOOL_NAME [--args JSON] [--token TOKEN]\n  ping [--token TOKEN]\n\nBacktest:\n  backtest:schema [--token TOKEN]\n  backtest:tokens [--platform PLATFORM] [--token TOKEN]\n  backtest:validate --expression JSON [--data-source kline|factors] [--token TOKEN]\n  backtest:create --config JSON [--backtest-id ID] [--token TOKEN]\n  backtest:list [--status STATUS] [--limit N] [--offset N] [--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 uses a provided OAuth access token.\n  Without --token, OAuth runs automatically in the browser when needed.\n\nProxy Mode (recommended for AI tools):\n  1. Login once:  npx @crush-protocol/mcp-client login SERVER_URL\n  2. Configure:   { "command": "npx", "args": ["-y", "@crush-protocol/mcp-client", "proxy", "SERVER_URL"] }\n\nEnv:\n  CRUSH_MCP_SERVER_URL\n  CRUSH_OAUTH_ACCESS_TOKEN\n  CH_HOST, CH_PORT, CH_USER, CH_PASSWORD, CH_DATABASE, CH_ROW_CAP\n`);
+    console.log(`\ncrush-mcp-client v${CLIENT_VERSION}\n\nQuick start:\n  setup [--cursor] [--claude] [--codex] [--gemini] [--opencode] [--all] [--scope user|project]\n  login\n  ping\n\nGeneral:\n  auth:status                  Show whether Crush is authenticated on this machine\n  doctor                       Check auth state and connectivity\n  proxy [SERVER_URL]           stdio proxy mode for MCP hosts\n  tools:list [--token TOKEN]\n  tool:call --name TOOL_NAME [--args JSON] [--token TOKEN]\n  ping [--token TOKEN]\n  --version\n\nBacktest:\n  backtest:schema [--token TOKEN]\n  backtest:tokens [--platform PLATFORM] [--token TOKEN]\n  backtest:validate --expression JSON [--data-source kline|factors] [--token TOKEN]\n  backtest:create --config JSON [--backtest-id ID] [--token TOKEN]\n  backtest:list [--status STATUS] [--limit N] [--offset N] [--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\nAuthentication:\n  Without --token, Crush uses locally cached OAuth credentials.\n  If not authenticated yet, run:\n    ${getLoginCommand(MCP_SERVER_URL)}\n\nEnv:\n  CRUSH_MCP_SERVER_URL\n  CRUSH_OAUTH_ACCESS_TOKEN\n  CH_HOST, CH_PORT, CH_USER, CH_PASSWORD, CH_DATABASE, CH_ROW_CAP\n`);
 };
 const parseFlags = (args) => {
     const flags = {};
@@ -34,6 +38,7 @@ const requireString = (value, message) => {
     return value;
 };
 const getServerUrl = (override) => override || MCP_SERVER_URL;
+const getExplicitToken = (flags) => typeof flags.token === "string" ? flags.token : process.env.CRUSH_OAUTH_ACCESS_TOKEN || "";
 const getSetupTargets = (flags) => {
     if (flags.all === true) {
         return [...ALL_TARGETS];
@@ -54,7 +59,7 @@ const getSetupTargets = (flags) => {
 const createSmartClient = (flags) => {
     const serverUrl = getServerUrl(typeof flags.server === "string" ? flags.server : undefined);
     // 显式传了 token → 用简单客户端
-    const explicitToken = typeof flags.token === "string" ? flags.token : process.env.CRUSH_OAUTH_ACCESS_TOKEN || "";
+    const explicitToken = getExplicitToken(flags);
     if (explicitToken) {
         return {
             client: new RemoteMcpClient({ serverUrl, token: explicitToken }),
@@ -77,6 +82,78 @@ const connectClient = async (flags) => {
     }
     return client;
 };
+const buildDoctorChecks = async (flags) => {
+    const serverUrl = getServerUrl(typeof flags.server === "string" ? flags.server : undefined);
+    const checks = [];
+    const explicitToken = getExplicitToken(flags);
+    const authStatus = await getCachedAuthStatus(serverUrl);
+    checks.push({
+        status: serverUrl === DEFAULT_MCP_SERVER_URL ? "ok" : "warn",
+        label: "MCP server URL",
+        detail: serverUrl === DEFAULT_MCP_SERVER_URL
+            ? "Using the official hosted Crush MCP URL."
+            : `Using a custom MCP URL: ${serverUrl}`,
+    });
+    if (explicitToken) {
+        checks.push({
+            status: "ok",
+            label: "Access token",
+            detail: "Using an explicit OAuth access token from --token or CRUSH_OAUTH_ACCESS_TOKEN.",
+        });
+    }
+    else if (authStatus.status === "authenticated") {
+        checks.push({
+            status: "ok",
+            label: "Cached credentials",
+            detail: `OAuth credentials found${authStatus.storageFile ? ` in ${authStatus.storageFile}` : ""}.`,
+        });
+    }
+    else if (authStatus.status === "registered") {
+        checks.push({
+            status: "warn",
+            label: "Cached credentials",
+            detail: `Crush client registration exists, but no usable access token was found. Run: ${getLoginCommand(serverUrl)}`,
+        });
+    }
+    else {
+        checks.push({
+            status: "warn",
+            label: "Cached credentials",
+            detail: `No local Crush credentials found. Run: ${getLoginCommand(serverUrl)}`,
+        });
+    }
+    const storedTokens = explicitToken ? undefined : await loadStoredTokens(serverUrl);
+    const accessToken = explicitToken || storedTokens?.access_token || "";
+    if (!accessToken) {
+        checks.push({
+            status: "warn",
+            label: "Connectivity",
+            detail: "Skipped MCP connectivity check because no access token is available yet.",
+        });
+        return { serverUrl, checks };
+    }
+    const client = new RemoteMcpClient({ serverUrl, token: accessToken });
+    try {
+        await client.connect();
+        await client.ping();
+        checks.push({
+            status: "ok",
+            label: "Connectivity",
+            detail: "Connected to Crush MCP and ping succeeded.",
+        });
+    }
+    catch (error) {
+        checks.push({
+            status: "error",
+            label: "Connectivity",
+            detail: `Failed to connect to Crush MCP: ${error.message}`,
+        });
+    }
+    finally {
+        await client.close().catch(() => undefined);
+    }
+    return { serverUrl, checks };
+};
 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");
@@ -111,10 +188,27 @@ const run = async () => {
     // 如果没有已知子命令，自动进入 proxy 模式
     const isStdioPipe = !process.stdin.isTTY;
     const knownCommands = new Set([
-        "proxy", "login", "setup", "tools:list", "tool:call", "ping",
-        "backtest:schema", "backtest:tokens", "backtest:validate", "backtest:create", "backtest:list",
-        "clickhouse:list-tables", "clickhouse:query",
-        "help", "--help", "-h",
+        "proxy",
+        "login",
+        "setup",
+        "auth:status",
+        "doctor",
+        "tools:list",
+        "tool:call",
+        "ping",
+        "backtest:schema",
+        "backtest:tokens",
+        "backtest:validate",
+        "backtest:create",
+        "backtest:list",
+        "clickhouse:list-tables",
+        "clickhouse:query",
+        "help",
+        "--help",
+        "-h",
+        "version",
+        "--version",
+        "-v",
     ]);
     if (isStdioPipe && (!command || !knownCommands.has(command))) {
         // 无命令或第一个参数是 URL → 自动进入 proxy 模式
@@ -126,6 +220,10 @@ const run = async () => {
         printUsage();
         return;
     }
+    if (command === "version" || command === "--version" || command === "-v") {
+        console.log(CLIENT_VERSION);
+        return;
+    }
     const flags = parseFlags(rest);
     switch (command) {
         case "proxy": {
@@ -139,11 +237,23 @@ const run = async () => {
             // login [SERVER_URL] — 第一个非 flag 参数作为 server URL
             const loginUrl = rest.find((a) => !a.startsWith("--"));
             const serverUrl = getServerUrl(loginUrl);
-            console.log(`Connecting to ${serverUrl} ...`);
+            const authStatus = await getCachedAuthStatus(serverUrl);
+            console.log("Connecting to Crush...");
+            console.log(`Server: ${serverUrl}`);
+            if (authStatus.status === "authenticated") {
+                console.log("Existing credentials found. Verifying they are still valid...");
+            }
+            else {
+                console.log("Opening browser for authorization...");
+                console.log("If the browser does not open, use the authorization URL printed below.");
+                console.log("Waiting for authorization callback on:");
+                console.log("http://127.0.0.1:8787/oauth/callback");
+            }
             const client = new OAuthRemoteMcpClient({ serverUrl });
             try {
                 await client.ensureAuthorized();
-                console.log("OAuth authorization is ready. Tokens are stored locally.");
+                console.log("Crush login complete.");
+                console.log("Credentials are stored locally and will be reused across supported MCP hosts.");
             }
             finally {
                 await client.close();
@@ -153,17 +263,29 @@ const run = async () => {
         case "setup": {
             const targets = getSetupTargets(flags);
             if (targets.length === 0) {
-                throw new Error(`Specify at least one setup target: ${ALL_TARGETS.map((t) => "--" + t).join(", ")}, or --all`);
+                throw new Error(`Specify at least one setup target: ${ALL_TARGETS.map((t) => `--${t}`).join(", ")}, or --all`);
             }
             const rawScope = typeof flags.scope === "string" ? flags.scope : "user";
             if (rawScope !== "user" && rawScope !== "project") {
                 throw new Error("Invalid --scope. Expected 'user' or 'project'.");
             }
             const scope = rawScope;
+            const results = [];
             for (const target of targets) {
-                const location = installClientConfig(target, scope);
-                console.log(`[setup] ${target}: configured (${location})`);
+                results.push(installClientConfig(target, scope));
             }
+            console.log(formatSetupSummary(results, scope));
+            return;
+        }
+        case "auth:status": {
+            const serverUrl = getServerUrl(typeof flags.server === "string" ? flags.server : undefined);
+            const authStatus = await getCachedAuthStatus(serverUrl);
+            console.log(formatAuthStatus(authStatus));
+            return;
+        }
+        case "doctor": {
+            const { serverUrl, checks } = await buildDoctorChecks(flags);
+            console.log(formatDoctorReport(serverUrl, checks));
             return;
         }
         case "tools:list": {

package/dist/config.d.ts

@@ -0,0 +1,4 @@
+export declare const PACKAGE_NAME = "@crush-protocol/mcp-client";
+export declare const SERVER_NAME = "crush-protocol";
+export declare const DEFAULT_MCP_SERVER_URL = "https://crush-mcp-ats.dev.xexlab.com/mcp";
+export declare const DEFAULT_OAUTH_SCOPE = "mcp:tools";

package/dist/config.js

@@ -0,0 +1,4 @@
+export const PACKAGE_NAME = "@crush-protocol/mcp-client";
+export const SERVER_NAME = "crush-protocol";
+export const DEFAULT_MCP_SERVER_URL = "https://crush-mcp-ats.dev.xexlab.com/mcp";
+export const DEFAULT_OAUTH_SCOPE = "mcp:tools";

package/dist/mcp/oauthProvider.js

@@ -1,10 +1,10 @@
 import { spawn } from "node:child_process";
-import { createHash, randomBytes } from "node:crypto";
+import { 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";
+import { DEFAULT_OAUTH_SCOPE } from "../config.js";
+import { defaultStorageDir, getStorageFileForServer } from "./oauthStorage.js";
 const DEFAULT_REDIRECT_PORT = 8787;
 const DEFAULT_REDIRECT_PATH = "/oauth/callback";
 const escapeHtml = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
@@ -50,8 +50,6 @@ const renderCallbackHtml = (title, message) => `<!DOCTYPE html>
   </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) {
@@ -82,10 +80,10 @@ export class InteractiveOAuthProvider {
         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.scope = options.scope ?? DEFAULT_OAUTH_SCOPE;
         this.openBrowserByDefault = options.openBrowser ?? true;
         const storageDir = options.storageDir ?? defaultStorageDir();
-        this.storageFile = path.join(storageDir, `oauth-${hashServerUrl(options.serverUrl)}.json`);
+        this.storageFile = getStorageFileForServer(options.serverUrl, storageDir);
         this.onAuthorizationUrl = options.onAuthorizationUrl;
     }
     get clientMetadata() {
@@ -169,7 +167,11 @@ export class InteractiveOAuthProvider {
         if (!this.pendingAuthorization) {
             this.createPendingAuthorization();
         }
-        return this.pendingAuthorization.promise;
+        const pendingAuthorization = this.pendingAuthorization;
+        if (!pendingAuthorization) {
+            throw new Error("Pending authorization was not initialized.");
+        }
+        return pendingAuthorization.promise;
     }
     async close() {
         await this.closeCallbackServer();
@@ -208,9 +210,10 @@ export class InteractiveOAuthProvider {
         this.callbackServer = createServer((req, res) => {
             void this.handleCallbackRequest(req, res);
         });
+        const callbackServer = this.callbackServer;
         await new Promise((resolve, reject) => {
-            this.callbackServer.once("error", (error) => reject(error));
-            this.callbackServer.listen(Number(this.redirectUrl.port), this.redirectUrl.hostname, () => resolve());
+            callbackServer.once("error", (error) => reject(error));
+            callbackServer.listen(Number(this.redirectUrl.port), this.redirectUrl.hostname, () => resolve());
         });
     }
     async closeCallbackServer() {

package/dist/mcp/oauthStorage.d.ts

@@ -0,0 +1,29 @@
+import type { OAuthClientInformationMixed, OAuthTokens } from "@modelcontextprotocol/sdk/shared/auth.js";
+export type PersistedOAuthState = {
+    clientInformation?: OAuthClientInformationMixed;
+    tokens?: OAuthTokens;
+    codeVerifier?: string;
+};
+export type CachedAuthStatus = {
+    serverUrl: string;
+    matchedServerUrl?: string;
+    storageFile?: string;
+    status: "not_authenticated" | "registered" | "authenticated";
+    hasClientInformation: boolean;
+    hasAccessToken: boolean;
+    hasRefreshToken: boolean;
+    hasCodeVerifier: boolean;
+    scope?: string;
+};
+export declare const defaultStorageDir: () => string;
+export declare const hashServerUrl: (serverUrl: string) => string;
+export declare const getStorageFileForServer: (serverUrl: string, storageDir?: string) => string;
+export declare const getServerUrlCandidates: (serverUrl: string) => string[];
+export declare const readPersistedOAuthState: (storageFile: string) => Promise<PersistedOAuthState | null>;
+export declare const findPersistedOAuthState: (serverUrl: string, storageDir?: string) => Promise<{
+    matchedServerUrl: string;
+    storageFile: string;
+    state: PersistedOAuthState;
+} | null>;
+export declare const loadStoredTokens: (serverUrl: string, storageDir?: string) => Promise<OAuthTokens | undefined>;
+export declare const getCachedAuthStatus: (serverUrl: string, storageDir?: string) => Promise<CachedAuthStatus>;

package/dist/mcp/oauthStorage.js

@@ -0,0 +1,81 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+export const defaultStorageDir = () => path.join(os.homedir(), ".crush-mcp");
+export const hashServerUrl = (serverUrl) => createHash("sha256").update(serverUrl).digest("hex").slice(0, 16);
+export const getStorageFileForServer = (serverUrl, storageDir = defaultStorageDir()) => path.join(storageDir, `oauth-${hashServerUrl(serverUrl)}.json`);
+export const getServerUrlCandidates = (serverUrl) => {
+    const candidates = [serverUrl];
+    if (serverUrl.endsWith("/mcp")) {
+        candidates.push(serverUrl.replace(/\/mcp$/, ""));
+    }
+    else {
+        candidates.push(`${serverUrl}/mcp`);
+    }
+    return [...new Set(candidates)];
+};
+export const readPersistedOAuthState = async (storageFile) => {
+    try {
+        const raw = await readFile(storageFile, "utf8");
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        const err = error;
+        if (err.code === "ENOENT") {
+            return null;
+        }
+        throw error;
+    }
+};
+export const findPersistedOAuthState = async (serverUrl, storageDir = defaultStorageDir()) => {
+    for (const candidate of getServerUrlCandidates(serverUrl)) {
+        const storageFile = getStorageFileForServer(candidate, storageDir);
+        const state = await readPersistedOAuthState(storageFile);
+        if (state) {
+            return {
+                matchedServerUrl: candidate,
+                storageFile,
+                state,
+            };
+        }
+    }
+    return null;
+};
+export const loadStoredTokens = async (serverUrl, storageDir = defaultStorageDir()) => {
+    const persisted = await findPersistedOAuthState(serverUrl, storageDir);
+    return persisted?.state.tokens;
+};
+export const getCachedAuthStatus = async (serverUrl, storageDir = defaultStorageDir()) => {
+    const persisted = await findPersistedOAuthState(serverUrl, storageDir);
+    if (!persisted) {
+        return {
+            serverUrl,
+            status: "not_authenticated",
+            hasClientInformation: false,
+            hasAccessToken: false,
+            hasRefreshToken: false,
+            hasCodeVerifier: false,
+        };
+    }
+    const { state, matchedServerUrl, storageFile } = persisted;
+    const hasClientInformation = Boolean(state.clientInformation);
+    const hasAccessToken = typeof state.tokens?.access_token === "string" && state.tokens.access_token.length > 0;
+    const hasRefreshToken = typeof state.tokens?.refresh_token === "string" && state.tokens.refresh_token.length > 0;
+    const hasCodeVerifier = typeof state.codeVerifier === "string" && state.codeVerifier.length > 0;
+    return {
+        serverUrl,
+        matchedServerUrl,
+        storageFile,
+        status: hasAccessToken
+            ? "authenticated"
+            : hasClientInformation || hasCodeVerifier
+                ? "registered"
+                : "not_authenticated",
+        hasClientInformation,
+        hasAccessToken,
+        hasRefreshToken,
+        hasCodeVerifier,
+        scope: state.tokens?.scope,
+    };
+};

package/dist/mcp/proxy.js

@@ -11,44 +11,18 @@
  *
  * 用户只需执行一次 `login` 获取 token，所有 AI 工具共享同一份凭证。
  */
-import { createHash } from "node:crypto";
-import { readFile, writeFile, mkdir } from "node:fs/promises";
-import os from "node:os";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
-import { ListToolsRequestSchema, CallToolRequestSchema, PingRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, PingRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { getLoginCommand } from "../onboarding/cliOutput.js";
+import { defaultStorageDir, getStorageFileForServer, loadStoredTokens, } from "./oauthStorage.js";
 import { CLIENT_NAME, CLIENT_VERSION } from "./version.js";
-const STORAGE_DIR = path.join(os.homedir(), ".crush-mcp");
-const hashServerUrl = (serverUrl) => createHash("sha256").update(serverUrl).digest("hex").slice(0, 16);
-const loadTokens = async (serverUrl) => {
-    // 尝试多个可能的 URL 变体（login 用 base URL，proxy 用 /mcp URL）
-    const candidates = [serverUrl];
-    if (serverUrl.endsWith("/mcp")) {
-        candidates.push(serverUrl.replace(/\/mcp$/, ""));
-    }
-    else {
-        candidates.push(`${serverUrl}/mcp`);
-    }
-    for (const url of candidates) {
-        const storageFile = path.join(STORAGE_DIR, `oauth-${hashServerUrl(url)}.json`);
-        try {
-            const raw = await readFile(storageFile, "utf8");
-            const state = JSON.parse(raw);
-            if (state.tokens?.access_token) {
-                return state.tokens;
-            }
-        }
-        catch {
-            // 继续尝试下一个
-        }
-    }
-    return undefined;
-};
 const saveTokens = async (serverUrl, tokens) => {
-    const storageFile = path.join(STORAGE_DIR, `oauth-${hashServerUrl(serverUrl)}.json`);
+    const storageFile = getStorageFileForServer(serverUrl, defaultStorageDir());
     let state = {};
     try {
         const raw = await readFile(storageFile, "utf8");
@@ -75,7 +49,7 @@ const refreshAccessToken = async (serverUrl, tokens) => {
             return null;
         const meta = (await metaRes.json());
         // 获取 client_id
-        const storageFile = path.join(STORAGE_DIR, `oauth-${hashServerUrl(serverUrl)}.json`);
+        const storageFile = getStorageFileForServer(serverUrl, defaultStorageDir());
         const raw = await readFile(storageFile, "utf8");
         const state = JSON.parse(raw);
         const clientInfo = state.clientInformation;
@@ -103,10 +77,12 @@ const refreshAccessToken = async (serverUrl, tokens) => {
 };
 export async function runProxy(serverUrl) {
     // 1. 加载缓存的 token
-    let tokens = await loadTokens(serverUrl);
+    let tokens = await loadStoredTokens(serverUrl);
     if (!tokens?.access_token) {
-        process.stderr.write(`[crush-mcp-proxy] No cached token found for ${serverUrl}\n` +
-            `  Run: npx @crush-protocol/mcp-client login ${serverUrl}\n`);
+        process.stderr.write("Crush is connected but not authenticated.\n\n" +
+            "Run this once in your terminal:\n" +
+            `${getLoginCommand(serverUrl)}\n\n` +
+            "After login, retry the same request.\n");
         process.exit(1);
     }
     // 2. 创建到远程 MCP Server 的 HTTP 客户端
@@ -126,11 +102,13 @@ export async function runProxy(serverUrl) {
     catch (error) {
         const msg = String(error);
         if (msg.includes("401") || msg.includes("Unauthorized")) {
-            process.stderr.write("[crush-mcp-proxy] Token expired, refreshing...\n");
+            process.stderr.write("Crush authentication expired. Attempting refresh...\n");
             const refreshed = await refreshAccessToken(serverUrl, tokens);
             if (!refreshed) {
-                process.stderr.write("[crush-mcp-proxy] Token refresh failed. Please re-login:\n" +
-                    `  npx @crush-protocol/mcp-client login ${serverUrl}\n`);
+                process.stderr.write("Crush authentication needs to be renewed.\n\n" +
+                    "Run:\n" +
+                    `${getLoginCommand(serverUrl)}\n\n` +
+                    "Then retry the same request.\n");
                 process.exit(1);
             }
             tokens = refreshed;

package/dist/onboarding/cliOutput.d.ts

@@ -0,0 +1,12 @@
+import type { CachedAuthStatus } from "../mcp/oauthStorage.js";
+import type { SetupInstallResult, SetupScope, SetupTarget } from "../setup/setupClients.js";
+export type DoctorCheck = {
+    status: "ok" | "warn" | "error";
+    label: string;
+    detail: string;
+};
+export declare const getTargetLabel: (target: SetupTarget) => string;
+export declare const getLoginCommand: (serverUrl: string) => string;
+export declare const formatSetupSummary: (results: SetupInstallResult[], scope: SetupScope) => string;
+export declare const formatAuthStatus: (status: CachedAuthStatus) => string;
+export declare const formatDoctorReport: (serverUrl: string, checks: DoctorCheck[]) => string;

package/dist/onboarding/cliOutput.js

@@ -0,0 +1,65 @@
+import { DEFAULT_MCP_SERVER_URL, PACKAGE_NAME } from "../config.js";
+const TARGET_LABELS = {
+    cursor: "Cursor",
+    claude: "Claude Code",
+    codex: "Codex",
+    gemini: "Gemini CLI",
+    opencode: "OpenCode",
+    vscode: "VS Code",
+    windsurf: "Windsurf",
+    "claude-desktop": "Claude Desktop",
+    warp: "Warp",
+};
+export const getTargetLabel = (target) => TARGET_LABELS[target];
+export const getLoginCommand = (serverUrl) => serverUrl === DEFAULT_MCP_SERVER_URL
+    ? `npx -y ${PACKAGE_NAME} login`
+    : `CRUSH_MCP_SERVER_URL=\"${serverUrl}\" npx -y ${PACKAGE_NAME} login`;
+export const formatSetupSummary = (results, scope) => {
+    const targets = results.map((result) => getTargetLabel(result.target)).join(", ");
+    const lines = [
+        `Crush MCP configured for ${targets}.`,
+        "",
+        "Configuration:",
+        ...results.map((result) => `- ${getTargetLabel(result.target)}: ${result.status} (${result.location})`),
+        "",
+        "Next steps:",
+        `1. Restart ${results.length === 1 ? getTargetLabel(results[0].target) : "your AI host"} to load the new MCP server.`,
+        `2. Authenticate once: ${getLoginCommand(DEFAULT_MCP_SERVER_URL)}`,
+        "3. Return to your AI host and ask it to use Crush tools.",
+        "",
+        "Tip:",
+        `This ${scope}-scope setup uses the official hosted Crush MCP for market data, indicators, backtests, and live strategies.`,
+    ];
+    return lines.join("\n");
+};
+export const formatAuthStatus = (status) => {
+    const lines = [
+        "Crush authentication status",
+        "",
+        `Server: ${status.serverUrl}`,
+        `Status: ${status.status === "authenticated" ? "Authenticated" : status.status === "registered" ? "Registered but not authorized" : "Not authenticated"}`,
+        `Client registration: ${status.hasClientInformation ? "present" : "missing"}`,
+        `Access token: ${status.hasAccessToken ? "present" : "missing"}`,
+        `Refresh token: ${status.hasRefreshToken ? "present" : "missing"}`,
+    ];
+    if (status.scope) {
+        lines.push(`Scope: ${status.scope}`);
+    }
+    if (status.storageFile) {
+        lines.push(`Cache file: ${status.storageFile}`);
+    }
+    if (status.matchedServerUrl && status.matchedServerUrl !== status.serverUrl) {
+        lines.push(`Matched cache URL: ${status.matchedServerUrl}`);
+    }
+    if (status.status !== "authenticated") {
+        lines.push("", "Run:", getLoginCommand(status.serverUrl));
+    }
+    return lines.join("\n");
+};
+export const formatDoctorReport = (serverUrl, checks) => {
+    const lines = ["Crush MCP doctor", "", `Server: ${serverUrl}`, ""];
+    for (const check of checks) {
+        lines.push(`[${check.status}] ${check.label} - ${check.detail}`);
+    }
+    return lines.join("\n");
+};

package/dist/setup/setupClients.d.ts

@@ -1,4 +1,11 @@
 export type SetupTarget = "cursor" | "claude" | "codex" | "gemini" | "opencode" | "vscode" | "windsurf" | "claude-desktop" | "warp";
 export type SetupScope = "user" | "project";
+export type SetupInstallStatus = "created" | "updated" | "unchanged" | "configured";
+export type SetupInstallResult = {
+    target: SetupTarget;
+    scope: SetupScope;
+    status: SetupInstallStatus;
+    location: string;
+};
 export declare const ALL_TARGETS: readonly SetupTarget[];
-export declare const installClientConfig: (target: SetupTarget, scope: SetupScope) => string;
+export declare const installClientConfig: (target: SetupTarget, scope: SetupScope) => SetupInstallResult;

package/dist/setup/setupClients.js

@@ -2,9 +2,7 @@ import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-const SERVER_NAME = "crush-protocol";
-const PACKAGE_NAME = "@crush-protocol/mcp-client";
-const REMOTE_URL = "https://crush-mcp-ats.dev.xexlab.com/mcp";
+import { PACKAGE_NAME, SERVER_NAME } from "../config.js";
 export const ALL_TARGETS = [
     "cursor",
     "claude",
@@ -30,8 +28,17 @@ const readJson = (filePath) => {
     }
 };
 const writeJson = (filePath, value) => {
+    const existed = fs.existsSync(filePath);
+    const next = `${JSON.stringify(value, null, 2)}\n`;
+    if (existed) {
+        const previous = fs.readFileSync(filePath, "utf8");
+        if (previous === next) {
+            return "unchanged";
+        }
+    }
     ensureDir(filePath);
-    fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+    fs.writeFileSync(filePath, next, "utf8");
+    return existed ? "updated" : "created";
 };
 const createNpxConfig = () => ({
     command: "npx",
@@ -47,8 +54,7 @@ const installCursor = (scope) => {
     const mcpServers = (config.mcpServers ?? {});
     mcpServers[SERVER_NAME] = createNpxConfig();
     config.mcpServers = mcpServers;
-    writeJson(filePath, config);
-    return filePath;
+    return { target: "cursor", scope, status: writeJson(filePath, config), location: filePath };
 };
 // ─── Gemini CLI ─────────────────────────────────────────
 const getGeminiConfigPath = () => path.join(os.homedir(), ".gemini", "settings.json");
@@ -58,8 +64,7 @@ const installGemini = () => {
     const mcpServers = (config.mcpServers ?? {});
     mcpServers[SERVER_NAME] = createNpxConfig();
     config.mcpServers = mcpServers;
-    writeJson(filePath, config);
-    return filePath;
+    return { target: "gemini", scope: "user", status: writeJson(filePath, config), location: filePath };
 };
 // ─── OpenCode ───────────────────────────────────────────
 const getOpenCodeConfigPath = (scope) => scope === "project"
@@ -78,8 +83,7 @@ const installOpenCode = (scope) => {
         enabled: true,
     };
     config.mcp = mcp;
-    writeJson(filePath, config);
-    return filePath;
+    return { target: "opencode", scope, status: writeJson(filePath, config), location: filePath };
 };
 // ─── OpenAI Codex ───────────────────────────────────────
 const getCodexConfigPath = () => path.join(os.homedir(), ".codex", "config.toml");
@@ -91,12 +95,15 @@ args = ["-y", "${PACKAGE_NAME}"]
 startup_timeout_ms = 20000
 `;
     ensureDir(filePath);
+    const existed = fs.existsSync(filePath);
     const existing = fs.existsSync(filePath) ? fs.readFileSync(filePath, "utf8") : "";
+    let status = "unchanged";
     if (!existing.includes(`[mcp_servers.${SERVER_NAME}]`)) {
         const next = existing.trim().length > 0 ? `${existing.trimEnd()}\n\n${section}` : section;
         fs.writeFileSync(filePath, next, "utf8");
+        status = existed ? "updated" : "created";
     }
-    return filePath;
+    return { target: "codex", scope: "user", status, location: filePath };
 };
 // ─── Claude Code CLI ────────────────────────────────────
 const installClaude = (scope) => {
@@ -116,7 +123,7 @@ const installClaude = (scope) => {
         const output = [result.stdout, result.stderr].filter(Boolean).join("\n").trim();
         throw new Error(output || "Claude CLI returned a non-zero exit code.");
     }
-    return "claude-managed-config";
+    return { target: "claude", scope, status: "configured", location: "claude-managed-config" };
 };
 // ─── VS Code ────────────────────────────────────────────
 const getVSCodeConfigPath = (scope) => scope === "project"
@@ -132,8 +139,7 @@ const installVSCode = (scope) => {
         args: ["-y", PACKAGE_NAME],
     };
     config.servers = servers;
-    writeJson(filePath, config);
-    return filePath;
+    return { target: "vscode", scope, status: writeJson(filePath, config), location: filePath };
 };
 // ─── Windsurf ───────────────────────────────────────────
 const getWindsurfConfigPath = () => path.join(os.homedir(), ".codeium", "windsurf", "mcp_config.json");
@@ -143,8 +149,7 @@ const installWindsurf = () => {
     const mcpServers = (config.mcpServers ?? {});
     mcpServers[SERVER_NAME] = createNpxConfig();
     config.mcpServers = mcpServers;
-    writeJson(filePath, config);
-    return filePath;
+    return { target: "windsurf", scope: "user", status: writeJson(filePath, config), location: filePath };
 };
 // ─── Claude Desktop ─────────────────────────────────────
 const getClaudeDesktopConfigPath = () => {
@@ -164,8 +169,7 @@ const installClaudeDesktop = () => {
     const mcpServers = (config.mcpServers ?? {});
     mcpServers[SERVER_NAME] = createNpxConfig();
     config.mcpServers = mcpServers;
-    writeJson(filePath, config);
-    return filePath;
+    return { target: "claude-desktop", scope: "user", status: writeJson(filePath, config), location: filePath };
 };
 // ─── Warp ───────────────────────────────────────────────
 const getWarpConfigPath = () => path.join(os.homedir(), ".warp", "mcp_config.json");
@@ -179,8 +183,7 @@ const installWarp = () => {
         working_directory: null,
         start_on_launch: true,
     };
-    writeJson(filePath, config);
-    return filePath;
+    return { target: "warp", scope: "user", status: writeJson(filePath, config), location: filePath };
 };
 // ─── Router ─────────────────────────────────────────────
 export const installClientConfig = (target, scope) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crush-protocol/mcp-client",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "Crush MCP npm client package (remote Streamable HTTP + optional ClickHouse direct)",
   "type": "module",
   "license": "MIT",