@michaleffffff/mcp-trading-server 3.0.3 → 3.0.5

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 3.0.5 - 2026-03-18
+
+### Changed
+- **Major Tool Consolidation**: Unified 40+ specialized tools into ~26 high-level semantic tools for easier AI steering.
+  - `get_market_price` & `get_oracle_price` → `get_price`
+  - `get_market_detail`, `get_pool_info`, `get_liquidity_info`, `get_pool_level_config` → `get_pool_metadata`
+  - `get_pool_list` & `get_pool_symbol_all` → `list_pools`
+  - `get_pool_by_symbol` & `search_market` → `find_pool` (Discovery)
+  - `cancel_order` & `cancel_all_orders` → `cancel_orders` (Batch support)
+  - `set_tp_sl` & `update_order_tp_sl` → `manage_tp_sl`
+  - `get_open_orders` & `get_order_history` → `get_orders`
+  - `get_positions` & `get_position_history` → `get_positions_all`
+  - `get_account` & `get_account_vip_info` → `get_account_snapshot`
+- Updated `README.md` and `TOOL_EXAMPLES.md` to reflect the new unified toolset.
+- Enhanced `trading_best_practices` prompt with updated v3.0.4 workflows.
+- Improved `zodSchemaToJsonSchema` to correctly expose `Enum` values to LLMs.
+- Removed 18+ obsolete tool files from the codebase.
+- Verified build and server initialization with the new structure.
+
+### Added
+- `get_my_lp_holdings` tool for listing all wallet LP balances with standardized naming.
+- Enriched `manage_liquidity` response with `lpAssetNames` (e.g., `mBTC.USDC`).
+
 ## 3.0.3 - 2026-03-17
 
 ### Changed

package/README.md

@@ -1,444 +1,84 @@
 # MYX MCP Trading Server
 
-A production-ready MCP (Model Context Protocol) server that exposes tools, resources, and prompts for AI agents.
-
-This server allows AI assistants (like Claude Desktop, Cursor, etc.) to securely autonomously trade, manage liquidity, and fetch real-time market data on **MYX Finance**—a decentralized perpetual exchange. It interacts with smart contracts entirely via terminal/backend without requiring API keys or browser extensions.
+A production-ready MCP (Model Context Protocol) server for deep integration with **MYX Finance**—a decentralized perpetual exchange. It allows AI assistants to autonomously trade, manage liquidity, and analyze markets via terminal/backend using pure on-chain logic.
 
 ---
 
 # Release Notes
 
-- Current release: **3.0.0**
-- Breaking change: `get_account_info`, `get_balances`, and `get_margin_balance` were removed.
-- Replacement: use `get_account` for unified wallet + trading-account balance view.
-- Detailed history: `CHANGELOG.md`
+- **Current release: 3.0.4**
+- **Refinement**: Consolidated 40+ specialized tools into ~26 high-level unified tools.
+- **Improved UX**: Enhanced AI parameter parsing, automated unit conversion, and structured error reporting.
+- **Breaking changes**: Many low-level tools (e.g., `get_market_price`, `get_oracle_price`, `get_open_orders`) have been merged into unified counterparts.
 
 ---
 
 # Features
 
-* MCP compliant server
-* AI-friendly tool design (Unit normalization, Automated ID resolution)
-* Structured input/output schemas for Web3 execution
-* Resource browsing support (`system://state`)
-* Prompt templates for trading decisions
-* Modular architecture
-* Logging and error handling
-
----
-
-# Architecture
-
-The project follows a modular architecture separating tools from trading services.
-
-AI Agents
-↓
-MCP Server
-↓
-Tools → Services → MYX SDK → Web3 RPC (EVM)
-
-Project structure:
-
-```text
-src/
-  server.ts
-
-  tools/          # MCP exposed operations (e.g. executeTrade, searchMarket)
-  resources/      # MCP contextual data (e.g. systemStateResource)
-  prompts/        # MCP reusable templates (e.g. tradeAnalysisPrompt)
-  services/       # Business logic calling the MYX SDK
-  auth/           # Web3 wallet & client resolution
-  utils/          # logger.ts, errors.ts, units.ts
-
-schemas/
-examples/
-tests/
-```
-
----
-
-# Installation
-
-quick-start  `npx @michaleffffff/mcp-trading-server`
+* **Unified Toolset**: High-level semantic tools for simpler AI steering.
+* **AI-First Design**: Automated Pool ID resolution and flexible unit handling (`human:` vs `raw:`).
+* **Deep Liquidity Support**: Tools for both traders and liquidity providers.
+* **Production Ready**: Robust error handling with actionable hints for LLMs.
+* **Compliant**: Full Model Context Protocol (MCP) support.
 
 ---
 
 # Configuration
 
-Copy the example configuration:
+Copy `.env.example` to `.env` and configure your trading wallet:
 
 ```bash
-cp .env.example .env
-```
-
-## Non-Auth Mode (No AccessToken)
-
-This MCP server runs in **non-auth mode**:
-
-- It does **not** call `myxClient.auth()` and does **not** manage AccessTokens.
-- All tools are designed to work without AccessToken authentication.
-
-## User Key Configuration (Safe Practices)
-
-- **Local dev**: Put `PRIVATE_KEY` in a local `.env` (ignored by `.gitignore`) and never commit it.
-- **Production**: Inject via environment variables or a secrets manager, never store in code or repo.
-- **Best practice**: Use a dedicated low‑fund wallet, avoid reusing your main wallet, and rotate regularly.
-
-Environment variables needed for the trading wallet:
-
-```bash
-# BNB Smart Chain (BSC Mainnet) (Default)
-PRIVATE_KEY=0xYourPrivateKey
+PRIVATE_KEY=0x...
 RPC_URL=https://bsc-dataseed.bnbchain.org
 CHAIN_ID=56
-BROKER_ADDRESS=0xEb8C74fF05e76F85791dD2E4B972E7E78F6287C3
-QUOTE_TOKEN_ADDRESS=0x55d398326f99059fF775485246999027B3197955
+BROKER_ADDRESS=0x...
+QUOTE_TOKEN_ADDRESS=0x...
 QUOTE_TOKEN_DECIMALS=18
-IS_TESTNET=false
-MAX_TRADE_AMOUNT=5000 # Optional safety constraint limit for AI
 ```
 
-Testnet quick mapping:
-
-- `Arbitrum Sepolia (421614)`: `BROKER_ADDRESS=0x8f3153C18f698166f5D6124d8ba5B567F5f120f9`, `QUOTE_TOKEN_ADDRESS=0x7E248Ec1721639413A280d9E82e2862Cae2E6E28`
-- `Linea Sepolia (59141)`: `BROKER_ADDRESS=0x0FB08D3A1Ea6bE515fe78D3e0CaEb6990b468Cf3`, `QUOTE_TOKEN_ADDRESS=0xD984fd34f91F92DA0586e1bE82E262fF27DC431b`
-
 ---
 
-# Running the Server
-
-Build and Start the MCP server:
-
-```bash
-npm run build
-npm run start
-```
-
-The server will run using `stdio` transport and can be connected by any MCP-compatible client.
+# Core Tools Reference
+
+### 📈 Market Analysis
+* **`find_pool`**: Discover active markets by keyword/symbol (e.g., "BTC", "ETH").
+* **`list_pools`**: List all tradable assets on the current chain.
+* **`get_price`**: Fetch real-time prices (Impact Market Price or Oracle Price).
+* **`get_pool_metadata`**: Comprehensive metrics (Fees, Open Interest, Liquidity Depth).
+* **`get_kline`**: Fetch candlestick data for technical analysis.
+
+### ⚔️ Trading Operations
+* **`open_position_simple`**: The recommended entry point for new trades. Handles size/price/fee computation. Supports Stop-Loss/Take-Profit.
+* **`execute_trade`**: Low-level trade execution (Increase orders).
+* **`close_position`**: Strategy-based closing of specific positions.
+* **`close_all_positions`**: Emergency exit for all positions in a specific pool.
+* **`cancel_orders`**: Unified cancellation (Single ID, Pool-wide, or Account-wide).
+* **`manage_tp_sl`**: Adjust protection orders for active positions or pending orders.
+* **`adjust_margin`**: Add or remove collateral to manage liquidation risk.
+
+### 📁 Account & Portfolio
+* **`get_account_snapshot`**: Unified overview of balances, trading metrics, and VIP tier.
+* **`get_orders`**: Historical and active order ledger.
+* **`get_positions_all`**: Currently open and recently closed positions.
+* **`get_trade_flow`**: Granular transaction history.
+* **`check_account_ready`**: Pre-trade balance validator with auto-deposit support.
 
 ---
 
-## Quick Start for Regular Users
+# Quick Start Flow
 
-1. **Prepare a wallet**: Use a testnet or a small dedicated wallet (avoid your main wallet).
-2. **Configure env**: Copy `.env.example` to `.env` and fill in `PRIVATE_KEY`, `RPC_URL`, etc.
-3. **Start the server**: Run `npm run build` then `npm run start` (use `npm run dev` for development).
-4. **Configure your MCP client**: Set `command/args/env` in your MCP client (see Claude Desktop example below).
-5. **Common flow**: Use `search_market` (or `get_pool_list`) to get `poolId`, then optionally `get_market_price` / `get_oracle_price` to view prices, and finally use `open_position_simple` (recommended) to open a position.
-6. **Tool examples**: See `TOOL_EXAMPLES.md` for practical examples for every tool, common workflows, and parameter-unit guidance.
-
-**Minimal open position example:**
-
-```json
-{
-  "keyword": "BTC",
-  "direction": 0,
-  "collateralAmount": "100",
-  "leverage": 5,
-  "orderType": "MARKET",
-  "autoDeposit": false
-}
-```
-
-**Dry run (no transaction) example:**
-
-```json
-{
-  "keyword": "BTC",
-  "direction": 0,
-  "collateralAmount": "100",
-  "leverage": 5,
-  "orderType": "MARKET",
-  "autoDeposit": false,
-  "dryRun": true
-}
-```
-
-## Units & Precision
-
-- **Human by default**: For trading tools (e.g. `open_position_simple`), amounts like `"100"` mean **human-readable units**.
-- **Raw units (explicit)**: Prefix with `raw:` to pass raw units exactly (e.g. `raw:100000000` for 100 USDC with 6 decimals).
-- **Price**: `"price"` is human by default and will be converted to **30-decimal** format internally. Use `raw:` to pass a 30-decimal integer directly.
-- **Slippage**: `slippagePct` uses 4-decimal raw units: `100` = `1%`, `50` = `0.5%`, `1000` = `10%`.
-- **Note**: Some account-transfer tools (e.g. `account_deposit`, `account_withdraw`, `check_approval`) use **raw integer strings**.
-- **`adjust_margin` units**: human amount is supported (e.g. `"1"` means 1 quote token). For exact atomic amount, use `raw:` (e.g. `"raw:1"`).
-
-## P0 Reliability Contract (AI-friendly)
-
-Starting with P0, tool failures are normalized to a structured JSON envelope:
-
-```json
-{
-  "status": "error",
-  "error": {
-    "tool": "execute_trade",
-    "code": "INVALID_PARAM",
-    "message": "Invalid arguments for tool \"execute_trade\".",
-    "hint": "Fix \"positionId\": positionId must be empty string for new position, or a bytes32 hex string.",
-    "action": "Call list_tools and resend valid arguments.",
-    "details": {
-      "issues": [
-        {
-          "field": "positionId",
-          "code": "custom",
-          "message": "positionId must be empty string for new position, or a bytes32 hex string."
-        }
-      ]
-    }
-  }
-}
-```
-
-Common error codes:
-- `INVALID_PARAM`: input schema/field error.
-- `INSUFFICIENT_BALANCE`: wallet or trading-account amount is not enough.
-- `INSUFFICIENT_ALLOWANCE`: token approval/allowance is insufficient.
-- `NOT_FOUND`: bad tool name or bad identifiers (`poolId`, `orderId`, `marketId`).
-- `TIMEOUT`: tx confirmation/query timeout.
-- `NETWORK_ERROR`: RPC or network issue.
-
-Search behavior in P0:
-- `search_market` now accepts empty `keyword` and returns active markets.
-- When `search_market` returns empty/unstable data, server-side fallback uses SDK `api.getMarketList()` and `api.getPoolList()` to rebuild active-market results.
-- For robust discovery, you can also call `get_pool_list` directly.
-
-Example:
-
-```json
-{
-  "name": "search_market",
-  "arguments": {
-    "keyword": "",
-    "limit": 20
-  }
-}
-```
+1. **Find Target**: `find_pool(keyword="BTC")`
+2. **Check State**: `get_account_snapshot(poolId="...")`
+3. **Execute**: `open_position_simple(poolId="...", direction="LONG", leverage=5, collateralAmount="100")`
+4. **Monitor**: `get_positions_all(status="OPEN")`
 
 ---
 
-## Secure Deployment Template (Systemd Example)
-
-**1) Put secrets in a system env file (chmod 600)**
+# Documentation
 
-```bash
-# /etc/myx-mcp.env
-PRIVATE_KEY=0xYourPrivateKey
-RPC_URL=https://bsc-dataseed.bnbchain.org
-CHAIN_ID=56
-BROKER_ADDRESS=0xEb8C74fF05e76F85791dD2E4B972E7E78F6287C3
-QUOTE_TOKEN_ADDRESS=0x55d398326f99059fF775485246999027B3197955
-QUOTE_TOKEN_DECIMALS=18
-IS_TESTNET=false
-```
-
-```bash
-sudo chmod 600 /etc/myx-mcp.env
-```
-
-**2) Systemd service**
-
-```ini
-# /etc/systemd/system/myx-mcp.service
-[Unit]
-Description=MYX MCP Trading Server
-After=network.target
-
-[Service]
-Type=simple
-User=myx
-Group=myx
-WorkingDirectory=/opt/myx-mcp-trading-server-v2
-EnvironmentFile=/etc/myx-mcp.env
-ExecStart=/usr/bin/node /opt/myx-mcp-trading-server-v2/dist/server.js
-Restart=on-failure
-
-[Install]
-WantedBy=multi-user.target
-```
-
-**3) Start**
-
-```bash
-sudo systemctl daemon-reload
-sudo systemctl enable --now myx-mcp
-```
-
-### Connecting Claude Desktop (MacOS)
-Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
-```json
-{
-  "mcpServers": {
-    "myx-trading-v2": {
-      "command": "node",
-      "args": [
-        "[/Absolute/Path/To/Your/Directory]/myx-mcp-trading-server-v2/dist/server.js"
-      ],
-      "env": {
-        "PRIVATE_KEY": "0xYourPrivateKey"
-      }
-    }
-  }
-}
-```
-
----
-
-# Tools
-
-The server exposes tools categorized for AI:
-
-For practical tool-by-tool examples, see: `TOOL_EXAMPLES.md`
-
-### Trading Operations
-* **open_position_simple**: High-level open position helper (recommended). Computes price/size/tradingFee internally.
-* **execute_trade**: Execute a new trade or add to an existing position (includes parameter preflight, supports `human:`/`raw:` amount prefixes, auto-computes `tradingFee` when omitted).
-* **close_position**: Close an open position.
-* **close_all_positions**: Emergency: close ALL open positions in a pool at once.
-* **cancel_order**: Cancel an open order by its order ID.
-* **cancel_all_orders**: Cancel open orders by IDs (supports array, JSON-array string, comma string, or single ID; use `get_open_orders` first).
-* **set_tp_sl**: Set take profit and stop loss prices for an open position.
-* **update_order_tp_sl**: Update TP/SL fields for an existing order. Accepts boolean-like values for `useOrderCollateral` / `isTpSlOrder`.
-* **adjust_margin**: Adjust the margin (collateral) of an open position.
-* **get_user_trading_fee_rate**: Query current maker/taker fee rates by asset class and risk tier.
-* **get_network_fee**: Query estimated network fee requirements for a market.
-
-### Market Data
-* **search_market**: Search for an active market (e.g., "BTC") to retrieve its unique `poolId` (Crucial prerequisite).
-* **get_market_price**: Get the current ticker market price for a specific pool.
-* **get_oracle_price**: Get the current EVM oracle price for a specific pool.
-* **get_kline_latest_bar**: Get only the latest bar for an interval.
-* **get_all_tickers**: Get all ticker snapshots in one request.
-* **get_kline**, **get_pool_info**... (`get_pool_info` auto-retries with oracle/ticker price on divide-by-zero reads)
-* **get_pool_symbol_all**, **get_base_detail**, **get_pool_level_config**...
-
-### Account & Portfolio
-* **get_positions**: Get all open positions for the current account.
-* **get_account**: Unified account snapshot. Clearly separates **wallet balance** and **trading-account balance** (provide `poolId` for full trading-account metrics).
-* **get_my_lp_holdings**: Scan pools and return your base/quote LP token balances on the current chain, with standardized LP asset names (`base: mBASE.QUOTE`, `quote: mQUOTE.BASE`).
-* **get_account_vip_info**: Query account VIP tier details.
-* **get_position_history**, **get_open_orders**, **get_order_history**...
-
-`get_account` note:
-- `poolId` omitted: wallet-focused snapshot only.
-- `poolId` provided: wallet + trading-account + margin snapshot.
-- If one section fails (wallet or trading-account), the tool may return a **partial** snapshot with `meta.partial=true` and section-level `error` details.
-
-### Liquidity Provision (LP)
-* **manage_liquidity**: Add or withdraw liquidity from a BASE or QUOTE pool (aliases: `add/remove/increase/decrease` are supported). `poolId` is pre-validated on target `chainId` for clearer errors. Response includes LP naming metadata (`baseLpAssetName=mBASE.QUOTE`, `quoteLpAssetName=mQUOTE.BASE`, `operatedLpAssetName`).
-  - Example (`BTC/USDC`, `poolType=QUOTE`): `operatedLpAssetName = mUSDC.BTC`.
-* **create_perp_market**: Create a new perpetual trading pair.
-
----
-
-# Resources
-
-Resources provide contextual data that AI agents can read.
-
-Available resources:
-
-**`system://state`**
-
-Description:
-Readonly contextual data about the active EVM network, connected wallet address, chain ID, and RPC health available to the AI.
-
----
-
-# Prompts
-
-Reusable prompt templates for AI tasks.
-
-## `analyze_positions`
-
-Analyze the user's current trading positions based on real-time market action.
-
-**Arguments:**
-
-* `marketContext` (string, optional) - Provide the latest market insights or news to contextualize the analysis.
-
-**Returns:**
-Messages including a stringified dump of the user's active portfolio on MYX ready to be sent to an LLM for trading advice.
-
----
-
-# Example Usage
-
-Example MCP client usage workflow:
-
-1. Connect to the MCP server.
-2. Read the `system://state` resource to confirm wallet connectivity.
-3. Call the `search_market` tool (e.g., `keyword: "ETH"`) to retrieve the `poolId`.
-4. Call `open_position_simple` passing the retrieved `poolId` to open a 10x long position.
-
-## Limit Order Lifecycle (P0)
-
-Use this query/mutation loop for limit-order management:
-
-1. Place order with `execute_trade` (`orderType=LIMIT`).
-2. Query active orders with `get_open_orders`.
-3. If still pending, you can cancel/update order-level fields; if filled into a position, prefer `set_tp_sl` for position TP/SL.
-4. Check historical fills/cancellations with `get_order_history`.
-5. Cancel one order via `cancel_order` or batch via `cancel_all_orders`.
-
-## Unit Safety (P0)
-
-- Monetary fields in major mutation tools support `human:` and `raw:` prefixes.
-- Default behavior is human-readable units (e.g. `1` means `1.0` token), while `raw:<int>` enforces exact raw units.
-- `execute_trade` and `adjust_margin` responses include normalized raw values for auditability.
-
-Minimal query examples:
-
-```json
-{
-  "name": "get_open_orders",
-  "arguments": {}
-}
-```
-
-```json
-{
-  "name": "get_order_history",
-  "arguments": {
-    "poolId": "0x...",
-    "limit": 20
-  }
-}
-```
-
-Example integration scripts are located in:
-`examples/basicUsage.ts`
-
----
-
-# Development
-
-Run in development mode (watcher):
-
-```bash
-npm run dev
-```
-
-Run tests:
-
-```bash
-npm test
-npm run test:new-tools
-```
+For detailed implementation examples and parameter guides, see:
+* **[TOOL_EXAMPLES.md](./TOOL_EXAMPLES.md)**: Payload examples for every tool.
+* **[CHANGELOG.md](./CHANGELOG.md)**: Version history and migration paths.
+* **[mcp_config_guide.md](./mcp_config_guide.md)**: Client setup instructions.
 
 ---
-
-# Extending the Server
-
-To add a new tool:
-
-1. Create a new file in `src/tools/myNewTool.ts`
-2. Define the Zod input schema and description
-3. Implement the `handler(args)` executing the trading logic
-4. Export and register it in `src/tools/index.ts`
-
----
-
-# Contributing
-
-Contributions are welcome.
-
-Please open an issue or submit a pull request.