Algorand

Um servidor MCP abrangente para interações com ferramentas (40+) e acessibilidade a recursos (60+), além de muitos prompts úteis para interagir com a Blockchain Algorand.

Documentação

Servidor MCP Algorand

npm version npm downloads License: MIT

Um servidor abrangente de Model Context Protocol (MCP) que dá a agentes de IA e LLMs acesso completo à blockchain Algorand. Construído pela GoPlausible.

Algorand é uma blockchain Layer 1 de proof-of-stake puro, carbono-negativa, com finalidade instantânea, taxas baixas e suporte integrado para contratos inteligentes (AVM), ativos padrão (ASAs) e transações atômicas.

O que é MCP?

Model Context Protocol é um padrão aberto que permite que aplicações de IA se conectem a ferramentas externas e fontes de dados. Este servidor expõe operações da blockchain Algorand como ferramentas MCP que qualquer cliente de IA compatível pode usar — Claude Desktop, Claude Code, Cursor, Windsurf e outros.

Recursos

  • Carteira do agente — mnemônicos armazenados em um banco de dados SQLite local, usados pelo servidor MCP para assinar em nome do agente (mnemônicos nunca são retornados nas respostas das ferramentas)
  • Contas de carteira com apelidos legíveis por humanos
  • Criação de contas, gerenciamento de chaves e rekeying
  • Construção, assinatura e envio de transações (pagamentos, ativos, aplicações, registro de chaves)
  • Grupos de transações atômicas
  • Compilação e desmontagem de TEAL
  • Acesso completo às APIs Algod e Indexer
  • Integração com o serviço de nomes NFDomains (NFD)
  • Micropagamentos HTTP x402 — descoberta automática e requisições pagas em uma única chamada usando a carteira ativa (USDC/ALGO)
  • Ferramentas AP2 para Algorand
  • Integração com Tinyman AMM (pools, swaps, liquidez)
  • Agregação DEX Haystack Router (melhores preços de swaps entre Tinyman, Pact, Folks)
  • Negociação no mercado de previsão Alpha Arcade (navegar mercados, orderbooks, ordens limitadas/a mercado, posições, reivindicações)
  • Geração de URI e QR code ARC-26
  • Base de conhecimento Algorand com taxonomia completa de documentação para desenvolvedores
  • Seleção de rede por chamada de ferramenta (mainnet, testnet, localnet) e paginação

Requisitos

  • Node.js v20 ou posterior
  • npm, pnpm ou yarn

Instalação

Via npm

npm install -g @goplausible/algorand-mcp

A partir do código-fonte

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

Configuração do MCP

O servidor roda sobre stdio. Há três formas de invocá-lo — escolha a que melhor se adequa à sua configuração:

MétodoComandoQuando usar
npx (recomendado)npx @goplausible/algorand-mcpSem necessidade de instalação, sempre a versão mais recente
Instalação globalalgorand-mcpApós npm install -g @goplausible/algorand-mcp
Caminho absolutonode /path/to/dist/index.jsCompilado a partir do código-fonte ou clone local

Nenhuma variável de ambiente é necessária para uso padrão. Seleção de rede, paginação e URLs de nós são tratadas dinamicamente por chamada de ferramenta.


OpenClaw

Nenhuma configuração manual necessária — instale o pacote npm @goplausible/openclaw-algorand-plugin e o servidor MCP Algorand é configurado automaticamente:

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

Claude Desktop

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

Usando npx:

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

Usando instalação global:

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

Usando caminho absoluto:

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

Claude Code

Crie .mcp.json na raiz do seu projeto (escopo do projeto) ou ~/.claude.json (escopo do usuário):

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

Ou adicione interativamente:

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

Cursor

Adicione via Settings > MCP Servers, ou edite .cursor/mcp.json na raiz do seu projeto:

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

Windsurf

Adicione via Settings > MCP, ou edite ~/.codeium/windsurf/mcp_config.json:

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

VS Code / GitHub Copilot

Edite .vscode/mcp.json na raiz do seu workspace, ou abra Settings > MCP Servers:

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

Cline

Adicione via painel MCP Servers na barra lateral do Cline, ou edite ~/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

Crie .codex/mcp.json na raiz do seu projeto ou ~/.codex/mcp.json para escopo global:

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

Open Code

Edite ~/.config/opencode/config.json:

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

Qualquer cliente compatível com MCP

O servidor fala o protocolo padrão MCP stdio. Para qualquer cliente não listado acima, configure-o com:

  • Comando: npx (ou algorand-mcp se instalado globalmente, ou node /path/to/dist/index.js)
  • Argumentos: ["@goplausible/algorand-mcp"] (para npx)
  • Transporte: stdio

Seleção de Rede

Toda ferramenta aceita um parâmetro opcional network: "mainnet" (padrão), "testnet" ou "localnet". URLs do Algod e Indexer são integradas para mainnet e testnet via AlgoNode.

Exemplo de chamada de ferramenta:

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

Se nenhum network for fornecido, as ferramentas usam mainnet por padrão.

Paginação

Respostas da API são paginadas automaticamente. Toda ferramenta aceita um parâmetro opcional itemsPerPage (padrão: 10). Passe o pageToken de uma resposta anterior para buscar a próxima página.

Carteira do Agente

Arquitetura

A carteira do agente é um banco de dados SQLite local que o servidor MCP controla em nome do agente. O servidor guarda os mnemônicos e assina transações para o agente — o agente nunca vê os mnemônicos em nenhuma resposta de ferramenta.

CamadaO que armazenaOnde
SQLite (wallet.db)Linhas de contas (address, public_key, nickname, mnemonic, created_at) e o índice da conta ativa~/.algorand-mcp/wallet.db (modo 0600)

Modelo de ameaça. O arquivo wallet.db é o segredo. Qualquer pessoa com acesso de leitura a ele pode recuperar todos os mnemônicos armazenados na carteira. As mitigações são permissões de sistema de arquivos (0600, somente proprietário), manter o diretório de dados fora de volumes compartilhados/legíveis por todos, e tratar o diretório de dados como qualquer outro cofre de segredos (faça snapshots com cuidado, restrinja backups, criptografe o disco do host para proteção em repouso). Para implantações Docker, monte ~/.algorand-mcp como um volume nomeado e restrinja o acesso a ele como faria com qualquer material secreto.

Como funciona

  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. Criação de conta (wallet_add_account) — Gera um par de chaves e insere uma linha contendo o mnemônico em accounts. Retorna endereço, chave pública, apelido e índice. O mnemônico nunca é retornado.
  2. Conta ativa — Uma conta está ativa por vez. wallet_switch_account a altera por apelido ou índice. Todas as ferramentas de assinatura e consulta operam na conta ativa.
  3. Assinatura de transações (wallet_sign_transaction) — Lê o mnemônico do banco de dados, assina em memória, retorna apenas o blob assinado.
  4. Assinatura de dados (wallet_sign_data) — Assina dados hex arbitrários usando Ed25519 puro via biblioteca @noble/curves (sem prefixo do SDK Algorand). Útil para autenticação fora da cadeia.
  5. Opt-in de ativos (wallet_optin_asset) — Cria, assina e envia uma transação de opt-in para a conta ativa em uma única etapa.

Compatibilidade reversa (migração silenciosa do keychain do SO)

Instalações mais antigas deste MCP armazenavam mnemônicos no keychain do SO (@napi-rs/keyring). Na primeira inicialização após a atualização, o servidor executa uma migração silenciosa de uma única execução:

  • Para cada linha accounts cuja coluna mnemonic seja NULL ou vazia, ele tenta ler o mnemônico do keychain do SO sob o nome de serviço algorand-mcp chaveado pelo endereço.
  • Se encontrado, o mnemônico é copiado para a coluna do banco de dados.
  • A entrada original do keychain é mantida como backup redundante; nada é excluído.

Após isso, o banco de dados é a única fonte de verdade. O keychain é consultado apenas como fallback se o banco ainda tiver um mnemônico NULL para um endereço (por exemplo, se o keychain estava indisponível durante a inicialização e ficou disponível depois). Todas as novas contas criadas após a atualização são gravadas diretamente no banco e nunca tocam o keychain.

Tratamento de órfãos (arquivar, não excluir). Se uma linha accounts existir, mas seu mnemônico não estiver no keychain e não estiver no banco (por exemplo, o usuário copiou wallet.db para uma nova máquina sem mover também as entradas do keychain, restaurou de um backup parcial, ou instalou em Docker onde o keychain nunca existiu), essa linha não pode ser usada para assinatura. Em vez de excluí-la, o servidor marca a linha como arquivada (UPDATE accounts SET archived = 1 WHERE mnemonic IS NULL OR mnemonic = ''). Linhas arquivadas:

  • são ocultadas da resposta padrão wallet_list_accounts
  • nunca se tornam a conta ativa (o índice da conta ativa é limitado ao final da lista ativa restante, ou redefinido para 0 se nenhuma conta ativa restar)
  • mantêm seu apelido original (um índice único parcial idx_active_nickname garante unicidade de apelido apenas entre linhas ativas, então um novo wallet_add_account pode reutilizar o mesmo apelido para um novo par de chaves)
  • são expostas via wallet_list_accounts { archived: true } para análise forense ou recuperação futura

O arquivamento é silencioso na camada de ferramentas MCP. O único diagnóstico é um log de uma linha no stderr por leitura de keychain com falha ([algorand-mcp] keychain read failed for <addr>…: <msg>), para que, se um usuário investigar um arquivamento falso, possa ver se o keychain retornou "entrada não encontrada" vs "acesso negado" vs "sem DBus" etc.

Nenhuma ação do usuário é necessária para nada disso. Sem prompts, sem variáveis de ambiente, sem ferramentas de migração.

Versões de esquema

O esquema do banco evolui aditivamente via uma migração idempotente que roda na inicialização:

VersãoMudança
v1inicial — colunas accounts: id, address, public_key, nickname (UNIQUE), created_at
v2adicionada coluna mnemonic TEXT
v3adicionada coluna archived INTEGER NOT NULL DEFAULT 0; removida a restrição UNIQUE de nível de coluna em nickname e substituída por CREATE UNIQUE INDEX idx_active_nickname ON accounts(nickname) WHERE archived = 0 para que linhas arquivadas possam manter seus apelidos originais sem bloquear reutilização

A etapa v2→v3 recria a tabela accounts (SQLite não pode remover uma restrição UNIQUE de nível de coluna via ALTER) e copia os dados adiante com archived = 0. Carteiras existentes continuam funcionando sem alterações.

Pagamentos HTTP x402

x402 é um protocolo de micropagamentos nativo de HTTP. Ele usa o status de longa reserva 402 Payment Required como um handshake real: quando um cliente solicita um recurso pago sem pagar, o servidor retorna 402 com um corpo JSON listando o que aceita (redes, ativos, valores, endereço do destinatário). O cliente constrói um pagamento, o anexa como cabeçalho HTTP, tenta a mesma requisição novamente, e o servidor retorna 200 com o recurso. Sem chaves de API, sem webhooks Stripe, sem contas para gerenciar — o pagamento faz parte da própria requisição.

Este MCP implementa a variante Algorand do x402, onde pagamentos são transferências USDC (ou ALGO nativo) na Algorand. Ele expõe duas ferramentas que condensam o fluxo manual de sete etapas (sondar → analisar → verificar opt-in → construir pagador de taxas → construir pagamento → agrupar → assinar → codificar → cabeçalho → tentar novamente) em uma única chamada de ferramenta.

Formato do protocolo (variante Algorand)

  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: {...}}│                            │                          │
       │                            │                            │                          │

O que é diferente da versão Coinbase/EVM

  1. O nome do cabeçalho é PAYMENT-SIGNATURE, não X-PAYMENT. O corpo do cabeçalho é JSON codificado em base64 com x402Version, scheme, network (um identificador CAIP-2 como algorand:wGHE2Pw… para mainnet), um payload e uma cópia verbatim da entrada accepts[] que o cliente escolheu.
  2. O pagamento é um grupo atômico de 2 transações. O índice 0 é uma transação de pagador de taxas (remetente = facilitador, valor = 0, taxa = 2000 µAlgo para o grupo inteiro); o índice 1 é a transferência real do ASA USDC (remetente = carteira, taxa = 0). A carteira assina apenas o índice 1 — o facilitador assina o índice 0 no servidor na liquidação. A carteira do usuário paga apenas o USDC, nem mesmo taxas de rede.
  3. As strings de rede são CAIP-2 da Algorand. Este MCP reconhece mainnet (wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8=) e testnet (SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=). Endpoints que só aceitam Base, Solana ou outras redes não-Algorand não podem ser atendidos aqui e a ferramenta retorna um erro claro.

Compatibilidade com Coinbase Wallet MCP (superfície x402)

As ferramentas x402 — make_http_request_with_x402 e x402_discover_payment_requirements — são intencionalmente compatíveis em nome e formato com as ferramentas x402 do Coinbase Wallet MCP. Os parâmetros de entrada (baseURL, path, method, queryParams, body, headers, correlationId, maxAmountPerRequest, paymentRequirements, preferredNetwork, extensions) são os mesmos. O envelope de saída (result, _atomicUnitsNote) é o mesmo.

O que isso significa na prática:

  • Substituição direta para x402 Algorand. Agentes e aplicativos MCP escritos para as ferramentas x402 do Coinbase Wallet MCP funcionam com este servidor sem nenhuma alteração de prompt — eles apenas acessam endpoints x402 Algorand em vez dos da Base/Solana.
  • Mesmos reflexos de agente. Modelos treinados em rastros de chamadas de ferramentas do ecossistema Coinbase usam essas ferramentas corretamente na primeira chamada. Nada para reaprender.
  • A compatibilidade é limitada apenas à superfície x402. As ferramentas de carteira, conta, construção de transações e DEX neste MCP são específicas do Algorand e não espelham a API de carteira do Coinbase. Apenas make_http_request_with_x402 e x402_discover_payment_requirements são compatíveis como substituição direta.

O único parâmetro que necessariamente difere: preferredNetwork aceita apenas mainnet | testnet | localnet (redes Algorand), porque a carteira só assina transações Algorand. O enum do Coinbase lista base | base-sepolia | solana | solana-devnet. Agentes que passam um desses valores recebem um erro claro indicando que não existe entrada de aceite pagável em Algorand.

Exemplo — API de clima paga

# 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: <weather payload>, paid: { network: "testnet",
#                                                asset: "10458941",
#                                                amount: "100", payTo: "AAAA..." },
#           paymentResponse: <decoded X-PAYMENT-RESPONSE> }

A conta ativa da carteira deve estar optada no ASA alvo (ex.: USDC) e ter saldo suficiente para cobrir maxAmountRequired. Se não estiver optada, o pagamento falha na liquidação — faça o opt-in primeiro com wallet_optin_asset.

Pré-requisitos

  • Existe uma conta ativa na carteira (wallet_get_info para verificar)
  • Essa conta está optada no ativo de pagamento (USDC mainnet ASA 31566704, testnet ASA 10458941)
  • A conta tem saldo suficiente do ativo de pagamento para maxAmountRequired
  • O accepts[] do endpoint inclui pelo menos uma entrada com uma rede Algorand que o MCP reconhece

Variáveis de Ambiente Opcionais

Variáveis de ambiente são necessárias apenas para configurações especiais. Passe-as via bloco env na sua configuração MCP.

VariávelDescriçãoPadrãoQuando necessário
ALGORAND_TOKENToken de API para nós privados/autenticados""Conectar a um nó Algod/Indexer privado
ALGORAND_LOCALNET_URLURL base da localnet""Usando network: "localnet" (ex.: http://localhost:4001)
ALPHA_API_KEYChave de API Alpha Arcade""Acessando dados de mercado de recompensas

Exemplo: 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"
      }
    }
  }
}

Depois use "network": "localnet" nas suas chamadas de ferramenta.

Ferramentas Disponíveis

Ferramentas de Carteira (10 ferramentas)

Veja Carteira Segura para detalhes completos da arquitetura.

FerramentaDescrição
wallet_add_accountCriar uma nova conta Algorand com apelido (retorna apenas endereço + chave pública)
wallet_remove_accountRemover uma conta da carteira por apelido ou índice
wallet_list_accountsListar contas ativas com apelidos e endereços. Passe { archived: true } para listar contas arquivadas (linhas cuja mnemônica não pôde ser recuperada do chaveiro do SO na inicialização — mantidas no banco para perícia, não assináveis).
wallet_switch_accountAlternar a conta ativa por apelido ou índice
wallet_get_infoObter informações da conta ativa que este servidor MCP possui (com suporte a banco de dados): endereço, chave pública, saldo, contagens de opt-in. Para contas on-chain arbitrárias use api_algod_get_account_info.
wallet_get_assetsObter todas as participações ASA da conta ativa que este servidor MCP possui. Para contas on-chain arbitrárias use api_algod_get_account_info ou api_algod_get_account_asset_info.
wallet_sign_transactionAssinar uma única transação com a conta ativa
wallet_sign_transaction_groupAssinar um grupo de transações com a conta ativa (atribui ID de grupo automaticamente)
wallet_sign_dataAssinar dados hex arbitrários com Ed25519 puro (noble, sem prefixo SDK)
wallet_optin_assetOptar a conta ativa em um ativo (cria, assina e submete)

Ferramentas de Pagamento HTTP x402 (5 ferramentas)

Veja Pagamentos HTTP x402 para a explicação completa do protocolo.

FerramentaDescrição
x402_discover_payment_requirementsSondar um endpoint protegido por x402 e retornar seu array accepts[] (custo, ativo, rede, payTo) sem pagar. Somente leitura.
make_http_request_with_x402Chamar um endpoint protegido por x402 com pagamento automático USDC/ALGO da carteira ativa. Descobre internamente se paymentRequirements não for fornecido, constrói o grupo atômico pagador de taxa + pagamento, assina e tenta novamente com o cabeçalho PAYMENT-SIGNATURE.
bazaar_listNavegar pelo catálogo de APIs pagas registradas no diretório de descoberta Bazaar hospedado pelo facilitador configurado (facilitator.goplausible.xyz por padrão). Resumo compacto por padrão; full: true retorna registros verbatim. Filtros: network, method, merchantId, limit, offset.
bazaar_searchPesquisa por palavras-chave nos recursos Bazaar (URL + descrição). No lado do servidor: query, network. Pós-filtros no lado do cliente: scheme, maxUsdPrice, asset, payTo, extensions, includeTestnets.
bazaar_get_resource_detailsBuscar um único recurso Bazaar pela URL exata de resource. Retorna o registro verbatim (accepts[], discoveryInfo, contadores de popularidade).

Gerenciamento de Contas (8 ferramentas)

FerramentaDescrição
create_accountCriar uma nova conta Algorand (retorna endereço + mnemônica em texto claro)
rekey_accountRechavear uma conta para um novo endereço
mnemonic_to_mdkConverter mnemônica em chave de derivação mestre
mdk_to_mnemonicConverter chave de derivação mestre em mnemônica
secret_key_to_mnemonicConverter chave secreta em mnemônica
mnemonic_to_secret_keyConverter mnemônica em chave secreta
seed_from_mnemonicGerar seed a partir de mnemônica
mnemonic_from_seedGerar mnemônica a partir de seed

Ferramentas Utilitárias (13 ferramentas)

FerramentaDescrição
pingVerificação de conectividade e informações do servidor
validate_addressVerificar se um endereço Algorand é válido
encode_addressCodificar uma chave pública em endereço Algorand
decode_addressDecodificar um endereço Algorand em chave pública
get_application_addressObter endereço para um ID de aplicativo específico
bytes_to_bigintConverter bytes em BigInt
bigint_to_bytesConverter BigInt em bytes
encode_uint64Codificar uint64 em bytes
decode_uint64Decodificar bytes em uint64
verify_bytesVerificar assinatura contra bytes
sign_bytesAssinar bytes com uma chave secreta
encode_objCodificar objeto em msgpack
decode_objDecodificar msgpack em objeto

Ferramentas de Transação (18 ferramentas)

FerramentaDescrição
make_payment_txnCriar uma transação de pagamento
make_keyreg_txnCriar uma transação de registro de chave
make_asset_create_txnCriar uma transação de criação de ativo
make_asset_config_txnCriar uma transação de configuração de ativo
make_asset_destroy_txnCriar uma transação de destruição de ativo
make_asset_freeze_txnCriar uma transação de congelamento de ativo
make_asset_transfer_txnCriar uma transação de transferência de ativo
make_app_create_txnCriar uma transação de criação de aplicativo
make_app_update_txnCriar uma transação de atualização de aplicativo
make_app_delete_txnCriar uma transação de exclusão de aplicativo
make_app_optin_txnCriar uma transação de opt-in de aplicativo
make_app_closeout_txnCriar uma transação de close-out de aplicativo
make_app_clear_txnCriar uma transação de limpeza de estado de aplicativo
make_app_call_txnCriar uma transação de chamada de aplicativo
assign_group_idAtribuir ID de grupo para transações atômicas
sign_transactionAssinar uma transação com uma chave secreta
encode_unsigned_transactionCodificar uma transação não assinada em bytes msgpack base64
decode_signed_transactionDecodificar um blob de transação assinada de volta para JSON com detalhes de assinatura

Ferramentas Algod (5 ferramentas)

FerramentaDescrição
compile_tealCompilar código-fonte TEAL
disassemble_tealDesmontar bytecode TEAL para código-fonte
send_raw_transactionSubmeter transações assinadas à rede
simulate_raw_transactionsSimular transações já codificadas (bytes base64). Apenas passou/falhou + log/custo — sem trace, sem orçamento extra.
simulate_transactionsSimular grupos de transações decodificados com configuração completa de SimulateRequest (trace, orçamento extra de opcode, manipulação de recursos sem nome, transações não assinadas).

Ferramentas da API Algod (13 ferramentas)

Leituras ao vivo do estado atual contra um nó Algod. Escolha padrão para consultas de conta/aplicativo/ativo — os endpoints indexer correspondentes foram intencionalmente desativados para manter a superfície de ferramentas enxuta (veja .notes/redundant-tools-report.md). Use a família indexer abaixo apenas quando precisar de consultas históricas ou filtradas que o algod não pode atender.

FerramentaDescrição
api_algod_get_account_infoObter saldo da conta, ativos e endereço de autorização
api_algod_get_account_application_infoObter informações de aplicativo específicas da conta
api_algod_get_account_asset_infoObter informações de ativo específicas da conta
api_algod_get_application_by_idObter informações do aplicativo
api_algod_get_application_boxObter box de aplicativo por nome
api_algod_get_application_boxesObter todos os boxes de aplicativo
api_algod_get_asset_by_idObter informações do ativo
api_algod_get_pending_transactionObter informações de transação pendente
api_algod_get_pending_transactions_by_addressObter transações pendentes para um endereço
api_algod_get_pending_transactionsObter todas as transações pendentes
api_algod_get_transaction_paramsObter parâmetros de transação sugeridos
api_algod_get_node_statusObter status atual do nó
api_algod_get_node_status_after_blockObter status do nó após uma rodada específica

Ferramentas da API Indexer (10 ferramentas)

Consultas históricas/filtradas contra uma instância do Algorand Indexer. Use-as para varreduras de intervalo de tempo, pesquisas paginadas, recuperação de logs e descoberta de criador/detentor — qualquer coisa que os endpoints de estado atual do algod não possam responder.

Sete endpoints indexer que duplicavam equivalentes do algod (conta por ID, ativos da conta, estados locais de aplicativo da conta, aplicativo por ID, box de aplicativo, boxes de aplicativo, ativo por ID) foram intencionalmente desativados. Eles permanecem comentados em src/tools/apiManager/indexer/ e podem ser reativados em um único lugar se necessário.

FerramentaDescrição
api_indexer_lookup_account_created_applicationsObter aplicativos criados por conta
api_indexer_search_for_accountsPesquisar contas com filtros (participações em ativos/aplicativos, faixas de saldo)
api_indexer_lookup_application_logsObter mensagens de log de aplicativo em um intervalo de rodadas
api_indexer_search_for_applicationsPesquisar aplicativos por criador
api_indexer_lookup_asset_balancesObter todas as contas que detêm um ativo com seus saldos
api_indexer_lookup_asset_transactionsObter transações envolvendo um ativo (filtros de tempo/rodada/papel do endereço)
api_indexer_search_for_assetsPesquisar ativos por criador, nome ou unidade
api_indexer_lookup_transaction_by_idObter uma transação confirmada por ID
api_indexer_lookup_account_transactionsObter histórico de transações de uma conta (filtros de tempo/rodada/tipo/ativo)
api_indexer_search_for_transactionsPesquisar transações na cadeia com filtros

Ferramentas NFDomains (6 ferramentas)

FerramentaDescrição
api_nfd_get_nfdObter NFD por nome ou ID de aplicativo
api_nfd_get_nfds_for_addressesObter NFDs para endereços específicos
api_nfd_get_nfd_activityObter atividade/alterações para NFDs
api_nfd_get_nfd_analyticsObter dados analíticos de NFD
api_nfd_browse_nfdsNavegar por NFDs com filtros
api_nfd_search_nfdsPesquisar NFDs

Ferramentas Tinyman AMM (9 ferramentas)

FerramentaDescrição
api_tinyman_get_poolObter informações do pool por par de ativos
api_tinyman_get_pool_analyticsObter análises do pool
api_tinyman_get_pool_creation_quoteObter cotação para criar um pool
api_tinyman_get_liquidity_quoteObter cotação para adicionar liquidez
api_tinyman_get_remove_liquidity_quoteObter cotação para remover liquidez
api_tinyman_get_swap_quoteObter cotação para trocar ativos
api_tinyman_get_asset_optin_quoteObter cotação para opt-in de ativo
api_tinyman_get_validator_optin_quoteObter cotação para opt-in de validador
api_tinyman_get_validator_optout_quoteObter cotação para opt-out de validador

Ferramentas do Haystack Router (3 ferramentas)

FerramentaDescrição
api_haystack_get_swap_quoteObter cotação de troca otimizada com roteamento entre os protocolos Tinyman V2, Pact, Folks e LST
api_haystack_execute_swapTroca tudo-em-um: cotação → assinar (via carteira) → enviar → confirmar
api_haystack_needs_optinVerificar se o endereço precisa de opt-in de ativo antes de trocar

Ferramentas da Pera Wallet (3 ferramentas)

FerramentaDescrição
api_pera_asset_verification_statusObter status de verificação de um ativo na mainnet (verificado, confiável, suspeito, desconhecido)
api_pera_verified_asset_detailsObter informações detalhadas do ativo da Pera (nome, unidade, logotipo, decimais, verificação)
api_pera_verified_asset_searchPesquisar ativos verificados da Pera por nome, nome da unidade ou palavra-chave

As ferramentas da Pera Wallet são somente mainnet — a API pública da Pera não suporta testnet ou localnet.

Ferramentas do Alpha Arcade (14 ferramentas)

Negocie mercados de previsão on-chain (resultados SIM/NÃO) denominados em USDC. Todos os preços e quantidades usam microunidades (1.000.000 = $1,00 ou 1 ação). Ferramentas somente leitura funcionam sem carteira; ferramentas de negociação exigem uma conta de carteira ativa.

FerramentaDescrição
alpha_get_live_marketsBuscar todos os mercados de previsão ao vivo com preços, volume e categorias
alpha_get_reward_marketsBuscar mercados com recompensas de liquidez (requer a variável de ambiente ALPHA_API_KEY)
alpha_get_marketBuscar detalhes completos de um único mercado por ID do aplicativo
alpha_get_orderbookLivro de ofertas unificado na perspectiva SIM com cálculo de spread
alpha_get_open_ordersOrdens abertas para uma carteira em um mercado específico
alpha_get_positionsPosições de tokens SIM/NÃO em todos os mercados
alpha_create_limit_orderColocar uma ordem limitada a um preço específico (bloqueia ~0,957 ALGO como garantia)
alpha_create_market_orderColocar uma ordem de mercado com correspondência automática e tolerância a slippage
alpha_cancel_orderCancelar uma ordem aberta (reembolsa USDC/tokens e garantia em ALGO)
alpha_amend_orderEditar uma ordem existente não preenchida no local (preço, quantidade, slippage)
alpha_propose_matchPropor uma correspondência entre uma ordem maker existente e sua carteira
alpha_split_sharesDividir USDC em tokens de resultado SIM + NÃO iguais
alpha_merge_sharesMesclar tokens SIM + NÃO iguais de volta em USDC
alpha_claimReivindicar USDC de um mercado resolvido resgatando tokens vencedores

Variável de ambiente opcional: ALPHA_API_KEY — necessária para dados de mercado de recompensas. ALPHA_API_BASE_URL — endpoint de API personalizado (padrão: https://platform.alphaarcade.com/api).

Ferramentas de URI ARC-26 (1 ferramenta)

FerramentaDescrição
generate_algorand_qrcodeGerar URI e código QR do Algorand conforme especificação ARC-26

Ferramentas de Conhecimento (1 ferramenta)

FerramentaDescrição
get_knowledge_docObter conteúdo em markdown para documentos de conhecimento do Algorand

Recursos

O servidor expõe recursos MCP para acesso direto a dados. Os recursos da carteira são descritos na seção Secure Wallet acima.

Recursos de Conhecimento

URIDescrição
algorand://knowledge/taxonomyTaxonomia completa de conhecimento do Algorand
algorand://knowledge/taxonomy/arcsAlgorand Request for Comments
algorand://knowledge/taxonomy/sdksDocumentação do SDK
algorand://knowledge/taxonomy/algokitDocumentação do AlgoKit
algorand://knowledge/taxonomy/algokit-utilsDocumentação do AlgoKit Utils
algorand://knowledge/taxonomy/tealscriptDocumentação do TEALScript
algorand://knowledge/taxonomy/puyaDocumentação do Puya
algorand://knowledge/taxonomy/liquid-authDocumentação do Liquid Auth
algorand://knowledge/taxonomy/pythonDocumentação do SDK Python
algorand://knowledge/taxonomy/developersDocumentação do desenvolvedor
algorand://knowledge/taxonomy/clisDocumentação das ferramentas CLI
algorand://knowledge/taxonomy/nodesDocumentação de gerenciamento de nós
algorand://knowledge/taxonomy/detailsDocumentação de detalhes técnicos

Estrutura do Projeto

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

Formato de Resposta

Todas as respostas das ferramentas seguem o formato de conteúdo MCP. As respostas da API incluem paginação automática quando os conjuntos de dados excedem itemsPerPage (padrão 10):

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

Passe pageToken de uma resposta anterior para buscar a próxima página. Defina itemsPerPage em qualquer chamada de ferramenta para controlar o tamanho da página.

Desenvolvimento

# Install dependencies
npm install

# Type-check
npm run typecheck

# Build
npm run build

# Clean build output
npm run clean

Testes

O projeto possui uma suíte de testes abrangente em duas camadas: testes unitários rápidos (simulados, sem rede) e testes E2E reais (testnet ao vivo). Ambos usam Jest 29 com ts-jest e suporte a ESM.

Início rápido

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

Testes unitários

Os testes unitários cobrem todas as 11 categorias de ferramentas com dependências de rede totalmente simuladas. Eles são executados em paralelo e terminam em ~5 segundos. Nenhuma variável de ambiente ou contas financiadas são necessárias.

npm test

Cobertura: 11 suítes, mais de 75 testes cobrindo caminhos de sucesso, tratamento de erros e casos extremos para cada categoria de ferramenta.

SuíteO que testa
accountManagerCriação de conta, idas e voltas de mnemônico, validação de parâmetros de rekey
utilityManagerPing, validação de endereço, codificar/decodificar, assinar/verificar bytes, codificar/decodificar objetos
walletManagerCiclo de vida completo: adicionar → listar → alternar → obter informações → assinar dados → remover (keychain simulado + SQLite)
transactionManagerConstrução de transações de pagamento, ativo e aplicativo; sign_transaction; assign_group_id
algodManagerCompilar/desmontar TEAL, enviar bruto, simular
apiAlgodTodas as 13 ferramentas da API algod com roteamento simulado correto
apiIndexerTodas as 10 ferramentas ativas da API indexer com mocks de construtor fluente
apiNfdNFD obter/pesquisar/navegar com fetch simulado
apiTinymanPool/troca Tinyman com tratamento de erros
arc26ManagerGeração de URI ARC-26 e saída de QR code SVG
knowledgeManagerRecuperação de documentos de conhecimento e tratamento de erro de documento ausente

Como funciona a simulação

Os testes unitários usam jest.unstable_mockModule() (compatível com ESM) para interceptar importações antes que sejam carregadas. O tests/helpers/mockFactories.ts compartilhado fornece:

  • setupNetworkMocks() — Substitui algorand-client.ts por clientes algod/indexer simulados que retornam respostas determinísticas sem nenhuma chamada de rede.
  • createKeychainMock() — Substitui @napi-rs/keyring por um Map em memória, para que os testes de carteira funcionem sem um keychain do sistema operacional.
  • Mocks de proxy fluente — O SDK do Indexer da Algorand usa um padrão de construtor (.searchForAssets().limit(5).do()). A fábrica de mocks usa objetos ES Proxy que retornam a si mesmos para qualquer método encadeado e resolvem quando .do() é chamado.

Testes E2E

Os testes E2E chamam os manipuladores de ferramentas diretamente contra a testnet do Algorand (via nós públicos do AlgoNode). Eles são executados em série para evitar limitação de taxa.

npm run test:e2e

Na primeira execução (sem mnemônico fornecido), a configuração do teste:

  1. Gera uma nova conta Algorand
  2. Imprime o endereço e o mnemônico
  3. Imprime um link de financiamento: https://lora.algokit.io/testnet/fund
  4. Executa todos os testes (testes sem financiamento ainda passam)

Para executar com uma conta financiada:

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

Cobertura: 11 suítes, mais de 35 testes cobrindo interações reais de rede.

SuíteO que testa
accountCriação de conta, cadeia de ida e volta de mnemônico para chave
utilityPing, validação de endereço, codificar/decodificar, assinar/verificar bytes, codificar/decodificar objetos
walletCiclo de vida completo da carteira: adicionar → listar → alternar → obter informações → obter ativos → assinar dados → remover
transactionConstruir pagamento → assinar → verificar txID; construir opt-in de ativo; construir grupo com assign_group_id
algodCompilar + desmontar TEAL ida e volta
algodApiInformações da conta, parâmetros sugeridos, status do nó, informações de ativo via algod
indexerApiConsulta de conta, pesquisa de ativo/transação/conta via indexer
nfdConsultar "algo.algo", pesquisar NFDs, navegar por NFDs
tinymanObter pool ALGO/USDC
arc26Gerar URI ARC-26, verificar formato + QR SVG
knowledgeRecuperar conteúdo de documento de conhecimento conhecido

Ativação de categoria

Os testes E2E podem ser habilitados seletivamente por categoria ou ferramenta individual por meio de variáveis de ambiente. Por padrão, todas as categorias estão habilitadas.

Habilitar categorias específicas

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

Sinalizadores de categoria disponíveis

Variável de ambienteCategoria
E2E_ALL=1Todas as categorias (explícito)
E2E_WALLET=1Ferramentas de carteira
E2E_ACCOUNT=1Ferramentas de conta
E2E_UTILITY=1Ferramentas utilitárias
E2E_TRANSACTION=1Ferramentas de transação
E2E_ALGOD=1Ferramentas algod
E2E_ALGOD_API=1Ferramentas da API algod
E2E_INDEXER_API=1Ferramentas da API indexer
E2E_NFD=1Ferramentas NFDomains
E2E_TINYMAN=1Ferramentas Tinyman
E2E_ARC26=1Ferramentas ARC-26
E2E_KNOWLEDGE=1Ferramentas de conhecimento

Importante: Definir qualquer sinalizador individual (por exemplo, E2E_WALLET=1) desativa todas as outras categorias, a menos que E2E_ALL=1 também seja definido.

Habilitar ferramentas específicas

E2E_TOOLS=ping,validate_address npm run test:e2e

A variável E2E_TOOLS aceita uma lista separada por vírgulas de nomes de ferramentas. Somente os testes dessas ferramentas específicas serão executados.

Estrutura de arquivos de teste

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

Configuração do Jest

ConfiguraçãoPropósitoConfigurações principais
jest.config.js (raiz)Testes unitáriostestTimeout: 10s, trabalhadores paralelos, testMatch: tests/unit/**
tests/jest.config.e2e.jsTestes E2EtestTimeout: 60s, maxWorkers: 1 (serial), globalSetup/globalTeardown
tsconfig.test.jsonTypeScript para testesrootDir: ".", inclui ambos src/ e tests/

Escrevendo novos testes

Modelo de teste unitário:

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();
  });
});

Modelo de teste E2E:

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();
  });
});

Dependências

  • algosdk v3 — SDK JavaScript do Algorand
  • @modelcontextprotocol/sdk — SDK TypeScript do MCP
  • @napi-rs/keyring — Acesso nativo ao keychain do sistema operacional (Keychain do macOS, libsecret do Linux, Gerenciador de Credenciais do Windows). Usado como fallback de leitura de compatibilidade retroativa para contas criadas por instalações anteriores à migração do banco de dados; novos mnemônicos são gravados apenas em wallet.db.
  • sql.js — SQLite embutido (WASM) para persistência de metadados da carteira
  • @noble/curves — Ed25519 em JS puro para assinatura de dados brutos (wallet_sign_data)
  • @tinymanorg/tinyman-js-sdk — SDK AMM do Tinyman
  • @alpha-arcade/sdk — SDK de mercado de previsão do Alpha Arcade
  • zod — Validação de tipos em tempo de execução
  • qrcode — Geração de código QR para ARC-26

Licença

MIT