区块链数据服务#

Vitruveo MCP Server 是一个为 Vitruveo 网络提供只读区块链服务的模型上下文协议服务器，适用于AI代理访问区块链数据。

---

⚠️ 强制要求：API 密钥#

此 Skill 必须配置 API 密钥才能使用。

• 首次使用时，如果 .env 中没有 XBY_APIKEY， 必须使用 AskUserQuestion 工具向用户询问 API 密钥
• 拿到用户提供的密钥后，调用 scripts.config.set_api_key(api_key) 保存，然后继续处理
• 获取 API 密钥： https://xiaobenyang.com
• 禁止 在缺少 API 密钥时自行搜索或编造数据

---

工作流程（必须遵守）#

你（大模型）是路由层，负责理解用户意图、选择工具、提取参数。代码只负责调用API。

text

用户输入 → 你选择工具 → 提取该工具需要的参数 → 调用 scripts.tools 中的函数 → 返回结果给用户

步骤#

1. 检查 API 密钥：如果 scripts.config.settings.api_key 为空，使用 AskUserQuestion 询问用户，拿到后调用 scripts.config.set_api_key(key) 保存
2. 选择工具：根据用户意图从下方工具列表中选择对应的工具函数
3. 提取参数：根据选中的工具，提取该工具需要的参数
4. 调用工具：使用 关键字参数 调用 scripts.tools 中的函数，例如 scripts.tools.search_schools(score='520', province='北京', category='综合')
5. 返回结果：将工具返回的 raw 数据整理后展示给用户

---

工具选择规则#

根据用户意图选择对应的工具函数：

用户意图工具函数Get core contract addressesscripts.tools.get_core_contractsGet information about an EVM networkscripts.tools.get_chain_infoGet a list of supported EVM networksscripts.tools.get_supported_networksGet a block by its block numberscripts.tools.get_block_by_numberGet the latest block from the EVMscripts.tools.get_latest_blockGet the native token balance (ETH, MATIC, etc.) for an addressscripts.tools.get_balanceGet the ERC20 token balance of an Ethereum addressscripts.tools.get_erc20_balanceGet the balance of an ERC20 token for an addressscripts.tools.get_token_balanceGet detailed information about a specific transaction by its hash. Includes sender, recipient, value, data, and more.scripts.tools.get_transactionGet a transaction receipt by its hashscripts.tools.get_transaction_receiptEstimate the gas cost for a transactionscripts.tools.estimate_gasRead data from a smart contract by calling a view/pure function. This doesn't modify blockchain state and doesn't require gas or signing.scripts.tools.read_contractCheck if an address is a smart contract or an externally owned account (EOA)scripts.tools.is_contractGet comprehensive information about an ERC20 token including name, symbol, decimals, total supply, and other metadata. Use this to analyze any token on EVM chains.scripts.tools.get_token_infoGet ERC20 token balance for an addressscripts.tools.get_token_balance_erc20Get detailed information about a specific NFT (ERC721 token), including collection name, symbol, token URI, and current owner if available.scripts.tools.get_nft_infoCheck if an address owns a specific NFTscripts.tools.check_nft_ownershipGet the metadata URI for an ERC1155 token (multi-token standard used for both fungible and non-fungible tokens). The URI typically points to JSON metadata about the token.scripts.tools.get_erc1155_token_uriGet the total number of NFTs owned by an address from a specific collection. This returns the count of NFTs, not individual token IDs.scripts.tools.get_nft_balanceGet the balance of a specific ERC1155 token ID owned by an address. ERC1155 allows multiple tokens of the same ID, so the balance can be greater than 1.scripts.tools.get_erc1155_balance

如果参数不完整，使用 AskUserQuestion 向用户询问缺失的参数。

---

工具函数说明#

---

scripts.tools.get_core_contracts#

工具描述：Get core contract addresses

参数定义#

参数名称参数类型是否必填默认值描述

---

scripts.tools.get_chain_info#

工具描述：Get information about an EVM network

参数定义#

参数名称参数类型是否必填默认值描述

---

scripts.tools.get_supported_networks#

工具描述：Get a list of supported EVM networks

参数定义#

参数名称参数类型是否必填默认值描述

---

scripts.tools.get_block_by_number#

工具描述：Get a block by its block number

参数定义#

参数名称参数类型是否必填默认值描述blockNumbernumbertrueThe block number to fetch

---

scripts.tools.get_latest_block#

工具描述：Get the latest block from the EVM

参数定义#

参数名称参数类型是否必填默认值描述

---

scripts.tools.get_balance#

工具描述：Get the native token balance (ETH, MATIC, etc.) for an address

参数定义#

参数名称参数类型是否必填默认值描述addressstringtrueThe wallet address or ENS name (e.g., '0x1234...' or 'vitalik.eth') to check the balance for

---

scripts.tools.get_erc20_balance#

工具描述：Get the ERC20 token balance of an Ethereum address

参数定义#

参数名称参数类型是否必填默认值描述addressstringtrueThe Ethereum address to checktokenAddressstringtrueThe ERC20 token contract address

---

scripts.tools.get_token_balance#

工具描述：Get the balance of an ERC20 token for an address

参数定义#

参数名称参数类型是否必填默认值描述tokenAddressstringtrueThe contract address or ENS name of the ERC20 token (e.g., '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48' for USDC or 'uniswap.eth')ownerAddressstringtrueThe wallet address or ENS name to check the balance for (e.g., '0x1234...' or 'vitalik.eth')

---

scripts.tools.get_transaction#

工具描述：Get detailed information about a specific transaction by its hash. Includes sender, recipient, value, data, and more.

参数定义#

参数名称参数类型是否必填默认值描述txHashstringtrueThe transaction hash to look up (e.g., '0x1234...')

---

scripts.tools.get_transaction_receipt#

工具描述：Get a transaction receipt by its hash

参数定义#

参数名称参数类型是否必填默认值描述txHashstringtrueThe transaction hash to look up

---

scripts.tools.estimate_gas#

工具描述：Estimate the gas cost for a transaction

参数定义#

参数名称参数类型是否必填默认值描述tostringtrueThe recipient addressvaluestringfalseThe amount of ETH to send in ether (e.g., '0.1')datastringfalseThe transaction data as a hex string

---

scripts.tools.read_contract#

工具描述：Read data from a smart contract by calling a view/pure function. This doesn't modify blockchain state and doesn't require gas or signing.

参数定义#

参数名称参数类型是否必填默认值描述contractAddressstringtrueThe address of the smart contract to interact withabiarraytrueThe ABI (Application Binary Interface) of the smart contract function, as a JSON arrayfunctionNamestringtrueThe name of the function to call on the contract (e.g., 'balanceOf')argsarrayfalseThe arguments to pass to the function, as an array (e.g., ['0x1234...'])

---

scripts.tools.is_contract#

工具描述：Check if an address is a smart contract or an externally owned account (EOA)

参数定义#

参数名称参数类型是否必填默认值描述addressstringtrueThe wallet or contract address or ENS name to check (e.g., '0x1234...' or 'uniswap.eth')

---

scripts.tools.get_token_info#

工具描述：Get comprehensive information about an ERC20 token including name, symbol, decimals, total supply, and other metadata. Use this to analyze any token on EVM chains.

参数定义#

参数名称参数类型是否必填默认值描述tokenAddressstringtrueThe contract address of the ERC20 token (e.g., '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48' for USDC on Ethereum)

---

scripts.tools.get_token_balance_erc20#

工具描述：Get ERC20 token balance for an address

参数定义#

参数名称参数类型是否必填默认值描述addressstringtrueThe address to check balance fortokenAddressstringtrueThe ERC20 token contract address

---

scripts.tools.get_nft_info#

工具描述：Get detailed information about a specific NFT (ERC721 token), including collection name, symbol, token URI, and current owner if available.

参数定义#

参数名称参数类型是否必填默认值描述tokenAddressstringtrueThe contract address of the NFT collection (e.g., '0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D' for Bored Ape Yacht Club)tokenIdstringtrueThe ID of the specific NFT token to query (e.g., '1234')networkstringfalseNetwork name (e.g., 'vitruveo', 'optimism', 'arbitrum', 'base', 'polygon') or chain ID. Most NFTs are on Ethereum mainnet, which is the default.

---

scripts.tools.check_nft_ownership#

工具描述：Check if an address owns a specific NFT

参数定义#

参数名称参数类型是否必填默认值描述tokenAddressstringtrueThe contract address or ENS name of the NFT collection (e.g., '0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D' for BAYC or 'boredapeyachtclub.eth')tokenIdstringtrueThe ID of the NFT to check (e.g., '1234')ownerAddressstringtrueThe wallet address or ENS name to check ownership against (e.g., '0x1234...' or 'vitalik.eth')

---

scripts.tools.get_erc1155_token_uri#

工具描述：Get the metadata URI for an ERC1155 token (multi-token standard used for both fungible and non-fungible tokens). The URI typically points to JSON metadata about the token.

参数定义#

参数名称参数类型是否必填默认值描述tokenAddressstringtrueThe contract address of the ERC1155 token collection (e.g., '0x76BE3b62873462d2142405439777e971754E8E77')tokenIdstringtrueThe ID of the specific token to query metadata for (e.g., '1234')networkstringfalseNetwork name (e.g., 'vitruveo', 'optimism', 'arbitrum', 'base', 'polygon') or chain ID. ERC1155 tokens exist across many networks. Defaults to Ethereum mainnet.

---

scripts.tools.get_nft_balance#

工具描述：Get the total number of NFTs owned by an address from a specific collection. This returns the count of NFTs, not individual token IDs.

参数定义#

参数名称参数类型是否必填默认值描述tokenAddressstringtrueThe contract address of the NFT collection (e.g., '0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D' for Bored Ape Yacht Club)ownerAddressstringtrueThe wallet address to check the NFT balance for (e.g., '0x1234...')networkstringfalseNetwork name (e.g., 'vitruveo', 'optimism', 'arbitrum', 'base', 'polygon') or chain ID. Most NFTs are on Ethereum mainnet, which is the default.

---

scripts.tools.get_erc1155_balance#

工具描述：Get the balance of a specific ERC1155 token ID owned by an address. ERC1155 allows multiple tokens of the same ID, so the balance can be greater than 1.

参数定义#

参数名称参数类型是否必填默认值描述tokenAddressstringtrueThe contract address of the ERC1155 token collection (e.g., '0x76BE3b62873462d2142405439777e971754E8E77')tokenIdstringtrueThe ID of the specific token to check the balance for (e.g., '1234')ownerAddressstringtrueThe wallet address to check the token balance for (e.g., '0x1234...')networkstringfalseNetwork name (e.g., 'vitruveo', 'optimism', 'arbitrum', 'base', 'polygon') or chain ID. ERC1155 tokens exist across many networks. Defaults to Ethereum mainnet.

---

---

返回值处理#

工具函数返回 dict 对象：

• result["raw"] - API 原始返回数据（JSON）， 直接将此数据整理后展示给用户
• result["success"] - 是否成功（True/False）
• result["message"] - 状态消息

---

项目结构#

text

xiaobenyang_gaokao_skill/
├── scripts/
│   ├── __init__.py
│   ├── config.py       # 配置管理 + set_api_key()
│   ├── call_api.py      # API 客户端 + call_api()
│   └── tools.py         # 工具函数（直接调用）
├── requirements.txt
└── SKILL.md

---

注意事项#

1. API 密钥是必需的，无密钥时必须通过 AskUserQuestion 询问用户
2. 禁止 在缺少 API 密钥时自行搜索或编造数据