Verified X Spyglass MCP

已验证的X Spyglass MCP服务器

模型上下文协议（MCP）服务器，提供对VerifiedX区块链API的无缝访问。该服务器使Claude和其他MCP客户端能够与区块链数据进行交互，包括地址、交易、块、NFT和可替代令牌。

特性

• 完整的区块链访问：查询地址、事务、块和网络统计信息
• NFT和令牌支持：搜索和检索NFT元数据、可替换令牌信息
• 主节点数据：访问验证器信息和网络拓扑
• 可选身份验证：立即用于读取操作，可选令牌用于写入操作
• Docker支持：使用Docker和Docker compose轻松部署
• 类型安全：使用TypeScript构建，提供可靠性和IDE支持
• 速率限制意识：遵守API速率限制（300次请求/分钟）

先决条件

• Node.js 20+ （用于本地安装）
• 码头工人 （可选，用于容器化部署）
• 验证API访问 （公共读取端点，用于身份验证操作的可选令牌）
• 制造 （可选，用于使用Makefile命令）

Makefile快速入门

此项目包括一个包含所有常用命令的全面Makefile。要查看所有可用命令，请执行以下操作：

make help

快速启动命令

# Check prerequisites
make check

# Install dependencies and build
make quick-start

# Test with MCP Inspector
make inspector

# Run the server
make start

# Or use Docker
make docker-run

常见Makefile命令

看 make help 查看可用命令的完整列表。

安装

本地安装

1. 克隆和安装依赖关系：

git clone git@github.com:VerifiedXBlockchain/VerifiedX-SpyglassMCP.git
cd VerifiedX-SpyglassMCP
npm install

1. 构建TypeScript代码：

npm run build

1. 配置环境（可选）：

cp .env.example .env
# Edit .env to set VERIFIEDX_NETWORK and optionally VERIFIEDX_API_TOKEN

1. 运行服务器：

npm start
# or for development with auto-reload:
npm run dev

Docker安装

1. 构建Docker镜像：

docker build -t verifiedx-mcp-server .

1. 使用Docker运行：

docker run --rm -i verifiedx-mcp-server

1. 或者使用docker compose：

docker-compose up

配置

环境变量

• VERIFIEDX_NETWORK：要使用的网络(mainnet 或 testnet).违约： mainnet
• VERIFIEDX_API_TOKEN：用于已验证请求的可选API令牌。为只读模式留空。

网络URL

• 主网: https://data.verifiedx.io/api/
• 测试网: https://data-testnet.verifiedx.io/api/

认证

大多数区块链数据端点（地址、交易、区块、NFT、令牌） 无需身份验证即可公开访问。仅以下情况需要身份验证：

• 写入操作（POST/PATCH/DELETE）
• 聊天/消息功能
• 原始交易提交
• 用户特定数据

要启用经过身份验证的操作，请设置 VERIFIEDX_API_TOKEN 在您的环境中。

MCP客户端配置

克劳德桌面

添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%/Claude/claude_desktop_config.json

本地安装：

{
  "mcpServers": {
    "verifiedx": {
      "command": "node",
      "args": ["/absolute/path/to/verifiedx-mcp-server/build/index.js"],
      "env": {
        "VERIFIEDX_NETWORK": "mainnet"
      }
    }
  }
}

Docker安装：

{
  "mcpServers": {
    "verifiedx": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "verifiedx-mcp-server"],
      "env": {
        "VERIFIEDX_NETWORK": "mainnet"
      }
    }
  }
}

使用身份验证：

{
  "mcpServers": {
    "verifiedx": {
      "command": "node",
      "args": ["/absolute/path/to/verifiedx-mcp-server/build/index.js"],
      "env": {
        "VERIFIEDX_NETWORK": "mainnet",
        "VERIFIEDX_API_TOKEN": "your-jwt-token-here"
      }
    }
  }
}

克劳德代码

克劳德代码设置中的类似配置。

可用工具

服务器提供22个工具，分为6类：

地址工具

• get_address -获取地址余额和信息
• get_address_tokens -获取地址的令牌余额
• get_address_transactions -通过分页获取交易历史记录
• lookup_domain -解析要寻址的ADNR域

交易工具

• get_transaction -通过哈希获取交易详细信息
• list_transactions -列出最近的交易
• get_block_transactions -获取一个区块中的所有交易

块工具

• get_latest_blocks -获取最新区块
• get_block -按高度或哈希值获取块
• get_blocks_by_validator -通过验证器地址获取区块

NFT工具

• list_nfts -列出带过滤器的NFT（所有者、制造商）
• get_nft -获取NFT详细信息和元数据
• get_nft_history -获取NFT所有权历史记录
• search_nfts_by_owner -按所有者查找所有NFT

令牌工具

• list_fungible_tokens -列出所有可替代的代币
• get_fungible_token -获取令牌详细信息

主节点工具

• list_master_nodes -列表验证器节点
• get_master_node -按地址/名称获取节点详细信息
• get_master_node_map -获取地理节点数据

网络工具

• get_network_metrics -获取网络统计信息
• get_circulation -获取供应指标
• get_circulating_supply -仅获得循环供应

使用示例

连接到Claude后，您可以提出以下问题：

• “地址VFX1的余额是多少…？”
• “显示VerifiedX上的最新5个块”
• “获取哈希abc123的交易详细信息…”
• “列出地址VFX1拥有的所有NFT…”
• “当前的网络指标是什么？”
• “有多少主节点处于活动状态？”
• “获取VFX代币的流通数据”

测试

使用MCP检查员进行测试

MCP检查器是测试服务器的好工具：

npx @modelcontextprotocol/inspector build/index.js

这将打开一个web界面，您可以在其中：

• 查看所有可用工具
• 具有不同参数的测试工具调用
• 查看请求/响应数据
• 调试问题

手动测试

您还可以通过运行服务器并发送MCP协议消息进行测试：

npm start

发展

项目结构

verifiedx-mcp-server/
├── src/
│   ├── index.ts              # MCP server and tool handlers
│   ├── verifiedx-client.ts   # API client implementation
│   └── types.ts              # TypeScript type definitions
├── build/                    # Compiled JavaScript (generated)
├── Dockerfile                # Docker configuration
├── docker-compose.yml        # Docker Compose setup
├── package.json              # Node.js dependencies
├── tsconfig.json             # TypeScript configuration
├── .env.example              # Environment template
└── README.md                 # This file

开发命令

npm run dev      # Run with auto-reload (tsx)
npm run build    # Compile TypeScript
npm start        # Run compiled code

添加新工具

1. 将工具定义添加到 tools 数组in src/index.ts
2. 在switch语句中添加相应的case
3. 使用 VerifiedXClient 方法
4. 重建和测试

API文档

有关API端点文档的详细信息，请访问：

• 主要文件: https://docs.verifiedx.io/docs/integration/web-api/
• Swagger用户界面: https://data.verifiedx.io/docs/
• OpenAPI规范: https://data.verifiedx.io/docs.json

速率限制

VerifiedX API的速率限制为 每分钟300个请求。服务器不实现客户端速率限制，因此请注意您的使用模式。

错误处理

服务器为常见问题提供描述性错误消息：

• 404错误：找不到资源（无效地址、事务哈希等）
• 身份验证错误：受保护端点的令牌缺失或无效
• 网络错误：API的连接问题
• 验证错误：传递给工具的参数无效

MCP响应中返回错误 isError: true.

故障排除

服务器无法启动

• 确保已安装Node.js 20+： node --version
• 检查是否安装了依赖项： npm install
• 验证TypeScript是否已编译： npm run build

工具返回错误

• 检查网络连接 data.verifiedx.io
• 验证地址/哈希格式是否正确（VerifiedX地址以“VFX1”开头）
• 对于写入操作，请确保 VERIFIEDX_API_TOKEN 已设置

Docker问题

• 确保Docker正在运行： docker --version
• 代码更改后重建映像： docker-compose build
• 检查日志： docker-compose logs

MCP连接问题

• 验证路径 build/index.js 在您的配置中是绝对的
• 检查服务器是否成功构建： npm run build
• 在连接到克劳德之前，先与MCP检查员进行测试

贡献

欢迎投稿！拜托：

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 如果适用，添加测试
5. 提交拉取请求

许可证

MIT许可证-有关详细信息，请参阅许可证文件

链接

• 已验证的X平台: https://verifiedx.io
• API文档: https://docs.verifiedx.io
• MCP协议: https://modelcontextprotocol.io
• 克劳德桌面: https://claude.ai/download

支持

对于问题和疑问：

• API问题：联系VerifiedX支持
• MCP服务器问题：在GitHub上打开一个问题
• 一般问题：请参阅VerifiedX文档

______________________________________________________________________

使用模型上下文协议SDK和TypeScript构建。