shll-skills 4.0.0 → 5.0.0

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
+

package/dist/index.js

@@ -2152,6 +2152,71 @@ lendingInfoCmd.action(async (opts) => {
     process.exit(1);
   }
 });
+var OPERATOR_OF_ABI = [{
+  type: "function",
+  name: "operatorOf",
+  inputs: [{ name: "tokenId", type: "uint256" }],
+  outputs: [{ name: "", type: "address" }],
+  stateMutability: "view"
+}];
+var myAgentsCmd = new import_commander.Command("my-agents").description("List all agents where the current RUNNER_PRIVATE_KEY is the operator").option("-r, --rpc <url>", "BSC RPC URL", DEFAULT_RPC).option("--nfa-address <address>", "AgentNFA contract address", DEFAULT_NFA).option("--indexer <url>", "Indexer base URL", DEFAULT_INDEXER);
+myAgentsCmd.action(async (opts) => {
+  try {
+    if (!process.env.RUNNER_PRIVATE_KEY) {
+      output({ status: "error", message: "RUNNER_PRIVATE_KEY environment variable is missing" });
+      process.exit(1);
+    }
+    const operator = (0, import_accounts2.privateKeyToAccount)(toHex(process.env.RUNNER_PRIVATE_KEY)).address.toLowerCase();
+    const rpcUrl = opts.rpc || DEFAULT_RPC;
+    const nfaAddr = toHex(opts.nfaAddress || DEFAULT_NFA);
+    const indexerUrl = (opts.indexer || DEFAULT_INDEXER).replace(/\/+$/, "");
+    const publicClient = (0, import_viem2.createPublicClient)({ chain: import_chains2.bsc, transport: (0, import_viem2.http)(rpcUrl) });
+    const res = await fetch(`${indexerUrl}/api/agents`);
+    if (!res.ok) {
+      output({ status: "error", message: `Indexer error: ${res.status}` });
+      process.exit(1);
+    }
+    const json = await res.json();
+    const agents = (json.items || []).filter((a) => !a.isTemplate && a.tokenId !== void 0);
+    if (agents.length === 0) {
+      output({ status: "success", agents: [], message: "No agents found in indexer" });
+      return;
+    }
+    const checks = await Promise.all(
+      agents.map(async (a) => {
+        const tokenId = BigInt(a.tokenId);
+        try {
+          const op = await publicClient.readContract({
+            address: nfaAddr,
+            abi: OPERATOR_OF_ABI,
+            functionName: "operatorOf",
+            args: [tokenId]
+          });
+          return {
+            tokenId: tokenId.toString(),
+            vault: a.account || "",
+            owner: a.owner || "",
+            agentType: a.agentType || "unknown",
+            isOperator: op.toLowerCase() === operator
+          };
+        } catch {
+          return null;
+        }
+      })
+    );
+    const myAgents = checks.filter((c) => c !== null && c.isOperator);
+    output({
+      status: "success",
+      operator,
+      agents: myAgents,
+      count: myAgents.length
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Unknown error";
+    output({ status: "error", message });
+    process.exit(1);
+  }
+});
 program.addCommand(swapCmd);
 program.addCommand(rawCmd);
 program.addCommand(tokensCmd);
@@ -2173,4 +2238,5 @@ program.addCommand(statusCmd);
 program.addCommand(lendCmd);
 program.addCommand(redeemCmd);
 program.addCommand(lendingInfoCmd);
+program.addCommand(myAgentsCmd);
 program.parse(process.argv);

package/dist/index.mjs

@@ -1664,6 +1664,71 @@ lendingInfoCmd.action(async (opts) => {
     process.exit(1);
   }
 });
+var OPERATOR_OF_ABI = [{
+  type: "function",
+  name: "operatorOf",
+  inputs: [{ name: "tokenId", type: "uint256" }],
+  outputs: [{ name: "", type: "address" }],
+  stateMutability: "view"
+}];
+var myAgentsCmd = new Command("my-agents").description("List all agents where the current RUNNER_PRIVATE_KEY is the operator").option("-r, --rpc <url>", "BSC RPC URL", DEFAULT_RPC).option("--nfa-address <address>", "AgentNFA contract address", DEFAULT_NFA).option("--indexer <url>", "Indexer base URL", DEFAULT_INDEXER);
+myAgentsCmd.action(async (opts) => {
+  try {
+    if (!process.env.RUNNER_PRIVATE_KEY) {
+      output({ status: "error", message: "RUNNER_PRIVATE_KEY environment variable is missing" });
+      process.exit(1);
+    }
+    const operator = privateKeyToAccount(toHex(process.env.RUNNER_PRIVATE_KEY)).address.toLowerCase();
+    const rpcUrl = opts.rpc || DEFAULT_RPC;
+    const nfaAddr = toHex(opts.nfaAddress || DEFAULT_NFA);
+    const indexerUrl = (opts.indexer || DEFAULT_INDEXER).replace(/\/+$/, "");
+    const publicClient = createPublicClient({ chain: bsc, transport: http(rpcUrl) });
+    const res = await fetch(`${indexerUrl}/api/agents`);
+    if (!res.ok) {
+      output({ status: "error", message: `Indexer error: ${res.status}` });
+      process.exit(1);
+    }
+    const json = await res.json();
+    const agents = (json.items || []).filter((a) => !a.isTemplate && a.tokenId !== void 0);
+    if (agents.length === 0) {
+      output({ status: "success", agents: [], message: "No agents found in indexer" });
+      return;
+    }
+    const checks = await Promise.all(
+      agents.map(async (a) => {
+        const tokenId = BigInt(a.tokenId);
+        try {
+          const op = await publicClient.readContract({
+            address: nfaAddr,
+            abi: OPERATOR_OF_ABI,
+            functionName: "operatorOf",
+            args: [tokenId]
+          });
+          return {
+            tokenId: tokenId.toString(),
+            vault: a.account || "",
+            owner: a.owner || "",
+            agentType: a.agentType || "unknown",
+            isOperator: op.toLowerCase() === operator
+          };
+        } catch {
+          return null;
+        }
+      })
+    );
+    const myAgents = checks.filter((c) => c !== null && c.isOperator);
+    output({
+      status: "success",
+      operator,
+      agents: myAgents,
+      count: myAgents.length
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Unknown error";
+    output({ status: "error", message });
+    process.exit(1);
+  }
+});
 program.addCommand(swapCmd);
 program.addCommand(rawCmd);
 program.addCommand(tokensCmd);
@@ -1685,4 +1750,5 @@ program.addCommand(statusCmd);
 program.addCommand(lendCmd);
 program.addCommand(redeemCmd);
 program.addCommand(lendingInfoCmd);
+program.addCommand(myAgentsCmd);
 program.parse(process.argv);