Algorand MCP Implementation

Algorand MCP 服务

一款全面的 Model Context Protocol (MCP) 服务，为 AI Agent 和大模型提供对 Algorand 区块链的完整访问权限。由 GoPlausible 构建。

Algorand 是一种负碳的纯权益证明 Layer 1 区块链，具有即时最终性、低费用，并内置对智能合约（AVM）、标准资产（ASA）和原子交易的支持。

什么是 MCP？

Model Context Protocol 是一项开放标准，可让 AI 应用连接到外部工具和数据源。此服务将 Algorand 区块链操作公开为 MCP 工具，任何兼容的 AI 客户端都可以使用——包括 Claude Desktop、Claude Code、Cursor、Windsurf 等。

功能

• Agent 钱包——助记词存储在本地 SQLite 数据库中，由 MCP 服务代表 Agent 进行签名（工具响应中不会返回助记词）
• 带有易读昵称的钱包账户
• 账户创建、密钥管理和密钥轮换
• 交易构建、签名和提交（支付、资产、应用、密钥注册）
• 原子交易组
• TEAL 编译和反汇编
• 完整的 Algod 和 Indexer API 访问权限
• NFDomains（NFD）命名服务集成
• x402 HTTP 微支付——使用当前钱包自动发现并通过一次调用发起付费请求（USDC/ALGO）
• 面向 Algorand 的 AP2 工具
• Tinyman AMM 集成（池、兑换、流动性）
• Haystack Router DEX 聚合（在 Tinyman、Pact、Folks 上以最优价格兑换）
• Alpha Arcade 预测市场交易（浏览市场、订单簿、限价/市价订单、持仓、领取）
• ARC-26 URI 和二维码生成
• Algorand 知识库，包含完整的开发者文档分类体系
• 每次工具调用均可选择网络（mainnet、testnet、localnet）并支持分页

要求

• Node.js v20 或更高版本
• npm、pnpm 或 yarn

安装

从 npm 安装

npm install -g @goplausible/algorand-mcp

从源代码安装

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

MCP 配置

此服务通过 stdio 运行。可通过三种方式调用——选择适合你设置的方式：

方式	命令	适用场景
npx（推荐）	npx @goplausible/algorand-mcp	无需安装，始终使用最新版本
全局安装	algorand-mcp	运行 npm install -g @goplausible/algorand-mcp 后使用
绝对路径	node /path/to/dist/index.js	从源代码构建或使用本地克隆版本

标准用法无需设置环境变量。网络选择、分页和节点 URL 均由每次工具调用动态处理。

---

OpenClaw

无需手动配置——安装 @goplausible/openclaw-algorand-plugin npm 包后，Algorand MCP 服务会自动配置：

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

---

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

使用 npx：

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

使用全局安装：

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

使用绝对路径：

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

---

Claude Code

在项目根目录（项目范围）创建 .mcp.json，或在 ~/.claude.json（用户范围）中创建：

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

或者通过交互方式添加：

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

---

Cursor

通过 Settings > MCP Servers 添加，或编辑项目根目录中的 .cursor/mcp.json：

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

---

Windsurf

通过 Settings > MCP 添加，或编辑 ~/.codeium/windsurf/mcp_config.json：

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

---

VS Code / GitHub Copilot

编辑工作区根目录中的 .vscode/mcp.json，或打开 Settings > MCP Servers：

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

---

Cline

通过 Cline 侧边栏中的 MCP Servers 面板添加，或编辑 ~/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

在项目根目录中创建 .codex/mcp.json，或创建 ~/.codex/mcp.json 以进行全局配置：

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

---

Open Code

编辑 ~/.config/opencode/config.json：

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

---

任何兼容 MCP 的客户端

该服务使用标准 MCP stdio 协议。对于上面未列出的客户端，请按以下方式配置：

• 命令： npx（如果已全局安装，也可使用 algorand-mcp，或 node /path/to/dist/index.js）
• 参数： ["@goplausible/algorand-mcp"]（用于 npx）
• 传输方式： stdio

网络选择

每个工具都接受可选的 network 参数："mainnet"（默认值）、"testnet" 或 "localnet"。mainnet 和 testnet 的 Algod 与 Indexer URL 已通过 AlgoNode 内置。

工具调用示例：

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

如果未提供 network，工具默认使用 mainnet。

分页

API 响应会自动分页。每个工具都接受可选的 itemsPerPage 参数（默认值：10）。传入上一次响应中的 pageToken，即可获取下一页。

Agent 钱包

架构

Agent 钱包是一个本地 SQLite 数据库，由 MCP 服务代表 Agent 控制。服务保管助记词并为 Agent 签署交易，Agent 不会在任何工具响应中看到助记词。

层	存储内容	位置
SQLite (wallet.db)	账户行（address、public_key、nickname、mnemonic、created_at）和活动账户索引	~/.algorand-mcp/wallet.db（模式 0600）

威胁模型。 wallet.db 文件就是机密。任何拥有该文件读取权限的人都可以恢复钱包中存储的所有助记词。缓解措施包括使用文件系统权限（0600，仅限所有者访问）、避免将数据目录放在共享或所有人可读的卷上，以及像对待其他机密存储一样对待数据目录（谨慎创建快照、限制备份，并加密主机磁盘以保护静态数据）。对于 Docker 部署，请将 ~/.algorand-mcp 挂载为命名卷，并像保护其他机密材料一样限制其访问权限。

工作原理

  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. 创建账户（wallet_add_account）——生成密钥对，并向 accounts 插入一行，其中包含助记词。返回地址、公钥、昵称和索引。不会返回助记词。
2. 活动账户——一次只能有一个活动账户。wallet_switch_account 可通过昵称或索引切换活动账户。所有签名和查询工具都使用活动账户。
3. 交易签名（wallet_sign_transaction）——从数据库读取助记词，在内存中签名，并且只返回已签名的 Blob。
4. 数据签名（wallet_sign_data）——使用 @noble/curves 库，通过原始 Ed25519 签署任意十六进制数据（不添加 Algorand SDK 前缀）。适用于链下身份验证。
5. 资产选择加入（wallet_optin_asset）——一步完成为活动账户创建、签署并提交资产选择加入交易。

向后兼容（从 OS 密钥链静默迁移）

此 MCP 的旧版安装会将助记词存储在 OS 密钥链（@napi-rs/keyring）中。升级后首次启动时，服务会执行一次性静默迁移：

• 对于每一条 accounts 记录，如果 mnemonic 列为 NULL 或为空，服务会尝试从 OS 密钥链中读取助记词，服务名称为 algorand-mcp，并以地址为键。
• 如果找到助记词，就会将其复制到 DB 列中。
• 原密钥链条目会保留，作为多余的备份；不会删除任何内容。

迁移完成后，DB 是唯一的数据源。只有在 DB 中某个地址的助记词仍为 NULL 时，才会将密钥链作为回退来源（例如，密钥链在启动时不可用，之后才恢复可用）。升级后创建的所有新账户都会直接写入 DB，不会访问密钥链。

孤立账户处理（归档而非删除）。 如果 accounts 中存在某条记录，但其助记词既不在密钥链中，也不在 DB 中（例如，用户将 wallet.db 复制到新设备，却没有同时迁移密钥链条目；从不完整的备份中恢复；或在从未有过密钥链的 Docker 环境中安装），那么该记录无法用于签名。服务不会删除它，而是将其标记为已归档（UPDATE accounts SET archived = 1 WHERE mnemonic IS NULL OR mnemonic = ''）。已归档的记录：

• 默认情况下会从 wallet_list_accounts 的响应中隐藏
• 永远不会成为活动账户（活动账户索引会被限制在剩余活动账户列表的末尾；如果没有剩余活动账户，则重置为 0）
• 保留其原始昵称（部分唯一索引 idx_active_nickname 仅对活动记录强制昵称唯一，因此新的 wallet_add_account 可以为新密钥对复用相同昵称）
• 可通过 wallet_list_accounts { archived: true } 查看，以便取证或日后恢复

在 MCP 工具层，归档操作不会发出任何提示。唯一的诊断信息是每次密钥链读取失败时向 stderr 输出一行日志（[algorand-mcp] keychain read failed for <addr>…: <msg>），因此，如果用户要调查误归档，可以查看密钥链报错究竟是“无条目”、“拒绝访问”还是“无 DBus”等。

上述操作都不需要用户采取任何行动。没有提示词、没有环境变量，也没有迁移工具。

架构版本

DB 架构通过一项在启动时运行、可幂等执行的迁移逐步扩展：

版本	变更
v1	初始版本 — accounts 列：id、address、public_key、nickname（UNIQUE）、created_at
v2	新增 mnemonic TEXT 列
v3	新增 archived INTEGER NOT NULL DEFAULT 0 列；删除 nickname 上的列级 UNIQUE 约束，并替换为 CREATE UNIQUE INDEX idx_active_nickname ON accounts(nickname) WHERE archived = 0，使已归档记录可以保留原昵称而不妨碍复用

v2→v3 步骤会重新创建 accounts 表（SQLite 无法通过 ALTER 删除列级 UNIQUE 约束），并将数据复制到新表，同时将 archived 设为 0。现有钱包可继续照常使用。

x402 HTTP Payments

x402 是一种原生支持 HTTP 的微支付协议。它将长期保留的 402 Payment Required 状态码用作实际握手：当客户端请求付费资源但未付款时，服务会返回 402，并在 JSON 正文中列出其接受的内容（网络、资产、金额、收款地址）。客户端构建付款信息，将其附加为 HTTP 标头，然后重试同一请求，服务便会返回包含资源的 200 响应。无需 API 密钥、无需 Stripe webhook，也无需管理账户——付款本身就是请求的一部分。

此 MCP 实现了 x402 的 Algorand 版本，付款是在 Algorand 上转移 USDC（或原生 ALGO）。它提供两个工具，将七步手动流程（探测 → 解析 → 检查是否已选择加入 → 构建费用支付方 → 构建付款 → 分组 → 签名 → 编码 → 标头 → 重试）合并为一次工具调用。

协议格式（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: {...}}│                            │                          │
       │                            │                            │                          │

与 Coinbase/EVM 版本的区别

1. 请求头名称为 PAYMENT-SIGNATURE，而不是 X-PAYMENT。请求头内容是经过 base64 编码的 JSON，包含 x402Version、scheme、network（CAIP-2 标识符，例如主网的 algorand:wGHE2Pw…）、payload，以及客户端所选 accepts[] 条目的原样副本。
2. 付款由 2 笔交易组成的原子交易组完成。 索引 0 是费用支付方交易（发送方 = facilitator，金额 = 0，整个交易组的费用 = 2000 µAlgo）；索引 1 是实际的 USDC ASA 转账（发送方 = 钱包，费用 = 0）。钱包只对索引 1 签名；结算时由 facilitator 在服务器端为索引 0 签名。用户的钱包只支付 USDC，甚至无需支付网络费用。
3. 网络字符串采用 Algorand CAIP-2 格式。 此 MCP 支持主网（wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8=）和测试网（SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=）。仅接受 Base、Solana 或其他非 Algorand 网络的端点无法在此处完成支付，工具会返回明确的错误。

Coinbase Wallet MCP 兼容性（x402 接口）

x402 工具——make_http_request_with_x402 和 x402_discover_payment_requirements——特意采用与 Coinbase Wallet MCP 的 x402 工具兼容的名称和格式。输入参数（baseURL、path、method、queryParams、body、headers、correlationId、maxAmountPerRequest、paymentRequirements、preferredNetwork、extensions）相同。输出封装（result、_atomicUnitsNote）也相同。

实际效果如下：

• 可直接用于 Algorand x402。 基于 Coinbase Wallet MCP 的 x402 工具编写的 Agent 和 MCP 应用，无需修改任何提示词即可使用此服务；它们只需访问 Algorand x402 端点，而不是 Base/Solana 端点。
• Agent 的使用习惯相同。 基于 Coinbase 生态工具调用轨迹训练的模型，首次调用即可正确使用这些工具，无需重新学习。
• 兼容性仅限于 x402 接口。 此 MCP 中的钱包、账户、交易构建和 DEX 工具均为 Algorand 专用，不会复刻 Coinbase 的钱包 API。只有 make_http_request_with_x402 和 x402_discover_payment_requirements 可直接兼容使用。

有一个参数必然不同：preferredNetwork 仅接受 mainnet | testnet | localnet（Algorand 网络），因为钱包只对 Algorand 交易签名。若 Agent 传入上述选项之外的值，会收到明确错误，指出不存在可通过 Algorand 付款的 accepts 条目。

示例 — 付费天气 API

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

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

活动钱包账户必须已选择加入目标 ASA（例如 USDC），并持有足够余额以支付 maxAmountRequired。如果尚未选择加入，付款会在结算时失败；请先使用 wallet_optin_asset 选择加入。

前提条件

• 存在活动钱包账户（使用 wallet_get_info 验证）
• 该账户已选择加入付款资产（主网 USDC ASA 31566704，测试网 ASA 10458941）
• 该账户持有足够的付款资产以支付 maxAmountRequired
• 端点的 accepts[] 至少包含一个此 MCP 支持的 Algorand 网络条目

可选环境变量

仅特殊配置需要环境变量。请通过 MCP 配置中的 env 块传入。

变量	描述	默认值	适用场景
ALGORAND_TOKEN	私有/需认证节点的 API 令牌	""	连接私有 Algod/Indexer 节点
ALGORAND_LOCALNET_URL	Localnet 基础 URL	""	使用 network: "localnet"（例如 http://localhost:4001）
ALPHA_API_KEY	Alpha Arcade API 密钥	""	访问奖励市场数据

示例：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"
      }
    }
  }
}

然后在工具调用中使用 "network": "localnet"。

可用工具

钱包工具（10 个工具）

有关完整的架构详情，请参阅 Secure Wallet。

工具	描述
wallet_add_account	创建新的 Algorand 账户并设置昵称（仅返回地址和公钥）
wallet_remove_account	按昵称或索引从钱包中移除账户
wallet_list_accounts	列出包含昵称和地址的活跃账户。传入 { archived: true } 可改为列出已归档账户（这些账户的助记词在启动时无法从 OS 密钥链中恢复，因此保留在数据库中以供取证，无法用于签名）。
wallet_switch_account	按昵称或索引切换活跃账户
wallet_get_info	获取此 MCP 服务所拥有的活跃账户信息（由数据库提供）：地址、公钥、余额和已选择加入的数量。对于任意链上账户，请使用 api_algod_get_account_info。
wallet_get_assets	获取此 MCP 服务所拥有的活跃账户的所有 ASA 资产。对于任意链上账户，请使用 api_algod_get_account_info 或 api_algod_get_account_asset_info。
wallet_sign_transaction	使用活跃账户为单笔交易签名
wallet_sign_transaction_group	使用活跃账户为一组交易签名（自动分配组 ID）
wallet_sign_data	使用原始 Ed25519（noble，无 SDK 前缀）为任意十六进制数据签名
wallet_optin_asset	让活跃账户选择加入某项资产（创建、签名并提交）

x402 HTTP 支付工具（5 个工具）

有关完整的协议说明，请参阅 x402 HTTP Payments。

工具	描述
x402_discover_payment_requirements	探测受 x402 保护的端点，并返回其 accepts[] 数组（费用、资产、网络、payTo），不会进行支付。只读。
make_http_request_with_x402	使用活跃钱包自动支付 USDC/ALGO，调用受 x402 保护的端点。如果未提供 paymentRequirements，则会在内部发现支付要求；构建原子费用支付方 + 支付交易组、签名，并使用 PAYMENT-SIGNATURE 标头重试。
bazaar_list	浏览由已配置的协调器托管的 Bazaar 发现目录中的付费 API 资源（默认值为 facilitator.goplausible.xyz）。默认返回精简摘要；full: true 则返回原始记录。筛选条件：network、method、merchantId、limit、offset。
bazaar_search	按关键字搜索 Bazaar 资源（URL + 描述）。服务端筛选：query、network。客户端后置筛选：scheme、maxUsdPrice、asset、payTo、extensions、includeTestnets。
bazaar_get_resource_details	按资源的精确 resource URL 获取单个 Bazaar 资源。返回原始记录（accepts[]、discoveryInfo、受欢迎程度计数）。

账户管理（8 个工具）

工具	描述
create_account	创建新的 Algorand 账户（以明文形式返回地址和助记词）
rekey_account	将账户的密钥重新指定为新地址
mnemonic_to_mdk	将助记词转换为主派生密钥
mdk_to_mnemonic	将主派生密钥转换为助记词
secret_key_to_mnemonic	将密钥转换为助记词
mnemonic_to_secret_key	将助记词转换为密钥
seed_from_mnemonic	根据助记词生成种子
mnemonic_from_seed	根据种子生成助记词

实用工具（13 个工具）

工具	描述
ping	检查服务连通性并获取信息
validate_address	检查 Algorand 地址是否有效
encode_address	将公钥编码为 Algorand 地址
decode_address	将 Algorand 地址解码为公钥
get_application_address	获取指定应用 ID 对应的地址
bytes_to_bigint	将字节转换为 BigInt
bigint_to_bytes	将 BigInt 转换为字节
encode_uint64	将 uint64 编码为字节
decode_uint64	将字节解码为 uint64
verify_bytes	验证字节的签名
sign_bytes	使用密钥签署字节
encode_obj	将对象编码为 msgpack
decode_obj	将 msgpack 解码为对象

交易工具（18 个工具）

工具	描述
make_payment_txn	创建支付交易
make_keyreg_txn	创建密钥注册交易
make_asset_create_txn	创建资产
make_asset_config_txn	创建资产配置交易
make_asset_destroy_txn	创建资产销毁交易
make_asset_freeze_txn	创建资产冻结交易
make_asset_transfer_txn	创建资产转账交易
make_app_create_txn	创建应用
make_app_update_txn	创建应用更新交易
make_app_delete_txn	创建应用删除交易
make_app_optin_txn	创建应用加入交易
make_app_closeout_txn	创建应用退出交易
make_app_clear_txn	创建应用清除状态交易
make_app_call_txn	创建应用调用交易
assign_group_id	为原子交易分配组 ID
sign_transaction	使用密钥签署交易
encode_unsigned_transaction	将未签名交易编码为 base64 msgpack 字节
decode_signed_transaction	将已签名交易数据块解码回包含签名详情的 JSON

Algod 工具（5 个工具）

工具	描述
compile_teal	编译 TEAL 源代码
disassemble_teal	将 TEAL 字节码反汇编为源代码
send_raw_transaction	向网络提交已签名的交易
simulate_raw_transactions	模拟已编码的交易（base64 字节）。仅返回通过/失败结果和日志/成本，不含跟踪信息或额外预算。
simulate_transactions	使用完整的 SimulateRequest 配置（跟踪信息、额外操作码预算、未命名资源处理、未签名交易）模拟已解码的交易组。

Algod API 工具（13 个）

针对 Algod 节点进行实时的当前状态读取。查询账户／应用／资产时的默认选择——为保持工具集精简，已禁用对应的索引器端点（参见 .notes/redundant-tools-report.md）。只有在需要 algod 无法提供的历史或筛选查询时，才使用下方的索引器工具系列。

工具	描述
api_algod_get_account_info	获取账户余额、资产和授权地址
api_algod_get_account_application_info	获取账户专属的应用信息
api_algod_get_account_asset_info	获取账户专属的资产信息
api_algod_get_application_by_id	获取应用信息
api_algod_get_application_box	按名称获取应用存储区
api_algod_get_application_boxes	获取所有应用存储区
api_algod_get_asset_by_id	获取资产信息
api_algod_get_pending_transaction	获取待处理交易信息
api_algod_get_pending_transactions_by_address	获取指定地址的待处理交易
api_algod_get_pending_transactions	获取所有待处理交易
api_algod_get_transaction_params	获取建议的交易参数
api_algod_get_node_status	获取当前节点状态
api_algod_get_node_status_after_block	获取特定轮次后的节点状态

索引器 API 工具（10 个）

针对 Algorand 索引器实例进行历史／筛选查询。用于时间范围扫描、分页搜索、日志检索以及查找创建者／持有者——也就是任何 algod 当前状态端点无法回答的问题。

七个与 algod 对应端点重复的索引器端点（按 ID 查询账户、账户资产、账户应用本地状态、按 ID 查询应用、应用存储区、应用的所有存储区、按 ID 查询资产）已被禁用。它们以注释形式保留在 src/tools/apiManager/indexer/ 中，如有需要，可在一个位置重新启用。

工具	描述
api_indexer_lookup_account_created_applications	获取账户创建的应用
api_indexer_search_for_accounts	按筛选条件搜索账户（资产／应用持有情况、余额范围）
api_indexer_lookup_application_logs	获取指定轮次范围内的应用日志消息
api_indexer_search_for_applications	按创建者搜索应用
api_indexer_lookup_asset_balances	获取持有某项资产的所有账户及其余额
api_indexer_lookup_asset_transactions	获取涉及某项资产的交易（按时间／轮次／地址角色筛选）
api_indexer_search_for_assets	按创建者、名称或单位搜索资产
api_indexer_lookup_transaction_by_id	按 ID 获取已确认的交易
api_indexer_lookup_account_transactions	获取账户的交易历史（按时间／轮次／类型／资产筛选）
api_indexer_search_for_transactions	按筛选条件搜索整个链上的交易

NFDomains 工具（6 个）

工具	描述
api_nfd_get_nfd	按名称或应用 ID 获取 NFD
api_nfd_get_nfds_for_addresses	获取指定地址的 NFD
api_nfd_get_nfd_activity	获取 NFD 的活动／变更记录
api_nfd_get_nfd_analytics	获取 NFD 分析数据
api_nfd_browse_nfds	按筛选条件浏览 NFD
api_nfd_search_nfds	搜索 NFD

Tinyman AMM 工具（9 个工具）

工具	描述
api_tinyman_get_pool	根据资产对获取池信息
api_tinyman_get_pool_analytics	获取池分析数据
api_tinyman_get_pool_creation_quote	获取创建池的报价
api_tinyman_get_liquidity_quote	获取添加流动性的报价
api_tinyman_get_remove_liquidity_quote	获取移除流动性的报价
api_tinyman_get_swap_quote	获取资产兑换报价
api_tinyman_get_asset_optin_quote	获取资产加入报价
api_tinyman_get_validator_optin_quote	获取验证器加入报价
api_tinyman_get_validator_optout_quote	获取验证器退出报价

Haystack 路由工具（3 个工具）

工具	描述
api_haystack_get_swap_quote	获取优化的兑换报价，支持通过 Tinyman V2、Pact、Folks 和 LST 协议进行路由
api_haystack_execute_swap	一站式兑换：报价 → 签名（通过钱包）→ 提交 → 确认
api_haystack_needs_optin	检查地址在兑换前是否需要加入资产

Pera Wallet 工具（3 个工具）

工具	描述
api_pera_asset_verification_status	获取主网资产的验证状态（已验证、可信、可疑、未知）
api_pera_verified_asset_details	从 Pera 获取详细资产信息（名称、单位、徽标、小数位数、验证状态）
api_pera_verified_asset_search	按名称、单位名称或关键词搜索 Pera 已验证资产

Pera Wallet 工具仅支持主网——Pera 公共 API 不支持测试网或本地网。

Alpha Arcade 工具（14 个工具）

在链上预测市场中交易以 USDC 计价的 YES/NO 结果。所有价格和数量均使用微单位（1,000,000 = $1.00 或 1 股）。只读工具无需钱包即可使用；交易工具需要有一个活跃的钱包账户。

工具	描述
alpha_get_live_markets	获取所有开放的预测市场，包括价格、交易量和类别
alpha_get_reward_markets	获取提供流动性奖励的市场（需要 ALPHA_API_KEY 环境变量）
alpha_get_market	根据应用 ID 获取单个市场的完整详情
alpha_get_orderbook	获取统一的 YES 视角订单簿，并计算价差
alpha_get_open_orders	获取钱包在指定市场中的未成交订单
alpha_get_positions	获取所有市场中的 YES/NO 代币持仓
alpha_create_limit_order	以指定价格下限价单（锁定约 0.957 ALGO 作为抵押品）
alpha_create_market_order	下市价单，支持自动撮合和滑点容差
alpha_cancel_order	取消未成交订单（退还 USDC/代币和 ALGO 抵押品）
alpha_amend_order	就地编辑现有的未成交订单（价格、数量、滑点）
alpha_propose_match	提议将现有做市订单与您的钱包进行撮合
alpha_split_shares	将 USDC 拆分为数量相等的 YES + NO 结果代币
alpha_merge_shares	将数量相等的 YES + NO 代币合并回 USDC
alpha_claim	通过兑换获胜代币，从已结算市场领取 USDC

可选环境变量：ALPHA_API_KEY——获取奖励市场数据时需要。ALPHA_API_BASE_URL——自定义 API 端点（默认值：https://platform.alphaarcade.com/api）。

ARC-26 URI 工具（1 个工具）

工具	描述
generate_algorand_qrcode	根据 ARC-26 规范生成 Algorand URI 和二维码

知识库工具（1 个工具）

工具	描述
get_knowledge_doc	获取 Algorand 知识文档的 Markdown 内容

资源

该服务公开 MCP 资源，以便直接访问数据。钱包资源详见上文的安全钱包部分。

知识资源

URI	描述
algorand://knowledge/taxonomy	完整的 Algorand 知识分类体系
algorand://knowledge/taxonomy/arcs	Algorand 征求意见稿
algorand://knowledge/taxonomy/sdks	SDK 文档
algorand://knowledge/taxonomy/algokit	AlgoKit 文档
algorand://knowledge/taxonomy/algokit-utils	AlgoKit Utils 文档
algorand://knowledge/taxonomy/tealscript	TEALScript 文档
algorand://knowledge/taxonomy/puya	Puya 文档
algorand://knowledge/taxonomy/liquid-auth	Liquid Auth 文档
algorand://knowledge/taxonomy/python	Python SDK 文档
algorand://knowledge/taxonomy/developers	开发者文档
algorand://knowledge/taxonomy/clis	CLI 工具文档
algorand://knowledge/taxonomy/nodes	节点管理文档
algorand://knowledge/taxonomy/details	技术细节文档

项目结构

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

响应格式

所有工具响应均遵循 MCP 内容格式。当数据集超过 itemsPerPage（默认值为 10）时，API 响应会自动分页：

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

传入上一条响应中的 pageToken 以获取下一页。在任何工具调用中设置 itemsPerPage，即可控制每页大小。

开发

# Install dependencies
npm install

# Type-check
npm run typecheck

# Build
npm run build

# Clean build output
npm run clean

测试

项目采用全面的双层测试套件：快速的单元测试（使用模拟，不访问网络）和真实的 E2E 测试（连接实时测试网）。两者均使用支持 ESM 的 Jest 29 和 ts-jest。

快速开始

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

单元测试

单元测试覆盖全部 11 类工具，并完全模拟网络依赖。测试并行运行，约 5 秒即可完成。无需环境变量或已注资账户。

npm test

**覆盖范围：**11 个测试套件、75+ 项测试，覆盖每类工具的成功流程、错误处理和边缘情况。

套件	测试内容
accountManager	账户创建、助记词往返转换、重设密钥参数验证
utilityManager	Ping、地址验证、编码/解码、字节签名/验证、对象编码/解码
walletManager	完整生命周期：添加 → 列表 → 切换 → 获取信息 → 签名数据 → 移除（模拟 keychain + SQLite）
transactionManager	支付、资产、应用交易构建；sign_transaction；assign_group_id
algodManager	TEAL 编译/反汇编、发送原始数据、模拟
apiAlgod	全部 13 个 algod API 工具，并使用正确的模拟路由
apiIndexer	全部 10 个启用的 indexer API 工具，并使用链式构建器模拟
apiNfd	NFD 获取/搜索/浏览，并模拟 fetch
apiTinyman	Tinyman 池/交换及错误处理
arc26Manager	ARC-26 URI 生成和 QR 码 SVG 输出
knowledgeManager	知识文档检索和缺失文档错误处理

模拟的工作原理

单元测试使用 jest.unstable_mockModule()（兼容 ESM）在导入加载前拦截它们。共享文件 tests/helpers/mockFactories.ts 提供：

• setupNetworkMocks() — 将 algorand-client.ts 替换为模拟 algod/indexer 客户端，使其无需任何网络调用即可返回确定性响应。
• createKeychainMock() — 将 @napi-rs/keyring 替换为内存中的 Map，因此钱包测试无需操作操作系统 keychain 即可运行。
• 链式 Proxy 模拟 — Algorand 的 Indexer SDK 使用构建器模式（.searchForAssets().limit(5).do()）。模拟工厂使用 ES Proxy 对象，对任意链式方法均返回自身，并在调用 .do() 时解析结果。

E2E 测试

E2E 测试会直接针对 Algorand 测试网调用工具处理器（通过 AlgoNode 公共节点）。测试按顺序运行，以避免触发速率限制。

npm run test:e2e

首次运行时（未提供助记词），测试设置会：

1. 生成一个新的 Algorand 账户
2. 输出地址和助记词
3. 输出资金注入链接：https://lora.algokit.io/testnet/fund
4. 运行所有测试（未注资的测试也能通过）

使用已注资的账户运行：

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

覆盖范围： 11 个测试套件、35+ 个测试，涵盖真实网络交互。

套件	测试内容
account	账户创建、助记词到密钥的往返转换链
utility	Ping、地址验证、编码/解码、签名/验证字节、编码/解码对象
wallet	完整的钱包生命周期：添加 → 列表 → 切换 → 获取信息 → 获取资产 → 签名数据 → 移除
transaction	构建支付 → 签名 → 验证 txID；构建资产选择加入交易；使用 assign_group_id 构建交易组
algod	编译 + 反汇编 TEAL 往返转换
algodApi	通过 algod 获取账户信息、建议参数、节点状态、资产信息
indexerApi	通过 indexer 查询账户、资产/交易/账户搜索
nfd	查询 "algo.algo"、搜索 NFD、浏览 NFD
tinyman	获取 ALGO/USDC 池
arc26	生成 ARC-26 URI，验证格式 + QR SVG
knowledge	获取已知知识文档内容

类别启用

可通过环境变量按类别或单个工具选择性启用 E2E 测试。默认情况下会启用所有类别。

启用特定类别

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

可用的类别标志

环境变量	类别
E2E_ALL=1	所有类别（显式启用）
E2E_WALLET=1	钱包工具
E2E_ACCOUNT=1	账户工具
E2E_UTILITY=1	实用工具
E2E_TRANSACTION=1	交易工具
E2E_ALGOD=1	Algod 工具
E2E_ALGOD_API=1	Algod API 工具
E2E_INDEXER_API=1	Indexer API 工具
E2E_NFD=1	NFDomains 工具
E2E_TINYMAN=1	Tinyman 工具
E2E_ARC26=1	ARC-26 工具
E2E_KNOWLEDGE=1	知识工具

重要： 设置任何单独的标志（例如 E2E_WALLET=1）都会禁用所有其他类别，除非同时设置 E2E_ALL=1。

启用特定工具

E2E_TOOLS=ping,validate_address npm run test:e2e

E2E_TOOLS 变量接受以逗号分隔的工具名称列表。仅运行这些特定工具的测试。

测试文件结构

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

Jest 配置

配置	用途	关键设置
jest.config.js（根目录）	单元测试	testTimeout: 10s、并行工作进程、testMatch: tests/unit/**
tests/jest.config.e2e.js	E2E 测试	testTimeout: 60s、maxWorkers: 1（串行）、globalSetup/globalTeardown
tsconfig.test.json	测试用 TypeScript	rootDir: "."，包含 src/ 和 tests/

编写新测试

单元测试模板：

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

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

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

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

E2E 测试模板：

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

依赖项

• algosdk v3 — Algorand JavaScript SDK
• @modelcontextprotocol/sdk — MCP TypeScript SDK
• @napi-rs/keyring — 原生操作系统密钥链访问（macOS Keychain、Linux libsecret、Windows Credential Manager）。用于为数据库迁移前安装创建的账户提供向后兼容的读取回退；新的助记词仅写入 wallet.db。
• sql.js — 用于持久化钱包元数据的嵌入式 SQLite（WASM）
• @noble/curves — 用于原始数据签名（wallet_sign_data）的纯 JS Ed25519
• @tinymanorg/tinyman-js-sdk — Tinyman AMM SDK
• @alpha-arcade/sdk — Alpha Arcade 预测市场 SDK
• zod — 运行时类型验证
• qrcode — 用于 ARC-26 的 QR 码生成

License

MIT