Etrap MCP

ETRAP MCP服务器

ETRAP（企业事务记录和审计平台）系统的模型上下文协议（MCP）服务器。该服务器提供工具，用于根据存储在NEAR协议上的区块链记录验证数据库事务。

特性

• 交易验证：根据区块链记录验证单个交易
• 批验证：并行高效地验证多个交易
• 批次管理：列出、搜索和检查交易批次
• NFT资产信息：访问区块链NFT元数据和所有权详细信息
• 合同信息：获取ETRAP智能合约的详细信息
• 多运输支持：stdio、SSE和可流式传输HTTP

安装

此项目使用 紫外线 用于依赖关系管理和虚拟环境设置。

选项1：使用UV虚拟环境（推荐）

# Create and activate virtual environment
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install the project with dependencies
uv pip install -e .

# Run the server
python -m mcp_etrap.app

选项2：使用UV Run（替代方案）

# Install dependencies
uv sync

# Run the server directly with uv
uv run python -m mcp_etrap.app

配置

使用环境变量配置服务器：

必修的：

• ETRAP_ORGANIZATION：组织标识符（例如“acme”）

可选：

• ETRAP_NETWORK：NEAR网络（测试网/主网，默认：测试网）
• ETRAP_RPC_ENDPOINT：自定义NEAR RPC端点
• ETRAP_TIMEOUT：请求超时（秒）（默认值：30）
• ETRAP_CACHE_TTL：缓存TTL（秒）（默认值：300）
• ETRAP_MAX_RETRIES：最大重试次数（默认值：3）

AWS S3：

• AWS_ACCESS_KEY_ID：S3访问密钥
• AWS_SECRET_ACCESS_KEY：S3密钥
• AWS_DEFAULT_REGION：S3区域（默认：us-west-2）

用法

基本用法

使用虚拟环境：

# Start with stdio transport (default for MCP)
ETRAP_ORGANIZATION=myorg python -m mcp_etrap.app

# Start with HTTP transport  
ETRAP_ORGANIZATION=myorg python -m mcp_etrap.app --transport sse --port 8000

使用UV运行：

# Start with stdio transport (default for MCP)
ETRAP_ORGANIZATION=myorg uv run python -m mcp_etrap.app

# Start with HTTP transport  
ETRAP_ORGANIZATION=myorg uv run python -m mcp_etrap.app --transport sse --port 8000

可用工具

• get_config：获取当前服务器配置
• verify_transaction：使用可选提示验证单个交易
• verify_batch：高效验证多笔交易
• get_batch：按ID获取详细的批次信息
• get_nft：获取批量令牌的NFT元数据和区块链详细信息
• list_batches：列出具有筛选和分页功能的批次
• search_batches：带条件的高级批量搜索
• get_contract_info：获取合同统计数据和信息

优化指示

所有验证工具都支持可选提示作为JSON对象，以提高性能：

时间范围提示

{
  "time_start": "2025-07-01T09:54:00",
  "time_end": "2025-07-01T09:56:00"
}

批次ID提示（最快）

{
  "batch_id": "BATCH-2025-07-01-abc123"
}

数据库/表提示

{
  "database_name": "production",
  "table_name": "financial_transactions"
}

消除分歧行动

{
  "expected_operation": "INSERT"
}

组合提示

{
  "time_start": "2025-07-01T09:54:00",
  "time_end": "2025-07-01T09:56:00",
  "expected_operation": "INSERT",
  "database_name": "production"
}

重要：时间范围指 区块链批量创建时间，而不是数据库事务时间。当您提供时间范围时，您正在搜索在此期间在区块链上生成的批次。这与原始数据库事务发生时不同。区块链时间戳始终以UTC为单位。

NFT工具

get_nft-nft元数据和区块链资产信息

这 get_nft 该工具检索ETRAP批处理令牌的全面NFT信息。在ETRAP中，每个批次在NEAR区块链上创建一个唯一的NFT，代表审计记录的所有权。

输入：NFT令牌ID（与批ID相同）

{
  "nft_token_id": "BATCH-2025-07-01-c9de5968"
}

输出：完整的NFT元数据和区块链详细信息

{
  "token_id": "BATCH-2025-07-01-c9de5968",
  "owner_id": "lunaris.testnet",
  "metadata": {
    "title": "ETRAP Batch BATCH-2025-07-01-c9de5968",
    "description": "Integrity certificate for 4 transactions from table financial_transactions",
    "reference": "https://s3.amazonaws.com/etrap-lunaris/BATCH-2025-07-01-c9de5968/batch-data.json",
    "issued_at": "1751388910475",
    "copies": 1
  },
  "minted_timestamp": "2025-07-01T09:55:10.475000",
  "batch_id": "BATCH-2025-07-01-c9de5968",
  "organization_id": "lunaris",
  "merkle_root": "b1e52265e4fd5afaf673454fe7351cbc516bea056c08f99e3d0876217b0aacab",
  "blockchain_details": {
    "contract_id": "lunaris.testnet",
    "network": "testnet",
    "token_standard": "NEP-171",
    "approved_account_ids": {}
  }
}

主要特点:

• 符合NEP-171标准：完全符合NEAR NFT标准
• 所有权信息：当前所有者和已批准的账户
• 元数据：标题、描述和S3参考
• 区块链资产数据：合同详情和铸造信息
• 加密完整性：用于验证的默克尔根

用例:

• 资产所有权：确定审计记录NFT的所有者
• 元数据访问：获取有关批次的人类可读信息
• 区块链集成：访问NFT数据以进行市场或转移操作
• 合规文件：生成审计记录所有权证书

工具比较：get_batch与get_nft

get_batch -审核记录数据：

• 交易详情和操作计数
• S3存储信息和批次统计
• 数据库和表信息
• 聚焦：审计跟踪和验证数据

get_nft -区块链资产数据：

• NFT所有权和元数据
• 区块链资产信息
• 铸造时间戳和合同详细信息
• 聚焦：数字资产和所有权信息

这两种工具相辅相成，为ETRAP的防篡改审计系统提供了完整的可见性。

示例

使用虚拟环境：

# Set environment
export ETRAP_ORGANIZATION=lunaris
export ETRAP_NETWORK=testnet

# Activate environment and start the server
source .venv/bin/activate
python -m mcp_etrap.app

使用UV运行：

# Set environment
export ETRAP_ORGANIZATION=lunaris
export ETRAP_NETWORK=testnet

# Start the server
uv run python -m mcp_etrap.app

服务器将连接到 lunaris.testnet NEAR合约并提供交易验证功能。

建筑

• FastMCP：支持多传输的现代MCP服务器框架
• ETRAP SDK：用于NEAR区块链交互和S3数据访问的Python SDK
• 派丹蒂克：类型安全数据模型和验证
• 紫外线的：具有冲突覆盖功能的快速依赖关系解决

发展

SDK更改后的重建

重要：更新ETRAP SDK时，您必须重建MCP服务器以包含更改：

# Method 1: Force reinstall the SDK package
uv sync --reinstall-package etrap-sdk

# Method 2: Complete reinstall (if needed)
uv pip uninstall etrap-sdk
uv sync

# Restart the server after rebuilding
ETRAP_ORGANIZATION=myorg uv run python -m mcp_etrap.app

MCP服务器使用对本地ETRAP SDK的直接文件引用(etrap-sdk @ file:///path/to/etrap-sdk)，因此重建可确保包含最新的SDK更改。

开发工作流程

虚拟环境

# Create and activate environment
uv venv
source .venv/bin/activate

# Install project with dev dependencies
uv pip install -e ".[dev]"

# Run tests
pytest

# Lint code
ruff check .

使用UV Run

# Install development dependencies
uv sync --group dev

# Run tests
uv run pytest

# Lint code
uv run ruff check .

测试

MCP服务器测试

测试完整的MCP服务器功能：

使用stdio传输（推荐）：

# Run comprehensive MCP server test
uv run python test_mcp_stdio.py

该测试验证：

• MCP服务器初始化和工具列表
• 带有时间范围提示的个人交易验证
• 使用优化提示进行批量验证
• 端到端MCP→ SDK → 区块链流程

测试覆盖范围：

• ✅ 时间范围提示（对性能至关重要）
• ✅ 操作消歧（插入/更新/删除）
• ✅ 批次ID提示（最快验证方法）
• ✅ 组合提示场景

依赖项

服务器通过使用UV的覆盖功能解决了FastMCP和pynear之间的复杂依赖冲突：

• FastMCP 2.9.x需要 httpx>=0.28.1
• py接近1.1.52需要 httpx==0.26.0
• UV超控力 httpx>=0.28.1 为了兼容性

生成配置

该项目使用Hatching作为构建后端，具有以下特定配置：

• 直接参考: tool.hatch.metadata.allow-direct-references = true 启用本地ETRAP SDK依赖关系
• 包发现: tool.hatch.build.targets.wheel.packages = ["mcp_etrap"] 指定包位置
• 依赖性覆盖：UV的覆盖功能确保httpx兼容性

这种方法确保我们在保持ETRAP SDK功能的同时获得最新的MCP功能。

🪪 许可证

MIT。看 ./LICENSE

📄 版权

版权所有（c）2025 Graziano Labs Corp.保留所有权利。

📧 联系

如有疑问或支持，请在GitHub存储库中打开问题。

______________________________________________________________________