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
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étodo | Comando | Quando usar |
|---|---|---|
| npx (recomendado) | npx @goplausible/algorand-mcp | Sem necessidade de instalação, sempre a versão mais recente |
| Instalação global | algorand-mcp | Após npm install -g @goplausible/algorand-mcp |
| Caminho absoluto | node /path/to/dist/index.js | Compilado 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(oualgorand-mcpse instalado globalmente, ounode /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.
| Camada | O que armazena | Onde |
|---|---|---|
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) │
│ │ │
- Criação de conta (
wallet_add_account) — Gera um par de chaves e insere uma linha contendo o mnemônico emaccounts. Retorna endereço, chave pública, apelido e índice. O mnemônico nunca é retornado. - Conta ativa — Uma conta está ativa por vez.
wallet_switch_accounta altera por apelido ou índice. Todas as ferramentas de assinatura e consulta operam na conta ativa. - Assinatura de transações (
wallet_sign_transaction) — Lê o mnemônico do banco de dados, assina em memória, retorna apenas o blob assinado. - 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. - 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
accountscuja colunamnemonicsejaNULLou vazia, ele tenta ler o mnemônico do keychain do SO sob o nome de serviçoalgorand-mcpchaveado 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
0se nenhuma conta ativa restar) - mantêm seu apelido original (um índice único parcial
idx_active_nicknamegarante unicidade de apelido apenas entre linhas ativas, então um novowallet_add_accountpode 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ão | Mudança |
|---|---|
| v1 | inicial — colunas accounts: id, address, public_key, nickname (UNIQUE), created_at |
| v2 | adicionada coluna mnemonic TEXT |
| v3 | adicionada 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
- O nome do cabeçalho é
PAYMENT-SIGNATURE, nãoX-PAYMENT. O corpo do cabeçalho é JSON codificado em base64 comx402Version,scheme,network(um identificador CAIP-2 comoalgorand:wGHE2Pw…para mainnet), umpayloade uma cópia verbatim da entradaaccepts[]que o cliente escolheu. - 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.
- 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_x402ex402_discover_payment_requirementssã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_infopara verificar) - Essa conta está optada no ativo de pagamento (USDC mainnet ASA
31566704, testnet ASA10458941) - 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ável | Descrição | Padrão | Quando necessário |
|---|---|---|---|
ALGORAND_TOKEN | Token de API para nós privados/autenticados | "" | Conectar a um nó Algod/Indexer privado |
ALGORAND_LOCALNET_URL | URL base da localnet | "" | Usando network: "localnet" (ex.: http://localhost:4001) |
ALPHA_API_KEY | Chave 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.
| Ferramenta | Descrição |
|---|---|
wallet_add_account | Criar uma nova conta Algorand com apelido (retorna apenas endereço + chave pública) |
wallet_remove_account | Remover uma conta da carteira por apelido ou índice |
wallet_list_accounts | Listar 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_account | Alternar a conta ativa por apelido ou índice |
wallet_get_info | Obter 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_assets | Obter 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_transaction | Assinar uma única transação com a conta ativa |
wallet_sign_transaction_group | Assinar um grupo de transações com a conta ativa (atribui ID de grupo automaticamente) |
wallet_sign_data | Assinar dados hex arbitrários com Ed25519 puro (noble, sem prefixo SDK) |
wallet_optin_asset | Optar 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.
| Ferramenta | Descrição |
|---|---|
x402_discover_payment_requirements | Sondar um endpoint protegido por x402 e retornar seu array accepts[] (custo, ativo, rede, payTo) sem pagar. Somente leitura. |
make_http_request_with_x402 | Chamar 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_list | Navegar 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_search | Pesquisa 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_details | Buscar um único recurso Bazaar pela URL exata de resource. Retorna o registro verbatim (accepts[], discoveryInfo, contadores de popularidade). |
Gerenciamento de Contas (8 ferramentas)
| Ferramenta | Descrição |
|---|---|
create_account | Criar uma nova conta Algorand (retorna endereço + mnemônica em texto claro) |
rekey_account | Rechavear uma conta para um novo endereço |
mnemonic_to_mdk | Converter mnemônica em chave de derivação mestre |
mdk_to_mnemonic | Converter chave de derivação mestre em mnemônica |
secret_key_to_mnemonic | Converter chave secreta em mnemônica |
mnemonic_to_secret_key | Converter mnemônica em chave secreta |
seed_from_mnemonic | Gerar seed a partir de mnemônica |
mnemonic_from_seed | Gerar mnemônica a partir de seed |
Ferramentas Utilitárias (13 ferramentas)
| Ferramenta | Descrição |
|---|---|
ping | Verificação de conectividade e informações do servidor |
validate_address | Verificar se um endereço Algorand é válido |
encode_address | Codificar uma chave pública em endereço Algorand |
decode_address | Decodificar um endereço Algorand em chave pública |
get_application_address | Obter endereço para um ID de aplicativo específico |
bytes_to_bigint | Converter bytes em BigInt |
bigint_to_bytes | Converter BigInt em bytes |
encode_uint64 | Codificar uint64 em bytes |
decode_uint64 | Decodificar bytes em uint64 |
verify_bytes | Verificar assinatura contra bytes |
sign_bytes | Assinar bytes com uma chave secreta |
encode_obj | Codificar objeto em msgpack |
decode_obj | Decodificar msgpack em objeto |
Ferramentas de Transação (18 ferramentas)
| Ferramenta | Descrição |
|---|---|
make_payment_txn | Criar uma transação de pagamento |
make_keyreg_txn | Criar uma transação de registro de chave |
make_asset_create_txn | Criar uma transação de criação de ativo |
make_asset_config_txn | Criar uma transação de configuração de ativo |
make_asset_destroy_txn | Criar uma transação de destruição de ativo |
make_asset_freeze_txn | Criar uma transação de congelamento de ativo |
make_asset_transfer_txn | Criar uma transação de transferência de ativo |
make_app_create_txn | Criar uma transação de criação de aplicativo |
make_app_update_txn | Criar uma transação de atualização de aplicativo |
make_app_delete_txn | Criar uma transação de exclusão de aplicativo |
make_app_optin_txn | Criar uma transação de opt-in de aplicativo |
make_app_closeout_txn | Criar uma transação de close-out de aplicativo |
make_app_clear_txn | Criar uma transação de limpeza de estado de aplicativo |
make_app_call_txn | Criar uma transação de chamada de aplicativo |
assign_group_id | Atribuir ID de grupo para transações atômicas |
sign_transaction | Assinar uma transação com uma chave secreta |
encode_unsigned_transaction | Codificar uma transação não assinada em bytes msgpack base64 |
decode_signed_transaction | Decodificar um blob de transação assinada de volta para JSON com detalhes de assinatura |
Ferramentas Algod (5 ferramentas)
| Ferramenta | Descrição |
|---|---|
compile_teal | Compilar código-fonte TEAL |
disassemble_teal | Desmontar bytecode TEAL para código-fonte |
send_raw_transaction | Submeter transações assinadas à rede |
simulate_raw_transactions | Simular transações já codificadas (bytes base64). Apenas passou/falhou + log/custo — sem trace, sem orçamento extra. |
simulate_transactions | Simular 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.
| Ferramenta | Descrição |
|---|---|
api_algod_get_account_info | Obter saldo da conta, ativos e endereço de autorização |
api_algod_get_account_application_info | Obter informações de aplicativo específicas da conta |
api_algod_get_account_asset_info | Obter informações de ativo específicas da conta |
api_algod_get_application_by_id | Obter informações do aplicativo |
api_algod_get_application_box | Obter box de aplicativo por nome |
api_algod_get_application_boxes | Obter todos os boxes de aplicativo |
api_algod_get_asset_by_id | Obter informações do ativo |
api_algod_get_pending_transaction | Obter informações de transação pendente |
api_algod_get_pending_transactions_by_address | Obter transações pendentes para um endereço |
api_algod_get_pending_transactions | Obter todas as transações pendentes |
api_algod_get_transaction_params | Obter parâmetros de transação sugeridos |
api_algod_get_node_status | Obter status atual do nó |
api_algod_get_node_status_after_block | Obter 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.
| Ferramenta | Descrição |
|---|---|
api_indexer_lookup_account_created_applications | Obter aplicativos criados por conta |
api_indexer_search_for_accounts | Pesquisar contas com filtros (participações em ativos/aplicativos, faixas de saldo) |
api_indexer_lookup_application_logs | Obter mensagens de log de aplicativo em um intervalo de rodadas |
api_indexer_search_for_applications | Pesquisar aplicativos por criador |
api_indexer_lookup_asset_balances | Obter todas as contas que detêm um ativo com seus saldos |
api_indexer_lookup_asset_transactions | Obter transações envolvendo um ativo (filtros de tempo/rodada/papel do endereço) |
api_indexer_search_for_assets | Pesquisar ativos por criador, nome ou unidade |
api_indexer_lookup_transaction_by_id | Obter uma transação confirmada por ID |
api_indexer_lookup_account_transactions | Obter histórico de transações de uma conta (filtros de tempo/rodada/tipo/ativo) |
api_indexer_search_for_transactions | Pesquisar transações na cadeia com filtros |
Ferramentas NFDomains (6 ferramentas)
| Ferramenta | Descrição |
|---|---|
api_nfd_get_nfd | Obter NFD por nome ou ID de aplicativo |
api_nfd_get_nfds_for_addresses | Obter NFDs para endereços específicos |
api_nfd_get_nfd_activity | Obter atividade/alterações para NFDs |
api_nfd_get_nfd_analytics | Obter dados analíticos de NFD |
api_nfd_browse_nfds | Navegar por NFDs com filtros |
api_nfd_search_nfds | Pesquisar NFDs |
Ferramentas Tinyman AMM (9 ferramentas)
| Ferramenta | Descrição |
|---|---|
api_tinyman_get_pool | Obter informações do pool por par de ativos |
api_tinyman_get_pool_analytics | Obter análises do pool |
api_tinyman_get_pool_creation_quote | Obter cotação para criar um pool |
api_tinyman_get_liquidity_quote | Obter cotação para adicionar liquidez |
api_tinyman_get_remove_liquidity_quote | Obter cotação para remover liquidez |
api_tinyman_get_swap_quote | Obter cotação para trocar ativos |
api_tinyman_get_asset_optin_quote | Obter cotação para opt-in de ativo |
api_tinyman_get_validator_optin_quote | Obter cotação para opt-in de validador |
api_tinyman_get_validator_optout_quote | Obter cotação para opt-out de validador |
Ferramentas do Haystack Router (3 ferramentas)
| Ferramenta | Descrição |
|---|---|
api_haystack_get_swap_quote | Obter cotação de troca otimizada com roteamento entre os protocolos Tinyman V2, Pact, Folks e LST |
api_haystack_execute_swap | Troca tudo-em-um: cotação → assinar (via carteira) → enviar → confirmar |
api_haystack_needs_optin | Verificar se o endereço precisa de opt-in de ativo antes de trocar |
Ferramentas da Pera Wallet (3 ferramentas)
| Ferramenta | Descrição |
|---|---|
api_pera_asset_verification_status | Obter status de verificação de um ativo na mainnet (verificado, confiável, suspeito, desconhecido) |
api_pera_verified_asset_details | Obter informações detalhadas do ativo da Pera (nome, unidade, logotipo, decimais, verificação) |
api_pera_verified_asset_search | Pesquisar 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.
| Ferramenta | Descrição |
|---|---|
alpha_get_live_markets | Buscar todos os mercados de previsão ao vivo com preços, volume e categorias |
alpha_get_reward_markets | Buscar mercados com recompensas de liquidez (requer a variável de ambiente ALPHA_API_KEY) |
alpha_get_market | Buscar detalhes completos de um único mercado por ID do aplicativo |
alpha_get_orderbook | Livro de ofertas unificado na perspectiva SIM com cálculo de spread |
alpha_get_open_orders | Ordens abertas para uma carteira em um mercado específico |
alpha_get_positions | Posições de tokens SIM/NÃO em todos os mercados |
alpha_create_limit_order | Colocar uma ordem limitada a um preço específico (bloqueia ~0,957 ALGO como garantia) |
alpha_create_market_order | Colocar uma ordem de mercado com correspondência automática e tolerância a slippage |
alpha_cancel_order | Cancelar uma ordem aberta (reembolsa USDC/tokens e garantia em ALGO) |
alpha_amend_order | Editar uma ordem existente não preenchida no local (preço, quantidade, slippage) |
alpha_propose_match | Propor uma correspondência entre uma ordem maker existente e sua carteira |
alpha_split_shares | Dividir USDC em tokens de resultado SIM + NÃO iguais |
alpha_merge_shares | Mesclar tokens SIM + NÃO iguais de volta em USDC |
alpha_claim | Reivindicar 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)
| Ferramenta | Descrição |
|---|---|
generate_algorand_qrcode | Gerar URI e código QR do Algorand conforme especificação ARC-26 |
Ferramentas de Conhecimento (1 ferramenta)
| Ferramenta | Descrição |
|---|---|
get_knowledge_doc | Obter 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
| URI | Descrição |
|---|---|
algorand://knowledge/taxonomy | Taxonomia completa de conhecimento do Algorand |
algorand://knowledge/taxonomy/arcs | Algorand Request for Comments |
algorand://knowledge/taxonomy/sdks | Documentação do SDK |
algorand://knowledge/taxonomy/algokit | Documentação do AlgoKit |
algorand://knowledge/taxonomy/algokit-utils | Documentação do AlgoKit Utils |
algorand://knowledge/taxonomy/tealscript | Documentação do TEALScript |
algorand://knowledge/taxonomy/puya | Documentação do Puya |
algorand://knowledge/taxonomy/liquid-auth | Documentação do Liquid Auth |
algorand://knowledge/taxonomy/python | Documentação do SDK Python |
algorand://knowledge/taxonomy/developers | Documentação do desenvolvedor |
algorand://knowledge/taxonomy/clis | Documentação das ferramentas CLI |
algorand://knowledge/taxonomy/nodes | Documentação de gerenciamento de nós |
algorand://knowledge/taxonomy/details | Documentaçã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íte | O que testa |
|---|---|
accountManager | Criação de conta, idas e voltas de mnemônico, validação de parâmetros de rekey |
utilityManager | Ping, validação de endereço, codificar/decodificar, assinar/verificar bytes, codificar/decodificar objetos |
walletManager | Ciclo de vida completo: adicionar → listar → alternar → obter informações → assinar dados → remover (keychain simulado + SQLite) |
transactionManager | Construção de transações de pagamento, ativo e aplicativo; sign_transaction; assign_group_id |
algodManager | Compilar/desmontar TEAL, enviar bruto, simular |
apiAlgod | Todas as 13 ferramentas da API algod com roteamento simulado correto |
apiIndexer | Todas as 10 ferramentas ativas da API indexer com mocks de construtor fluente |
apiNfd | NFD obter/pesquisar/navegar com fetch simulado |
apiTinyman | Pool/troca Tinyman com tratamento de erros |
arc26Manager | Geração de URI ARC-26 e saída de QR code SVG |
knowledgeManager | Recuperaçã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()— Substituialgorand-client.tspor clientes algod/indexer simulados que retornam respostas determinísticas sem nenhuma chamada de rede.createKeychainMock()— Substitui@napi-rs/keyringpor umMapem 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 ESProxyque 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:
- Gera uma nova conta Algorand
- Imprime o endereço e o mnemônico
- Imprime um link de financiamento: https://lora.algokit.io/testnet/fund
- 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íte | O que testa |
|---|---|
account | Criação de conta, cadeia de ida e volta de mnemônico para chave |
utility | Ping, validação de endereço, codificar/decodificar, assinar/verificar bytes, codificar/decodificar objetos |
wallet | Ciclo de vida completo da carteira: adicionar → listar → alternar → obter informações → obter ativos → assinar dados → remover |
transaction | Construir pagamento → assinar → verificar txID; construir opt-in de ativo; construir grupo com assign_group_id |
algod | Compilar + desmontar TEAL ida e volta |
algodApi | Informações da conta, parâmetros sugeridos, status do nó, informações de ativo via algod |
indexerApi | Consulta de conta, pesquisa de ativo/transação/conta via indexer |
nfd | Consultar "algo.algo", pesquisar NFDs, navegar por NFDs |
tinyman | Obter pool ALGO/USDC |
arc26 | Gerar URI ARC-26, verificar formato + QR SVG |
knowledge | Recuperar 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 ambiente | Categoria |
|---|---|
E2E_ALL=1 | Todas as categorias (explícito) |
E2E_WALLET=1 | Ferramentas de carteira |
E2E_ACCOUNT=1 | Ferramentas de conta |
E2E_UTILITY=1 | Ferramentas utilitárias |
E2E_TRANSACTION=1 | Ferramentas de transação |
E2E_ALGOD=1 | Ferramentas algod |
E2E_ALGOD_API=1 | Ferramentas da API algod |
E2E_INDEXER_API=1 | Ferramentas da API indexer |
E2E_NFD=1 | Ferramentas NFDomains |
E2E_TINYMAN=1 | Ferramentas Tinyman |
E2E_ARC26=1 | Ferramentas ARC-26 |
E2E_KNOWLEDGE=1 | Ferramentas 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ção | Propósito | Configurações principais |
|---|---|---|
jest.config.js (raiz) | Testes unitários | testTimeout: 10s, trabalhadores paralelos, testMatch: tests/unit/** |
tests/jest.config.e2e.js | Testes E2E | testTimeout: 60s, maxWorkers: 1 (serial), globalSetup/globalTeardown |
tsconfig.test.json | TypeScript para testes | rootDir: ".", 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