Chain Debugger MCP Server

链调试器MCP服务器

提供双区块链连接的集成MCP（模型上下文协议）服务器：

• 温柔整合：全面只读访问Tenderly的监控基础设施和警报系统
• 通用EVM RPC支持：与任何EVM兼容的区块链网络进行原生JSON-RPC通信

旨在将人工智能助手与区块链生态系统连接起来，通过Tendly实现无缝监控，同时通过标准化协议保持直接的链交互能力。

概述

该MCP服务器通过以下方式在人工智能系统和区块链基础设施之间建立了强大的连接 模型上下文协议该服务器赋予像Claude这样的AI助手全面的区块链功能：

投标整合：

• 完整的警报管理 -完全访问所有具有详细元数据的项目警报
• 精细警报检查 -通过ID深入了解特定警报，并提供全面的详细信息
• 高级监控分析 -处理区块链监控数据以获得可操作的见解
• 交易模拟引擎 -利用Tendly先进的仿真能力

EVM RPC功能：

• 通用JSON-RPC执行 -在EVM网络上运行任何标准或自定义RPC方法
• 直接区块链查询 -本机访问余额、交易、区块和合同数据
• 多链架构 -支持多种EVM兼容网络的可配置端点
• 专业链功能 -特定网络的增强功能（Zircuit隔离系统等）

核心架构特征

• 🔒 非侵入式设计 -仅基于检索的操作，无需修改
• 🚀 即插即用兼容性 -与任何符合MCP标准的AI助手无缝集成
• 📊 全面的警报情报 -完全访问警报表达式、交付配置、严重性分类和元数据
• 🛡️ 企业级安全型 -通过全面的Zod模式验证完成TypeScript实现
• 🔐 安全第一凭证处理 -基于环境的秘密管理，无硬编码凭据

先决条件

• Node.js v16+运行时环境
• 具有API权限的活动Tenderly帐户
• 投标身份验证凭据（帐户段、项目标识符、访问令牌）
• 可选：用于直接区块链连接的EVM RPC端点URL

安装和配置

1. 将存储库克隆到本地环境
2. 安装所有必需的依赖项：

   pnpm install

1. 初始化您的环境配置：

   cp .env.example .env

1. 配置您的 .env 具有以下参数的文件：

   # Tenderly Configuration (Required)
   TENDERLY_ACCOUNT_SLUG=your-account-slug
   TENDERLY_PROJECT_ID=your-project-id
   TENDERLY_ACCESS_TOKEN=your-access-token

   # EVM RPC Configuration (Optional)
   EVM_RPC_URL=https://eth.llamarpc.com
   EVM_CHAIN_NAME=Ethereum
   ENABLE_ANALYTICS=false
   ANALYTICS_DB_PATH=./analytics.db

1. 编译TypeScript项目：

   pnpm run build

运输方式

此服务器可以在三种模式下运行：

• 标准（默认）：最适合本地开发和SSH/容器
• 超文本传输协议：位于的无状态流式HTTP端点 /mcp
• 超文本传输安全协议：使用SSL/TLS证书保护HTTP

通过环境变量进行配置（请参见 .env.example):

MCP_TRANSPORT=stdio   # or "http"
PORT=3000             # only used when MCP_TRANSPORT=http
CORS_ORIGINS=http://localhost:3000,http://localhost:5173  # optional, HTTP only

# HTTPS Configuration (Optional)
HTTPS_ENABLED=false   # set to true to enable HTTPS
CERT_PATH=./certs/server.crt
KEY_PATH=./certs/server.key

用法

服务器执行（stdio）

启动MCP服务器：

pnpm start

服务器按照MCP规范标准通过stdio（标准输入/输出）通信运行。当服务器通过stdin等待MCP协议消息时，初始化会将输出记录到stderr。

对于动态EVM RPC配置，支持命令行参数：

pnpm start -- --rpc-url https://mainnet.zircuit.com --chain-name Zircuit --analytics

服务器执行（HTTP）

使用HTTP传输运行：

MCP_TRANSPORT=http PORT=3000 pnpm start

服务器将监听 http://0.0.0.0:3000/mcp 并通过POST接受MCP JSON-RPC请求。

简单的健康/方法检查：

curl -i http://localhost:3000/mcp   # returns 405 for GET (POST is required)

要从浏览器上下文调用，请设置 CORS_ORIGINS 您的客户来源。

服务器执行（HTTPS）

对于HTTPS支持，首先生成自签名证书：

./generate-certs.sh

然后在启用HTTPS的情况下运行：

# Option 1: Quick start script
./start-https.sh

# Option 2: Manual start
MCP_TRANSPORT=http HTTPS_ENABLED=true pnpm start

# Option 3: Using environment variables (in .env)
MCP_TRANSPORT=http
HTTPS_ENABLED=true

服务器将监听 https://0.0.0.0:3000/mcp 使用SSL/TLS加密。

备注：对于使用自签名证书的开发，您需要在浏览器中接受证书警告，或者将MCP客户端配置为忽略SSL验证。

AI助手集成

一旦投入使用，人工智能助手可以通过以下功能访问您的Tendly基础设施：

资源端点：

• tenderly://alerts -使用元数据完成所有项目警报的JSON枚举
• tenderly://simulations -直接访问Tenderly的交易模拟基础设施
• evm://rpc_info -当前EVM RPC连接状态和配置详细信息
• evm://chain_info -网络标识和链特定元数据

功能工具：

• get_alert_by_id(id: string) -使用全面的元数据进行详细的警报检索
• simulate_transaction(...) -通过Tendly引擎进行高级交易模拟
• eth_json_rpc_call(method, params) -通用以太坊JSON-RPC方法执行
• zirc_isQuarantined(transactionHash) -Zircuit特定交易隔离状态检查
• zirc_getQuarantined(address?) -Zircuit网络的隔离事务枚举

实际使用案例

将服务器连接到AI助手后，您可以执行以下查询：

招标操作：

• *“枚举我的投标项目中配置的所有警报”*
• *“提供警报ID abc123的全面详细信息”*
• *“确定哪些警报当前处于活动状态并正在运行”*
• *“分析需要立即关注的最关键警报”*
• *“对指定地址之间的1ETH转账执行模拟”*

EVM RPC操作：

• *“检索当前区块链高度”*
• *“查询地址0x742d35Cc6634C0532925a3b844Bc454e4438f44e的ETH余额”*
• *“获取哈希0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060的交易回执”*
• *“从USDC合约地址提取字节码”*
• *“验证事务0xabc的隔离状态…”* （特定于锆）

AI助手利用此服务器检索区块链数据，并对您的链上活动进行复杂的分析。

开发与测试

MCP Inspector提供全面的服务器测试功能：

# Build and launch inspection interface
make inspect

这将启动一个基于web的界面，可以直接测试所有MCP资源和工具。

码头工人

构建

docker build -t chain-debugger-mcp:local .

运行（stdio）

docker run --rm -i \
  --env-file .env \
  -e MCP_TRANSPORT=stdio \
  -v "$PWD/data:/data" -v "$PWD/cache:/cache" \
  chain-debugger-mcp:local

运行（HTTP）

docker run -d --name chain-debugger-http \
  --env-file .env \
  -e MCP_TRANSPORT=http -e PORT=3000 \
  -e CORS_ORIGINS=http://localhost:5173 \
  -p 3000:3000 \
  -v "$PWD/data:/data" -v "$PWD/cache:/cache" \
  chain-debugger-mcp:local

运行（HTTPS）

首先生成证书，然后使用HTTPS运行：

# Generate certificates
./generate-certs.sh

# Run with HTTPS
docker run -d --name chain-debugger-https \
  --env-file .env \
  -e MCP_TRANSPORT=http -e PORT=3000 \
  -e HTTPS_ENABLED=true \
  -e CORS_ORIGINS=https://localhost:5173 \
  -p 3000:3000 \
  -v "$PWD/data:/data" -v "$PWD/cache:/cache" \
  -v "$PWD/certs:/app/certs" \
  chain-debugger-mcp:local

Docker Compose

看 docker-compose.yml 用于配置用于装载卷的stdio传输的最小服务，以及 .env.

SSH包装器（远程stdio）

使用 scripts/ssh-stdio-wrapper.sh 在远程主机上运行容器，并通过SSH代理stdio。

所需的环境变量：

REMOTE_HOST=user@your.server
REMOTE_DOCKER_IMAGE=ghcr.io/your/repo:tag  # or built local image name
REMOTE_ENV_FILE=/path/on/remote/.env
REMOTE_DATA_DIR=/path/on/remote/data
REMOTE_CACHE_DIR=/path/on/remote/cache

然后，将MCP客户端指向服务器命令执行脚本。该脚本运行Docker -i 保留stdio并传递env/卷。

技术架构

MCP资源和工具实施

资源基础设施：

• tenderly://alerts -您的投标项目中的全面警报枚举，包括：

- 完整的警报元数据（ID、名称、描述） - 运行状态指示器（启用/禁用状态） - 警报表达式逻辑和触发条件 - 交付渠道配置和路由 - 严重性分类和视觉编码 - 时间元数据（创建和修改时间戳）

工具框架：

• get_alert(id: string) -具有完整元数据提取功能的精细警报数据检索

数据结构设计

服务器返回结构化警报数据，其中包含：

• 核心属性：唯一标识符、名称、描述、操作状态
• 逻辑组件：触发器表达式、条件逻辑、评估标准
• 分发配置：交付机制、路由目的地、通知渠道
• 系统元数据：项目关联、时间标记、严重程度指标、视觉分类
• 访问控制：API令牌权限和修改权限

系统架构

AI Assistant  ↔  MCP Protocol  ↔  Chain Debugger MCP Server  ↔  Tenderly API

服务器作为一个安全的中间代理运行，处理MCP请求到Tenderly API调用的转换，同时确保响应格式符合MCP规范要求。

配置约束

当前的实现在这些架构边界内运行：

• 环境配置：单人 .env 每个实例的文件支持。多环境配置需要单独的 .env 用于不同部署场景的文件或命令行参数重写。
• 网络连接：每个服务器实例一个EVM RPC端点。多链同时连接需要单独的服务器实例，尽管未来的架构增强将解决这一限制。
• 内存存储配置：单内存存储配置(ENABLE_MEMORY 和 MEMORY_STORE_PATH)每个实例。目前，单个进程中不支持多个内存后端。
• 分析配置：一个分析配置集(ENABLE_ANALYTICS 和 ANALYTICS_DB_PATH)每个服务器实例。

对于这些功能的不同配置要求，部署具有不同配置文件或命令行参数集的多个服务器实例。

安全评估与验证

✅ 全面安全验证已完成

安全分析结果

对该代码库的全面安全评估揭示了以下经过验证的发现：

✅ 依赖安全许可

• npm audit 确认 零漏洞 跨越所有依赖关系
• 所有依赖项均来自已建立、维护良好的存储库
• 没有已知的CVE暴露影响此项目的依赖链

✅ 非破坏性操作模型

• 独家 数据检索操作 -零修改能力
• 不对区块链网络、数据库或文件系统进行写操作
• 事务执行和状态突变在架构上是不可能的

✅ 安全通信标准

• 与官方Tenderly API的独家连接 (api.tenderly.co)通过HTTPS
• 与未经验证或潜在恶意端点的零连接
• 使用提供的令牌对所有API通信进行正确身份验证

✅ 安全凭据体系结构

• 全权证书仅通过以下方式管理 .env 文件（不包括版本控制）
• 源代码中的零硬编码机密或API密钥
• 使用前进行全面的环境变量验证

✅ 企业代码质量标准

• 完整的TypeScript实现 严格执行打字
• 全面的Zod验证 针对防止注入漏洞的所有API响应
• 干净、可维护的代码架构，具有强大的错误处理能力
• 完全没有eval（）、exec（）或其他潜在危险的函数

✅ 最低权限要求

• 操作方式 标准用户权限 -无需提升权限
• 文件系统修改严格限于项目目录范围
• 无系统级操作或管理访问要求

依赖信任验证

• @modelcontextprotocol/sdk -Anthropic维护的官方MCP SDK
• dotenv -行业标准、经过广泛审核的环境变量管理
• zod -具有经过验证的安全记录的TypeScript本机模式验证库

安全风险分类： 最小

此实现代表了一个简单、安全的API客户端，当使用正确的配置进行部署时，没有发现任何安全风险。

温柔的凭证设置

服务器操作需要有效的Tenderly API凭据：

1. 帐户注册 -建立一个 温柔的帐户
2. 项目初始化 -创建新项目或利用现有项目
3. API代币生成:

- 导航至 账户设置 - 选择“创建API密钥” - 安全地复制您生成的访问令牌

1. 凭证标识 -从Tendly仪表板URL中提取您的帐户段和项目ID：

- URL格式： https://dashboard.tenderly.co/{account-slug}/{project-id}/...

贡献

欢迎为这个项目捐款！请确保所有更改都保持既定的安全标准，并保持实现的架构简单性。

许可证

麻省理工学院