Algorand MCP Server

A comprehensive Model Context Protocol (MCP) server that gives AI agents and LLMs full access to the Algorand blockchain. Built by GoPlausible.

Algorand is a carbon-negative, pure proof-of-stake Layer 1 blockchain with instant finality, low fees, and built-in support for smart contracts (AVM), standard assets (ASAs), and atomic transactions.

What is MCP?

Model Context Protocol is an open standard that lets AI applications connect to external tools and data sources. This server exposes Algorand blockchain operations as MCP tools that any compatible AI client can use — Claude Desktop, Claude Code, Cursor, Windsurf, and others.

Features

• 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)
• Atomic transaction groups
• TEAL compilation and disassembly
• Full Algod and Indexer API access
• NFDomains (NFD) name service integration
• x402 HTTP micropayments — automatic discovery and one-call paid requests using the active wallet (USDC/ALGO)
• AP2 tooling for Algorand
• Tinyman AMM integration (pools, swaps, liquidity)
• Haystack Router DEX aggregation (best-price swaps across Tinyman, Pact, Folks)
• Alpha Arcade prediction market trading (browse markets, orderbooks, limit/market orders, positions, claims)
• ARC-26 URI and QR code generation
• Algorand knowledge base with full developer documentation taxonomy
• Per-tool-call network selection (mainnet, testnet, localnet) and pagination

Requirements

• Node.js v20 or later
• npm, pnpm, or yarn

Installation

From npm

npm install -g @goplausible/algorand-mcp

From source

git clone https://github.com/GoPlausible/algorand-mcp.git
cd algorand-mcp
npm install
npm run build

MCP Configuration

The server runs over stdio. There are three ways to invoke it — pick whichever suits your setup:

No environment variables are required for standard use. Network selection, pagination, and node URLs are all handled dynamically per tool call.

---

OpenClaw

No manual configuration needed — install the [@goplausible/openclaw-algorand-plugin](https://www.npmjs.com/package/@goplausible/openclaw-algorand-plugin) npm package and the Algorand MCP server is configured automatically:

npm install -g @goplausible/openclaw-algorand-plugin

---

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

Using npx:

{
  "mcpServers": {
    "algorand-mcp": {
      "command": "npx",
      "args": ["@goplausible/algorand-mcp"]
    }
  }
}

Using global install:

{
  "mcpServers": {
    "algorand-mcp": {
      "command": "algorand-mcp"
    }
  }
}

Using absolute path:

{
  "mcpServers": {
    "algorand-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/algorand-mcp/dist/index.js"]
    }
  }
}

---

Claude Code

Create .mcp.json in your project root (project scope) or ~/.claude.json (user scope):

{
  "mcpServers": {
    "algorand-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["@goplausible/algorand-mcp"]
    }
  }
}

Or add interactively:

claude mcp add algorand-mcp -- npx @goplausible/algorand-mcp

---

Cursor

Add via Settings > MCP Servers, or edit .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "algorand-mcp": {
      "command": "npx",
      "args": ["@goplausible/algorand-mcp"]
    }
  }
}

---

Windsurf

Add via Settings > MCP, or edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "algorand-mcp": {
      "command": "npx",
      "args": ["@goplausible/algorand-mcp"]
    }
  }
}

---

VS Code / GitHub Copilot

Edit .vscode/mcp.json in your workspace root, or open Settings > MCP Servers:

{
  "servers": {
    "algorand-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["@goplausible/algorand-mcp"]
    }
  }
}

---

Cline

Add via the MCP Servers panel in the Cline sidebar, or edit ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json (macOS):

{
  "mcpServers": {
    "algorand-mcp": {
      "command": "npx",
      "args": ["@goplausible/algorand-mcp"],
      "disabled": false
    }
  }
}

---

OpenAI Codex CLI

Create .codex/mcp.json in your project root or ~/.codex/mcp.json for global scope:

{
  "mcpServers": {
    "algorand-mcp": {
      "command": "npx",
      "args": ["@goplausible/algorand-mcp"]
    }
  }
}

---

Open Code

Edit ~/.config/opencode/config.json:

{
  "mcp": {
    "algorand-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["@goplausible/algorand-mcp"]
    }
  }
}

---

Any MCP-compatible client

The server speaks the standard MCP stdio protocol. For any client not listed above, configure it with:

• Command: npx (or algorand-mcp if globally installed, or node /path/to/dist/index.js)
• Args: ["@goplausible/algorand-mcp"] (for npx)
• Transport: stdio

Network Selection

Every tool accepts an optional network parameter: "mainnet" (default), "testnet", or "localnet". Algod and Indexer URLs are built-in for mainnet and testnet via AlgoNode.

Example tool call:

{ "name": "api_algod_get_account_info", "arguments": { "address": "ABC...", "network": "testnet" } }

If no network is provided, tools default to mainnet.

Pagination

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.

Agent Wallet

Architecture

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.

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                │
       │                              │  INSERT (address, public_key,    │
       │                              │           nickname, mnemonic) ──►│  wallet.db
       │  ◄─ { address, publicKey,    │                                  │
       │       nickname, index }      │                                  │
       │                              │                                  │
       │  wallet_sign_transaction     │                                  │
       │  { transaction: {...} }      │                                  │
       │ ──────────────────────────►  │  SELECT mnemonic FROM accounts ◄─│
       │                              │   WHERE address=         │
       │                              │  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) — 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.

Backward compatibility (silent migration from OS keychain)

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:

• 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.

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 …: ), 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:

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

x402 is an HTTP-native micropayments protocol. It uses the long-reserved 402 Payment Required status as a real handshake: when a client requests a paid resource without paying, the server returns 402 with a JSON body listing what it accepts (networks, assets, amounts, the recipient address). The client constructs a payment, attaches it as an HTTP header, retries the same request, and the server returns 200 with the resource. No API keys, no Stripe webhooks, no accounts to manage — payment is part of the request itself.

This MCP implements the Algorand flavor of x402, where payments are USDC (or native ALGO) transfers on Algorand. It exposes two tools that collapse the seven-step manual flow (probe → parse → opt-in check → build fee payer → build payment → group → sign → encode → header → retry) into a single tool call.

Protocol shape (Algorand variant)

Agent (LLM)                  algorand-mcp                   Endpoint                Facilitator
  ──────────                   ────────────                   ────────                ───────────
       │                            │                            │                          │
       │  make_http_request_       │                            │                          │
       │  with_x402 { url, ... }   │                            │                          │
       │ ────────────────────────► │  HTTP request              │                          │
       │                            │ ─────────────────────────► │                          │
       │                            │  402 PaymentRequired      │                          │
       │                            │ ◄───────────────────────── │                          │
       │                            │  pick accepts[i] for      │                          │
       │                            │  Algorand network          │                          │
       │                            │  build fee-payer + payment │                          │
       │                            │  (atomic group of 2)       │                          │
       │                            │  sign payment leg          │                          │
       │                            │  via agent wallet DB       │                          │
       │                            │  encode unsigned fee-payer │                          │
       │                            │  base64 PAYMENT-SIGNATURE  │                          │
       │                            │ ─────────────────────────► │                          │
       │                            │  HTTP request +            │  forward + settle        │
       │                            │  PAYMENT-SIGNATURE         │ ───────────────────────► │
       │                            │                            │  sign fee-payer,         │
       │                            │                            │  submit atomic group     │
       │                            │  200 + resource            │ ◄─────────────────────── │
       │                            │ ◄───────────────────────── │                          │
       │ ◄─ { result, paid: {...}}│                            │                          │
       │                            │                            │                          │

What's different from the Coinbase/EVM version

1. **Header name is PAYMENT-SIGNATURE**, not X-PAYMENT. The header body is base64-encoded JSON with x402Version, scheme, network (a CAIP-2 identifier like algorand:wGHE2Pw… for mainnet), a payload, and a verbatim copy of the accepts[] entry the client chose.

2. Payment is an atomic 2-transaction group. Index 0 is a fee-payer transaction (sender = facilitator, amount = 0, fee = 2000 µAlgo for the whole group); index 1 is the actual USDC ASA transfer (sender = wallet, fee = 0). The wallet signs only index 1 — the facilitator signs index 0 server-side at settlement. The user's wallet pays only the USDC, not even network fees.

3. Network strings are Algorand CAIP-2. This MCP recognizes mainnet (wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8=) and testnet (SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=). Endpoints that only accept Base, Solana, or other non-Algorand networks are not satisfiable here and the tool returns a clear error.

Coinbase Wallet MCP compatibility (x402 surface)

The x402 tools — make_http_request_with_x402 and x402_discover_payment_requirements — are intentionally name- and shape-compatible with the Coinbase Wallet MCP's x402 tools. The input parameters (baseURL, path, method, queryParams, body, headers, correlationId, maxAmountPerRequest, paymentRequirements, preferredNetwork, extensions) are the same. The output envelope (result, _atomicUnitsNote) is the same.

What this means in practice:

• Drop-in for Algorand x402. Agents and MCP apps written against the Coinbase Wallet MCP's x402 tools work against this server without any prompt changes — they just hit Algorand x402 endpoints instead of Base/Solana ones.
• Same agent reflexes. Models trained on tool-call traces from the Coinbase ecosystem use these tools correctly on first call. Nothing to relearn.
• Compatibility is scoped to the x402 surface only. The wallet, account, transaction-building, and DEX tools in this MCP are Algorand-specific and do not mirror Coinbase's wallet API. Only make_http_request_with_x402 and x402_discover_payment_requirements are drop-in compatible.

The one parameter that necessarily differs: preferredNetwork accepts mainnet | testnet | localnet only (Algorand networks), because the wallet only signs Algorand transactions. Coinbase's enum lists base | base-sepolia | solana | solana-devnet. Agents that pass one of those values get a clear error indicating no Algorand-payable accepts entry exists.

Example — paid weather API

# Step 1 (optional): peek at the cost
x402_discover_payment_requirements {
  "baseURL": "https://example.x402.goplausible.xyz",
  "path": "/weather",
  "method": "GET"
}
# returns: { result: { accepts: [{ scheme: "exact", network: "algorand:SGO1...",
#                                  maxAmountRequired: "100", asset: "10458941",
#                                  payTo: "AAAA...", extra: { feePayer: "BBBB..." } }] } }

# Step 2: pay and fetch in one call
make_http_request_with_x402 {
  "baseURL": "https://example.x402.goplausible.xyz",
  "path": "/weather",
  "method": "GET",
  "maxAmountPerRequest": 10000,
  "preferredNetwork": "testnet"
}
# returns: { result: , paid: { network: "testnet",
#                                                asset: "10458941",
#                                                amount: "100", payTo: "AAAA..." },
#           paymentResponse:  }

The active wallet account must be opted into the target ASA (e.g. USDC) and hold enough balance to cover maxAmountRequired. If it isn't opted in, the payment fails at settlement — opt in first with wallet_optin_asset.

Prerequisites

• An active wallet account exists (wallet_get_info to verify)
• That account is opted into the payment asset (USDC mainnet ASA 31566704, testnet ASA 10458941)
• The account has enough of the payment asset for maxAmountRequired
• The endpoint's accepts[] includes at least one entry with an Algorand network the MCP recognizes

Optional Environment Variables

Environment variables are only needed for special setups. Pass them via the env block in your MCP config.

Example: localnet (AlgoKit)

{
  "mcpServers": {
    "algorand-mcp": {
      "command": "node",
      "args": ["/path/to/algorand-mcp/dist/index.js"],
      "env": {
        "ALGORAND_LOCALNET_URL": "http://localhost:4001",
        "ALGORAND_TOKEN": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
      }
    }
  }
}

Then use "network": "localnet" in your tool calls.

Available Tools

Wallet Tools (10 tools)

See Secure Wallet for full architecture details.

x402 HTTP Payment Tools (5 tools)

See x402 HTTP Payments for the full protocol explanation.

Account Management (8 tools)

Utility Tools (13 tools)

Transaction Tools (18 tools)

Algod Tools (5 tools)

Algod API Tools (13 tools)

Live, current-state reads against an Algod node. Default choice for account/application/asset lookups — the matching indexer endpoints were intentionally disabled to keep the tool surface lean (see .notes/redundant-tools-report.md). Use the indexer family below only when you need historical or filtered queries that algod cannot serve.

Indexer API Tools (10 tools)

Historical / filtered queries against an Algorand Indexer instance. Use these for time-range scans, paginated searches, log retrieval, and creator/holder discovery — anything algod's current-state endpoints cannot answer.

Seven indexer endpoints that duplicated algod equivalents (account-by-id, account assets, account app local states, application by id, application box, application boxes, asset by id) were intentionally disabled. They live commented-out in src/tools/apiManager/indexer/ and can be re-enabled in one place if needed.

NFDomains Tools (6 tools)

Tinyman AMM Tools (9 tools)

Haystack Router Tools (3 tools)

Pera Wallet Tools (3 tools)

Pera Wallet tools are mainnet only — the Pera public API does not support testnet or localnet.

Alpha Arcade Tools (14 tools)

Trade on-chain prediction markets (YES/NO outcomes) denominated in USDC. All prices and quantities use microunits (1,000,000 = $1.00 or 1 share). Read-only tools work without a wallet; trading tools require an active wallet account.

Optional env var: ALPHA_API_KEY — needed for reward market data. ALPHA_API_BASE_URL — custom API endpoint (default: https://platform.alphaarcade.com/api).

ARC-26 URI Tools (1 tool)

Knowledge Tools (1 tool)

Resources

The server exposes MCP resources for direct data access. Wallet resources are described in the Secure Wallet section above.

Knowledge Resources

Project Structure

algorand-mcp/
├── src/                         # TypeScript source
│   ├── index.ts                 # Server entry point
│   ├── networkConfig.ts         # Hardcoded network URLs and client factories
│   ├── algorand-client.ts       # Re-exports from networkConfig
│   ├── env.ts                   # Legacy env shim (unused)
│   ├── types.ts                 # Shared types (Zod schemas)
│   ├── resources/               # MCP Resources
│   │   ├── knowledge/           # Documentation taxonomy
│   │   └── wallet/              # Wallet resources
│   ├── tools/                   # MCP Tools
│   │   ├── commonParams.ts      # Network + pagination schema fragments
│   │   ├── walletManager.ts     # Agent wallet (SQLite-backed)
│   │   ├── accountManager.ts    # Account operations
│   │   ├── utilityManager.ts    # Utility functions
│   │   ├── algodManager.ts      # TEAL compile, simulate, submit
│   │   ├── arc26Manager.ts      # ARC-26 URI generation
│   │   ├── knowledgeManager.ts  # Knowledge document access
│   │   ├── transactionManager/  # Transaction building
│   │   │   ├── accountTransactions.ts
│   │   │   ├── assetTransactions.ts
│   │   │   ├── appTransactions/
│   │   │   └── generalTransaction.ts
│   │   └── apiManager/          # API integrations
│   │       ├── algod/           # Algod API
│   │       ├── indexer/         # Indexer API
│   │       ├── nfd/             # NFDomains
│   │       ├── tinyman/         # Tinyman AMM
│   │       ├── hayrouter/       # Haystack Router DEX aggregator
│   │       ├── pera/            # Pera Wallet verified assets
│   │       └── alpha/           # Alpha Arcade prediction markets
│   └── utils/
│       └── responseProcessor.ts # Pagination and formatting
├── tests/                       # Test suite
│   ├── helpers/                 # Shared test utilities
│   │   ├── mockFactories.ts     # Mock algod/indexer/keychain factories
│   │   ├── testConfig.ts        # Category enable/disable logic
│   │   ├── e2eSetup.ts          # E2E account provisioning + invokeTool()
│   │   └── testConstants.ts     # Well-known testnet addresses and asset IDs
│   ├── unit/                    # 11 unit test suites (mocked, fast)
│   ├── e2e/                     # 11 E2E test suites (live testnet)
│   │   ├── globalSetup.ts       # Account provisioning + fund-check
│   │   └── globalTeardown.ts    # Cleanup
│   └── jest.config.e2e.js       # E2E-specific Jest config
├── dist/                        # Compiled output
├── jest.config.js               # Unit test Jest config
├── tsconfig.json                # Production TypeScript config
├── tsconfig.test.json           # Test TypeScript config
└── package.json

Response Format

All tool responses follow the MCP content format. API responses include automatic pagination when datasets exceed itemsPerPage (default 10):

{
  "data": { ... },
  "metadata": {
    "totalItems": 100,
    "itemsPerPage": 10,
    "currentPage": 1,
    "totalPages": 10,
    "hasNextPage": true,
    "pageToken": "eyJ..."
  }
}

Pass pageToken from a previous response to fetch the next page. Set itemsPerPage on any tool call to control page size.

Development

# Install dependencies
npm install

# Type-check
npm run typecheck

# Build
npm run build

# Clean build output
npm run clean

Testing

The project has a comprehensive dual-layer test suite: fast unit tests (mocked, no network) and real E2E tests (live testnet). Both use Jest 29 with ts-jest and ESM support.

Quick start

npm test                    # Unit tests (fast, no network)
npm run test:e2e            # E2E tests (testnet, generates account + fund link)
npm run test:all            # Both

Unit tests

Unit tests cover all 11 tool categories with fully mocked network dependencies. They run in parallel and finish in ~5 seconds. No environment variables or funded accounts are needed.

npm test

Coverage: 11 suites, 75+ tests covering success paths, error handling, and edge cases for every tool category.

How mocking works

Unit tests use jest.unstable_mockModule() (ESM-compatible) to intercept imports before they load. The shared tests/helpers/mockFactories.ts provides:

• **setupNetworkMocks()** — Replaces algorand-client.ts with mock algod/indexer clients that return deterministic responses without any network calls.
• **createKeychainMock()** — Replaces @napi-rs/keyring with an in-memory Map, so wallet tests work without an OS keychain.
• Fluent Proxy mocks — Algorand's Indexer SDK uses a builder pattern (.searchForAssets().limit(5).do()). The mock factory uses ES Proxy objects that return themselves for any chained method and resolve when .do() is called.

E2E tests

E2E tests call tool handlers directly against Algorand testnet (via AlgoNode public nodes). They run serially to avoid rate-limiting.

npm run test:e2e

On first run (no mnemonic provided), the test setup:

1. Generates a new Algorand account

2. Prints the address and mnemonic

3. Prints a fund link: https://lora.algokit.io/testnet/fund

4. Runs all tests (unfunded tests still pass)

To run with a funded account:

E2E_MNEMONIC="word1 word2 ... word25" npm run test:e2e

Coverage: 11 suites, 35+ tests covering real network interactions.

Category activation

E2E tests can be selectively enabled by category or individual tool via environment variables. By default all categories are enabled.

Enable specific categories

E2E_WALLET=1 npm run test:e2e            # Only wallet tests
E2E_ALGOD=1 E2E_UTILITY=1 npm run test:e2e  # Algod + utility tests

Available category flags

Important: Setting any individual flag (e.g. E2E_WALLET=1) disables all other categories unless E2E_ALL=1 is also set.

Enable specific tools

E2E_TOOLS=ping,validate_address npm run test:e2e

The E2E_TOOLS variable accepts a comma-separated list of tool names. Only tests for those specific tools will run.

Test file structure

tests/
├── helpers/
│   ├── mockFactories.ts       # Mock algod/indexer/keychain factories
│   ├── testConfig.ts          # Category enable/disable logic
│   ├── e2eSetup.ts            # E2E account provisioning + invokeTool()
│   └── testConstants.ts       # Well-known testnet addresses and asset IDs
├── unit/                      # 11 unit test files (*.test.ts)
│   ├── accountManager.test.ts
│   ├── utilityManager.test.ts
│   ├── walletManager.test.ts
│   ├── transactionManager.test.ts
│   ├── algodManager.test.ts
│   ├── apiAlgod.test.ts
│   ├── apiIndexer.test.ts
│   ├── apiNfd.test.ts
│   ├── apiTinyman.test.ts
│   ├── arc26Manager.test.ts
│   └── knowledgeManager.test.ts
├── e2e/                       # 11 E2E test files (*.e2e.test.ts)
│   ├── globalSetup.ts         # Account provisioning + fund-check
│   ├── globalTeardown.ts      # Cleanup
│   ├── account.e2e.test.ts
│   ├── utility.e2e.test.ts
│   ├── wallet.e2e.test.ts
│   ├── transaction.e2e.test.ts
│   ├── algod.e2e.test.ts
│   ├── algodApi.e2e.test.ts
│   ├── indexerApi.e2e.test.ts
│   ├── nfd.e2e.test.ts
│   ├── tinyman.e2e.test.ts
│   ├── arc26.e2e.test.ts
│   └── knowledge.e2e.test.ts
└── jest.config.e2e.js         # E2E-specific Jest config

Jest configuration

Writing new tests

Unit test template:

import { jest } from '@jest/globals';
import { setupNetworkMocks } from '../helpers/mockFactories.js';

jest.unstable_mockModule('../../src/algorand-client.js', () => setupNetworkMocks());

const { YourManager } = await import('../../src/tools/yourManager.js');

describe('YourManager', () => {
  it('does something', async () => {
    const result = await YourManager.handleTool('tool_name', { arg: 'value' });
    const data = JSON.parse(result.content[0].text);
    expect(data.field).toBeDefined();
  });
});

E2E test template:

import { describeIf, testConfig } from '../helpers/testConfig.js';
import { invokeTool, parseToolResponse } from '../helpers/e2eSetup.js';

describeIf(testConfig.isCategoryEnabled('your-category'))('Your Tools (E2E)', () => {
  it('does something on testnet', async () => {
    const data = parseToolResponse(
      await invokeTool('tool_name', { arg: 'value', network: 'testnet' }),
    );
    expect(data.field).toBeDefined();
  });
});

Dependencies

• algosdk v3 — Algorand JavaScript SDK
• @modelcontextprotocol/sdk — MCP TypeScript SDK
• @napi-rs/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 — Embedded SQLite (WASM) for wallet metadata persistence
• @noble/curves — Pure JS Ed25519 for raw data signing (wallet_sign_data)
• @tinymanorg/tinyman-js-sdk — Tinyman AMM SDK
• @alpha-arcade/sdk — Alpha Arcade prediction market SDK
• zod — Runtime type validation
• qrcode — QR code generation for ARC-26

License

MIT