Algorand MCP 实现

概述

模型上下文协议 (Model context protocol) 或 MCP，是一个开放协议，用于标准化应用程序如何向 LLM 提供上下文。 MCP 提供规范标准，为 LLM 提供工具、资源和指令，使其更有用和有效。

MCP Github 包含更多信息以及不同的工具和规范，以及 MCP 的文档。

此存储库是 Algorand 区块链交互的模型上下文协议 (MCP) 实现。 该实现包括：

• (生产环境) 用于区块链交互的服务器包（仅限 Node.js）
• (开发中) 用于钱包管理和交易签名的客户端包（支持浏览器和 Node.js）

📦 此存储库中的包：

• Algorand MCP 服务器 - Algorand MCP 服务器完整实现。
• Algorand MCP 客户端 - Algorand MCP 客户端，用于客户端钱包管理和交易签名，以及其他 Agent 主机的集成。

📦 NPM：

• Algorand MCP 服务器 NPM 包 - 通过 NPM 包安装实现的 Algorand MCP 服务器。

📦 Smithery：

• Smithery 上的 Algorand MCP 服务器 - 通过 smithery 实现的 Algorand MCP 服务器。

特性

• 完整的 Algorand 区块链交互能力
• 广泛的钱包管理系统
• 全面的交易处理
• 丰富的区块链状态查询
• 内置安全功能
• 支持 Claude Desktop 和 Cursor 集成

要求

• Node.js v23.6.1 或更高版本
• npm v10.2.4 或更高版本

安装

通过 NPM（适用于希望运行自己的实例的开发人员）

# 安装客户端和服务器包
npm install algorand-mcp

通过 Smithery（适用于所有用户）

通过 Smithery（适用于 Claude Desktop）

只需在终端中运行以下命令：

npx -y @smithery/cli@latest install @GoPlausible/algorand-mcp --client claude --config "{\"NFD_API_KEY\":\"\",\"NFD_API_URL\":\"https://api.nf.domains\",\"ALGORAND_ALGOD\":\"https://testnet-api.algonode.cloud\",\"ALGORAND_TOKEN\":\"\",\"ITEMS_PER_PAGE\":\"10\",\"VESTIGE_API_KEY\":\"\",\"VESTIGE_API_URL\":\"https://api.vestigelabs.org\",\"ALGORAND_INDEXER\":\"https://testnet-idx.algonode.cloud\",\"ALGORAND_NETWORK\":\"testnet\",\"ALGORAND_ALGOD_API\":\"https://testnet-api.algonode.cloud/v2\",\"ALGORAND_ALGOD_PORT\":\"\",\"ALGORAND_INDEXER_API\":\"https://testnet-idx.algonode.cloud/v2\",\"ALGORAND_INDEXER_PORT\":\"\"}"

通过 Smithery（适用于 Cursor）

只需在终端中运行以下命令：

npx -y @smithery/cli@latest install @GoPlausible/algorand-mcp --client cursor --config "{\"NFD_API_KEY\":\"\",\"NFD_API_URL\":\"https://api.nf.domains\",\"ALGORAND_ALGOD\":\"https://testnet-api.algonode.cloud\",\"ALGORAND_TOKEN\":\"\",\"ITEMS_PER_PAGE\":\"10\",\"VESTIGE_API_KEY\":\"\",\"VESTIGE_API_URL\":\"https://api.vestigelabs.org\",\"ALGORAND_INDEXER\":\"https://testnet-idx.algonode.cloud\",\"ALGORAND_NETWORK\":\"testnet\",\"ALGORAND_ALGOD_API\":\"https://testnet-api.algonode.cloud/v2\",\"ALGORAND_ALGOD_PORT\":\"\",\"ALGORAND_INDEXER_API\":\"https://testnet-idx.algonode.cloud/v2\",\"ALGORAND_INDEXER_PORT\":\"\"}"

重要提示 使用 Smithery UI 复制命令时，请确保在单击连接之前设置 ITEMS_PER_PAGE，以便将所有 ENV 变量都带到命令中，否则您的命令将不包含 Algorand MCP 运行所需的环境变量！

项目架构

该项目遵循模块化架构，包含两个主要包：

1. 服务器包 (@algorand-mcp/server)

   • 提供 MCP 工具和资源
   • 管理区块链交互
   • 处理交易创建和提交
   • 提供全面的区块链查询

2. 客户端包 (@algorand-mcp/client)

   • 处理钱包连接和交易签名
   • 支持本地和外部钱包
   • 通用兼容性（浏览器/Node.js）
   • 安全的凭证管理
   • 仍在开发中（服务器工作与客户端状态无关）

项目结构

algorand-mcp/
├── packages/
│   ├── client/                    # 客户端包
│   │   ├── src/
│   │   │   ├── index.ts          # 客户端入口点和钱包管理
│   │   │   └── LocalWallet.ts    # 本地钱包实现
│   │   ├── package.json
│   │   └── tsconfig.json
│   └── server/                    # 服务器包
│       ├── src/
│       │   ├── resources/         # MCP 资源
│       │   │   ├── algod/        # 实时区块链状态
│       │   │   ├── indexer/      # 历史区块链数据
│       │   │   ├── nfd/          # NFDomains 名称服务
│       │   │   ├── vestige/      # DeFi 分析和跟踪
│       │   │   ├── tinyman/      # Tinyman AMM 集成
│       │   │   └── ultrade/      # Ultrade DEX 集成
│       │   ├── tools/            # MCP 工具
│       │   │   ├── accountManager.ts     # 账户操作
│       │   │   ├── algodManager.ts       # 节点交互
│       │   │   ├── utilityManager.ts     # 实用函数
│       │   │   ├── resource_tools/       # 资源工具
│       │   │   │   ├── algod/           # Algod 资源工具
│       │   │   │   ├── indexer/         # Indexer 资源工具
│       │   │   │   ├── nfd/            # NFDomains 工具
│       │   │   │   ├── vestige/        # Vestige DeFi 工具
│       │   │   │   ├── tinyman/        # Tinyman AMM 工具
│       │   │   │   └── ultrade/        # Ultrade DEX 工具
│       │   │   └── transactionManager/   # 交易处理
│       │   ├── env.ts            # 环境配置
│       │   └── index.ts          # 服务器入口点
│       ├── package.json
│       └── tsconfig.json
├── package.json                   # 根包文件
└── tsconfig.json                 # 根 TypeScript 配置

核心功能

服务器特性

• 账户管理
• 资产操作
• 应用程序交互
• 交易创建和提交
• 区块链状态查询
• 全面的实用函数
• 标准化响应格式
• 内置分页支持
• NFDomains 集成
• Vestige DeFi 分析
• Tinyman AMM 集成
• Ultrade DEX 集成

客户端特性（开发中）

• 具有安全存储的本地钱包
• 外部钱包支持（Pera、Defly、Daffi）
• 交易签名
• 会话管理
• 通用 ES 模块支持

响应格式

所有响应都遵循标准化格式：

{
  "data": {
    // 响应数据
  },
  "metadata": {  // 仅用于分页响应
    "totalItems": number,
    "itemsPerPage": number,
    "currentPage": number,
    "totalPages": number,
    "hasNextPage": boolean,
    "pageToken": string,
    "arrayField": string  // 分页数组字段的名称
  }
}

错误以标准化格式返回：

{
  "error": {
    "code": string,
    "message": string
  }
}

可用工具和资源

Algorand MCP 实现提供 125 个用于区块链交互的工具和资源：

• 40 个基本工具（账户、资产、应用程序、交易管理）
• 30 个资源工具（algod 和 indexer）
• 6 个用于名称服务的 NFDomains (NFD) 工具
• 28 个用于 DeFi 分析的 Vestige 工具
• 9 个用于 AMM 交互的 Tinyman 工具
• 12 个用于 DEX 功能的 Ultrade 工具

资源工具

Algod 资源工具

• resource_algod_get_account_info：获取当前账户余额、资产和授权地址
• resource_algod_get_account_application_info：获取账户特定的应用程序信息
• resource_algod_get_account_asset_info：获取账户特定的资产信息
• resource_algod_get_application_by_id：获取应用程序信息
• resource_algod_get_application_box：按名称获取应用程序 box
• resource_algod_get_application_boxes：获取所有应用程序 box
• resource_algod_get_asset_by_id：获取当前资产信息
• resource_algod_get_pending_transaction：获取待处理交易信息
• resource_algod_get_pending_transactions_by_address：获取地址的待处理交易
• resource_algod_get_pending_transactions：获取所有待处理交易
• resource_algod_get_transaction_params：获取建议的交易参数
• resource_algod_get_node_status：获取当前节点状态
• resource_algod_get_node_status_after_block：获取特定轮次后的节点状态

Indexer 资源工具

• resource_indexer_lookup_account_by_id：获取账户信息
• resource_indexer_lookup_account_assets：获取账户资产
• resource_indexer_lookup_account_app_local_states：获取账户应用程序本地状态
• resource_indexer_lookup_account_created_applications：获取账户创建的应用程序
• resource_indexer_search_for_accounts：使用各种条件搜索账户
• resource_indexer_lookup_applications：获取应用程序信息
• resource_indexer_lookup_application_logs：获取应用程序日志消息
• resource_indexer_search_for_applications：搜索应用程序
• resource_indexer_lookup_asset_by_id：获取资产信息和配置
• resource_indexer_lookup_asset_balances：获取持有此资产的账户
• resource_indexer_lookup_asset_transactions：获取涉及此资产的交易
• resource_indexer_search_for_assets：搜索资产
• resource_indexer_lookup_transaction_by_id：获取交易信息
• resource_indexer_lookup_account_transactions：获取账户交易历史记录
• resource_indexer_search_for_transactions：搜索交易

NFDomains (NFD) 资源工具

• resource_nfd_get_nfd：按名称或应用程序 ID 获取 NFD
• resource_nfd_get_nfds_for_addresses：获取特定地址的 NFD
• resource_nfd_get_nfd_activity：获取 NFD 的活动/更改
• resource_nfd_get_nfd_analytics：获取 NFD 的分析数据
• resource_nfd_browse_nfds：使用各种过滤器浏览 NFD
• resource_nfd_search_nfds：使用各种过滤器搜索 NFD

Vestige 资源工具

1. 查看工具：

• resource_vestige_view_networks：获取所有网络
• resource_vestige_view_network_by_id：按 ID 获取网络
• resource_vestige_view_protocols：获取所有协议
• resource_vestige_view_protocol_by_id：按 ID 获取协议
• resource_vestige_view_protocol_volumes：获取特定日期的协议交易量
• resource_vestige_view_assets：获取有关资产的数据
• resource_vestige_view_assets_list：获取资产列表
• resource_vestige_view_assets_search：按查询搜索资产
• resource_vestige_view_asset_price：获取资产价格
• resource_vestige_view_asset_candles：获取资产蜡烛图
• resource_vestige_view_asset_history：获取资产交易量、交换、总锁定、vwap 和置信度历史记录
• resource_vestige_view_asset_composition：获取基于协议和交易对的资产锁定
• resource_vestige_view_pools：获取池
• resource_vestige_view_vaults：获取所有 vault
• resource_vestige_view_balances：按网络 ID、协议 ID 和资产 ID 获取余额
• resource_vestige_view_notes：按网络 ID 和可选的资产 ID 获取 notes
• resource_vestige_view_first_asset_notes：获取资产的第一个 note
• resource_vestige_view_asset_notes_count：获取资产的 notes 计数
• resource_vestige_view_swaps：获取交换

2. 交换工具：

• resource_vestige_get_best_v4_swap_data：获取最佳 V4 交换数据
• resource_vestige_get_v4_swap_discount：获取 V4 交换折扣
• resource_vestige_get_v4_swap_data_transactions：获取 V4 交换数据交易
• resource_vestige_get_aggregator_stats：获取聚合器统计信息

3. 货币工具：

• resource_vestige_view_currency_prices：获取所有最新的货币价格
• resource_vestige_view_currency_price_history：按时间戳范围获取货币价格
• resource_vestige_view_currency_price：按时间戳获取货币价格
• resource_vestige_view_currency_average_price：获取货币的平均价格
• resource_vestige_view_currency_prices_simple_30d：获取过去 30 天的货币价格

Tinyman 资源工具

• resource_tinyman_get_pool：按资产对获取 Tinyman 池信息
• resource_tinyman_get_pool_analytics：获取 Tinyman 池的分析
• resource_tinyman_get_pool_creation_quote：获取创建新池的报价
• resource_tinyman_get_liquidity_quote：获取添加流动性的报价
• resource_tinyman_get_remove_liquidity_quote：获取移除流动性的报价
• resource_tinyman_get_swap_quote：获取交换资产的报价
• resource_tinyman_get_asset_optin_quote：获取选择加入池 token 的报价
• resource_tinyman_get_validator_optin_quote：获取选择加入验证器的报价
• resource_tinyman_get_validator_optout_quote：获取选择退出验证器的报价

Ultrade 资源工具

1. 钱包工具：

• resource_ultrade_wallet_signin_message：从登录数据生成消息
• resource_ultrade_wallet_signin：登录到交易账户
• resource_ultrade_wallet_add_key：添加交易密钥
• resource_ultrade_wallet_revoke_key：撤销交易密钥
• resource_ultrade_wallet_keys：获取交易密钥
• resource_ultrade_wallet_key_message：从交易密钥数据生成消息
• resource_ultrade_wallet_trades：获取过滤后的钱包交易
• resource_ultrade_wallet_transactions：获取过滤后的钱包交易
• resource_ultrade_wallet_withdraw：提取 token
• resource_ultrade_wallet_withdraw_message：从提款数据生成消息

2. 市场工具：

• resource_ultrade_market_symbols：获取市场符号
• resource_ultrade_market_details：获取市场详细信息
• resource_ultrade_market_price：按交易对符号获取最后市场价格
• resource_ultrade_market_depth：获取订单簿深度
• resource_ultrade_market_last_trades：获取最后交易
• resource_ultrade_market_history：获取市场历史记录
• resource_ultrade_market_assets：获取交易资产
• resource_ultrade_market_fee_rates：获取费用率
• resource_ultrade_market_chains：获取区块链链
• resource_ultrade_market_withdrawal_fee：获取提款费用
• resource_ultrade_market_operation_details：获取操作详细信息
• resource_ultrade_market_settings：获取市场设置
• resource_ultrade_market_orders：获取订单
• resource_ultrade_market_open_orders：获取未结订单
• resource_ultrade_market_order_by_id：按 ID 获取订单
• resource_ultrade_market_order_message：从订单数据生成消息
• resource_ultrade_market_create_order：创建新订单
• resource_ultrade_market_create_orders：创建新订单
• resource_ultrade_market_cancel_order：取消未结订单
• resource_ultrade_market_cancel_orders：取消多个未结订单

3. 系统工具：

• resource_ultrade_system_time：获取当前系统时间
• resource_ultrade_system_maintenance：获取系统维护状态
• resource_ultrade_system_version：获取系统版本

账户管理工具

• create_account：创建一个新的 Algorand 账户
• rekey_account：将账户重新授权给新地址
• validate_address：检查 Algorand 地址是否有效
• encode_address：将公钥编码为 Algorand 地址
• decode_address：将 Algorand 地址解码为公钥

应用程序工具

• 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：创建应用程序调用交易
• get_application_address：获取给定应用程序 ID 的地址
• compile_teal：编译 TEAL 源代码
• disassemble_teal：将 TEAL 字节码反汇编回源代码

资产工具

• make_asset_create_txn：创建资产创建交易
• make_asset_config_txn：创建资产配置交易
• make_asset_destroy_txn：创建资产销毁交易
• make_asset_freeze_txn：创建资产冻结交易
• make_asset_transfer_txn：创建资产转移交易

交易工具

• send_raw_transaction：将签名后的交易提交到网络
• simulate_raw_transactions：模拟原始交易
• simulate_transactions：使用详细配置模拟交易
• make_payment_txn：创建支付交易
• assign_group_id：将组 ID 分配给交易列表
• sign_transaction：使用私钥签署交易

密钥管理工具

• mnemonic_to_mdk：将助记词转换为主派生密钥
• mdk_to_mnemonic：将主派生密钥转换为助记词
• secret_key_to_mnemonic：将私钥转换为助记词
• mnemonic_to_secret_key：将助记词转换为私钥
• seed_from_mnemonic：从助记词生成种子
• mnemonic_from_seed：从种子生成助记词
• sign_bytes：使用私钥签署任意字节

实用工具

• bytes_to_bigint：将字节转换为 BigInt
• bigint_to_bytes：将 BigInt 转换为字节
• encode_uint64：将 uint64 编码为字节
• decode_uint64：将字节解码为 uint64
• generate_algorand_uri：根据 ARC-26 规范生成 Algorand URI 和 QR 码

依赖项

• algosdk：Algorand JavaScript SDK
• @perawallet/connect：Pera Wallet 连接器
• @blockshake/defly-connect：Defly Wallet 连接器
• @daffiwallet/connect：Daffi Wallet 连接器

许可证

MIT