@goplausible/algorand-mcp 4.2.8 → 4.3.0

package/README.md

@@ -13,7 +13,7 @@ Algorand is a carbon-negative, pure proof-of-stake Layer 1 blockchain with insta
 
 ## Features
 
-- Secure wallet management via OS keychain — private keys never exposed to agents or LLMs
+- Agent wallet — mnemonics stored in a local SQLite database, used by the MCP server to sign on the agent's behalf (mnemonics never returned in tool responses)
 - Wallet accounts with human-readable nicknames
 - Account creation, key management, and rekeying
 - Transaction building, signing, and submission (payments, assets, applications, key registration)
@@ -268,57 +268,58 @@ If no `network` is provided, tools default to **mainnet**.
 
 API responses are automatically paginated. Every tool accepts an optional `itemsPerPage` parameter (default: 10). Pass the `pageToken` from a previous response to fetch the next page.
 
-## Secure Wallet
+## Agent Wallet
 
 ### Architecture
 
-The wallet system has two layers of storage, each with a distinct security role:
+The agent wallet is a local SQLite database that the MCP server controls on the agent's behalf. The server holds the mnemonics and signs transactions for the agent — the agent never sees the mnemonics in any tool response.
 
-| Layer | What it stores | Where | Encryption |
-|---|---|---|---|
-| **OS Keychain** | Mnemonics (secret keys) | macOS Keychain / Linux libsecret / Windows Credential Manager | OS-managed, hardware-backed where available |
-| **Embedded SQLite** | Account metadata (nicknames, active-account index) | `~/.algorand-mcp/wallet.db` | Plaintext (no secrets) |
+| Layer | What it stores | Where |
+|---|---|---|
+| **SQLite (`wallet.db`)** | Account rows (`address`, `public_key`, `nickname`, `mnemonic`, `created_at`) and the active-account index | `~/.algorand-mcp/wallet.db` (mode `0600`) |
 
-**Private key material never appears in tool responses, MCP config files, environment variables, or logs.** The agent only sees addresses, public keys, and signed transaction blobs.
+**Threat model.** The wallet.db file is the secret. Anyone with read access to it can recover every mnemonic stored in the wallet. The mitigations are filesystem permissions (`0600`, owner-only), keeping the data directory off shared/world-readable volumes, and treating the data directory like any other secret store (snapshot it carefully, restrict backups, encrypt the host disk for at-rest protection). For Docker deployments, mount `~/.algorand-mcp` as a named volume and restrict access to it like you would any secret material.
 
 ### How it works
 
 ```
-  Agent (LLM)                    MCP Server                     Storage
-  ──────────                     ──────────                     ───────
-       │                              │                              │
-       │  wallet_add_account          │                              │
-       │  { nickname: "main" }        │                              │
-       │ ──────────────────────────►  │  generate keypair            │
-       │                              │  store mnemonic ──────────►  │  OS Keychain (encrypted)
-       │                              │  store metadata ──────────►  │  SQLite (nickname)
-       │  ◄─ { address, publicKey }   │                              │
-       │                              │                              │
-       │  wallet_sign_transaction     │                              │
-       │  { transaction: {...} }      │                              │
-       │ ──────────────────────────►  │  retrieve mnemonic ◄──────  │  OS Keychain
-       │                              │  sign in memory              │
-       │  ◄─ { txID, blob }          │  (key discarded)             │
-       │                              │                              │
-```
-
-1. **Account creation** (`wallet_add_account`) — Generates a keypair, stores the mnemonic in the OS keychain, and stores the nickname in SQLite. Returns **only** address and public key.
+  Agent (LLM)                    MCP Server                          Storage
+  ──────────                     ──────────                          ───────
+       │                              │                                  │
+       │  wallet_add_account          │                                  │
+       │  { nickname: "main" }        │                                  │
+       │ ──────────────────────────►  │  generate keypair                │
+       │                              │  INSERT (address, public_key,    │
+       │                              │           nickname, mnemonic) ──►│  wallet.db
+       │  ◄─ { address, publicKey,    │                                  │
+       │       nickname, index }      │                                  │
+       │                              │                                  │
+       │  wallet_sign_transaction     │                                  │
+       │  { transaction: {...} }      │                                  │
+       │ ──────────────────────────►  │  SELECT mnemonic FROM accounts ◄─│
+       │                              │   WHERE address=<active>         │
+       │                              │  sign in memory                  │
+       │  ◄─ { txID, blob }           │  (key discarded after sign)      │
+       │                              │                                  │
+```
+
+1. **Account creation** (`wallet_add_account`) — Generates a keypair and inserts a row containing the mnemonic into `accounts`. Returns address, public key, nickname, and index. The mnemonic is never returned.
 2. **Active account** — One account is active at a time. `wallet_switch_account` changes it by nickname or index. All signing and query tools operate on the active account.
-3. **Transaction signing** (`wallet_sign_transaction`) — Retrieves the key from the keychain, signs in memory, discards the key. Returns only the signed blob.
+3. **Transaction signing** (`wallet_sign_transaction`) — Reads the mnemonic from the DB, signs in memory, returns only the signed blob.
 4. **Data signing** (`wallet_sign_data`) — Signs arbitrary hex data using raw Ed25519 via the [`@noble/curves`](https://github.com/paulmillr/noble-curves) library (no Algorand SDK prefix). Useful for off-chain authentication.
 5. **Asset opt-in** (`wallet_optin_asset`) — Creates, signs, and submits an opt-in transaction for the active account in one step.
 
-### Platform keychain support
+### Backward compatibility (silent migration from OS keychain)
 
-The keychain backend is provided by [`@napi-rs/keyring`](https://github.com/nicolo-ribaudo/napi-keyring) (Rust-based, prebuilt binaries):
+Older installs of this MCP stored mnemonics in the OS keychain (`@napi-rs/keyring`). On first startup after upgrading, the server runs a one-shot, silent migration:
 
-| Platform | Backend |
-|---|---|
-| macOS | Keychain Services (the system Keychain app) |
-| Linux | libsecret (GNOME Keyring) or KWallet |
-| Windows | Windows Credential Manager |
+- For every `accounts` row whose `mnemonic` column is `NULL` or empty, it attempts to read the mnemonic from the OS keychain under the service name `algorand-mcp` keyed by the address.
+- If found, the mnemonic is copied into the DB column.
+- The original keychain entry is left in place as a redundant backup; nothing is deleted.
+
+After this completes, the DB is the sole source of truth. The keychain is consulted only as a fallback if the DB still has a `NULL` mnemonic for an address (e.g., the keychain was unavailable during startup and became available later). All new accounts created after the upgrade are written directly to the DB and never touch the keychain.
 
-All credentials are stored under the service name `algorand-mcp`. You can inspect them with your OS keychain app (e.g. Keychain Access on macOS).
+No user action is required. No prompts, no env vars, no migration logs.
 
 ## x402 HTTP Payments
 
@@ -343,7 +344,7 @@ This MCP implements the Algorand flavor of x402, where payments are USDC (or nat
        │                            │  build fee-payer + payment │                          │
        │                            │  (atomic group of 2)       │                          │
        │                            │  sign payment leg          │                          │
-       │                            │  via OS keychain           │                          │
+       │                            │  via agent wallet DB       │                          │
        │                            │  encode unsigned fee-payer │                          │
        │                            │  base64 PAYMENT-SIGNATURE  │                          │
        │                            │ ─────────────────────────► │                          │
@@ -452,7 +453,7 @@ See [Secure Wallet](#secure-wallet) for full architecture details.
 | `wallet_remove_account` | Remove an account from the wallet by nickname or index |
 | `wallet_list_accounts` | List all accounts with nicknames and addresses |
 | `wallet_switch_account` | Switch the active account by nickname or index |
-| `wallet_get_info` | Get info for the **active account this MCP server owns** (keychain-backed): address, public key, balance, opted-in counts. For arbitrary on-chain accounts use `api_algod_get_account_info`. |
+| `wallet_get_info` | Get info for the **active account this MCP server owns** (DB-backed): address, public key, balance, opted-in counts. For arbitrary on-chain accounts use `api_algod_get_account_info`. |
 | `wallet_get_assets` | Get all ASA holdings for the **active account this MCP server owns**. For arbitrary on-chain accounts use `api_algod_get_account_info` or `api_algod_get_account_asset_info`. |
 | `wallet_sign_transaction` | Sign a single transaction with the active account |
 | `wallet_sign_transaction_group` | Sign a group of transactions with the active account (auto-assigns group ID) |
@@ -687,7 +688,7 @@ algorand-mcp/
 │   │   └── wallet/              # Wallet resources
 │   ├── tools/                   # MCP Tools
 │   │   ├── commonParams.ts      # Network + pagination schema fragments
-│   │   ├── walletManager.ts     # Secure wallet (keychain + SQLite)
+│   │   ├── walletManager.ts     # Agent wallet (SQLite-backed)
 │   │   ├── accountManager.ts    # Account operations
 │   │   ├── utilityManager.ts    # Utility functions
 │   │   ├── algodManager.ts      # TEAL compile, simulate, submit
@@ -967,7 +968,7 @@ describeIf(testConfig.isCategoryEnabled('your-category'))('Your Tools (E2E)', ()
 
 - [algosdk](https://github.com/algorand/js-algorand-sdk) v3 — Algorand JavaScript SDK
 - [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk) — MCP TypeScript SDK
-- [@napi-rs/keyring](https://github.com/nicolo-ribaudo/napi-keyring) — Native OS keychain access (macOS Keychain, Linux libsecret, Windows Credential Manager)
+- [@napi-rs/keyring](https://github.com/nicolo-ribaudo/napi-keyring) — Native OS keychain access (macOS Keychain, Linux libsecret, Windows Credential Manager). Used as a backward-compatibility read fallback for accounts created by pre-DB-migration installs; new mnemonics are written only to `wallet.db`.
 - [sql.js](https://github.com/sql-js/sql.js) — Embedded SQLite (WASM) for wallet metadata persistence
 - [@noble/curves](https://github.com/paulmillr/noble-curves) — Pure JS Ed25519 for raw data signing (`wallet_sign_data`)
 - [@tinymanorg/tinyman-js-sdk](https://github.com/tinymanorg/tinyman-js-sdk) — Tinyman AMM SDK

package/dist/tools/utilityManager.js

@@ -86,7 +86,7 @@ export class UtilityManager {
                                 type: 'text',
                                 text: JSON.stringify({
                                     name: 'Algorand MCP Server',
-                                    version: '4.2.8',
+                                    version: '4.3.0',
                                     builder: 'GoPlausible',
                                     description: 'A Model Context Protocol (MCP) server providing comprehensive access to the Algorand blockchain. Supports account management, transaction building and signing, smart contract interaction, asset operations, ARC-26 URI generation, and deep integration with Algorand ecosystem services including NFDomains, Tinyman, Vestige, and Ultrade.',
                                     blockchain: 'Algorand — a carbon-negative, pure proof-of-stake Layer 1 blockchain delivering instant finality, low fees, and advanced smart contract capabilities via AVM (Algorand Virtual Machine).',

package/dist/tools/walletManager.d.ts

@@ -3,6 +3,7 @@ export interface AccountRow {
     address: string;
     public_key: string;
     nickname: string;
+    mnemonic: string | null;
     created_at: string;
 }
 export declare class WalletManager {

package/dist/tools/walletManager.js

@@ -5,7 +5,7 @@ import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
 import { withCommonParams } from './commonParams.js';
 import { getAlgodClient, extractNetwork } from '../algorand-client.js';
 import initSqlJs from 'sql.js';
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync } from 'fs';
 import { homedir } from 'os';
 import { join } from 'path';
 // ── Constants ────────────────────────────────────────────────────────────────
@@ -35,6 +35,7 @@ async function getDb() {
       address TEXT UNIQUE NOT NULL,
       public_key TEXT NOT NULL,
       nickname TEXT UNIQUE NOT NULL,
+      mnemonic TEXT,
       created_at TEXT NOT NULL
     )
   `);
@@ -44,19 +45,56 @@ async function getDb() {
       value TEXT NOT NULL
     )
   `);
+    // Idempotent schema migration: ensure `mnemonic` column exists on pre-existing DBs.
+    ensureMnemonicColumn(db);
     // Initialize active index if not set
     const row = db.exec("SELECT value FROM wallet_state WHERE key = 'active_account_index'");
     if (row.length === 0) {
         db.run("INSERT INTO wallet_state (key, value) VALUES ('active_account_index', '0')");
     }
+    // Eager keychain → DB migration for any pre-existing accounts whose mnemonic
+    // still lives in the OS keychain. Runs once per startup; idempotent (rows
+    // already populated are skipped).
+    migrateKeychainToDb(db);
     persistDb();
     return db;
 }
+function ensureMnemonicColumn(database) {
+    const info = database.exec('PRAGMA table_info(accounts)');
+    if (!info.length)
+        return;
+    const cols = info[0].values.map(r => r[1]);
+    if (!cols.includes('mnemonic')) {
+        database.run('ALTER TABLE accounts ADD COLUMN mnemonic TEXT');
+    }
+}
+function migrateKeychainToDb(database) {
+    const result = database.exec("SELECT address FROM accounts WHERE mnemonic IS NULL OR mnemonic = ''");
+    if (!result.length || !result[0].values.length)
+        return;
+    for (const row of result[0].values) {
+        const address = row[0];
+        try {
+            const mnemonic = new Entry(KEYCHAIN_SERVICE, address).getPassword();
+            if (mnemonic) {
+                database.run('UPDATE accounts SET mnemonic = ? WHERE address = ?', [mnemonic, address]);
+            }
+        }
+        catch {
+            // No keychain entry for this address (or keychain unavailable). Leave
+            // mnemonic NULL — the row remains until the user re-imports or replaces it.
+        }
+    }
+}
 function persistDb() {
     if (!db)
         return;
     const data = db.export();
-    writeFileSync(DB_PATH, Buffer.from(data));
+    writeFileSync(DB_PATH, Buffer.from(data), { mode: 0o600 });
+    try {
+        chmodSync(DB_PATH, 0o600);
+    }
+    catch { /* best-effort on platforms that don't support it */ }
 }
 // ── Tool Schemas ─────────────────────────────────────────────────────────────
 const walletToolSchemas = {
@@ -184,35 +222,59 @@ export class WalletManager {
         }
         throw new McpError(ErrorCode.InvalidParams, 'Provide either nickname or index');
     }
-    // ── Keychain Access ────────────────────────────────────────────────────────
-    static storeMnemonic(address, mnemonic) {
-        const entry = new Entry(KEYCHAIN_SERVICE, address);
-        entry.setPassword(mnemonic);
+    // ── Mnemonic Storage ───────────────────────────────────────────────────────
+    //
+    // Mnemonics live in the `accounts.mnemonic` column of wallet.db. The OS
+    // keychain (@napi-rs/keyring) is kept only as a backward-compatibility read
+    // fallback for accounts that pre-date this change; the eager migration in
+    // getDb() copies any such mnemonics into the DB at startup, and the fallback
+    // below catches the rare case where the keychain was unavailable at startup
+    // but becomes available later. New mnemonics are never written to the
+    // keychain.
+    static async storeMnemonic(address, mnemonic) {
+        const database = await getDb();
+        database.run('UPDATE accounts SET mnemonic = ? WHERE address = ?', [mnemonic, address]);
+        persistDb();
     }
-    static getMnemonic(address) {
+    static async getMnemonic(address) {
+        const database = await getDb();
+        const result = database.exec('SELECT mnemonic FROM accounts WHERE address = ?', [address]);
+        if (result.length && result[0].values.length) {
+            const m = result[0].values[0][0];
+            if (typeof m === 'string' && m.length > 0)
+                return m;
+        }
+        // Fallback: read from keychain (handles the case where eager migration
+        // missed this address because the keychain wasn't available at startup).
+        // On success, copy into the DB so future reads are DB-native.
         try {
-            const entry = new Entry(KEYCHAIN_SERVICE, address);
-            const mnemonic = entry.getPassword();
-            if (!mnemonic)
-                throw new Error('No mnemonic found');
-            return mnemonic;
+            const m = new Entry(KEYCHAIN_SERVICE, address).getPassword();
+            if (m) {
+                database.run('UPDATE accounts SET mnemonic = ? WHERE address = ?', [m, address]);
+                persistDb();
+                return m;
+            }
         }
         catch {
-            throw new McpError(ErrorCode.InvalidParams, `No keychain entry found for address: ${address}`);
+            // No keychain entry / keychain unavailable.
         }
+        throw new McpError(ErrorCode.InvalidParams, `No mnemonic found for address: ${address}`);
     }
-    static deleteMnemonic(address) {
+    static async deleteMnemonic(address) {
+        const database = await getDb();
+        database.run('UPDATE accounts SET mnemonic = NULL WHERE address = ?', [address]);
+        persistDb();
+        // Best-effort cleanup of any stale keychain entry left over from a
+        // pre-migration install. Failure here is harmless.
         try {
-            const entry = new Entry(KEYCHAIN_SERVICE, address);
-            return entry.deleteCredential();
-        }
-        catch {
-            return false;
+            new Entry(KEYCHAIN_SERVICE, address).deleteCredential();
         }
+        catch { /* ignore */ }
+        return true;
     }
     static async getActiveSecretKey() {
         const account = await WalletManager.getActiveAccount();
-        const mnemonic = WalletManager.getMnemonic(account.address);
+        const mnemonic = await WalletManager.getMnemonic(account.address);
         return algosdk.mnemonicToSecretKey(mnemonic).sk;
     }
     // ── Transaction Helpers ────────────────────────────────────────────────────
@@ -376,9 +438,7 @@ export class WalletManager {
                     if (addrExists.length > 0 && addrExists[0].values.length > 0) {
                         throw new McpError(ErrorCode.InvalidParams, `Account with address ${address} already exists in wallet`);
                     }
-                    // Store mnemonic in OS keychain
-                    WalletManager.storeMnemonic(address, mnemonic);
-                    database.run('INSERT INTO accounts (address, public_key, nickname, created_at) VALUES (?, ?, ?, ?)', [address, publicKey, args.nickname, new Date().toISOString()]);
+                    database.run('INSERT INTO accounts (address, public_key, nickname, mnemonic, created_at) VALUES (?, ?, ?, ?, ?)', [address, publicKey, args.nickname, mnemonic, new Date().toISOString()]);
                     persistDb();
                     const accounts = await WalletManager.getAllAccounts();
                     const newIndex = accounts.findIndex(a => a.address === address);
@@ -406,7 +466,7 @@ export class WalletManager {
                     }
                     const idx = await WalletManager.resolveAccountIndex(args);
                     const removed = accounts[idx];
-                    WalletManager.deleteMnemonic(removed.address);
+                    await WalletManager.deleteMnemonic(removed.address);
                     const database = await getDb();
                     database.run('DELETE FROM accounts WHERE address = ?', [removed.address]);
                     // Adjust active index
@@ -675,7 +735,7 @@ export class WalletManager {
 WalletManager.walletTools = [
     {
         name: 'wallet_add_account',
-        description: 'Create a new Algorand account and store it securely in the OS keychain with a nickname. Returns only address and public key.',
+        description: 'Create a new Algorand account, store it in the agent-wallet database with a nickname, and auto-switch to it if it is the first account. Returns address, public key, nickname, and index. The mnemonic is held internally by the MCP server and never returned to the agent.',
         inputSchema: withCommonParams(walletToolSchemas.addAccount),
     },
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goplausible/algorand-mcp",
-  "version": "4.2.8",
+  "version": "4.3.0",
   "publishConfig": {
     "access": "public"
   },