使用说明

MCP响应标准化器

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

问题

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

某些端点返回JSON
有些返回Markdown
有些返回纯文本
一些返回混合格式（内嵌JSON的Markdown）

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

解决方案

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

{
  "success": true,
  "data": {
    // Standardized response data extracted from the original
  },
  "meta": {
    "format": "json|markdown|text|mixed",
    "endpoint": "endpoint_name",
    "timestamp": "ISO-timestamp"
  }
}

对于错误响应：

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

特性

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

用法

基本用法

from mcp_response_standardizer import MCPResponseStandardizer

# Initialize the standardizer
standardizer = MCPResponseStandardizer()

# Standardize a response
endpoint_name = "blockchain_status"
response_content = "..."  # Content from the MCP API
status_code = 200  # HTTP status code from the API call

# Get standardized response
standardized = standardizer.standardize_response(
    endpoint_name, 
    response_content, 
    status_code
)

# Access the standardized data
if standardized["success"]:
    data = standardized["data"]
    # Use the standardized data...
else:
    error = standardized["error"]
    print(f"Error {error['code']}: {error['message']}")

命令行用法

您还可以从命令行使用标准化器：

python mcp_response_standardizer.py blockchain_status response.txt

哪里：

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

测试

测试脚本 test_standardizer.py 提供样品响应来演示标准化器：

python test_standardizer.py

此脚本：

以不同格式创建示例响应
将它们保存到 sample_responses 目录
使用标准化器处理每个样品
保存标准化输出以供比较

实现细节

标准化者使用以下方法：

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

需求

Python 3.6+
不需要外部依赖

Ergo Explorer MCP

Ergo Explorer模型上下文协议（MCP）是一个全面的服务器，通过标准化的接口为AI助手提供对Ergo区块链数据的直接访问。

概述

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

以人工智能友好的格式提供结构化的区块链数据
通过简单的自然语言查询实现复杂的区块链分析
支持令牌分析、地址智能和生态系统监控
规范AI模型的区块链数据访问模式

特性

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

响应标准化

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

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

标准JSON响应结构：

{
  "status": "success",  // or "error"
  "data": {
    // Endpoint-specific structured data
  },
  "metadata": {
    "execution_time_ms": 123,
    "result_size_bytes": 456,
    "is_truncated": false,
    "token_estimate": 789
  }
}

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

实体识别和地址聚类

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

实体标识特征

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

地址群集端点

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

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

打开WebUI集成

Ergo Explorer MCP与打开WebUI 提供增强的可视化和交互功能：

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

用法示例

要识别与地址相关的实体，请执行以下操作：

from ergo_explorer.api import make_request

# Identify entities for an address
response = make_request("address_clustering/identify", {
    "address": "9gUDVVx75KyZ783YLECKngb1wy8KVwEfk3byjdfjUyDVAELAPUN",
    "depth": 2,
    "tx_limit": 100
})

# Get visualization for an address
viz_response = make_request("address_clustering/visualize", {
    "address": "9gUDVVx75KyZ783YLECKngb1wy8KVwEfk3byjdfjUyDVAELAPUN",
    "depth": 2,
    "tx_limit": 100
})

# Access entity clusters
entities = response["data"]["clusters"]
for entity_id, entity_data in entities.items():
    print(f"Entity {entity_id}: {len(entity_data['addresses'])} addresses")
    print(f"Confidence: {entity_data['confidence_score']}")

打开WebUI工具集成

要使用Open WebUI工具，请执行以下操作：

[Tool: openwebui_entity_tool]
[Address: 9gUDVVx75KyZ783YLECKngb1wy8KVwEfk3byjdfjUyDVAELAPUN]
[Depth: 2]
[TX Limit: 100]

[Tool: openwebui_viz_tool]
[Address: 9gUDVVx75KyZ783YLECKngb1wy8KVwEfk3byjdfjUyDVAELAPUN]
[Depth: 2]
[TX Limit: 100]

令牌估计

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

令牌估计特征

自动令牌计数：每个响应都包括其令牌计数的估计值
模型特定估计：支持各种LLM模型（Claude、GPT、Mistral等）
按响应部门细分：提供数据、元数据和状态的令牌计数
可配置阈值：基于令牌计数阈值的响应截断
回退机制：即使在以下情况下也能工作 tiktoken 不可用

响应中的令牌估计

令牌估计包含在 metadata 所有标准化回复的一部分：

{
  "status": "success",
  "data": {
    // Response 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

# Make a request to any endpoint
response = make_request("blockchain/status")

# Access token estimation information
token_count = response["metadata"]["token_estimate"]
is_truncated = response["metadata"]["is_truncated"]

print(f"Response contains approximately {token_count} tokens")
if is_truncated:
    print("Response was truncated to fit within token limits")

模型特定估计

您可以指定用于令牌估计的LLM模型：

from ergo_explorer.api import make_request

# Request with specific model type for token estimation
response = make_request("blockchain/address_info", 
                        {"address": "9hdcMw4eRpJPJGx8RJhvdRgFRsE1URpQCsAWM3wG547gQ9awZgi"},
                        model_type="gpt-4")

# The token_estimate will be calculated based on GPT-4's tokenization

代币使用指南

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

历史代币持有者跟踪

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

主要特点

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

使用示例

// Simple request with just essential parameters
GET /token/historical_token_holders
{
  "token_id": "d71693c49a84fbbecd4908c94813b46514b18b67a99952dc1e6e4791556de413",
  "max_transactions": 200
}

响应格式包括详细的令牌传输历史和不同时间点（或块高度）的令牌分布快照。

安装

先决条件

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

设置

克隆存储库：

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

安装依赖项：
```
pip install -r requirements.txt
```

配置您的环境：

# Set up environment variables
export ERGO_EXPLORER_API="https://api.ergoplatform.com/api/v1"
export ERGO_NODE_API="http://your-node-address:9053"  # Optional
export ERGO_NODE_API_KEY="your-api-key"  # Optional

运行MCP服务器：
```
python -m ergo_explorer.server
```

Docker安装（推荐）

构建Docker镜像：
```
docker build -t ergo-explorer-mcp .
```

运行容器：

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

发展

为项目做出贡献：

复刻仓库
创建要素分支

设置开发环境：

pip install -r requirements.txt
pip install -r requirements.test.txt

运行测试：
```
pytest
```
提交拉取请求

文档

有关综合文档，请参阅：

许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。