STARWARCLOUD STARWAR.AI
返回市场
依尔戈-MCP

依尔戈-MCP

作者：marctheshark33 星标更新：2025-06-02
安装使用来源：spider==github.com

项目介绍

MCP响应标准化工具

一个用于Ergo MCP API响应的标准化工具，它将各种输出格式（JSON、Markdown、纯文本）转换为一致的JSON结构，以提高集成性和易用性。

问题

MCP API返回的响应格式不一致：

  • 部分端点返回JSON
  • 部分返回Markdown
  • 部分返回纯文本
  • 部分返回混合格式（包含嵌入JSON的Markdown）

这种不一致性使得与其他系统集成变得困难，并且需要针对每个端点进行自定义处理。

解决方案

MCPResponseStandardizer将所有响应转换为一致的JSON结构：

{
  "success": true,
  "data": {
    // 从原始响应中提取的标准化响应数据
  },
  "meta": {
    "format": "json|markdown|text|mixed",
    "endpoint": "endpoint_name",
    "timestamp": "ISO-timestamp"
  }
}

对于错误响应：

{
  "success": false,
  "error": {
    "code": 400,
    "message": "错误信息"
  },
  "meta": {
    "format": "json|markdown|text|mixed",
    "endpoint": "endpoint_name",
    "timestamp": "ISO-timestamp"
  }
}

特性

  • 自动检测响应格式（JSON、Markdown、纯文本）
  • 从Markdown响应中提取结构化数据
  • 保留JSON响应的原始数据结构
  • 从混合格式响应中提取嵌入的JSON
  • 提供一致的错误处理
  • 包含关于原始格式和处理时间戳的元数据

使用方法

基本使用

from mcp_response_standardizer import MCPResponseStandardizer

# 初始化标准化工具
standardizer = MCPResponseStandardizer()

# 标准化响应
endpoint_name = "blockchain_status"
response_content = "..."  # 来自MCP API的内容
status_code = 200  # API调用的HTTP状态码

# 获取标准化响应
standardized = standardizer.standardize_response(
    endpoint_name, 
    response_content, 
    status_code
)

# 访问标准化的数据
if standardized["success"]:
    data = standardized["data"]
    # 使用标准化的数据...
else:
    error = standardized["error"]
    print(f"错误 {error['code']}: {error['message']}")

命令行使用

您也可以通过命令行使用标准化工具：

python mcp_response_standardizer.py blockchain_status response.txt

其中：

  • blockchain_status 是端点名称
  • response.txt 是包含响应内容的文件

测试

提供了一个测试脚本 test_standardizer.py，用于演示标准化工具有样本响应：

python test_standardizer.py

该脚本：

  1. 创建不同格式的样本响应
  2. 将它们保存到 sample_responses 目录
  3. 使用标准化工具处理每个样本
  4. 保存标准化输出以供比较

实现细节

标准化工具有以下方法：

  1. 根据HTTP状态码检查响应是否为错误
  2. 确定原始格式（JSON、Markdown、文本）
  3. 根据其格式处理响应：
    • JSON：解析并保留结构
    • Markdown：提取结构化数据（标题、列表、表格、代码块）
    • 文本：尽可能转换为键值对
    • 混合：提取嵌入的JSON并与其它提取的数据结合
  4. 将结果格式化为标准化结构
  5. 包含关于原始格式和处理的元数据

要求

  • Python 3.6+
  • 不需要外部依赖

Ergo Explorer MCP

Ergo Explorer Model Context Protocol (MCP) 是一个全面的服务器，通过标准化接口为AI助手提供了直接访问Ergo区块链数据的能力。

概述

该项目通过以下方式弥合了AI助手与Ergo区块链生态系统之间的差距：

  • 提供适合AI的结构化区块链数据格式
  • 通过简单的自然语言查询实现复杂的区块链分析
  • 支持代币分析、地址智能以及生态系统监控
  • 对AI模型的区块链数据访问模式进行标准化

功能

  • 区块链探索：检索区块、交易和网络统计信息
  • 地址分析：查询余额、交易历史并执行取证分析
  • 代币智能：查看代币信息、持有者分布、历史所有权追踪及集合数据
  • 生态系统集成：访问EIP信息、预言池数据及地址簿
  • 高级分析：分析区块链模式、代币指标及交易流
  • 实体识别：使用先进的地址聚类算法检测相关地址
  • 交互式可视化：生成并交互网络可视化图以进行实体分析

响应标准化

Ergo Explorer MCP中的所有端点都实现了标准化响应格式系统，该系统：

  • 支持人类可读（Markdown）和机器可读（JSON）格式
  • 在所有端点之间提供一致的结构
  • 通过双格式支持保持向后兼容性
  • 实现全面的错误处理
  • 使用 @standardize_response 装饰器进行自动格式转换

标准化的JSON响应结构：

{
  "status": "success",  // 或 "error"
  "data": {
    // 端点特定的结构化数据
  },
  "metadata": {
    "execution_time_ms": 123,
    "result_size_bytes": 456,
    "is_truncated": false,
    "token_estimate": 789
  }
}

有关响应标准化的更多信息，请参阅 RESPONSE_STANDARDIZATION.md。

实体识别与地址聚类

Ergo Explorer MCP通过地址聚类算法提供了先进的实体识别能力。此功能有助于识别可能由同一实体控制的一组地址。

实体识别功能

  • 基于图的聚类：使用交易图分析识别相关地址
  • 共同支出检测：检测在交易输入中一起使用的地址
  • 置信度评分：为检测到的实体集群分配置信水平
  • 地址关系映射：展示实体内地址的关系
  • 交互式可视化：提供实体的网络图可视化

地址聚类端点

以下端点可用于实体识别：

/address_clustering/identify
/address_clustering/visualize
/address_clustering/openwebui_entity_tool
/address_clustering/openwebui_viz_tool

Open WebUI 集成

Ergo Explorer MCP与 Open WebUI 集成，以提供增强的可视化和交互能力：

  • 实体文本工具：返回地址检测到的实体的文本摘要
  • 交互式可视化工具：渲染交互式的D3.js网络图可视化
  • 可定制视图：过滤和搜索实体，缩放和平移可视化
  • 实体分析：探索地址和实体之间的关系

使用示例

要识别与地址相关的实体：

from ergo_explorer.api import make_request

# 识别地址的实体
response = make_request("address_clustering/identify", {
    "address": "9gUDVVx75KyZ783YLECKngb1wy8KVwEfk3byjdfjUyDVAELAPUN",
    "depth": 2,
    "tx_limit": 100
})

# 获取地址的可视化
viz_response = make_request("address_clustering/visualize", {
    "address": "9gUDVVx75KyZ783YLECKngb1wy8KVwEfk3byjdfjUyDVAELAPUN",
    "depth": 2,
    "tx_limit": 100
})

# 访问实体集群
entities = response["data"]["clusters"]
for entity_id, entity_data in entities.items():
    print(f"实体 {entity_id}: {len(entity_data['addresses'])} 个地址")
    print(f"置信度: {entity_data['confidence_score']}")

Open WebUI 工具集成

要使用Open WebUI工具：

[工具: openwebui_entity_tool]
[地址: 9gUDVVx75KyZ783YLECKngb1wy8KVwEfk3byjdfjUyDVAELAPUN]
[深度: 2]
[交易限制: 100]

[工具: openwebui_viz_tool]
[地址: 9gUDVVx75KyZ783YLECKngb1wy8KVwEfk3byjdfjUyDVAELAPUN]
[深度: 2]
[交易限制: 100]

代币估算

Ergo Explorer MCP内置了代币估算功能，帮助AI助手优化其上下文窗口使用。此功能提供了每种LLM模型响应中的代币数量估计。

代币估算功能

  • 自动代币计数：每个响应包括其代币数量的估计
  • 模型特定估算：支持多种LLM模型（Claude、GPT、Mistral等）
  • 按响应部分细分：提供数据、元数据和状态的代币计数
  • 可配置阈值：基于代币数量阈值的响应截断
  • 备用机制：即使没有tiktoken也能工作

响应在代币估算

代币估算是所有标准化响应的metadata部分的一部分：

{
  "status": "success",
  "data": {
    // 响应数据
  },
  "metadata": {
    "execution_time_ms": 123,
    "result_size_bytes": 456,
    "is_truncated": false,
    "token_estimate": 789,
    "token_breakdown": {
      "data": 650,
      "metadata": 89,
      "status": 50
    }
  }
}

使用方法

要访问响应中的代币估算：

from ergo_explorer.api import make_request

# 向任何端点发出请求
response = make_request("blockchain/status")

# 访问代币估算信息
token_count = response["metadata"]["token_estimate"]
is_truncated = response["metadata"]["is_truncated"]

print(f"响应大约包含 {token_count} 个代币")
if is_truncated:
    print("响应被截断以适应代币限制")

模型特定估算

您可以指定用于代币估算的LLM模型类型：

from ergo_explorer.api import make_request

# 请求时指定特定模型类型进行代币估算
response = make_request("blockchain/address_info", 
                        {"address": "9hdcMw4eRpJPJGx8RJhvdRgFRsE1URpQCsAWM3wG547gQ9awZgi"},
                        model_type="gpt-4")

# 代币估算将基于GPT-4的标记化计算

代币使用指南

响应类型目标代币范围优化策略
简单查询< 500 代币完整响应，无截断
标准查询500-2000 代币选择性字段包含
复杂查询2000-5000 代币分页或截断响应
数据密集型> 5000 代币摘要，可选详细信息检索

历史代币持有者跟踪

Ergo Explorer MCP包括全面的功能，用于跟踪代币的历史所有权并分析其如何随时间变化：

关键特性

  • 完整的代币历史：跟踪所有曾经包含代币的盒子，以提供代币在区块链上的全面移动视图
  • 区块高度跟踪：包含所有代币转移的区块高度信息
  • 代币转移监控：跟踪代币在地址之间的移动
  • 分布指标：计算集中度指标（基尼系数）以分析代币分布
  • 高级盒分析：使用高效的盒分析方法来分析涉及代币的所有交易

使用示例

// 只包含基本参数的简单请求
GET /token/historical_token_holders
{
  "token_id": "d71693c49a84fbbecd4908c94813b46514b18b67a99952dc1e6e4791556de413",
  "max_transactions": 200
}

响应格式包括详细的代币转移历史和在各个时间点（或区块高度）的代币分布快照。

安装

先决条件

  • Python 3.8+
  • 访问Ergo Explorer API
  • 可选：访问Ergo Node API（用于高级功能）

设置

  1. 克隆仓库：

    git clone https://github.com/ergo-mcp/ergo-explorer-mcp.git
cd ergo-explorer-mcp

  2. 安装依赖项：

    pip install -r requirements.txt

  3. 配置环境：

    # 设置环境变量
export ERGO_EXPLORER_API="https://api.ergoplatform.com/api/v1"
export ERGO_NODE_API="http://your-node-address:9053"  # 可选
export ERGO_NODE_API_KEY="your-api-key"  # 可选

  4. 运行MCP服务器：

    python -m ergo_explorer.server

Docker安装（推荐）

  1. 构建Docker镜像：

    docker build -t ergo-explorer-mcp .

  2. 运行容器：

    docker run -d -p 8000:8000 \
  -e ERGO_EXPLORER_API="https://api.ergoplatform.com/api/v1" \
  -e ERGO_NODE_API="http://your-node-address:9053" \
  -e ERGO_NODE_API_KEY="your-api-key" \
  --name ergo-mcp ergo-explorer-mcp

开发

要贡献于项目：

  1. 分叉仓库
  2. 创建功能分支
  3. 设置开发环境： 
    pip install -r requirements.txt
pip install -r requirements.test.txt
  4. 运行测试： 
    pytest
  5. 提交拉取请求

文档

有关全面文档，请参阅：

许可证

本项目根据MIT许可证发布 - 详情见 LICENSE 文件。