shll-skills 3.1.0 → 4.0.1

package/README.md

@@ -2,7 +2,7 @@
 
 [![Website](https://img.shields.io/badge/Website-shll.run-blue)](https://shll.run) [![Twitter](https://img.shields.io/badge/Twitter-@shllrun-1DA1F2)](https://twitter.com/shllrun) [![npm](https://img.shields.io/npm/v/shll-skills)](https://www.npmjs.com/package/shll-skills)
 
-A CLI toolkit that gives **any AI agent** (OpenClaw, Claude, Codex, ChatGPT, etc.) the ability to execute DeFi operations on BSC Mainnet securely. All transactions are validated by the on-chain PolicyGuard — even if the AI hallucinates, the contract rejects unsafe operations.
+A **CLI + MCP Server** toolkit that gives any AI agent the ability to execute DeFi operations on BSC Mainnet securely. Supports PancakeSwap V2/V3 swap routing, Venus Protocol lending, and more. All transactions are validated by the on-chain PolicyGuard — even if the AI hallucinates, the contract rejects unsafe operations.
 
 ## Install
 
@@ -10,81 +10,141 @@ A CLI toolkit that gives **any AI agent** (OpenClaw, Claude, Codex, ChatGPT, etc
 npm install -g shll-skills
 ```
 
-## Quick Start
+This installs two binaries:
+- `shll-run` — CLI mode (for OpenClaw, shell scripts, etc.)
+- `shll-mcp` — MCP Server mode (for Claude, Cursor, Gemini, etc.)
+
+---
+
+## 🔌 MCP Server Setup (Recommended for AI Agents)
+
+The [Model Context Protocol](https://modelcontextprotocol.io/) lets AI agents discover and call SHLL tools natively — no CLI parsing needed.
+
+### Claude Desktop
+
+Edit `~/AppData/Roaming/Claude/claude_desktop_config.json` (Windows) or `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
+
+```json
+{
+  "mcpServers": {
+    "shll-defi": {
+      "command": "shll-mcp",
+      "env": {
+        "RUNNER_PRIVATE_KEY": "0x_YOUR_OPERATOR_PRIVATE_KEY"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. You'll see SHLL tools appear in the 🔧 menu.
+
+### Cursor
+
+Create `.cursor/mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "shll-defi": {
+      "command": "npx",
+      "args": ["-y", "shll-skills", "--mcp"],
+      "env": {
+        "RUNNER_PRIVATE_KEY": "0x_YOUR_OPERATOR_PRIVATE_KEY"
+      }
+    }
+  }
+}
+```
+
+### Custom Agent (programmatic)
+
+```bash
+RUNNER_PRIVATE_KEY=0x... shll-mcp
+```
+
+The server communicates via **stdio** using JSON-RPC 2.0. Send `tools/list` to discover all available tools.
+
+### Available MCP Tools
+
+| Tool | Type | Description |
+|------|------|-------------|
+| `portfolio` | Read | Vault holdings + token balances |
+| `balance` | Read | Operator wallet gas balance |
+| `price` | Read | Real-time token price (DexScreener) |
+| `lending_info` | Read | Venus Protocol supply balances + APY |
+| `swap` | Write | PancakeSwap V2/V3 auto-routing swap |
+| `lend` | Write | Supply tokens to Venus for yield |
+| `redeem` | Write | Withdraw from Venus |
+| `transfer` | Write | Send BNB or ERC20 from vault |
+
+---
+
+## 📟 CLI Mode
+
+For OpenClaw, shell scripts, or manual use.
+
+### Quick Start
 
 ```bash
 # 1. Generate an operator wallet (hot wallet for AI)
 shll-run generate-wallet
-# -> Outputs address + private key
+export RUNNER_PRIVATE_KEY="0x..."
 
-export RUNNER_PRIVATE_KEY="0x...(operator key)..."
-
-# 2. Get setup instructions (user completes on shll.run with their OWN wallet)
+# 2. Get setup link (user completes on shll.run with their OWN wallet)
 shll-run setup-guide --listing-id 0xABC...DEF --days 30
-# -> Outputs shll.run link for rent + authorize + fund
 
-# 3. After setup, trade with your token-id
-shll-run swap --from BNB --to USDC --amount 0.1 --token-id 5
+# 3. Trade
+shll-run swap --from BNB --to USDC --amount 0.1 -k 5
 ```
 
-## Commands
+### Commands
 
-### Trading & Asset Management
+#### Trading
 ```bash
-shll-run swap --from <TOKEN> --to <TOKEN> --amount <N> -k <ID> [--slippage <PERCENT>]
-shll-run wrap --amount <BNB> -k <ID>         # BNB -> WBNB
-shll-run unwrap --amount <BNB> -k <ID>       # WBNB -> BNB
-shll-run transfer --token <SYM> --amount <N> --to <ADDR> -k <ID>
-shll-run raw --target <ADDR> --data <HEX> -k <ID>
+shll-run swap -f <FROM> -t <TO> -a <AMT> -k <ID>            # Auto V2/V3 routing
+shll-run swap -f BNB -t USDT -a 0.1 -k 5 --dex v3 --fee 500 # Force V3, 0.05% fee
+shll-run wrap -a <BNB> -k <ID>                                # BNB -> WBNB
+shll-run unwrap -a <BNB> -k <ID>                              # WBNB -> BNB
+shll-run transfer --token <SYM> -a <AMT> --to <ADDR> -k <ID>
 ```
 
-### Market Data (read-only, no key needed)
+#### Lending (Venus Protocol)
+```bash
+shll-run lend -t USDT -a 100 -k <ID>      # Supply to Venus
+shll-run redeem -t USDT -a 50 -k <ID>     # Withdraw from Venus
+shll-run lending-info -k <ID>              # Show APY + positions
+```
+
+#### Market Data (read-only)
 ```bash
 shll-run portfolio -k <ID>        # Vault holdings + USD values
 shll-run price --token <SYM>      # Real-time price (DexScreener)
-shll-run search --query <TEXT>     # Find token by name on BSC
-shll-run tokens                   # List known token addresses
+shll-run search --query <TEXT>     # Find token by name
+shll-run tokens                   # List known tokens
 ```
 
-### Risk Management
+#### Risk Management
 ```bash
-shll-run policies -k <ID>         # View active policies
+shll-run policies -k <ID>         # View active on-chain policies
 shll-run config -k <ID> --tx-limit <BNB> --daily-limit <BNB> --cooldown <SEC>
 ```
 
-## AI Agent Integration
-
-This skill outputs **structured JSON** on stdout, making it easy for any AI agent to parse:
-
-```json
-{"status":"success","tx":"0xabc...","message":"Swapped 0.1 BNB -> 12.5 USDC"}
-```
-
-```json
-{"status":"rejected","reason":"Spending limit exceeded"}
-```
-
-### For AI providers:
-- **SKILL.md** — Structured skill metadata (name, description, commands, install instructions)
-- **stdout** — JSON-only output, designed for programmatic parsing
-- **stderr** — Human-readable errors
-- **Exit codes** — `0` = success, `1` = failure
+---
 
 ## How It Works
 
 ```
-AI Agent -> CLI command -> PolicyClient.validate() -> PolicyGuard (on-chain) -> execute via vault
+AI Agent -> CLI/MCP -> PolicyClient.validate() -> PolicyGuard (on-chain) -> vault
 ```
 
-1. AI constructs a CLI command based on user intent
+1. AI constructs a tool call (MCP) or CLI command
 2. `PolicyClient.validate()` simulates against all on-chain policies
-3. If approved, `AgentNFA.execute()` routes through PolicyGuard -> vault
-4. PolicyGuard enforces: spending limits, cooldowns, DEX whitelist, receiver guard
+3. If approved, `AgentNFA.execute()` routes through PolicyGuard → vault
+4. PolicyGuard enforces: spending limits, cooldowns, DEX whitelist, DeFi guard
 
 ## Security: Dual-Wallet Architecture
 
-SHLL enforces **separation of owner and operator wallets**:
-
 | | Owner Wallet | Operator Wallet (RUNNER_PRIVATE_KEY) |
 |---|---|---|
 | **Who holds it** | User (MetaMask/hardware) | AI agent |
@@ -93,26 +153,14 @@ SHLL enforces **separation of owner and operator wallets**:
 | **Can transfer NFT** | ✅ | ❌ |
 | **Risk if leaked** | 🚨 Full vault access | ⚠️ Limited to policy-allowed trades |
 
-**Additional on-chain enforcement:**
-- PolicyGuard validates every transaction, not the AI
-- Vault isolation — operator key cannot directly access vault funds
-- Risk limits can only be tightened, never loosened
-- Unknown selectors, targets, or recipients are rejected
-
 ## Environment Variables
 
 | Variable | Required | Description |
 |----------|----------|-------------|
-| `RUNNER_PRIVATE_KEY` | Yes | Operator wallet key (hot wallet, ~$1 BNB for gas) |
-| `RPC_URL` | No | BSC RPC (default: public endpoint) |
-| `NFA_ADDRESS` | No | AgentNFA contract override |
-| `GUARD_ADDRESS` | No | PolicyGuard contract override |
-
-## Updating
-
-```bash
-npm update -g shll-skills
-```
+| `RUNNER_PRIVATE_KEY` | Yes | Operator wallet key (~$1 BNB for gas) |
+| `SHLL_RPC` | No | BSC RPC URL override |
+| `SHLL_NFA` | No | AgentNFA contract override |
+| `SHLL_GUARD` | No | PolicyGuard contract override |
 
 ## Links
 
@@ -124,3 +172,4 @@ npm update -g shll-skills
 ## License
 
 MIT
+