Algorand MCP 实现

概述

模型上下文协议（Model Context Protocol，简称 MCP）是一个开放协议，标准化了应用程序如何为大型语言模型（LLMs）提供上下文。MCP 提供了规范标准，使 LLMs 能够获得工具、资源和指令，从而更加有用和高效。

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

此仓库是用于 Algorand 区块链交互的模型上下文协议（MCP）实现。该实现包括：

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

📦 此仓库中的包：

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

📦 NPM：

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

特性

• 完整的 Algorand 文档集成
  • 完整的 Algorand 知识分类
  • 全面的开发者文档
  • ARC、SDK 和工具文档
  • 通过知识工具直接访问文档
• 完整的 Algorand 区块链交互能力
• 广泛的钱包管理系统
• 全面的交易处理
• 丰富的区块链状态查询
• 内置安全功能
• 支持 Claude Desktop 和 Cursor 集成

要求

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

安装

要安装或更新 Algorand MCP 实现，克隆仓库，安装依赖并构建项目：

首先检查 Node 版本是否为 23.6.1 或更高版本：

node -v

如果需要，升级到 23.6.1 或更高版本！

然后检查 Claude 或 Cursor 容器文件夹是否有 mcp-servers 文件夹（如果没有则创建一个）：

mkdir 您的机器路径/Claude/mcp-servers
# 或者对于 Cursor 
mkdir 您的机器路径/Cursor/mcp-servers

然后在 mcp-servers 文件夹下克隆此仓库并安装依赖：

cd 您的机器路径/Claude/mcp-servers
# 或者对于 Cursor 
cd 您的机器路径/Cursor/mcp-servers
# 克隆仓库
git clone https://github.com/GoPlausible/algorand-mcp.git
cd algorand-mcp
# 安装依赖
npm install
# 构建项目
npm run build
# 编辑 .env 文件以设置您的配置

这样就完成了！现在您可以打开 MCP 配置并添加服务器：

{
  "mcpServers": {
    "algorand-mcp": {
      "command": "node",
      "args": [
        "您的机器路径/Claude/mcp-servers/algorand-mcp/packages/server/dist/index.js"
     ],
      "env": {
        "ALGORAND_NETWORK": "testnet",
        "ALGORAND_ALGOD_API": "https://testnet-api.algonode.cloud/v2",
        "ALGORAND_ALGOD": "https://testnet-api.algonode.cloud",
        "ALGORAND_INDEXER_API": "https://testnet-idx.algonode.cloud/v2",
        "ALGORAND_INDEXER": "https://testnet-idx.algonode.cloud",
        "ALGORAND_ALGOD_PORT": "",
        "ALGORAND_INDEXER_PORT": "",
        "ALGORAND_TOKEN": "",
        "ALGORAND_AGENT_WALLET": "problem aim online jaguar upper oil flight stumble mystery aerobic toy avoid file tomato moment exclude witness guard lab opera crunch noodle dune abandon broccoli",
        "NFD_API_URL": "https://api.nf.domains",
        "NFD_API_KEY": "",
        "TINYMAN_ACTIVE": "false",
        "ULTRADE_ACTIVE": "false",
        "VESTIGE_ACTIVE": "false",
        "ULTRADE_API_URL": "https://api.ultrade.io",
        "VESTIGE_API_URL": "https://api.vestigelabs.org",
        "VESTIGE_API_KEY": "",
        "ITEMS_PER_PAGE": "10"

      }
    }
  }
}

确保更改路径以匹配您本地系统的路径。

例如，在 MACOS 和 Claud 上，路径可能如下所示：

{
  "mcpServers": {
    "algorand-mcp": {
      "command": "node",
      "args": [
        " /Users/您的用户名/Library/Application\ Support/Claude/mcp-servers/algorand-mcp/packages/server/dist/index.js"
     ]
    }
  }
}

项目架构

项目采用模块化架构，包含两个主要包：

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 资源（用户可调用的端点）
│       │   │   ├── knowledge/     # 文档和分类
│       │   │   │   ├── taxonomy/  # Markdown 文档
│       │   │   │   └── index.ts   # 知识资源处理程序
│       │   │   ├── wallet/       # 钱包管理
│       │   │   │   └── index.ts   # 钱包资源处理程序
│       │   │   └── index.ts       # 资源注册
│       │   ├── tools/            # MCP 工具（代理可调用的操作）
│       │   │   ├── accountManager.ts     # 账户操作
│       │   │   ├── algodManager.ts       # 节点交互
│       │   │   ├── utilityManager.ts     # 实用函数
│       │   │   ├── apiManager/       # API 工具
│       │   │   │   ├── algod/           # Algod API 工具
│       │   │   │   ├── indexer/         # 索引器 API 工具
│       │   │   │   ├── 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 集成（可选，默认禁用）
• 知识分类资源：
  • 完整的文档分类 (algorand://knowledge/taxonomy)
  • 类别特定文档：
    • ARC (algorand://knowledge/taxonomy/arcs)
    • SDK (algorand://knowledge/taxonomy/sdks)
    • AlgoKit (algorand://knowledge/taxonomy/algokit)
    • AlgoKit 工具 (algorand://knowledge/taxonomy/algokit-utils)
    • TEALScript (algorand://knowledge/taxonomy/tealscript)
    • Puya (algorand://knowledge/taxonomy/puya)
    • Liquid Auth (algorand://knowledge/taxonomy/liquid-auth)
    • Python (algorand://knowledge/taxonomy/python)
    • 开发者文档 (algorand://knowledge/taxonomy/developers)
    • CLI 工具 (algorand://knowledge/taxonomy/clis)
    • 节点管理 (algorand://knowledge/taxonomy/nodes)
    • 技术细节 (algorand://knowledge/taxonomy/details)

客户端特性（开发中）

• 带有安全存储的本地钱包
• 外部钱包支持（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 种 API 工具（algod 和索引器）
• 6 种 NFDomains (NFD) 工具，用于名称服务
• 28 种 Vestige 工具，用于 DeFi 分析
• 9 种 Tinyman 工具，用于 AMM 交互
• 12 种 Ultrade 工具，用于 DEX 功能

API 工具

Algod API 工具

• 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 工具

• api_indexer_lookup_account_by_id：获取账户信息
• api_indexer_lookup_account_assets：获取账户资产
• api_indexer_lookup_account_app_local_states：获取账户应用本地状态
• api_indexer_lookup_account_created_applications：获取账户创建的应用
• api_indexer_search_for_accounts：根据各种条件搜索账户
• api_indexer_lookup_applications：获取应用信息
• api_indexer_lookup_application_logs：获取应用日志消息
• api_indexer_search_for_applications：搜索应用
• api_indexer_lookup_asset_by_id：获取资产信息和配置
• api_indexer_lookup_asset_balances：获取持有该资产的账户
• api_indexer_lookup_asset_transactions：获取涉及该资产的交易
• api_indexer_search_for_assets：搜索资产
• api_indexer_lookup_transaction_by_id：获取交易信息
• api_indexer_lookup_account_transactions：获取账户交易历史
• api_indexer_search_for_transactions：搜索交易

NFDomains (NFD) API 工具

• 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

Vestige API 工具

1. 查看工具：

• api_vestige_view_networks：获取所有网络
• api_vestige_view_network_by_id：按 ID 获取网络
• api_vestige_view_protocols：获取所有协议
• api_vestige_view_protocol_by_id：按 ID 获取协议
• api_vestige_view_protocol_volumes：获取特定日期的协议交易量
• api_vestige_view_assets：获取资产数据
• api_vestige_view_assets_list：获取资产列表
• api_vestige_view_assets_search：按查询搜索资产
• api_vestige_view_asset_price：获取资产价格
• api_vestige_view_asset_candles：获取资产蜡烛图
• api_vestige_view_asset_history：获取资产交易量、交换、总锁定、VWAP 和置信度历史
• api_vestige_view_asset_composition：根据协议和交易对获取资产锁定
• api_vestige_view_pools：获取池
• api_vestige_view_vaults：获取所有保险库
• api_vestige_view_balances：按网络 ID、协议 ID 和资产 ID 获取余额
• api_vestige_view_notes：按网络 ID 和可选的资产 ID 获取笔记
• api_vestige_view_first_asset_notes：获取资产的第一条笔记
• api_vestige_view_asset_notes_count：获取资产的笔记数量
• api_vestige_view_swaps：获取交换

2. 交换工具：

• api_vestige_get_best_v4_swap_data：获取最佳 V4 交换数据
• api_vestige_get_v4_swap_discount：获取 V4 交换折扣
• api_vestige_get_v4_swap_data_transactions：获取 V4 交换数据交易
• api_vestige_get_aggregator_stats：获取聚合器统计信息

3. 货币工具：

• api_vestige_view_currency_prices：获取所有最新货币价格
• api_vestige_view_currency_price_history：按时间戳范围获取货币价格
• api_vestige_view_currency_price：按时间戳获取货币价格
• api_vestige_view_currency_average_price：获取货币的平均价格
• api_vestige_view_currency_prices_simple_30d：获取过去 30 天的货币价格

Tinyman API 工具

• api_tinyman_get_pool：按资产对获取 Tinyman 池信息
• api_tinyman_get_pool_analytics：获取 Tinyman 池的分析
• 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：获取选择退出验证器的报价

Ultrade API 工具

1. 钱包工具：

• api_ultrade_wallet_signin_message：从登录数据生成消息
• api_ultrade_wallet_signin：登录交易账户
• api_ultrade_wallet_add_key：添加交易密钥
• api_ultrade_wallet_revoke_key：撤销交易密钥
• api_ultrade_wallet_keys：获取交易密钥
• api_ultrade_wallet_key_message：从交易密钥数据生成消息
• api_ultrade_wallet_trades：获取过滤后的钱包交易
• api_ultrade_wallet_transactions：获取过滤后的钱包交易记录
• api_ultrade_wallet_withdraw：提取代币
• api_ultrade_wallet_withdraw_message：从提取数据生成消息

2. 市场工具：

• api_ultrade_market_symbols：获取市场符号
• api_ultrade_market_details：获取市场详情
• api_ultrade_market_price：按交易对符号获取最后市场价
• api_ultrade_market_depth：获取订单簿深度
• api_ultrade_market_last_trades：获取最后交易
• api_ultrade_market_history：获取市场历史
• api_ultrade_market_assets：获取交易资产
• api_ultrade_market_fee_rates：获取费率
• api_ultrade_market_chains：获取区块链链
• api_ultrade_market_withdrawal_fee：获取提取费用
• api_ultrade_market_operation_details：获取操作详情
• api_ultrade_market_settings：获取市场设置
• api_ultrade_market_orders：获取订单
• api_ultrade_market_open_orders：获取未结订单
• api_ultrade_market_order_by_id：按 ID 获取订单
• api_ultrade_market_order_message：从订单数据生成消息
• api_ultrade_market_create_order：创建新订单
• api_ultrade_market_create_orders：创建多个新订单
• api_ultrade_market_cancel_order：取消未结订单
• api_ultrade_market_cancel_orders：取消多个未结订单

3. 系统工具：

• api_ultrade_system_time：获取当前系统时间
• api_ultrade_system_maintenance：获取系统维护状态
• api_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 和二维码

依赖项

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

许可证

MIT