@portkey/ca-agent-skills 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Portkey
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,270 @@
+# Portkey CA Agent Skills
+
+> AI Agent toolkit for [Portkey Wallet](https://portkey.finance) on the [aelf](https://aelf.com) blockchain — Email registration, login, transfers, guardian management, and generic contract calls.
+
+[中文文档](./README.zh-CN.md)
+
+## Architecture
+
+```
+ca-agent-skills/
+├── index.ts                    # SDK entry — direct import for LangChain / LlamaIndex
+├── src/
+│   ├── core/                   # Pure business logic (no I/O side effects)
+│   │   ├── account.ts          # checkAccount, getGuardianList, getHolderInfo, getChainInfo
+│   │   ├── auth.ts             # sendVerificationCode, verifyCode, registerWallet, recoverWallet
+│   │   ├── assets.ts           # getTokenBalance, getTokenList, getNftCollections, getNftItems, getTokenPrice
+│   │   ├── transfer.ts         # sameChainTransfer, crossChainTransfer, recoverStuckTransfer
+│   │   ├── guardian.ts         # addGuardian, removeGuardian
+│   │   ├── contract.ts         # managerForwardCall, callContractViewMethod
+│   │   └── keystore.ts         # Encrypted wallet persistence (save, unlock, lock)
+│   └── mcp/
+│       └── server.ts           # MCP adapter — for Claude Desktop, Cursor, GPT, etc.
+├── portkey_query_skill.ts      # CLI adapter — query commands
+├── portkey_auth_skill.ts       # CLI adapter — registration & login commands
+├── portkey_tx_skill.ts         # CLI adapter — transfer & guardian commands
+├── cli-helpers.ts              # CLI output helpers
+├── bin/
+│   └── setup.ts                # One-command setup for AI platforms
+├── lib/
+│   ├── config.ts               # Network config, env overrides
+│   ├── types.ts                # TypeScript interfaces & enums
+│   ├── aelf-client.ts          # aelf-sdk wrapper (wallet, contract, signing)
+│   └── http.ts                 # HTTP client for Portkey backend API
+└── __tests__/                  # Unit / Integration / E2E tests
+```
+
+**Core + Adapters pattern:** Three adapters (MCP, CLI, SDK) call the same Core functions — zero duplicated logic.
+
+## Features
+
+| # | Category | Capability | MCP Tool | CLI Command | SDK Function |
+|---|----------|-----------|----------|-------------|--------------|
+| 1 | Account | Check email registration | `portkey_check_account` | `check-account` | `checkAccount` |
+| 2 | Account | Get guardian list | `portkey_get_guardian_list` | `guardian-list` | `getGuardianList` |
+| 3 | Account | Get CA holder info | `portkey_get_holder_info` | `holder-info` | `getHolderInfo` |
+| 4 | Account | Get chain info | `portkey_get_chain_info` | `chain-info` | `getChainInfo` |
+| 5 | Auth | Get verifier server | `portkey_get_verifier` | `get-verifier` | `getVerifierServer` |
+| 6 | Auth | Send verification code | `portkey_send_code` | `send-code` | `sendVerificationCode` |
+| 7 | Auth | Verify code | `portkey_verify_code` | `verify-code` | `verifyCode` |
+| 8 | Auth | Register wallet | `portkey_register` | `register` | `registerWallet` |
+| 9 | Auth | Recover wallet (login) | `portkey_recover` | `recover` | `recoverWallet` |
+| 10 | Auth | Check status | `portkey_check_status` | `check-status` | `checkRegisterOrRecoveryStatus` |
+| 11 | Assets | Token balance | `portkey_balance` | `balance` | `getTokenBalance` |
+| 12 | Assets | Token list | `portkey_token_list` | `token-list` | `getTokenList` |
+| 13 | Assets | NFT collections | `portkey_nft_collections` | `nft-collections` | `getNftCollections` |
+| 14 | Assets | NFT items | `portkey_nft_items` | `nft-items` | `getNftItems` |
+| 15 | Assets | Token price | `portkey_token_price` | `token-price` | `getTokenPrice` |
+| 16 | Transfer | Same-chain transfer | `portkey_transfer` | `transfer` | `sameChainTransfer` |
+| 17 | Transfer | Cross-chain transfer | `portkey_cross_chain_transfer` | `cross-chain-transfer` | `crossChainTransfer` |
+| 18 | Transfer | Transaction result | `portkey_tx_result` | `tx-result` | `getTransactionResult` |
+| 19 | Transfer | Recover stuck transfer | `portkey_recover_stuck_transfer` | `recover-stuck-transfer` | `recoverStuckTransfer` |
+| 20 | Guardian | Add guardian | `portkey_add_guardian` | `add-guardian` | `addGuardian` |
+| 21 | Guardian | Remove guardian | `portkey_remove_guardian` | `remove-guardian` | `removeGuardian` |
+| 22 | Contract | ManagerForwardCall | `portkey_forward_call` | `forward-call` | `managerForwardCall` |
+| 23 | Contract | View method call | `portkey_view_call` | `view-call` | `callContractViewMethod` |
+| 24 | Wallet | Create wallet | `portkey_create_wallet` | `create-wallet` | `createWallet` |
+| 25 | Wallet | Save keystore | `portkey_save_keystore` | `save-keystore` | `saveKeystore` |
+| 26 | Wallet | Unlock wallet | `portkey_unlock` | `unlock` | `unlockWallet` |
+| 27 | Wallet | Lock wallet | `portkey_lock` | `lock` | `lockWallet` |
+| 28 | Wallet | Wallet status | `portkey_wallet_status` | `wallet-status` | `getWalletStatus` |
+
+## Wallet Persistence (Keystore)
+
+Manager private keys are encrypted and stored locally using aelf-sdk's keystore scheme (scrypt + AES-128-CTR).
+
+**Storage location:** `~/.portkey/ca/{network}.keystore.json`
+
+### First-time setup (after registration/recovery)
+
+```bash
+# AI flow: create_wallet → register → check_status → save_keystore(password)
+# The wallet is auto-unlocked after saving.
+```
+
+### New conversation
+
+```bash
+# AI calls portkey_wallet_status to check if keystore exists
+# If locked, asks user for password → portkey_unlock(password)
+# Write operations now work automatically
+```
+
+### Manual CLI usage
+
+```bash
+# Save keystore
+bun run portkey_auth_skill.ts save-keystore \
+  --password "your-password" \
+  --private-key "hex-key" \
+  --mnemonic "word1 word2 ..." \
+  --ca-hash "xxx" --ca-address "ELF_xxx_AELF"
+
+# Unlock
+bun run portkey_auth_skill.ts unlock --password "your-password"
+
+# Check status
+bun run portkey_auth_skill.ts wallet-status
+
+# Lock
+bun run portkey_auth_skill.ts lock
+```
+
+### How it works
+
+1. **Save** — encrypts the Manager private key + mnemonic with a user-provided password, writes to `~/.portkey/ca/`
+2. **Unlock** — decrypts the keystore, loads the wallet into memory for the current process
+3. **Lock** — clears the private key from memory
+4. **Write operations** — automatically use the unlocked wallet; falls back to `PORTKEY_PRIVATE_KEY` env var if no keystore is unlocked
+
+## Prerequisites
+
+- [Bun](https://bun.sh) >= 1.0
+- An aelf wallet private key or an unlocked keystore (for write operations only)
+
+## Quick Start
+
+### 1. Install
+
+```bash
+bun add @portkey/ca-agent-skills
+
+# Or clone locally
+git clone https://github.com/AwakenFinance/ca-agent-skills.git
+cd ca-agent-skills
+bun install
+```
+
+### 2. Configure
+
+```bash
+cp .env.example .env
+# Edit .env — add your PORTKEY_PRIVATE_KEY (only for write operations)
+```
+
+### 3. One-Command Setup
+
+```bash
+# Claude Desktop
+bun run bin/setup.ts claude
+
+# Cursor (project-level)
+bun run bin/setup.ts cursor
+
+# Cursor (global)
+bun run bin/setup.ts cursor --global
+
+# OpenClaw — output config to stdout
+bun run bin/setup.ts openclaw
+
+# OpenClaw — merge into existing config
+bun run bin/setup.ts openclaw --config-path ./my-openclaw.json
+
+# Check status (Claude, Cursor, OpenClaw)
+bun run bin/setup.ts list
+
+# Remove
+bun run bin/setup.ts uninstall claude
+bun run bin/setup.ts uninstall cursor
+bun run bin/setup.ts uninstall openclaw --config-path ./my-openclaw.json
+```
+
+## Usage
+
+### MCP (Claude Desktop / Cursor)
+
+Add to your MCP config (`mcp-config.example.json`):
+
+```json
+{
+  "mcpServers": {
+    "ca-agent-skills": {
+      "command": "bun",
+      "args": ["run", "/path/to/ca-agent-skills/src/mcp/server.ts"],
+      "env": {
+        "PORTKEY_PRIVATE_KEY": "your_private_key_here",
+        "PORTKEY_NETWORK": "mainnet"
+      }
+    }
+  }
+}
+```
+
+### OpenClaw
+
+The `openclaw.json` in the project root defines 13 CLI-based tools for OpenClaw. Use `bun run bin/setup.ts openclaw` to generate or merge the config.
+
+### CLI
+
+```bash
+# Check if email is registered
+bun run portkey_query_skill.ts check-account --email user@example.com
+
+# Get chain info
+bun run portkey_query_skill.ts chain-info
+
+# Create wallet
+bun run portkey_auth_skill.ts create-wallet
+
+# Transfer tokens (requires PORTKEY_PRIVATE_KEY env)
+bun run portkey_tx_skill.ts transfer --ca-hash xxx --token-contract xxx --symbol ELF --to xxx --amount 100000000 --chain-id AELF
+```
+
+### SDK
+
+```typescript
+import { getConfig, checkAccount, createWallet, getTokenBalance } from '@portkey/ca-agent-skills';
+
+const config = getConfig({ network: 'mainnet' });
+
+// Check account
+const account = await checkAccount(config, { email: 'user@example.com' });
+
+// Create wallet
+const wallet = createWallet();
+
+// Get balance
+const balance = await getTokenBalance(config, {
+  caAddress: 'xxx',
+  chainId: 'AELF',
+  symbol: 'ELF',
+});
+```
+
+## Network
+
+| Network | Chain IDs | API URL |
+|---------|-----------|---------|
+| mainnet (default) | AELF, tDVV | `https://aa-portkey.portkey.finance` |
+| testnet | AELF, tDVW | `https://aa-portkey-test.portkey.finance` |
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `PORTKEY_PRIVATE_KEY` | Fallback | — | Manager wallet private key (fallback if keystore not unlocked) |
+| `PORTKEY_NETWORK` | No | `mainnet` | `mainnet` or `testnet` |
+| `PORTKEY_API_URL` | No | Per network | Override API endpoint |
+| `PORTKEY_GRAPHQL_URL` | No | Per network | Override GraphQL endpoint |
+
+## Testing
+
+```bash
+bun test                    # All tests
+bun run test:unit           # Unit tests only
+bun run test:integration    # Integration (requires network)
+bun run test:e2e            # E2E (requires private key)
+```
+
+## Security
+
+- Never commit your `.env` file (git-ignored by default)
+- Private keys are only needed for write operations (transfer, guardian management, contract calls)
+- **Keystore encryption**: Manager private keys are encrypted with scrypt (N=8192) + AES-128-CTR via aelf-sdk's keystore module. Files are stored with `0600` permissions.
+- **In-memory lifecycle**: private keys exist in memory only while unlocked; `portkey_lock` clears them immediately
+- When using MCP, the keystore password only exists in the AI conversation context — it is never written to disk
+- `PORTKEY_PRIVATE_KEY` env var is supported as a fallback but keystore is the recommended approach
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,265 @@
+# Portkey CA Agent Skills
+
+> [Portkey Wallet](https://portkey.finance) 的 AI Agent 工具包，基于 [aelf](https://aelf.com) 区块链 — 支持 Email 注册/登录、转账、Guardian 管理和通用合约调用。
+
+[English](./README.md)
+
+## 架构
+
+```
+ca-agent-skills/
+├── index.ts                    # SDK 入口 — 供 LangChain / LlamaIndex 直接 import
+├── src/
+│   ├── core/                   # 纯业务逻辑（无副作用）
+│   │   ├── account.ts          # 账户查询
+│   │   ├── auth.ts             # 注册/登录/验证
+│   │   ├── assets.ts           # 资产查询（Token、NFT、价格）
+│   │   ├── transfer.ts         # 同链/跨链转账、卡单恢复
+│   │   ├── guardian.ts         # Guardian 管理
+│   │   ├── contract.ts         # 通用合约调用（ManagerForwardCall）
+│   │   └── keystore.ts         # 钱包加密持久化（save、unlock、lock）
+│   └── mcp/
+│       └── server.ts           # MCP 适配器 — Claude Desktop / Cursor / GPT
+├── portkey_query_skill.ts      # CLI — 查询命令
+├── portkey_auth_skill.ts       # CLI — 注册/登录命令
+├── portkey_tx_skill.ts         # CLI — 交易/Guardian 命令
+├── bin/setup.ts                # 一键配置工具
+└── lib/                        # 基础设施（config、types、aelf-sdk 封装、HTTP 客户端）
+```
+
+**核心模式：** 三个适配器（MCP / CLI / SDK）调用同一套 Core 函数，零重复逻辑。
+
+## 功能清单
+
+| # | 分类 | 功能 | MCP Tool | SDK 函数 |
+|---|------|------|----------|----------|
+| 1 | 账户 | 检查 Email 是否注册 | `portkey_check_account` | `checkAccount` |
+| 2 | 账户 | 获取 Guardian 列表 | `portkey_get_guardian_list` | `getGuardianList` |
+| 3 | 账户 | 获取 CA Holder 信息 | `portkey_get_holder_info` | `getHolderInfo` |
+| 4 | 账户 | 获取链信息 | `portkey_get_chain_info` | `getChainInfo` |
+| 5 | 验证 | 获取 Verifier | `portkey_get_verifier` | `getVerifierServer` |
+| 6 | 验证 | 发送验证码 | `portkey_send_code` | `sendVerificationCode` |
+| 7 | 验证 | 校验验证码 | `portkey_verify_code` | `verifyCode` |
+| 8 | 注册 | 注册 CA 钱包 | `portkey_register` | `registerWallet` |
+| 9 | 登录 | 恢复/登录 CA 钱包 | `portkey_recover` | `recoverWallet` |
+| 10 | 状态 | 查询注册/恢复状态 | `portkey_check_status` | `checkRegisterOrRecoveryStatus` |
+| 11 | 资产 | 查询 Token 余额 | `portkey_balance` | `getTokenBalance` |
+| 12 | 资产 | Token 列表 | `portkey_token_list` | `getTokenList` |
+| 13 | 资产 | NFT 集合 | `portkey_nft_collections` | `getNftCollections` |
+| 14 | 资产 | NFT 项目 | `portkey_nft_items` | `getNftItems` |
+| 15 | 资产 | Token 价格 | `portkey_token_price` | `getTokenPrice` |
+| 16 | 转账 | 同链转账 | `portkey_transfer` | `sameChainTransfer` |
+| 17 | 转账 | 跨链转账 | `portkey_cross_chain_transfer` | `crossChainTransfer` |
+| 18 | 转账 | 查询交易结果 | `portkey_tx_result` | `getTransactionResult` |
+| 19 | 转账 | 跨链卡单恢复 | `portkey_recover_stuck_transfer` | `recoverStuckTransfer` |
+| 20 | Guardian | 添加 Guardian | `portkey_add_guardian` | `addGuardian` |
+| 21 | Guardian | 移除 Guardian | `portkey_remove_guardian` | `removeGuardian` |
+| 22 | 合约 | 通用 ManagerForwardCall | `portkey_forward_call` | `managerForwardCall` |
+| 23 | 合约 | 只读合约调用 | `portkey_view_call` | `callContractViewMethod` |
+| 24 | 钱包 | 创建钱包 | `portkey_create_wallet` | `createWallet` |
+| 25 | 钱包 | 保存 Keystore | `portkey_save_keystore` | `saveKeystore` |
+| 26 | 钱包 | 解锁钱包 | `portkey_unlock` | `unlockWallet` |
+| 27 | 钱包 | 锁定钱包 | `portkey_lock` | `lockWallet` |
+| 28 | 钱包 | 钱包状态 | `portkey_wallet_status` | `getWalletStatus` |
+
+## 钱包持久化（Keystore）
+
+Manager 私钥使用 aelf-sdk 内置的 keystore 方案（scrypt + AES-128-CTR）加密存储到本地。
+
+**存储路径：** `~/.portkey/ca/{network}.keystore.json`
+
+### 首次设置（注册/恢复成功后）
+
+```bash
+# AI 流程：create_wallet → register → check_status → save_keystore(密码)
+# 保存后自动解锁，当前对话可直接使用。
+```
+
+### 新对话
+
+```bash
+# AI 调用 portkey_wallet_status 检查是否存在 keystore
+# 如果已锁定，向用户索要密码 → portkey_unlock(密码)
+# 之后写操作自动生效
+```
+
+### CLI 手动操作
+
+```bash
+# 保存 keystore
+bun run portkey_auth_skill.ts save-keystore \
+  --password "你的密码" \
+  --private-key "hex私钥" \
+  --mnemonic "助记词" \
+  --ca-hash "xxx" --ca-address "ELF_xxx_AELF"
+
+# 解锁
+bun run portkey_auth_skill.ts unlock --password "你的密码"
+
+# 查看状态
+bun run portkey_auth_skill.ts wallet-status
+
+# 锁定
+bun run portkey_auth_skill.ts lock
+```
+
+### 工作原理
+
+1. **Save** — 用用户密码加密 Manager 私钥 + 助记词，写入 `~/.portkey/ca/`
+2. **Unlock** — 解密 keystore，将钱包加载到进程内存
+3. **Lock** — 清除内存中的私钥
+4. **写操作** — 优先使用已解锁的钱包；如果没有解锁的 keystore，fallback 到 `PORTKEY_PRIVATE_KEY` 环境变量
+
+## 前置条件
+
+- [Bun](https://bun.sh) >= 1.0
+- aelf 钱包私钥或已解锁的 keystore（仅写操作需要）
+
+## 快速开始
+
+```bash
+# 安装
+bun add @portkey/ca-agent-skills
+
+# 配置
+cp .env.example .env
+# 编辑 .env，添加 PORTKEY_PRIVATE_KEY（仅写操作需要）
+
+# 一键配置到 AI 平台
+bun run bin/setup.ts claude          # Claude Desktop
+bun run bin/setup.ts cursor          # Cursor（项目级）
+bun run bin/setup.ts cursor --global # Cursor（全局）
+bun run bin/setup.ts openclaw        # OpenClaw — 输出配置到 stdout
+bun run bin/setup.ts openclaw --config-path ./my-openclaw.json  # 合并到已有配置
+
+# 查看配置状态（Claude / Cursor / OpenClaw）
+bun run bin/setup.ts list
+
+# 卸载
+bun run bin/setup.ts uninstall claude
+bun run bin/setup.ts uninstall cursor
+bun run bin/setup.ts uninstall openclaw --config-path ./my-openclaw.json
+```
+
+## SDK 使用示例
+
+```typescript
+import { getConfig, checkAccount, createWallet, getTokenBalance } from '@portkey/ca-agent-skills';
+
+const config = getConfig({ network: 'mainnet' });
+
+// 检查账户
+const account = await checkAccount(config, { email: 'user@example.com' });
+console.log(account.isRegistered, account.originChainId);
+
+// 创建钱包
+const wallet = createWallet();
+console.log(wallet.address, wallet.privateKey);
+
+// 查询余额
+const balance = await getTokenBalance(config, {
+  caAddress: 'xxx',
+  chainId: 'AELF',
+  symbol: 'ELF',
+});
+```
+
+## 注册流程示例（Email）
+
+```typescript
+import {
+  getConfig, createWallet, getVerifierServer,
+  sendVerificationCode, verifyCode, registerWallet,
+  checkRegisterOrRecoveryStatus, OperationType,
+} from '@portkey/ca-agent-skills';
+
+const config = getConfig({ network: 'mainnet' });
+
+// 1. 获取 Verifier
+const verifier = await getVerifierServer(config);
+
+// 2. 发送验证码（注意：mainnet 已废弃 Register(0)，统一使用 CommunityRecovery(1)）
+const { verifierSessionId } = await sendVerificationCode(config, {
+  email: 'user@example.com',
+  verifierId: verifier.id,
+  chainId: 'AELF',
+  operationType: OperationType.CreateCAHolder, // 注册用 1，登录用 SocialRecovery(2)
+});
+
+// 3. 用户输入验证码后校验
+const { signature, verificationDoc } = await verifyCode(config, {
+  email: 'user@example.com',
+  verificationCode: '123456',
+  verifierId: verifier.id,
+  verifierSessionId,
+  chainId: 'AELF',
+  operationType: OperationType.CreateCAHolder,
+});
+
+// 4. 创建 Manager 钱包
+const wallet = createWallet();
+
+// 5. 提交注册
+const { sessionId } = await registerWallet(config, {
+  email: 'user@example.com',
+  manager: wallet.address,
+  verifierId: verifier.id,
+  verificationDoc,
+  signature,
+  chainId: 'AELF',
+});
+
+// 6. 轮询状态
+let status;
+do {
+  await new Promise(r => setTimeout(r, 3000));
+  status = await checkRegisterOrRecoveryStatus(config, { sessionId, type: 'register' });
+} while (status.status === 'pending');
+
+console.log('CA Address:', status.caAddress);
+console.log('CA Hash:', status.caHash);
+
+// 7. 保存 keystore（加密持久化 Manager 私钥）
+import { saveKeystore } from '@portkey/ca-agent-skills';
+saveKeystore({
+  password: 'user-chosen-password',
+  privateKey: wallet.privateKey,
+  mnemonic: wallet.mnemonic,
+  caHash: status.caHash!,
+  caAddress: status.caAddress!,
+  originChainId: 'AELF',
+  network: 'mainnet',
+});
+// 钱包已自动解锁，后续写操作无需再设置 PORTKEY_PRIVATE_KEY
+```
+
+## 环境变量
+
+| 变量 | 必需 | 默认值 | 说明 |
+|------|------|--------|------|
+| `PORTKEY_PRIVATE_KEY` | Fallback | — | Manager 钱包私钥（keystore 未解锁时的 fallback） |
+| `PORTKEY_NETWORK` | 否 | `mainnet` | `mainnet` 或 `testnet` |
+| `PORTKEY_API_URL` | 否 | 按网络 | 覆盖 API 地址 |
+| `PORTKEY_GRAPHQL_URL` | 否 | 按网络 | 覆盖 GraphQL 地址 |
+
+## 测试
+
+```bash
+bun test                    # 全部测试
+bun run test:unit           # 单元测试
+bun run test:integration    # 集成测试（需要网络）
+bun run test:e2e            # E2E 测试（需要私钥）
+```
+
+## 安全
+
+- `.env` 文件已默认 git-ignore，不要提交
+- 私钥仅写操作需要（转账、Guardian 管理、合约调用）
+- **Keystore 加密**：Manager 私钥使用 scrypt（N=8192）+ AES-128-CTR 加密，文件权限 `0600`
+- **内存生命周期**：私钥仅在 unlock 期间存在于内存，`portkey_lock` 立即清除
+- MCP 模式下，keystore 密码仅存在于 AI 对话上下文，不会写入磁盘
+- `PORTKEY_PRIVATE_KEY` 环境变量仍然支持作为 fallback，但推荐使用 keystore
+
+## License
+
+MIT

package/bin/platforms/claude.ts

@@ -0,0 +1,36 @@
+import {
+  getPlatformPaths,
+  readJsonFile,
+  writeJsonFile,
+  mergeMcpConfig,
+  generateMcpEntry,
+  SERVER_NAME,
+} from './utils.js';
+
+export interface ClaudeSetupOptions {
+  configPath?: string;
+  serverPath?: string;
+  force?: boolean;
+}
+
+export function setupClaude(options: ClaudeSetupOptions = {}): void {
+  const paths = getPlatformPaths();
+  const configPath = options.configPath || paths.claude;
+
+  const existing = readJsonFile(configPath);
+  const entry = generateMcpEntry(options.serverPath);
+  const { config, action } = mergeMcpConfig(existing, SERVER_NAME, entry, options.force);
+
+  if (action === 'skipped') {
+    console.log(`[SKIP] "${SERVER_NAME}" already exists in ${configPath}`);
+    console.log('       Use --force to overwrite.');
+    return;
+  }
+
+  writeJsonFile(configPath, config);
+  console.log(`[${action.toUpperCase()}] ${SERVER_NAME} in ${configPath}`);
+  console.log('');
+  console.log('Next steps:');
+  console.log('  1. Edit the config to replace <YOUR_PRIVATE_KEY> with your actual key');
+  console.log('  2. Restart Claude Desktop');
+}

package/bin/platforms/cursor.ts

@@ -0,0 +1,39 @@
+import {
+  getPlatformPaths,
+  readJsonFile,
+  writeJsonFile,
+  mergeMcpConfig,
+  generateMcpEntry,
+  SERVER_NAME,
+} from './utils.js';
+
+export interface CursorSetupOptions {
+  configPath?: string;
+  serverPath?: string;
+  force?: boolean;
+  global?: boolean;
+}
+
+export function setupCursor(options: CursorSetupOptions = {}): void {
+  const paths = getPlatformPaths();
+  const configPath =
+    options.configPath || (options.global ? paths.cursorGlobal : paths.cursorProject);
+
+  const existing = readJsonFile(configPath);
+  const entry = generateMcpEntry(options.serverPath);
+  const { config, action } = mergeMcpConfig(existing, SERVER_NAME, entry, options.force);
+
+  if (action === 'skipped') {
+    console.log(`[SKIP] "${SERVER_NAME}" already exists in ${configPath}`);
+    console.log('       Use --force to overwrite.');
+    return;
+  }
+
+  writeJsonFile(configPath, config);
+  const scope = options.global ? 'global' : 'project-level';
+  console.log(`[${action.toUpperCase()}] ${SERVER_NAME} (${scope}) in ${configPath}`);
+  console.log('');
+  console.log('Next steps:');
+  console.log('  1. Edit the config to replace <YOUR_PRIVATE_KEY> with your actual key');
+  console.log('  2. Restart Cursor or reload the MCP servers');
+}

package/bin/platforms/openclaw.ts

@@ -0,0 +1,39 @@
+import * as path from 'path';
+import * as fs from 'fs';
+import { getPackageRoot, readJsonFile, writeJsonFile } from './utils.js';
+
+export interface OpenClawSetupOptions {
+  configPath?: string;
+  cwd?: string;
+  force?: boolean;
+}
+
+export function setupOpenClaw(options: OpenClawSetupOptions = {}): void {
+  const packageRoot = getPackageRoot();
+  const openclawSource = path.join(packageRoot, 'openclaw.json');
+
+  if (!fs.existsSync(openclawSource)) {
+    console.log('[ERROR] openclaw.json not found at', openclawSource);
+    console.log('        Please create it first.');
+    return;
+  }
+
+  const sourceConfig = readJsonFile(openclawSource);
+
+  // Replace cwd placeholders if needed
+  const cwd = options.cwd || packageRoot;
+
+  if (options.configPath) {
+    // Merge into existing config
+    const existing = readJsonFile(options.configPath);
+    const merged = {
+      ...existing,
+      tools: [...((existing.tools as unknown[]) || []), ...((sourceConfig.tools as unknown[]) || [])],
+    };
+    writeJsonFile(options.configPath, merged);
+    console.log(`[MERGED] OpenClaw tools into ${options.configPath}`);
+  } else {
+    // Output to stdout for piping
+    console.log(JSON.stringify({ ...sourceConfig, cwd }, null, 2));
+  }
+}