shll-skills 4.0.0 → 4.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +109 -60
  2. package/dist/mcp.js +1 -3
  3. package/dist/mcp.mjs +1 -3
  4. package/package.json +1 -1
  5. package/src/mcp.ts +3 -3
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  [![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)
4
4
 
5
- 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.
5
+ 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.
6
6
 
7
7
  ## Install
8
8
 
@@ -10,81 +10,141 @@ A CLI toolkit that gives **any AI agent** (OpenClaw, Claude, Codex, ChatGPT, etc
10
10
  npm install -g shll-skills
11
11
  ```
12
12
 
13
- ## Quick Start
13
+ This installs two binaries:
14
+ - `shll-run` — CLI mode (for OpenClaw, shell scripts, etc.)
15
+ - `shll-mcp` — MCP Server mode (for Claude, Cursor, Gemini, etc.)
16
+
17
+ ---
18
+
19
+ ## 🔌 MCP Server Setup (Recommended for AI Agents)
20
+
21
+ The [Model Context Protocol](https://modelcontextprotocol.io/) lets AI agents discover and call SHLL tools natively — no CLI parsing needed.
22
+
23
+ ### Claude Desktop
24
+
25
+ Edit `~/AppData/Roaming/Claude/claude_desktop_config.json` (Windows) or `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
26
+
27
+ ```json
28
+ {
29
+ "mcpServers": {
30
+ "shll-defi": {
31
+ "command": "shll-mcp",
32
+ "env": {
33
+ "RUNNER_PRIVATE_KEY": "0x_YOUR_OPERATOR_PRIVATE_KEY"
34
+ }
35
+ }
36
+ }
37
+ }
38
+ ```
39
+
40
+ Restart Claude Desktop. You'll see SHLL tools appear in the 🔧 menu.
41
+
42
+ ### Cursor
43
+
44
+ Create `.cursor/mcp.json` in your project root:
45
+
46
+ ```json
47
+ {
48
+ "mcpServers": {
49
+ "shll-defi": {
50
+ "command": "npx",
51
+ "args": ["-y", "shll-skills", "--mcp"],
52
+ "env": {
53
+ "RUNNER_PRIVATE_KEY": "0x_YOUR_OPERATOR_PRIVATE_KEY"
54
+ }
55
+ }
56
+ }
57
+ }
58
+ ```
59
+
60
+ ### Custom Agent (programmatic)
61
+
62
+ ```bash
63
+ RUNNER_PRIVATE_KEY=0x... shll-mcp
64
+ ```
65
+
66
+ The server communicates via **stdio** using JSON-RPC 2.0. Send `tools/list` to discover all available tools.
67
+
68
+ ### Available MCP Tools
69
+
70
+ | Tool | Type | Description |
71
+ |------|------|-------------|
72
+ | `portfolio` | Read | Vault holdings + token balances |
73
+ | `balance` | Read | Operator wallet gas balance |
74
+ | `price` | Read | Real-time token price (DexScreener) |
75
+ | `lending_info` | Read | Venus Protocol supply balances + APY |
76
+ | `swap` | Write | PancakeSwap V2/V3 auto-routing swap |
77
+ | `lend` | Write | Supply tokens to Venus for yield |
78
+ | `redeem` | Write | Withdraw from Venus |
79
+ | `transfer` | Write | Send BNB or ERC20 from vault |
80
+
81
+ ---
82
+
83
+ ## 📟 CLI Mode
84
+
85
+ For OpenClaw, shell scripts, or manual use.
86
+
87
+ ### Quick Start
14
88
 
15
89
  ```bash
16
90
  # 1. Generate an operator wallet (hot wallet for AI)
17
91
  shll-run generate-wallet
18
- # -> Outputs address + private key
92
+ export RUNNER_PRIVATE_KEY="0x..."
19
93
 
20
- export RUNNER_PRIVATE_KEY="0x...(operator key)..."
21
-
22
- # 2. Get setup instructions (user completes on shll.run with their OWN wallet)
94
+ # 2. Get setup link (user completes on shll.run with their OWN wallet)
23
95
  shll-run setup-guide --listing-id 0xABC...DEF --days 30
24
- # -> Outputs shll.run link for rent + authorize + fund
25
96
 
26
- # 3. After setup, trade with your token-id
27
- shll-run swap --from BNB --to USDC --amount 0.1 --token-id 5
97
+ # 3. Trade
98
+ shll-run swap --from BNB --to USDC --amount 0.1 -k 5
28
99
  ```
29
100
 
30
- ## Commands
101
+ ### Commands
31
102
 
32
- ### Trading & Asset Management
103
+ #### Trading
33
104
  ```bash
34
- shll-run swap --from <TOKEN> --to <TOKEN> --amount <N> -k <ID> [--slippage <PERCENT>]
35
- shll-run wrap --amount <BNB> -k <ID> # BNB -> WBNB
36
- shll-run unwrap --amount <BNB> -k <ID> # WBNB -> BNB
37
- shll-run transfer --token <SYM> --amount <N> --to <ADDR> -k <ID>
38
- shll-run raw --target <ADDR> --data <HEX> -k <ID>
105
+ shll-run swap -f <FROM> -t <TO> -a <AMT> -k <ID> # Auto V2/V3 routing
106
+ shll-run swap -f BNB -t USDT -a 0.1 -k 5 --dex v3 --fee 500 # Force V3, 0.05% fee
107
+ shll-run wrap -a <BNB> -k <ID> # BNB -> WBNB
108
+ shll-run unwrap -a <BNB> -k <ID> # WBNB -> BNB
109
+ shll-run transfer --token <SYM> -a <AMT> --to <ADDR> -k <ID>
39
110
  ```
40
111
 
41
- ### Market Data (read-only, no key needed)
112
+ #### Lending (Venus Protocol)
113
+ ```bash
114
+ shll-run lend -t USDT -a 100 -k <ID> # Supply to Venus
115
+ shll-run redeem -t USDT -a 50 -k <ID> # Withdraw from Venus
116
+ shll-run lending-info -k <ID> # Show APY + positions
117
+ ```
118
+
119
+ #### Market Data (read-only)
42
120
  ```bash
43
121
  shll-run portfolio -k <ID> # Vault holdings + USD values
44
122
  shll-run price --token <SYM> # Real-time price (DexScreener)
45
- shll-run search --query <TEXT> # Find token by name on BSC
46
- shll-run tokens # List known token addresses
123
+ shll-run search --query <TEXT> # Find token by name
124
+ shll-run tokens # List known tokens
47
125
  ```
48
126
 
49
- ### Risk Management
127
+ #### Risk Management
50
128
  ```bash
51
- shll-run policies -k <ID> # View active policies
129
+ shll-run policies -k <ID> # View active on-chain policies
52
130
  shll-run config -k <ID> --tx-limit <BNB> --daily-limit <BNB> --cooldown <SEC>
53
131
  ```
54
132
 
55
- ## AI Agent Integration
56
-
57
- This skill outputs **structured JSON** on stdout, making it easy for any AI agent to parse:
58
-
59
- ```json
60
- {"status":"success","tx":"0xabc...","message":"Swapped 0.1 BNB -> 12.5 USDC"}
61
- ```
62
-
63
- ```json
64
- {"status":"rejected","reason":"Spending limit exceeded"}
65
- ```
66
-
67
- ### For AI providers:
68
- - **SKILL.md** — Structured skill metadata (name, description, commands, install instructions)
69
- - **stdout** — JSON-only output, designed for programmatic parsing
70
- - **stderr** — Human-readable errors
71
- - **Exit codes** — `0` = success, `1` = failure
133
+ ---
72
134
 
73
135
  ## How It Works
74
136
 
75
137
  ```
76
- AI Agent -> CLI command -> PolicyClient.validate() -> PolicyGuard (on-chain) -> execute via vault
138
+ AI Agent -> CLI/MCP -> PolicyClient.validate() -> PolicyGuard (on-chain) -> vault
77
139
  ```
78
140
 
79
- 1. AI constructs a CLI command based on user intent
141
+ 1. AI constructs a tool call (MCP) or CLI command
80
142
  2. `PolicyClient.validate()` simulates against all on-chain policies
81
- 3. If approved, `AgentNFA.execute()` routes through PolicyGuard -> vault
82
- 4. PolicyGuard enforces: spending limits, cooldowns, DEX whitelist, receiver guard
143
+ 3. If approved, `AgentNFA.execute()` routes through PolicyGuard → vault
144
+ 4. PolicyGuard enforces: spending limits, cooldowns, DEX whitelist, DeFi guard
83
145
 
84
146
  ## Security: Dual-Wallet Architecture
85
147
 
86
- SHLL enforces **separation of owner and operator wallets**:
87
-
88
148
  | | Owner Wallet | Operator Wallet (RUNNER_PRIVATE_KEY) |
89
149
  |---|---|---|
90
150
  | **Who holds it** | User (MetaMask/hardware) | AI agent |
@@ -93,26 +153,14 @@ SHLL enforces **separation of owner and operator wallets**:
93
153
  | **Can transfer NFT** | ✅ | ❌ |
94
154
  | **Risk if leaked** | 🚨 Full vault access | ⚠️ Limited to policy-allowed trades |
95
155
 
96
- **Additional on-chain enforcement:**
97
- - PolicyGuard validates every transaction, not the AI
98
- - Vault isolation — operator key cannot directly access vault funds
99
- - Risk limits can only be tightened, never loosened
100
- - Unknown selectors, targets, or recipients are rejected
101
-
102
156
  ## Environment Variables
103
157
 
104
158
  | Variable | Required | Description |
105
159
  |----------|----------|-------------|
106
- | `RUNNER_PRIVATE_KEY` | Yes | Operator wallet key (hot wallet, ~$1 BNB for gas) |
107
- | `RPC_URL` | No | BSC RPC (default: public endpoint) |
108
- | `NFA_ADDRESS` | No | AgentNFA contract override |
109
- | `GUARD_ADDRESS` | No | PolicyGuard contract override |
110
-
111
- ## Updating
112
-
113
- ```bash
114
- npm update -g shll-skills
115
- ```
160
+ | `RUNNER_PRIVATE_KEY` | Yes | Operator wallet key (~$1 BNB for gas) |
161
+ | `SHLL_RPC` | No | BSC RPC URL override |
162
+ | `SHLL_NFA` | No | AgentNFA contract override |
163
+ | `SHLL_GUARD` | No | PolicyGuard contract override |
116
164
 
117
165
  ## Links
118
166
 
@@ -124,3 +172,4 @@ npm update -g shll-skills
124
172
  ## License
125
173
 
126
174
  MIT
175
+
package/dist/mcp.js CHANGED
@@ -609,9 +609,7 @@ function getConfig() {
609
609
  const privateKey = process.env.RUNNER_PRIVATE_KEY;
610
610
  if (!privateKey) throw new Error("RUNNER_PRIVATE_KEY environment variable is required");
611
611
  const rpc = process.env.SHLL_RPC || DEFAULT_RPC;
612
- const nfa = process.env.SHLL_NFA || DEFAULT_NFA;
613
- const guard = process.env.SHLL_GUARD || DEFAULT_GUARD;
614
- return { privateKey, rpc, nfa, guard };
612
+ return { privateKey, rpc, nfa: DEFAULT_NFA, guard: DEFAULT_GUARD };
615
613
  }
616
614
  function createClients() {
617
615
  const config = getConfig();
package/dist/mcp.mjs CHANGED
@@ -118,9 +118,7 @@ function getConfig() {
118
118
  const privateKey = process.env.RUNNER_PRIVATE_KEY;
119
119
  if (!privateKey) throw new Error("RUNNER_PRIVATE_KEY environment variable is required");
120
120
  const rpc = process.env.SHLL_RPC || DEFAULT_RPC;
121
- const nfa = process.env.SHLL_NFA || DEFAULT_NFA;
122
- const guard = process.env.SHLL_GUARD || DEFAULT_GUARD;
123
- return { privateKey, rpc, nfa, guard };
121
+ return { privateKey, rpc, nfa: DEFAULT_NFA, guard: DEFAULT_GUARD };
124
122
  }
125
123
  function createClients() {
126
124
  const config = getConfig();
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "shll-skills",
3
- "version": "4.0.0",
3
+ "version": "4.0.1",
4
4
  "description": "SHLL DeFi Agent — CLI + MCP Server for BSC",
5
5
  "main": "dist/index.js",
6
6
  "bin": {
package/src/mcp.ts CHANGED
@@ -150,9 +150,9 @@ function getConfig() {
150
150
  const privateKey = process.env.RUNNER_PRIVATE_KEY;
151
151
  if (!privateKey) throw new Error("RUNNER_PRIVATE_KEY environment variable is required");
152
152
  const rpc = process.env.SHLL_RPC || DEFAULT_RPC;
153
- const nfa = process.env.SHLL_NFA || DEFAULT_NFA;
154
- const guard = process.env.SHLL_GUARD || DEFAULT_GUARD;
155
- return { privateKey, rpc, nfa, guard };
153
+ // Security: NFA and Guard addresses are hardcoded — never allow env overrides
154
+ // in MCP mode. This prevents pointing at fake contracts that always approve.
155
+ return { privateKey, rpc, nfa: DEFAULT_NFA, guard: DEFAULT_GUARD };
156
156
  }
157
157
 
158
158
  function createClients() {