@crush-protocol/mcp-client 0.1.9 → 0.1.10

package/INSTRUCTIONS.md

@@ -0,0 +1,127 @@
+# Crush Protocol MCP — AI Instructions
+
+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.
+
+## Tool Categories
+
+### 🔍 Signal Discovery
+
+| Tool                      | Purpose                                                                                |
+| ------------------------- | -------------------------------------------------------------------------------------- |
+| `get_signal_metadata`     | Get all categories, operators, timeframes, and expression limits. **Call this first.** |
+| `get_signals_by_category` | Get signals in a category with their params, operators, and operand types.             |
+
+### 📊 Backtest
+
+| Tool                         | Purpose                                                                                          |
+| ---------------------------- | ------------------------------------------------------------------------------------------------ |
+| `get_backtest_config_schema` | Get supported platforms, timeframes, directions, exit strategy types.                            |
+| `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)
+
+| Tool                    | Purpose                                                                      |
+| ----------------------- | ---------------------------------------------------------------------------- |
+| `list_tables`           | List all ClickHouse tables with descriptions.                                |
+| `list_tokens`           | List available trading pairs in the data warehouse.                          |
+| `list_indicators`       | List pre-computed indicators with categories.                                |
+| `list_timeframes`       | List available data timeframes.                                              |
+| `get_data_range`        | Get earliest/latest date for a token + timeframe.                            |
+| `check_query_size`      | Estimate row count before fetching. **Call this before large queries.**      |
+| `fetch_ohlcv`           | Fetch OHLCV candlestick data (row cap: 5000).                                |
+| `fetch_indicator`       | Fetch pre-computed indicator values (row cap: 5000).                         |
+| `get_connection_config` | Get read-only ClickHouse credentials for local processing of large datasets. |
+
+### 🧮 Custom Indicators
+
+| Tool                      | Purpose                               |
+| ------------------------- | ------------------------------------- |
+| `save_custom_indicator`   | Save a custom indicator formula.      |
+| `list_custom_indicators`  | List user's saved indicator formulas. |
+| `get_custom_indicator`    | Retrieve a formula by name.           |
+| `delete_custom_indicator` | Delete a formula by name.             |
+
+### ⚙️ Strategy Management
+
+| Tool                | Purpose                                           |
+| ------------------- | ------------------------------------------------- |
+| `create_strategy`   | Create a live strategy from a completed backtest. |
+| `list_strategies`   | List user's strategies with pagination.           |
+| `get_strategy`      | Get strategy details with backtest performance.   |
+| `update_strategy`   | Update strategy name, description, or note.       |
+| `delete_strategy`   | Delete a strategy (must be deactivated first).    |
+| `toggle_strategy`   | Activate or deactivate live trading.              |
+| `get_strategy_logs` | Get execution logs for a strategy.                |
+
+### 💰 Trading (Hyperliquid)
+
+| Tool               | Purpose                                                  |
+| ------------------ | -------------------------------------------------------- |
+| `place_order`      | Place a market or limit order on Hyperliquid perpetuals. |
+| `get_positions`    | Get current open positions.                              |
+| `get_account_info` | Get account balance, margin, and PnL.                    |
+| `get_portfolio`    | Get all balances across chains.                          |
+
+### 🌐 Market Intelligence
+
+| Tool                  | Purpose                                                |
+| --------------------- | ------------------------------------------------------ |
+| `search_tokens`       | Search tokens by name, symbol, or address.             |
+| `get_token_info`      | Get token metadata, price, and market cap.             |
+| `get_trending_tokens` | Get trending tokens on a given chain.                  |
+| `get_alpha_feed`      | Get recent alpha posts from Twitter and communities.   |
+| `get_token_feed`      | Get token-specific news and events.                    |
+| `fetch_news`          | Fetch news and intel feeds with keyword/token filters. |
+
+---
+
+## Workflows
+
+### Strategy Backtest (Most Common)
+
+```
+1. get_signal_metadata          → Understand available signals and operators
+2. get_signals_by_category      → Explore signals in relevant categories (price, technicalIndicator, etc.)
+3. get_backtest_config_schema   → Get platform/timeframe/exit options
+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
+   └─ If COMPLETED: present summary (totalReturn, sharpeRatio, maxDrawdown, winRate, tradeCount)
+   └─ If FAILED: show error, suggest fixes, iterate
+```
+
+### Market Research
+
+```
+1. list_tokens / search_tokens  → Find tokens of interest
+2. get_data_range               → Check data availability
+3. check_query_size             → Estimate dataset size
+4. fetch_ohlcv / fetch_indicator → Fetch data (≤5000 rows)
+   └─ If too large: get_connection_config → write Python script for local processing
+```
+
+### Go Live
+
+```
+1. list_backtests (status=COMPLETED) → Find a profitable backtest
+2. create_strategy              → Create live strategy from backtest
+3. toggle_strategy (isActive=true) → Activate live trading
+4. get_strategy_logs            → Monitor execution
+5. get_positions / get_account_info → Check trading status
+```
+
+---
+
+## 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.
+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.
+5. **Strategy lifecycle**: Backtest → Create Strategy → Toggle Active. A strategy must be deactivated before deletion.
+6. **Trading is real**: `place_order` executes real trades on Hyperliquid. Always confirm with the user before placing orders.

package/README.md

@@ -93,14 +93,17 @@ Add to `~/.cursor/mcp.json`:
 
 ## Available Tools
 
-| Tool                         | Description                                                     |
-| ---------------------------- | --------------------------------------------------------------- |
-| `get_backtest_config_schema` | Get supported platforms, timeframes, and strategy config schema |
-| `get_available_tokens`       | List tradable tokens, optionally filtered by platform           |
-| `validate_expression`        | Validate and compile an entry/exit AST expression               |
-| `create_backtest`            | Create or update a backtest with a strategy config              |
-| `get_backtest_result`        | Fetch result, summary, portfolio history and trades             |
-| `list_backtests`             | List your backtests with optional status filter and pagination  |
+| Category                | Tools                                                                                                                                                               |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Signal Discovery**    | `get_signal_metadata`, `get_signals_by_category`                                                                                                                    |
+| **Backtest**            | `get_backtest_config_schema`, `get_available_tokens`, `validate_expression`, `create_backtest`, `get_backtest_result`, `list_backtests`                             |
+| **Market Data**         | `list_tables`, `list_tokens`, `list_indicators`, `list_timeframes`, `get_data_range`, `check_query_size`, `fetch_ohlcv`, `fetch_indicator`, `get_connection_config` |
+| **Custom Indicators**   | `save_custom_indicator`, `list_custom_indicators`, `get_custom_indicator`, `delete_custom_indicator`                                                                |
+| **Strategy Management** | `create_strategy`, `list_strategies`, `get_strategy`, `update_strategy`, `delete_strategy`, `toggle_strategy`, `get_strategy_logs`                                  |
+| **Trading**             | `place_order`, `get_positions`, `get_account_info`, `get_portfolio`                                                                                                 |
+| **Market Intelligence** | `search_tokens`, `get_token_info`, `get_trending_tokens`, `get_alpha_feed`, `get_token_feed`, `fetch_news`                                                          |
+
+> 📖 See [INSTRUCTIONS.md](./INSTRUCTIONS.md) for detailed tool descriptions, workflows, and AI system prompt template.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crush-protocol/mcp-client",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "description": "Crush MCP npm client package (remote Streamable HTTP + optional ClickHouse direct)",
   "type": "module",
   "license": "MIT",
@@ -10,7 +10,8 @@
     "crush-mcp-client": "dist/cli.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "INSTRUCTIONS.md"
   ],
   "exports": {
     ".": {