@goplausible/algorand-mcp 4.3.0 → 4.3.1

package/README.md

@@ -319,7 +319,28 @@ Older installs of this MCP stored mnemonics in the OS keychain (`@napi-rs/keyrin
 
 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.
 
-No user action is required. No prompts, no env vars, no migration logs.
+**Orphan handling (archive, not delete).** If an `accounts` row exists but its mnemonic isn't in the keychain *and* isn't already in the DB (e.g., the user copied `wallet.db` to a new machine without also moving the keychain entries, restored from a partial backup, or installed in Docker where the keychain never existed), that row is unusable for signing. Rather than delete it, the server marks the row as **archived** (`UPDATE accounts SET archived = 1 WHERE mnemonic IS NULL OR mnemonic = ''`). Archived rows:
+
+- are **hidden from the default** `wallet_list_accounts` response
+- **never become the active account** (the active-account index is clamped to the end of the remaining active list, or reset to `0` if no active accounts remain)
+- keep their **original nickname** (a partial unique index `idx_active_nickname` enforces nickname uniqueness only among active rows, so a new `wallet_add_account` can reuse the same nickname for a fresh keypair)
+- are **surfaced via `wallet_list_accounts { archived: true }`** for forensics or future recovery
+
+Archiving is silent at the MCP tool layer. The only diagnostic is a one-line stderr log per failed keychain read (`[algorand-mcp] keychain read failed for <addr>…: <msg>`), so if a user investigates a false archive they can see whether the keychain threw "no entry" vs "access denied" vs "no DBus" etc.
+
+No user action is required for any of this. No prompts, no env vars, no migration tools.
+
+### Schema versions
+
+The DB schema evolves additively via an idempotent migration that runs at startup:
+
+| Version | Change |
+|---|---|
+| v1 | initial — `accounts` columns: `id`, `address`, `public_key`, `nickname` (UNIQUE), `created_at` |
+| v2 | added `mnemonic TEXT` column |
+| v3 | added `archived INTEGER NOT NULL DEFAULT 0` column; dropped the column-level UNIQUE on `nickname` and replaced it with `CREATE UNIQUE INDEX idx_active_nickname ON accounts(nickname) WHERE archived = 0` so archived rows can keep their original nicknames without blocking reuse |
+
+The v2→v3 step recreates the `accounts` table (SQLite cannot drop a column-level UNIQUE constraint via ALTER) and copies data forward with `archived = 0`. Existing wallets keep working unchanged.
 
 ## x402 HTTP Payments
 
@@ -451,7 +472,7 @@ See [Secure Wallet](#secure-wallet) for full architecture details.
 |---|---|
 | `wallet_add_account` | Create a new Algorand account with nickname (returns address + public key only) |
 | `wallet_remove_account` | Remove an account from the wallet by nickname or index |
-| `wallet_list_accounts` | List all accounts with nicknames and addresses |
+| `wallet_list_accounts` | List active accounts with nicknames and addresses. Pass `{ archived: true }` to list archived accounts instead (rows whose mnemonic couldn't be recovered from the OS keychain at startup — kept in the DB for forensics, not signable). |
 | `wallet_switch_account` | Switch the active account by nickname or index |
 | `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`. |

package/dist/tools/utilityManager.js

@@ -86,7 +86,7 @@ export class UtilityManager {
                                 type: 'text',
                                 text: JSON.stringify({
                                     name: 'Algorand MCP Server',
-                                    version: '4.3.0',
+                                    version: '4.3.1',
                                     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

@@ -4,6 +4,7 @@ export interface AccountRow {
     public_key: string;
     nickname: string;
     mnemonic: string | null;
+    archived: number;
     created_at: string;
 }
 export declare class WalletManager {
@@ -12,6 +13,14 @@ export declare class WalletManager {
         description: string;
         inputSchema: any;
     }[];
+    /**
+     * Returns accounts from wallet.db.
+     *   - includeArchived = false (default): only active rows (archived = 0).
+     *     Used by every signing/lookup path and by wallet_list_accounts in its
+     *     default mode.
+     *   - includeArchived = true: only archived rows (archived = 1). Used by
+     *     wallet_list_accounts { archived: true } for forensics.
+     */
     private static getAllAccounts;
     private static getActiveIndex;
     private static setActiveIndex;

package/dist/tools/walletManager.js

@@ -28,14 +28,16 @@ async function getDb() {
     else {
         db = new SQL.Database();
     }
-    // Create tables if they don't exist
+    // Create tables if they don't exist. For fresh installs the schema is
+    // already at the latest shape; for older DBs ensureSchema() below upgrades.
     db.run(`
     CREATE TABLE IF NOT EXISTS accounts (
       id INTEGER PRIMARY KEY AUTOINCREMENT,
       address TEXT UNIQUE NOT NULL,
       public_key TEXT NOT NULL,
-      nickname TEXT UNIQUE NOT NULL,
+      nickname TEXT NOT NULL,
       mnemonic TEXT,
+      archived INTEGER NOT NULL DEFAULT 0,
       created_at TEXT NOT NULL
     )
   `);
@@ -45,8 +47,12 @@ async function getDb() {
       value TEXT NOT NULL
     )
   `);
-    // Idempotent schema migration: ensure `mnemonic` column exists on pre-existing DBs.
-    ensureMnemonicColumn(db);
+    // Idempotent schema migration: add mnemonic + archived columns on
+    // pre-existing DBs; replace the legacy column-level UNIQUE on nickname with
+    // a partial unique index that only enforces uniqueness among non-archived
+    // accounts (so an archived account can keep its original nickname while a
+    // new active account with the same nickname can be created).
+    ensureSchema(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) {
@@ -56,36 +62,113 @@ async function getDb() {
     // still lives in the OS keychain. Runs once per startup; idempotent (rows
     // already populated are skipped).
     migrateKeychainToDb(db);
+    // Any row that's still NULL after the migration attempt is an orphan
+    // (e.g. wallet.db was restored without its keychain counterpart, or this
+    // is a Docker install where the keychain never existed). Archive them so
+    // the agent doesn't see unusable accounts in the default wallet_list, but
+    // the rows stay in the DB and can be surfaced via wallet_list_accounts
+    // { archived: true } for forensics or future recovery.
+    archiveOrphanedAccounts(db);
     persistDb();
     return db;
 }
-function ensureMnemonicColumn(database) {
+/**
+ * Brings older DBs forward to the latest schema:
+ *   v1 → no mnemonic column, nickname is a column-level UNIQUE
+ *   v2 → mnemonic column added, nickname still column-level UNIQUE
+ *   v3 → archived column added, nickname UNIQUE replaced with a partial unique
+ *        index (idx_active_nickname) that only enforces uniqueness among rows
+ *        WHERE archived = 0
+ *
+ * SQLite cannot drop a column-level UNIQUE constraint via ALTER, so when the
+ * upgrade to v3 is needed we recreate the table. Idempotent: subsequent
+ * startups detect the archived column already exists and skip.
+ */
+function ensureSchema(database) {
     const info = database.exec('PRAGMA table_info(accounts)');
     if (!info.length)
         return;
     const cols = info[0].values.map(r => r[1]);
+    // v1 → v2: add mnemonic column
     if (!cols.includes('mnemonic')) {
         database.run('ALTER TABLE accounts ADD COLUMN mnemonic TEXT');
+        cols.push('mnemonic');
     }
+    // v2 → v3: add archived column + drop nickname UNIQUE via table recreation
+    if (!cols.includes('archived')) {
+        database.run(`
+      CREATE TABLE accounts_new (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        address TEXT UNIQUE NOT NULL,
+        public_key TEXT NOT NULL,
+        nickname TEXT NOT NULL,
+        mnemonic TEXT,
+        archived INTEGER NOT NULL DEFAULT 0,
+        created_at TEXT NOT NULL
+      )
+    `);
+        database.run(`
+      INSERT INTO accounts_new (id, address, public_key, nickname, mnemonic, archived, created_at)
+      SELECT id, address, public_key, nickname, mnemonic, 0, created_at FROM accounts
+    `);
+        database.run('DROP TABLE accounts');
+        database.run('ALTER TABLE accounts_new RENAME TO accounts');
+    }
+    // Partial unique index — applies to fresh and migrated DBs. Idempotent.
+    database.run('CREATE UNIQUE INDEX IF NOT EXISTS idx_active_nickname ON accounts(nickname) WHERE archived = 0');
 }
 function migrateKeychainToDb(database) {
-    const result = database.exec("SELECT address FROM accounts WHERE mnemonic IS NULL OR mnemonic = ''");
+    const result = database.exec("SELECT address FROM accounts WHERE (mnemonic IS NULL OR mnemonic = '') AND archived = 0");
     if (!result.length || !result[0].values.length)
         return;
     for (const row of result[0].values) {
         const address = row[0];
+        let mnemonic = null;
         try {
-            const mnemonic = new Entry(KEYCHAIN_SERVICE, address).getPassword();
-            if (mnemonic) {
-                database.run('UPDATE accounts SET mnemonic = ? WHERE address = ?', [mnemonic, address]);
-            }
+            mnemonic = new Entry(KEYCHAIN_SERVICE, address).getPassword();
         }
-        catch {
-            // No keychain entry for this address (or keychain unavailable). Leave
-            // mnemonic NULL — the row remains until the user re-imports or replaces it.
+        catch (err) {
+            // Keychain unavailable, entry not found, or permission denied. Log to
+            // stderr so a user investigating a false archive can see what happened.
+            // The MCP tool surface remains silent.
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(`[algorand-mcp] keychain read failed for ${address.slice(0, 10)}…: ${msg}`);
+        }
+        if (mnemonic && mnemonic.length > 0) {
+            database.run('UPDATE accounts SET mnemonic = ? WHERE address = ?', [mnemonic, address]);
         }
     }
 }
+/**
+ * Marks any `accounts` rows that still have no mnemonic after the keychain
+ * migration step as archived (archived = 1). Archived rows:
+ *   - are hidden from the default wallet_list_accounts response
+ *   - never become the active account
+ *   - keep their original nickname (the partial unique index on
+ *     idx_active_nickname allows a new active account to reuse the nickname)
+ *   - are surfaced via wallet_list_accounts { archived: true } for forensics
+ *
+ * Silent at the MCP tool layer. The active-account index is clamped to the
+ * end of the remaining active list (or 0 if no active accounts remain).
+ */
+function archiveOrphanedAccounts(database) {
+    const orphans = database.exec("SELECT id FROM accounts WHERE (mnemonic IS NULL OR mnemonic = '') AND archived = 0");
+    if (!orphans.length || !orphans[0].values.length)
+        return;
+    database.run("UPDATE accounts SET archived = 1 WHERE (mnemonic IS NULL OR mnemonic = '') AND archived = 0");
+    // Clamp active_account_index against the (now reduced) active list.
+    const countResult = database.exec('SELECT COUNT(*) FROM accounts WHERE archived = 0');
+    const remaining = countResult.length && countResult[0].values.length
+        ? Number(countResult[0].values[0][0])
+        : 0;
+    const activeResult = database.exec("SELECT value FROM wallet_state WHERE key = 'active_account_index'");
+    const activeIdx = activeResult.length && activeResult[0].values.length
+        ? parseInt(activeResult[0].values[0][0], 10) || 0
+        : 0;
+    if (remaining === 0 || activeIdx >= remaining) {
+        database.run("UPDATE wallet_state SET value = '0' WHERE key = 'active_account_index'");
+    }
+}
 function persistDb() {
     if (!db)
         return;
@@ -115,7 +198,12 @@ const walletToolSchemas = {
     },
     listAccounts: {
         type: 'object',
-        properties: {},
+        properties: {
+            archived: {
+                type: 'boolean',
+                description: 'If true, return archived accounts (rows whose mnemonic could not be recovered from the OS keychain at startup, kept in the DB for forensics). If false or omitted, returns only active (signable) accounts.'
+            }
+        },
         required: []
     },
     switchAccount: {
@@ -172,9 +260,20 @@ const walletToolSchemas = {
 // ── Tool Definitions ─────────────────────────────────────────────────────────
 export class WalletManager {
     // ── Database Helpers ───────────────────────────────────────────────────────
-    static async getAllAccounts() {
+    /**
+     * Returns accounts from wallet.db.
+     *   - includeArchived = false (default): only active rows (archived = 0).
+     *     Used by every signing/lookup path and by wallet_list_accounts in its
+     *     default mode.
+     *   - includeArchived = true: only archived rows (archived = 1). Used by
+     *     wallet_list_accounts { archived: true } for forensics.
+     */
+    static async getAllAccounts(includeArchived = false) {
         const database = await getDb();
-        const result = database.exec('SELECT * FROM accounts ORDER BY id');
+        const sql = includeArchived
+            ? 'SELECT * FROM accounts WHERE archived = 1 ORDER BY id'
+            : 'SELECT * FROM accounts WHERE archived = 0 ORDER BY id';
+        const result = database.exec(sql);
         if (result.length === 0)
             return [];
         const cols = result[0].columns;
@@ -422,7 +521,10 @@ export class WalletManager {
                     }
                     const database = await getDb();
                     // Check nickname uniqueness
-                    const existing = database.exec('SELECT id FROM accounts WHERE nickname = ?', [args.nickname]);
+                    // Nickname uniqueness is enforced only among ACTIVE accounts (the
+                    // partial unique index idx_active_nickname). Archived rows with the
+                    // same nickname don't conflict — the new account takes over the name.
+                    const existing = database.exec('SELECT id FROM accounts WHERE nickname = ? AND archived = 0', [args.nickname]);
                     if (existing.length > 0 && existing[0].values.length > 0) {
                         throw new McpError(ErrorCode.InvalidParams, `Account with nickname "${args.nickname}" already exists`);
                     }
@@ -492,17 +594,20 @@ export class WalletManager {
                 }
                 // ── wallet_list_accounts ─────────────────────────────────────────
                 case 'wallet_list_accounts': {
-                    const accounts = await WalletManager.getAllAccounts();
-                    const activeIdx = await WalletManager.getActiveIndex();
+                    const showArchived = args.archived === true;
+                    const accounts = await WalletManager.getAllAccounts(showArchived);
+                    const activeIdx = showArchived ? -1 : await WalletManager.getActiveIndex();
                     return {
                         content: [{
                                 type: 'text',
                                 text: JSON.stringify({
+                                    archived: showArchived,
                                     activeIndex: activeIdx,
                                     count: accounts.length,
                                     accounts: accounts.map((a, i) => ({
                                         index: i,
-                                        active: i === activeIdx,
+                                        active: !showArchived && i === activeIdx,
+                                        archived: showArchived,
                                         nickname: a.nickname,
                                         address: a.address,
                                         publicKey: a.public_key,
@@ -745,7 +850,7 @@ WalletManager.walletTools = [
     },
     {
         name: 'wallet_list_accounts',
-        description: 'List all wallet accounts with their nicknames and addresses.',
+        description: 'List wallet accounts with their nicknames and addresses. By default returns only ACTIVE accounts (signable). Pass { archived: true } to return ARCHIVED accounts instead — these are accounts whose mnemonic could not be recovered from the OS keychain at startup (e.g., wallet.db moved to a new machine without keychain, or fresh Docker install over an existing DB). Archived rows stay in the DB for forensics but cannot sign; their nicknames are freed for reuse by new active accounts.',
         inputSchema: withCommonParams(walletToolSchemas.listAccounts),
     },
     {

package/package.json

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