Chain Debugger MCP Server

<img width="1024" height="1536" alt="image" src="https://github.com/user-attachments/assets/a91ae637-38a3-47a8-8ceb-3e18144479d0" /> # Chain Debugger MCP Server An integrated MCP (Model Context Protocol) server providing dual blockchain connectivity: - **Tenderly Integration**: Comprehensive read-only access to Tenderly's monitoring infrastructure and alerting systems - **Universal EVM RPC Support**: Native JSON-RPC communication with any EVM-compatible blockchain network Built to bridge AI assistants with blockchain ecosystems, enabling seamless monitoring through Tenderly while maintaining direct chain interaction capabilities via standardized protocols. ## Overview This MCP server establishes a robust connection between AI systems and blockchain infrastructure via the [Model Context Protocol](https://modelcontextprotocol.io/). The server empowers AI assistants like Claude with comprehensive blockchain capabilities: **Tenderly Integration:** - **Complete alert management** - Full access to all project alerts with detailed metadata - **Granular alert inspection** - Deep-dive into specific alerts by ID with comprehensive details - **Advanced monitoring analytics** - Process blockchain monitoring data for actionable insights - **Transaction simulation engine** - Leverage Tenderly's sophisticated simulation capabilities **EVM RPC Capabilities:** - **Universal JSON-RPC execution** - Run any standard or custom RPC method across EVM networks - **Direct blockchain querying** - Access balances, transactions, blocks, and contract data natively - **Multi-chain architecture** - Configurable endpoints supporting diverse EVM-compatible networks - **Specialized chain functions** - Enhanced features for specific networks (Zircuit quarantine system, etc.) ### Core Architecture Features - 🔒 **Non-invasive design** - Exclusively retrieval-based operations with zero modification capabilities - 🚀 **Plug-and-play compatibility** - Seamless integration with any MCP-compliant AI assistant - 📊 **Comprehensive alert intelligence** - Full access to alert expressions, delivery configurations, severity classifications, and metadata - 🛡️ **Enterprise-grade type safety** - Complete TypeScript implementation with comprehensive Zod schema validation - 🔐 **Security-first credential handling** - Environment-based secret management with zero hardcoded credentials ## Prerequisites - Node.js v16+ runtime environment - Active Tenderly account with API privileges - Tenderly authentication credentials (account slug, project identifier, access token) - Optional: EVM RPC endpoint URL for direct blockchain connectivity ## Installation & Configuration 1. Clone the repository to your local environment 2. Install all required dependencies: ```bash pnpm install ``` 3. Initialize your environment configuration: ```bash cp .env.example .env ``` 4. Configure your `.env` file with the following parameters: ``` # 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 ``` 5. Compile the TypeScript project: ```bash pnpm run build ``` ## Transport Modes This server can run in three modes: - **Stdio (default)**: best for local dev and SSH/containers - **HTTP**: stateless Streamable HTTP endpoint at `/mcp` - **HTTPS**: secure HTTP with SSL/TLS certificates Configure via environment variables (see `.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 ``` ## Usage ### Server Execution (stdio) Launch the MCP server: ```bash pnpm start ``` The server operates through stdio (standard input/output) communication following MCP specification standards. Initialization logs output to stderr while the server awaits MCP protocol messages via stdin. For dynamic EVM RPC configuration, command-line arguments are supported: ```bash pnpm start -- --rpc-url https://mainnet.zircuit.com --chain-name Zircuit --analytics ``` ### Server Execution (HTTP) Run with HTTP transport: ```bash MCP_TRANSPORT=http PORT=3000 pnpm start ``` The server will listen on `http://0.0.0.0:3000/mcp` and accept MCP JSON-RPC requests via POST. Simple health/method check: ```bash curl -i http://localhost:3000/mcp # returns 405 for GET (POST is required) ``` To call from a browser context, set `CORS_ORIGINS` to your client origin(s). ### Server Execution (HTTPS) For HTTPS support, first generate self-signed certificates: ```bash ./generate-certs.sh ``` Then run with HTTPS enabled: ```bash # 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 ``` The server will listen on `https://0.0.0.0:3000/mcp` with SSL/TLS encryption. **Note**: For development with self-signed certificates, you'll need to accept the certificate warning in your browser or configure your MCP client to ignore SSL verification. ### AI Assistant Integration Once operational, AI assistants gain access to your Tenderly infrastructure through the following capabilities: **Resource Endpoints:** - `tenderly://alerts` - Complete JSON enumeration of all project alerts with metadata - `tenderly://simulations` - Direct access to Tenderly's transaction simulation infrastructure - `evm://rpc_info` - Current EVM RPC connection status and configuration details - `evm://chain_info` - Network identification and chain-specific metadata **Functional Tools:** - `get_alert_by_id(id: string)` - Detailed alert retrieval with comprehensive metadata - `simulate_transaction(...)` - Advanced transaction simulation via Tenderly's engine - `eth_json_rpc_call(method, params)` - Universal Ethereum JSON-RPC method execution - `zirc_isQuarantined(transactionHash)` - Zircuit-specific transaction quarantine status checking - `zirc_getQuarantined(address?)` - Quarantined transaction enumeration for Zircuit network ### Practical Use Cases With the server connected to an AI assistant, you can perform queries such as: **Tenderly Operations:** - *"Enumerate all alerts configured in my Tenderly project"* - *"Provide comprehensive details for alert ID abc123"* - *"Identify which alerts are currently active and operational"* - *"Analyze the most critical alerts requiring immediate attention"* - *"Execute a simulation for a 1 ETH transfer between specified addresses"* **EVM RPC Operations:** - *"Retrieve the current blockchain height"* - *"Query ETH balance for address 0x742d35Cc6634C0532925a3b844Bc454e4438f44e"* - *"Fetch transaction receipt for hash 0x5c504ed432cb51138bcf09aa5e8a410dd4a1e204ef84bfed1be16dfba1b22060"* - *"Extract bytecode from the USDC contract address"* - *"Verify quarantine status for transaction 0xabc..."* (Zircuit-specific) The AI assistant leverages this server to retrieve blockchain data and deliver sophisticated analysis of your on-chain activities. ### Development & Testing The MCP Inspector provides comprehensive server testing capabilities: ```bash # Build and launch inspection interface make inspect ``` This launches a web-based interface enabling direct testing of all MCP resources and tools. ## Docker ### Build ```bash docker build -t chain-debugger-mcp:local . ``` ### Run (stdio) ```bash docker run --rm -i \ --env-file .env \ -e MCP_TRANSPORT=stdio \ -v "$PWD/data:/data" -v "$PWD/cache:/cache" \ chain-debugger-mcp:local ``` ### Run (HTTP) ```bash 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 ``` ### Run (HTTPS) First generate certificates, then run with HTTPS: ```bash # 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 See `docker-compose.yml` for a minimal service configured for stdio transport with mounted volumes and `.env`. ## SSH Wrapper (remote stdio) Use `scripts/ssh-stdio-wrapper.sh` to run the container on a remote host and proxy stdio over SSH. Required environment variables: ``` 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 ``` Then point your MCP client to execute the script as the server command. The script runs Docker with `-i` preserving stdio and passes your env/volumes. ## Technical Architecture ### MCP Resource & Tool Implementation **Resource Infrastructure:** - `tenderly://alerts` - Comprehensive alert enumeration from your Tenderly project, including: - Complete alert metadata (IDs, names, descriptions) - Operational status indicators (enabled/disabled states) - Alert expression logic and trigger conditions - Delivery channel configurations and routing - Severity classification and visual coding - Temporal metadata (creation and modification timestamps) **Tool Framework:** - `get_alert(id: string)` - Granular alert data retrieval with complete metadata extraction ### Data Structure Design The server returns structured alert data containing: - **Core Attributes**: Unique identifiers, names, descriptions, operational status - **Logic Components**: Trigger expressions, conditional logic, evaluation criteria - **Distribution Configuration**: Delivery mechanisms, routing destinations, notification channels - **System Metadata**: Project associations, temporal markers, severity indicators, visual classifications - **Access Control**: API token permissions and modification privileges ### System Architecture ``` AI Assistant ↔ MCP Protocol ↔ Chain Debugger MCP Server ↔ Tenderly API ``` The server operates as a secure intermediary proxy, handling MCP request translation to Tenderly API calls while ensuring response formatting adheres to MCP specification requirements. ## Configuration Constraints The current implementation operates within these architectural boundaries: - **Environment Configuration**: Single `.env` file support per instance. Multi-environment configurations require separate `.env` files or command-line parameter overrides for different deployment scenarios. - **Network Connectivity**: One EVM RPC endpoint per server instance. Multi-chain simultaneous connections require separate server instances, though future architectural enhancements will address this limitation. - **Memory Store Configuration**: Single memory store configuration (`ENABLE_MEMORY` and `MEMORY_STORE_PATH`) per instance. Multiple memory backends are not currently supported within a single process. - **Analytics Configuration**: One analytics configuration set (`ENABLE_ANALYTICS` and `ANALYTICS_DB_PATH`) per server instance. For diverse configuration requirements across these features, deploy multiple server instances with distinct configuration profiles or command-line parameter sets. ## Security Assessment & Verification **✅ COMPREHENSIVE SECURITY VALIDATION COMPLETED** ### Security Analysis Results A thorough security evaluation of this codebase reveals the following validated findings: **✅ Dependency Security Clearance** - `npm audit` confirms **zero vulnerabilities** across all dependencies - All dependencies sourced from established, well-maintained repositories - No known CVE exposures affecting this project's dependency chain **✅ Non-Destructive Operation Model** - Exclusively **data retrieval operations** - zero modification capabilities - No write operations to blockchain networks, databases, or file systems - Transaction execution and state mutation are architecturally impossible **✅ Secure Communication Standards** - **Exclusive connections to official Tenderly API** (`api.tenderly.co`) via HTTPS - Zero connections to unverified or potentially malicious endpoints - All API communications properly authenticated using provided tokens **✅ Secure Credential Architecture** - Credentials exclusively managed through `.env` files (version control excluded) - Zero hardcoded secrets or API keys within source code - Comprehensive environment variable validation prior to utilization **✅ Enterprise Code Quality Standards** - **Complete TypeScript implementation** with strict typing enforcement - **Comprehensive Zod validation** for all API responses preventing injection vulnerabilities - Clean, maintainable code architecture with robust error handling - Complete absence of eval(), exec(), or other potentially dangerous functions **✅ Minimal Privilege Requirements** - Operates with **standard user permissions** - no elevated privileges required - File system modifications strictly limited to project directory scope - Zero system-level operations or administrative access requirements ### Dependency Trust Verification - `@modelcontextprotocol/sdk` - Official MCP SDK maintained by Anthropic - `dotenv` - Industry-standard, extensively audited environment variable management - `zod` - TypeScript-native schema validation library with proven security record ### Security Risk Classification: **MINIMAL** This implementation represents a straightforward, secure API client with zero identified security risks when deployed with proper configuration. ## Tenderly Credential Setup Server operation requires valid Tenderly API credentials: 1. **Account Registration** - Establish a [Tenderly account](https://tenderly.co/) 2. **Project Initialization** - Create a new project or utilize an existing project 3. **API Token Generation**: - Navigate to [Account Settings](https://dashboard.tenderly.co/account/api-keys) - Select "Create API Key" - Securely copy your generated access token 4. **Credential Identification** - Extract your account slug and project ID from the Tenderly dashboard URL: - URL Format: `https://dashboard.tenderly.co/{account-slug}/{project-id}/...` ## Contributing Contributions to this project are welcome! Please ensure all changes preserve the established security standards and maintain the implementation's architectural simplicity. ## License MIT