infura-mcp-server / rules

---
description: 
globs: 
alwaysApply: true
---
---
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):**
```javascript
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](mdc:https:/docs.metamask.io/services/get-started/endpoints)

### 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
```bash
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
```dockerfile
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
```javascript
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
```javascript
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: tools.map(tool => ({
    name: tool.name,
    description: tool.description,
    inputSchema: tool.inputSchema
  }))
}));
```

## Claude Desktop Configuration
```json
{
  "mcpServers": {
    "Infura MCP Server": {
      "command": "npx",
      "args": ["infura-mcp-server"],
      "env": {
        "INFURA_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

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

## Network-Specific Usage
```bash
# 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/`