@eforest-finance/agent-skills 0.2.0

package/.env.example

@@ -0,0 +1,13 @@
+# aelf wallet private key (hex string, 64 chars)
+# Used for signing transactions on aelf blockchain.
+# WARNING: Never commit real private keys to version control.
+AELF_PRIVATE_KEY=your_private_key_here
+
+# Optional: override environment (default: mainnet)
+# AELF_ENV=testnet
+
+# Optional: override API base URL
+# AELF_API_URL=https://test.eforest.finance/api
+
+# Optional: override RPC URL
+# AELF_RPC_URL=https://aelf-test-node.aelf.io

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 eForest Finance
+
+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,187 @@
+[English](README.md) | [中文](README_zh-CN.md)
+
+# eForest Agent Skills
+
+AI Agent Kit for aelf token lifecycle on [eForest](https://www.eforest.finance). Provides CLI, MCP Server, and SDK interfaces for:
+
+- **buy-seed** — Purchase a SEED from the SymbolRegister contract
+- **create-token** — Create a new FT token using an owned SEED (with cross-chain sync)
+- **issue-token** — Issue tokens via Proxy ForwardCall
+
+## Quick Start
+
+### Prerequisites
+
+- [Bun](https://bun.sh) >= 1.0
+- An aelf wallet private key with ELF balance
+
+### Install
+
+```bash
+git clone https://github.com/eforest-finance/eforest-agent-skills.git
+cd eforest-agent-skills
+bun install
+```
+
+### Configure
+
+```bash
+cp .env.example .env
+# Edit .env and set your AELF_PRIVATE_KEY
+```
+
+### CLI Usage
+
+```bash
+# Check SEED price (dry-run)
+bun run cli buy-seed --symbol MYTOKEN --issuer <your-address> --dry-run
+
+# Buy SEED (max 2 ELF)
+bun run cli buy-seed --symbol MYTOKEN --issuer <your-address> --force 2
+
+# Create token on tDVV side chain
+bun run cli create-token \
+  --symbol MYTOKEN --token-name "My Token" \
+  --seed-symbol SEED-321 \
+  --total-supply 100000000 --decimals 8 \
+  --issue-chain tDVV
+
+# Issue tokens
+bun run cli issue-token \
+  --symbol MYTOKEN --amount 10000000000000000 \
+  --to <recipient-address> --chain tDVV
+```
+
+## MCP Server (Claude Desktop / Cursor)
+
+One-command setup for AI platforms:
+
+```bash
+# Claude Desktop
+bun run setup claude
+
+# Cursor IDE (project-level)
+bun run setup cursor
+
+# Cursor IDE (global)
+bun run setup cursor --global
+
+# Check status
+bun run setup list
+```
+
+Then edit the generated config to replace `<YOUR_PRIVATE_KEY>` with your actual key.
+
+### Manual MCP Config
+
+If you prefer manual configuration, add this to your MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "eforest-token": {
+      "command": "bun",
+      "args": ["run", "/path/to/eforest-agent-skills/src/mcp/server.ts"],
+      "env": {
+        "AELF_PRIVATE_KEY": "your_private_key",
+        "EFOREST_NETWORK": "mainnet"
+      }
+    }
+  }
+}
+```
+
+## OpenClaw
+
+```bash
+# Generate OpenClaw config with absolute paths
+bun run setup openclaw
+
+# Merge into existing config
+bun run setup openclaw --config-path /path/to/openclaw.json
+```
+
+## SDK Usage
+
+```typescript
+import { buySeed, createToken, issueToken } from '@eforest-finance/agent-skills';
+import { getNetworkConfig } from '@eforest-finance/agent-skills';
+
+const config = await getNetworkConfig({ env: 'mainnet', privateKey: '...' });
+
+const seedResult = await buySeed(config, {
+  symbol: 'MYTOKEN',
+  issueTo: config.walletAddress,
+  force: 2,
+});
+
+const tokenResult = await createToken(config, {
+  symbol: 'MYTOKEN',
+  tokenName: 'My Token',
+  seedSymbol: seedResult.seedSymbol!,
+  totalSupply: '100000000',
+  decimals: 8,
+  issuer: config.walletAddress,
+  issueChain: 'tDVV',
+  isBurnable: true,
+  tokenImage: '',
+});
+```
+
+## Architecture
+
+```
+eforest-agent-skills/
+├── lib/                  # Infrastructure layer
+│   ├── types.ts          # Interfaces, constants, validators
+│   ├── config.ts         # Network config & .env loader
+│   ├── aelf-client.ts    # aelf-sdk wrapper
+│   └── api-client.ts     # eForest backend API client
+├── src/
+│   ├── core/             # Pure business logic (no I/O side effects)
+│   │   ├── seed.ts       # buySeed + parseSeedSymbolFromLogs
+│   │   ├── token.ts      # createToken
+│   │   └── issue.ts      # issueToken + encodeIssueInput
+│   └── mcp/
+│       └── server.ts     # MCP Server adapter (Zod validation)
+├── bin/
+│   ├── setup.ts          # Setup CLI entry point
+│   └── platforms/        # Claude, Cursor, OpenClaw adapters
+├── create_token_skill.ts # CLI adapter (thin wrapper)
+├── index.ts              # SDK entry (re-exports)
+├── openclaw.json         # OpenClaw tool definitions
+└── __tests__/            # Unit + Integration tests
+```
+
+## Configuration Priority
+
+Settings are resolved in this order (highest priority first):
+
+1. Function params (SDK callers)
+2. CLI args (`--env`, `--rpc-url`)
+3. `EFOREST_*` / `AELF_*` environment variables
+4. `.env` file
+5. CMS remote config
+6. Code defaults (ENV_PRESETS)
+
+## Testing
+
+```bash
+bun test              # All tests
+bun test:unit         # Unit tests only
+bun test:integration  # Integration tests only
+```
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `AELF_PRIVATE_KEY` | aelf wallet private key | (required) |
+| `EFOREST_NETWORK` / `AELF_ENV` | `mainnet` or `testnet` | `mainnet` |
+| `EFOREST_API_URL` / `AELF_API_URL` | Backend API URL | auto |
+| `EFOREST_RPC_URL` / `AELF_RPC_URL` | AELF MainChain RPC | auto |
+| `EFOREST_RPC_URL_TDVV` | tDVV RPC URL | auto |
+
+## License
+
+[MIT](LICENSE)

package/bin/platforms/claude.ts

@@ -0,0 +1,65 @@
+// ============================================================
+// Setup: Claude Desktop — write MCP config
+// ============================================================
+
+import {
+  getPlatformPaths,
+  readJsonFile,
+  writeJsonFile,
+  generateMcpEntry,
+  mergeMcpConfig,
+  removeMcpEntry,
+  SERVER_NAME,
+  LOG,
+} from './utils';
+
+export function setupClaude(opts: {
+  configPath?: string;
+  serverPath?: string;
+  force?: boolean;
+}): boolean {
+  const configPath = opts.configPath || getPlatformPaths().claude;
+  const entry = generateMcpEntry(opts.serverPath);
+
+  LOG.step(`Config file: ${configPath}`);
+  LOG.step(`MCP server: ${entry.args[1]}`);
+
+  const existing = readJsonFile(configPath);
+  const { config, action } = mergeMcpConfig(
+    existing,
+    SERVER_NAME,
+    entry,
+    opts.force,
+  );
+
+  if (action === 'skipped') {
+    LOG.warn(`"${SERVER_NAME}" already exists in Claude Desktop config.`);
+    LOG.info('Use --force to overwrite.');
+    return false;
+  }
+
+  writeJsonFile(configPath, config);
+  LOG.success(`Claude Desktop MCP config ${action}: ${configPath}`);
+  LOG.info('');
+  LOG.warn(
+    'IMPORTANT: Edit the config file and replace <YOUR_PRIVATE_KEY> with your actual aelf private key.',
+  );
+  LOG.info('Then restart Claude Desktop to pick up the new MCP server.');
+  return true;
+}
+
+export function uninstallClaude(opts: { configPath?: string }): boolean {
+  const configPath = opts.configPath || getPlatformPaths().claude;
+  const existing = readJsonFile(configPath);
+  const { config, removed } = removeMcpEntry(existing, SERVER_NAME);
+
+  if (!removed) {
+    LOG.info(`"${SERVER_NAME}" not found in Claude Desktop config.`);
+    return false;
+  }
+
+  writeJsonFile(configPath, config);
+  LOG.success(`Removed "${SERVER_NAME}" from Claude Desktop config.`);
+  LOG.info('Restart Claude Desktop to apply changes.');
+  return true;
+}

package/bin/platforms/cursor.ts

@@ -0,0 +1,95 @@
+// ============================================================
+// Setup: Cursor — write MCP config (project or global)
+// ============================================================
+
+import {
+  getPlatformPaths,
+  getCursorProjectPath,
+  readJsonFile,
+  writeJsonFile,
+  generateMcpEntry,
+  mergeMcpConfig,
+  removeMcpEntry,
+  SERVER_NAME,
+  LOG,
+} from './utils';
+
+export function setupCursor(opts: {
+  global?: boolean;
+  configPath?: string;
+  serverPath?: string;
+  force?: boolean;
+  projectDir?: string;
+}): boolean {
+  let configPath: string;
+  let scope: string;
+
+  if (opts.configPath) {
+    configPath = opts.configPath;
+    scope = 'custom';
+  } else if (opts.global) {
+    configPath = getPlatformPaths().cursorGlobal;
+    scope = 'global';
+  } else {
+    configPath = getCursorProjectPath(opts.projectDir);
+    scope = 'project';
+  }
+
+  const entry = generateMcpEntry(opts.serverPath);
+
+  LOG.step(`Scope: ${scope}`);
+  LOG.step(`Config file: ${configPath}`);
+  LOG.step(`MCP server: ${entry.args[1]}`);
+
+  const existing = readJsonFile(configPath);
+  const { config, action } = mergeMcpConfig(
+    existing,
+    SERVER_NAME,
+    entry,
+    opts.force,
+  );
+
+  if (action === 'skipped') {
+    LOG.warn(`"${SERVER_NAME}" already exists in Cursor ${scope} config.`);
+    LOG.info('Use --force to overwrite.');
+    return false;
+  }
+
+  writeJsonFile(configPath, config);
+  LOG.success(`Cursor ${scope} MCP config ${action}: ${configPath}`);
+  LOG.info('');
+  LOG.warn(
+    'IMPORTANT: Edit the config file and replace <YOUR_PRIVATE_KEY> with your actual aelf private key.',
+  );
+  LOG.info(
+    'Cursor will auto-detect the new MCP server (or restart Cursor).',
+  );
+  return true;
+}
+
+export function uninstallCursor(opts: {
+  global?: boolean;
+  configPath?: string;
+  projectDir?: string;
+}): boolean {
+  let configPath: string;
+  if (opts.configPath) {
+    configPath = opts.configPath;
+  } else if (opts.global) {
+    configPath = getPlatformPaths().cursorGlobal;
+  } else {
+    configPath = getCursorProjectPath(opts.projectDir);
+  }
+
+  const existing = readJsonFile(configPath);
+  const { config, removed } = removeMcpEntry(existing, SERVER_NAME);
+
+  if (!removed) {
+    LOG.info(`"${SERVER_NAME}" not found in Cursor config: ${configPath}`);
+    return false;
+  }
+
+  writeJsonFile(configPath, config);
+  LOG.success(`Removed "${SERVER_NAME}" from Cursor config: ${configPath}`);
+  return true;
+}

package/bin/platforms/openclaw.ts

@@ -0,0 +1,125 @@
+// ============================================================
+// Setup: OpenClaw — register skills from openclaw.json
+// ============================================================
+
+import * as path from 'path';
+import * as fs from 'fs';
+import { getPackageRoot, readJsonFile, writeJsonFile, LOG } from './utils';
+
+/** Skill names owned by this package (for uninstall) */
+const EFOREST_SKILL_NAMES = new Set([
+  'aelf-buy-seed',
+  'aelf-create-token',
+  'aelf-issue-token',
+]);
+
+export function setupOpenClaw(opts: {
+  configPath?: string;
+  cwd?: string;
+  force?: boolean;
+}): boolean {
+  const packageRoot = getPackageRoot();
+  const sourceFile = path.join(packageRoot, 'openclaw.json');
+
+  if (!fs.existsSync(sourceFile)) {
+    LOG.error(`openclaw.json not found at ${sourceFile}`);
+    return false;
+  }
+
+  const source = readJsonFile(sourceFile);
+  const skills: any[] = source.skills || [];
+
+  if (!skills.length) {
+    LOG.error('No skills found in openclaw.json');
+    return false;
+  }
+
+  // Resolve working_directory for all skills — use explicit cwd, or package root
+  const resolvedCwd = opts.cwd || packageRoot;
+
+  const updatedSkills = skills.map((skill: any) => ({
+    ...skill,
+    working_directory: resolvedCwd,
+  }));
+
+  // If user specified a target config path, merge into it
+  if (opts.configPath) {
+    LOG.step(`Merging ${skills.length} skills into: ${opts.configPath}`);
+
+    const existing = readJsonFile(opts.configPath);
+    if (!existing.skills) existing.skills = [];
+
+    let added = 0;
+    let updated = 0;
+    let skipped = 0;
+
+    for (const skill of updatedSkills) {
+      const idx = existing.skills.findIndex(
+        (s: any) => s.name === skill.name,
+      );
+      if (idx >= 0) {
+        if (opts.force) {
+          existing.skills[idx] = skill;
+          updated++;
+        } else {
+          skipped++;
+        }
+      } else {
+        existing.skills.push(skill);
+        added++;
+      }
+    }
+
+    writeJsonFile(opts.configPath, existing);
+    LOG.success(
+      `OpenClaw config updated: ${added} added, ${updated} updated, ${skipped} skipped.`,
+    );
+    if (skipped > 0) {
+      LOG.info('Use --force to overwrite existing skills.');
+    }
+  } else {
+    // No target path: generate a standalone config file in current dir
+    const outPath = path.join(process.cwd(), 'eforest-openclaw.json');
+    LOG.step(`Generating OpenClaw config: ${outPath}`);
+    LOG.step(`Skill working_directory: ${resolvedCwd}`);
+
+    writeJsonFile(outPath, { skills: updatedSkills });
+    LOG.success(`OpenClaw config generated: ${outPath}`);
+    LOG.info(
+      `Contains ${updatedSkills.length} skills with working_directory set to: ${resolvedCwd}`,
+    );
+    LOG.info('Import this file into your OpenClaw configuration.');
+  }
+
+  return true;
+}
+
+export function uninstallOpenClaw(opts: { configPath?: string }): boolean {
+  if (!opts.configPath) {
+    LOG.info(
+      'OpenClaw: no --config-path specified. Remove skills manually from your OpenClaw config.',
+    );
+    return false;
+  }
+
+  const existing = readJsonFile(opts.configPath);
+  if (!existing.skills?.length) {
+    LOG.info('No skills found in config.');
+    return false;
+  }
+
+  const before = existing.skills.length;
+  existing.skills = existing.skills.filter(
+    (s: any) => !EFOREST_SKILL_NAMES.has(s.name),
+  );
+  const removed = before - existing.skills.length;
+
+  if (removed === 0) {
+    LOG.info('No eForest skills found in config.');
+    return false;
+  }
+
+  writeJsonFile(opts.configPath, existing);
+  LOG.success(`Removed ${removed} eForest skills from OpenClaw config.`);
+  return true;
+}

package/bin/platforms/utils.ts

@@ -0,0 +1,180 @@
+// ============================================================
+// Setup Utilities — path detection, JSON merge, cross-platform
+// ============================================================
+
+import * as os from 'os';
+import * as path from 'path';
+import * as fs from 'fs';
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+export const SERVER_NAME = 'eforest-token';
+
+// ============================================================================
+// Package root detection
+// ============================================================================
+
+/** Resolve the absolute path to this package's root directory */
+export function getPackageRoot(): string {
+  // import.meta.dir points to bin/platforms/ — go up 2 levels
+  return path.resolve(import.meta.dir, '..', '..');
+}
+
+/** Resolve the absolute path to the MCP server.ts */
+export function getMcpServerPath(): string {
+  return path.join(getPackageRoot(), 'src', 'mcp', 'server.ts');
+}
+
+/** Detect bun executable path */
+export function getBunPath(): string {
+  const platform = os.platform();
+  try {
+    const cmd = platform === 'win32' ? 'where bun' : 'which bun';
+    const result = Bun.spawnSync(cmd.split(' '));
+    const stdout = result.stdout.toString().trim();
+    if (stdout) return stdout.split('\n')[0].trim();
+  } catch {}
+  return 'bun';
+}
+
+// ============================================================================
+// Platform config paths
+// ============================================================================
+
+export interface PlatformPaths {
+  claude: string;
+  cursorGlobal: string;
+}
+
+export function getPlatformPaths(): PlatformPaths {
+  const home = os.homedir();
+  const platform = os.platform();
+
+  let claude: string;
+  if (platform === 'darwin') {
+    claude = path.join(
+      home,
+      'Library',
+      'Application Support',
+      'Claude',
+      'claude_desktop_config.json',
+    );
+  } else if (platform === 'win32') {
+    claude = path.join(
+      process.env.APPDATA || path.join(home, 'AppData', 'Roaming'),
+      'Claude',
+      'claude_desktop_config.json',
+    );
+  } else {
+    claude = path.join(
+      home,
+      '.config',
+      'Claude',
+      'claude_desktop_config.json',
+    );
+  }
+
+  const cursorGlobal = path.join(home, '.cursor', 'mcp.json');
+
+  return { claude, cursorGlobal };
+}
+
+export function getCursorProjectPath(projectDir?: string): string {
+  const dir = projectDir || process.cwd();
+  return path.join(dir, '.cursor', 'mcp.json');
+}
+
+// ============================================================================
+// JSON file operations (safe merge)
+// ============================================================================
+
+/** Read a JSON file, return empty object if not exists or invalid */
+export function readJsonFile(filePath: string): any {
+  try {
+    if (!fs.existsSync(filePath)) return {};
+    const content = fs.readFileSync(filePath, 'utf-8');
+    return JSON.parse(content);
+  } catch {
+    return {};
+  }
+}
+
+/** Write JSON to file, creating parent dirs if needed */
+export function writeJsonFile(filePath: string, data: any): void {
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+}
+
+// ============================================================================
+// MCP config generation
+// ============================================================================
+
+export interface McpServerEntry {
+  command: string;
+  args: string[];
+  env: Record<string, string>;
+}
+
+export function generateMcpEntry(customPath?: string): McpServerEntry {
+  const serverPath = customPath || getMcpServerPath();
+  return {
+    command: getBunPath(),
+    args: ['run', serverPath],
+    env: {
+      AELF_PRIVATE_KEY: '<YOUR_PRIVATE_KEY>',
+      EFOREST_NETWORK: 'mainnet',
+    },
+  };
+}
+
+/**
+ * Merge our MCP server entry into an existing config.
+ * Does NOT overwrite other servers — only operates on `serverName`.
+ */
+export function mergeMcpConfig(
+  existing: any,
+  serverName: string,
+  entry: McpServerEntry,
+  force: boolean = false,
+): { config: any; action: 'created' | 'updated' | 'skipped' } {
+  const config = { ...existing };
+  if (!config.mcpServers) config.mcpServers = {};
+
+  if (config.mcpServers[serverName] && !force) {
+    return { config, action: 'skipped' };
+  }
+
+  const action = config.mcpServers[serverName] ? 'updated' : 'created';
+  config.mcpServers[serverName] = entry;
+  return { config, action };
+}
+
+/** Remove our MCP server entry from config */
+export function removeMcpEntry(
+  existing: any,
+  serverName: string,
+): { config: any; removed: boolean } {
+  const config = { ...existing };
+  if (!config.mcpServers || !config.mcpServers[serverName]) {
+    return { config, removed: false };
+  }
+  delete config.mcpServers[serverName];
+  return { config, removed: true };
+}
+
+// ============================================================================
+// Console output helpers
+// ============================================================================
+
+export const LOG = {
+  success: (msg: string) => console.log(` ✅ ${msg}`),
+  info: (msg: string) => console.log(` ℹ️  ${msg}`),
+  warn: (msg: string) => console.log(` ⚠️  ${msg}`),
+  error: (msg: string) => console.error(` ❌ ${msg}`),
+  step: (msg: string) => console.log(` → ${msg}`),
+};