Instruction file imported from Qbandev/infura-mcp-server (.cursor/rules/infura-mcp-server.mdc). Copyright stays with the author.

description: "Comprehensive project context for the Infura MCP Server - provides technical architecture, development guidelines, testing strategy, release automation, and blockchain integration details" globs:

• "*.js"
• "*.json"
• "package.json"
• "*.md"
• ".github/**/*"
• "tools/**/*"
• "scripts/**/*"
• "test/**/*" alwaysApply: true

Infura MCP Server Project Context

📚 AI Assistant Resources

This document provides comprehensive guidance for AI assistants on:

• 29 read-only Ethereum JSON-RPC tools usage patterns
• Blockchain integration and technical architecture
• Security best practices
• Development guidelines
• Common troubleshooting scenarios

Project Overview

The Infura MCP Server is a Model Context Protocol (MCP) server that provides 29 read-only Ethereum JSON-RPC tools with multi-network support. It enables AI assistants like Claude Desktop and Cursor to interact with Ethereum blockchain data through Infura's infrastructure.

Key Statistics

• Language: Node.js ES modules (type: "module")
• Tools: 29 read-only Ethereum JSON-RPC methods
• Networks: 30+ network endpoints across 18 blockchain ecosystems supported
• Transport: SSE and stdio modes
• Version: Published on npm as infura-mcp-server
• Security: GPG signed commits, strict release access control

Technical Architecture

Core Files

• mcpServer.js - Main MCP server implementation
• index.js - Entry point and CLI handling
• tools/ - 29 read-only Ethereum JSON-RPC tools
• commands/ - Command definitions and metadata
• lib/ - Utility functions and helpers
• test/ - Validation and testing scripts

Supported Networks

Primary Networks (fully tested):

const PRIMARY_NETWORKS = {
  mainnet: 'mainnet',
  optimism: 'optimism-mainnet', 
  arbitrum: 'arbitrum-mainnet',
  polygon: 'polygon-mainnet',
  base: 'base-mainnet',
  sepolia: 'sepolia'
};

Additional Infura Networks (available via INFURA_NETWORK env var):

• avalanche-mainnet / avalanche-fuji - Avalanche C-Chain
• bsc-mainnet / bsc-testnet - Binance Smart Chain
• celo-mainnet / celo-alfajores - Celo
• linea-mainnet / linea-sepolia - Linea
• mantle-mainnet / mantle-sepolia - Mantle
• palm-mainnet / palm-testnet - Palm
• scroll-mainnet / scroll-sepolia - Scroll
• starknet-mainnet / starknet-sepolia - Starknet
• zksync-mainnet / zksync-sepolia - ZKsync Era
• blast-mainnet / blast-sepolia - Blast
• opbnb-mainnet / opbnb-testnet - opBNB
• swellchain-mainnet / swellchain-testnet - Swellchain
• unichain-mainnet / unichain-sepolia - Unichain

Reference: Complete Infura Endpoints List

Environment Variables

• INFURA_API_KEY - Required Infura API key
• INFURA_NETWORK - Network selection (defaults to mainnet)
• DEBUG - Enable debug logging

Available Tools (29)

Account & Balance Tools

• eth_getBalance - Get the native token balance of an account.
• eth_getCode - Get the compiled smart contract code at an address.
• eth_getTransactionCount - Get the number of transactions sent from an address (nonce).

Block Tools

• eth_getBlockNumber - Get the number of the most recent block.
• eth_getBlockByHash - Get information on a block by its hash.
• eth_getBlockByNumber - Get information on a block by its number.
• eth_getUncleByBlockHashAndIndex - Get information about an uncle of a block by hash and index.
• eth_getUncleByBlockNumberAndIndex - Get information about an uncle of a block by number and index.
• eth_getUncleCountByBlockHash - Get the number of uncles in a block from a block matching the given block hash.
• eth_getUncleCountByBlockNumber - Get the number of uncles in a block matching the given block number.

Transaction Tools

• eth_getBlockTransactionCountByHash - Get the number of transactions in a block from a block matching the given hash.
• eth_getBlockTransactionCountByNumber - Get the number of transactions in a block matching the given block number.
• eth_getTransactionByBlockHashAndIndex - Get information about a transaction by block hash and transaction index position.
• eth_getTransactionByBlockNumberAndIndex - Get information about a transaction by block number and transaction index.
• eth_getTransactionByHash - Get the information about a transaction requested by transaction hash.
• eth_getTransactionReceipt - Get the receipt of a transaction by transaction hash.

Smart Contract Tools

• eth_call - Execute a read-only call to a smart contract.
• eth_estimateGas - Estimate the gas necessary to perform a transaction.
• eth_getStorageAt - Get the value from a storage position at a given address.
• eth_getLogs - Get an array of all logs matching a given filter object.

Network & Node Tools

• eth_chainId - Get the chain ID of the current network.
• net_isListening - Check if the client is actively listening for network connections.
• net_getPeerCount - Get the number of peers currently connected to the client.
• net_getVersion - Get the network ID.
• web3_getClientVersion - Get the current client version.
• eth_getProtocolVersion - Get the current ethereum protocol version.
• eth_isSyncing - Check if the node is currently synchronizing with the network.

Fee & Gas Tools

• eth_getFeeHistory - Get historical gas fee data.
• eth_getGasPrice - Get the current price per gas in wei.

Development Guidelines

Code Style

• Use English for all code, documentation, and comments
• Follow ES module syntax (import/export)
• Use camelCase for variables and functions
• Use PascalCase for class names
• Use snake_case for file names
• Implement proper error handling with structured responses

Testing Strategy

npm test           # Run validation + tools discovery
npm run test:validate  # Package.json validation
npm run test:tools     # Validate all 29 tools
npm run test:sse       # SSE functionality test

Docker Support

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
EXPOSE 3000
CMD ["npm", "start"]

Release Automation & Security

Automated Release System

• Scripts: scripts/release.sh (bash) and scripts/release.js (Node.js)
• NPM Commands: npm run release:patch|minor|major|beta|alpha
• GitHub Workflows: Automated testing, versioning, tagging, and publishing

Security Features

• Access Control: Only repository owner (Qbandev) can trigger releases
• Authorization Job: Pre-flight security check in GitHub Actions
• GPG Signatures: All commits must be GPG signed
• Audit Logging: All release attempts logged for security monitoring

Release Process

1. Authorization verification (owner check)
2. Comprehensive testing (all 29 tools)
3. Version bumping (semantic versioning)
4. Git tagging and changelog generation
5. GitHub release creation
6. Automatic npm publishing

Error Handling Patterns

Structured Error Responses

return {
  isError: true,
  error: {
    code: 'INFURA_ERROR',
    message: 'Human-readable error message',
    details: errorDetails
  }
};

Common Error Types

• INFURA_API_ERROR - Infura service errors
• INVALID_PARAMETERS - Parameter validation failures
• NETWORK_ERROR - Connection issues
• RATE_LIMIT_ERROR - API rate limiting

MCP Integration

Transport Modes

• stdio: Standard input/output for Claude Desktop
• SSE: Server-Sent Events for web applications

Tool Registration

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: tools.map(tool => ({
    name: tool.name,
    description: tool.description,
    inputSchema: tool.inputSchema
  }))
}));

Claude Desktop Configuration

{
  "mcpServers": {
    "Infura MCP Server": {
      "command": "npx",
      "args": ["infura-mcp-server"],
      "env": {
        "INFURA_API_KEY": "your_api_key_here"
      }
    }
  }
}

Cursor Integration

{
  "mcpServers": {
    "Infura MCP Server": {
      "command": "npx", 
      "args": ["infura-mcp-server"],
      "env": {
        "INFURA_API_KEY": "your_api_key_here"
      }
    }
  }
}

Network-Specific Usage

# Mainnet (default)
INFURA_API_KEY=your_key npx infura-mcp-server

# Polygon 
INFURA_API_KEY=your_key INFURA_NETWORK=polygon-mainnet npx infura-mcp-server

# Arbitrum
INFURA_API_KEY=your_key INFURA_NETWORK=arbitrum-mainnet npx infura-mcp-server

# Avalanche C-Chain
INFURA_API_KEY=your_key INFURA_NETWORK=avalanche-mainnet npx infura-mcp-server

# Binance Smart Chain
INFURA_API_KEY=your_key INFURA_NETWORK=bsc-mainnet npx infura-mcp-server

Performance Considerations

Rate Limiting

• Infura enforces API rate limits
• Implement exponential backoff for retries
• Cache frequently accessed data when appropriate

Gas Optimization

• Use eth_estimateGas before transactions
• Monitor gas prices with eth_gasPrice
• Consider EIP-1559 fee mechanisms

Contributing Guidelines

Conventional Commits

• feat: - New features
• fix: - Bug fixes
• docs: - Documentation changes
• test: - Test additions/changes
• ci: - CI/CD changes
• security: - Security improvements

Development Workflow

1. Clone repository
2. Install dependencies: npm install
3. Set environment variables
4. Run tests: npm test
5. Create feature branch
6. Make changes with GPG signed commits
7. Submit pull request

Security Requirements

• All commits must be GPG signed
• Follow principle of least privilege
• Validate all user inputs
• Use environment variables for secrets
• Regular security audits of dependencies

Important Files Reference

• package.json - Project metadata and dependencies
• mcpServer.js - Core server implementation
• tools/ - All 29 read-only Ethereum JSON-RPC tools
• .github/workflows/