eth-mcp 0.2.0__py3-none-any.whl

ethereum_mcp/clients.py

@@ -0,0 +1,363 @@
+"""Ethereum client tracking.
+
+Tracks execution layer (EL) and consensus layer (CL) client implementations.
+Ethereum has better client diversity than most chains - a key security feature.
+"""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class EthereumClient:
+    """An Ethereum client implementation."""
+
+    name: str
+    layer: str  # "execution", "consensus", "both"
+    organization: str
+    language: str
+    repo: str
+    description: str
+    mainnet_status: str  # "production", "beta", "development"
+    stake_percentage: float | None  # For CL clients
+    node_percentage: float | None  # For EL clients
+    key_features: list[str]
+    notes: list[str]
+
+
+# Execution Layer Clients
+EXECUTION_CLIENTS: list[EthereumClient] = [
+    EthereumClient(
+        name="Geth",
+        layer="execution",
+        organization="Ethereum Foundation",
+        language="Go",
+        repo="https://github.com/ethereum/go-ethereum",
+        description="Original and most widely used Ethereum execution client.",
+        mainnet_status="production",
+        stake_percentage=None,
+        node_percentage=55.0,  # Approximate as of late 2025
+        key_features=[
+            "Reference implementation",
+            "Most battle-tested",
+            "Snap sync for fast initial sync",
+            "Full and light node modes",
+        ],
+        notes=[
+            "Historically >80% dominance, now improving",
+            "Single Geth bug could halt network if >66%",
+            "EF actively encouraging diversity",
+        ],
+    ),
+    EthereumClient(
+        name="Reth",
+        layer="execution",
+        organization="Paradigm",
+        language="Rust",
+        repo="https://github.com/paradigmxyz/reth",
+        description="High-performance Rust implementation. Fast sync, modular architecture.",
+        mainnet_status="production",
+        stake_percentage=None,
+        node_percentage=15.0,  # Growing rapidly
+        key_features=[
+            "Written in Rust for safety and performance",
+            "Modular architecture (reth-* crates)",
+            "Fast sync times",
+            "Lower memory usage than Geth",
+            "Active development by Paradigm",
+        ],
+        notes=[
+            "Fastest growing EL client",
+            "Production-ready since 2024",
+            "Popular with infrastructure providers",
+            "Excellent documentation",
+        ],
+    ),
+    EthereumClient(
+        name="Nethermind",
+        layer="execution",
+        organization="Nethermind",
+        language="C#/.NET",
+        repo="https://github.com/NethermindEth/nethermind",
+        description="Enterprise-grade .NET implementation with extensive plugin system.",
+        mainnet_status="production",
+        stake_percentage=None,
+        node_percentage=18.0,
+        key_features=[
+            ".NET ecosystem integration",
+            "Extensive plugin system",
+            "Good for enterprise deployments",
+            "MEV-boost compatible",
+        ],
+        notes=[
+            "Second most used EL client",
+            "Popular with institutional stakers",
+            "Good Windows support",
+        ],
+    ),
+    EthereumClient(
+        name="Besu",
+        layer="execution",
+        organization="Hyperledger / ConsenSys",
+        language="Java",
+        repo="https://github.com/hyperledger/besu",
+        description="Enterprise Ethereum client, Apache 2.0 licensed.",
+        mainnet_status="production",
+        stake_percentage=None,
+        node_percentage=8.0,
+        key_features=[
+            "Apache 2.0 license (enterprise-friendly)",
+            "Privacy features (Tessera integration)",
+            "Permissioning for private networks",
+            "GraphQL API",
+        ],
+        notes=[
+            "Popular for enterprise and consortium chains",
+            "Hyperledger project governance",
+            "Good for private Ethereum networks",
+        ],
+    ),
+    EthereumClient(
+        name="Erigon",
+        layer="execution",
+        organization="Erigon (formerly Turbo-Geth)",
+        language="Go",
+        repo="https://github.com/ledgerwatch/erigon",
+        description="Efficiency-focused client optimized for archive nodes.",
+        mainnet_status="production",
+        stake_percentage=None,
+        node_percentage=4.0,
+        key_features=[
+            "Extremely efficient disk usage",
+            "Best for archive nodes",
+            "Staged sync architecture",
+            "Lower hardware requirements for full history",
+        ],
+        notes=[
+            "Forked from Geth, heavily modified",
+            "Preferred for archive node operators",
+            "Different database structure (MDBX)",
+        ],
+    ),
+]
+
+# Consensus Layer Clients
+CONSENSUS_CLIENTS: list[EthereumClient] = [
+    EthereumClient(
+        name="Prysm",
+        layer="consensus",
+        organization="Prysmatic Labs (Offchain Labs)",
+        language="Go",
+        repo="https://github.com/prysmaticlabs/prysm",
+        description="Most popular consensus client, originally the first to mainnet.",
+        mainnet_status="production",
+        stake_percentage=35.0,
+        node_percentage=None,
+        key_features=[
+            "First production CL client",
+            "Slasher included",
+            "Web UI for monitoring",
+            "gRPC and REST APIs",
+        ],
+        notes=[
+            "~35% of stake (down from >60% historically)",
+            "Now part of Offchain Labs (Arbitrum)",
+            "Diversity improving",
+        ],
+    ),
+    EthereumClient(
+        name="Lighthouse",
+        layer="consensus",
+        organization="Sigma Prime",
+        language="Rust",
+        repo="https://github.com/sigp/lighthouse",
+        description="Rust implementation focused on security and performance.",
+        mainnet_status="production",
+        stake_percentage=33.0,
+        node_percentage=None,
+        key_features=[
+            "Rust safety guarantees",
+            "Security audit focused",
+            "Efficient memory usage",
+            "Good documentation",
+        ],
+        notes=[
+            "~33% of stake - excellent diversity",
+            "Security-focused development",
+            "Popular with solo stakers",
+        ],
+    ),
+    EthereumClient(
+        name="Teku",
+        layer="consensus",
+        organization="ConsenSys",
+        language="Java",
+        repo="https://github.com/ConsenSys/teku",
+        description="Enterprise-grade Java implementation, pairs well with Besu.",
+        mainnet_status="production",
+        stake_percentage=18.0,
+        node_percentage=None,
+        key_features=[
+            "Java enterprise ecosystem",
+            "Pairs naturally with Besu",
+            "REST API focused",
+            "Good institutional support",
+        ],
+        notes=[
+            "~18% of stake",
+            "ConsenSys enterprise offering",
+            "Popular with institutions",
+        ],
+    ),
+    EthereumClient(
+        name="Nimbus",
+        layer="consensus",
+        organization="Status",
+        language="Nim",
+        repo="https://github.com/status-im/nimbus-eth2",
+        description="Lightweight client designed for resource-constrained devices.",
+        mainnet_status="production",
+        stake_percentage=10.0,
+        node_percentage=None,
+        key_features=[
+            "Extremely lightweight",
+            "Can run on Raspberry Pi",
+            "Low memory footprint",
+            "Nim language (compiles to C)",
+        ],
+        notes=[
+            "~10% of stake",
+            "Best for home stakers with limited hardware",
+            "Also developing EL client (nimbus-eth1)",
+        ],
+    ),
+    EthereumClient(
+        name="Lodestar",
+        layer="consensus",
+        organization="ChainSafe",
+        language="TypeScript",
+        repo="https://github.com/ChainSafe/lodestar",
+        description="TypeScript implementation, great for JS/TS developers.",
+        mainnet_status="production",
+        stake_percentage=4.0,
+        node_percentage=None,
+        key_features=[
+            "TypeScript/JavaScript ecosystem",
+            "Good for web3 developers",
+            "Light client focus",
+            "Browser-compatible components",
+        ],
+        notes=[
+            "~4% of stake",
+            "Youngest production CL client",
+            "Growing adoption",
+        ],
+    ),
+]
+
+
+def list_execution_clients() -> list[EthereumClient]:
+    """List all execution layer clients."""
+    return EXECUTION_CLIENTS
+
+
+def list_consensus_clients() -> list[EthereumClient]:
+    """List all consensus layer clients."""
+    return CONSENSUS_CLIENTS
+
+
+def list_all_clients() -> list[EthereumClient]:
+    """List all Ethereum clients."""
+    return EXECUTION_CLIENTS + CONSENSUS_CLIENTS
+
+
+def get_client(name: str) -> EthereumClient | None:
+    """Get a specific client by name."""
+    name_lower = name.lower()
+    for client in list_all_clients():
+        if name_lower in client.name.lower():
+            return client
+    return None
+
+
+def get_client_diversity() -> dict:
+    """Get Ethereum client diversity statistics."""
+    return {
+        "execution_layer": {
+            "Geth (Go)": "~55% - Reference implementation, still dominant",
+            "Nethermind (C#)": "~18% - Enterprise-focused",
+            "Reth (Rust)": "~15% - Fastest growing, Paradigm",
+            "Besu (Java)": "~8% - Enterprise/Hyperledger",
+            "Erigon (Go)": "~4% - Archive node specialist",
+        },
+        "consensus_layer": {
+            "Prysm (Go)": "~35% - Prysmatic Labs/Offchain Labs",
+            "Lighthouse (Rust)": "~33% - Sigma Prime",
+            "Teku (Java)": "~18% - ConsenSys",
+            "Nimbus (Nim)": "~10% - Status, lightweight",
+            "Lodestar (TypeScript)": "~4% - ChainSafe",
+        },
+        "diversity_health": {
+            "consensus_layer": "GOOD - No client >34% (supermajority threshold)",
+            "execution_layer": "MODERATE - Geth still >50%, improving",
+        },
+        "recommendations": [
+            "CL diversity is healthy - no client can cause finality failure alone",
+            "EL still needs improvement - Geth bug could affect majority",
+            "Reth growth is positive for EL diversity",
+            "Run minority clients if possible to help the network",
+        ],
+        "supermajority_risk": (
+            "If any client >66%, a bug in that client could cause "
+            "incorrect finalization, requiring manual intervention to fix"
+        ),
+    }
+
+
+def get_recommended_pairs() -> list[dict]:
+    """Get recommended EL+CL client pairs."""
+    return [
+        {
+            "pair": "Geth + Lighthouse",
+            "notes": "Most common, very stable",
+        },
+        {
+            "pair": "Reth + Lighthouse",
+            "notes": "Modern stack, both Rust, good performance",
+        },
+        {
+            "pair": "Nethermind + Prysm",
+            "notes": "Enterprise-friendly combination",
+        },
+        {
+            "pair": "Besu + Teku",
+            "notes": "Both ConsenSys/Java, enterprise pairing",
+        },
+        {
+            "pair": "Geth + Nimbus",
+            "notes": "Good for resource-constrained setups",
+        },
+        {
+            "pair": "Reth + Nimbus",
+            "notes": "Minimal resource usage, modern stack",
+        },
+    ]
+
+
+if __name__ == "__main__":
+    print("Ethereum Execution Layer Clients:")
+    print("=" * 60)
+    for c in EXECUTION_CLIENTS:
+        pct = f" ({c.node_percentage}%)" if c.node_percentage else ""
+        print(f"  {c.name}{pct} - {c.language} - {c.organization}")
+
+    print("\nEthereum Consensus Layer Clients:")
+    print("=" * 60)
+    for c in CONSENSUS_CLIENTS:
+        pct = f" ({c.stake_percentage}%)" if c.stake_percentage else ""
+        print(f"  {c.name}{pct} - {c.language} - {c.organization}")
+
+    print("\nClient Diversity:")
+    print("=" * 60)
+    diversity = get_client_diversity()
+    print(f"  EL: {diversity['diversity_health']['execution_layer']}")
+    print(f"  CL: {diversity['diversity_health']['consensus_layer']}")

ethereum_mcp/config.py

@@ -0,0 +1,324 @@
+"""Configuration management for ethereum-mcp.
+
+Supports loading configuration from:
+1. Default values
+2. Config file (~/.ethereum-mcp/config.yaml)
+3. Environment variables (for secrets like API keys)
+
+Configuration precedence: env vars > config file > defaults
+"""
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from .logging import get_logger
+
+logger = get_logger("config")
+
+# Default values
+DEFAULT_EMBEDDING_MODEL = "all-MiniLM-L6-v2"
+DEFAULT_BATCH_SIZE = 32
+DEFAULT_CHUNK_SIZE = 1000
+DEFAULT_CHUNK_OVERLAP = 200
+
+# Supported embedding models with their properties
+EMBEDDING_MODELS = {
+    # Local models (sentence-transformers)
+    "all-MiniLM-L6-v2": {
+        "dimensions": 384,
+        "max_tokens": 256,
+        "type": "local",
+        "description": "Fast, lightweight fallback model",
+    },
+    "all-mpnet-base-v2": {
+        "dimensions": 768,
+        "max_tokens": 384,
+        "type": "local",
+        "description": "Better quality, moderate speed",
+    },
+    "codesage/codesage-large": {
+        "dimensions": 1024,
+        "max_tokens": 1024,
+        "type": "local",
+        "description": "Code-specialized, recommended for specs",
+    },
+    # API models (require API keys)
+    "voyage:voyage-code-3": {
+        "dimensions": 1024,
+        "max_tokens": 16000,
+        "type": "api",
+        "env_var": "VOYAGE_API_KEY",
+        "description": "Best quality, requires API key ($0.06/1M tokens)",
+    },
+}
+
+
+class ConfigError(Exception):
+    """Configuration error."""
+
+    pass
+
+
+@dataclass
+class EmbeddingConfig:
+    """Embedding model configuration."""
+
+    model: str = DEFAULT_EMBEDDING_MODEL
+    batch_size: int = DEFAULT_BATCH_SIZE
+
+    @property
+    def model_info(self) -> dict[str, Any]:
+        """Get model info from EMBEDDING_MODELS."""
+        return EMBEDDING_MODELS.get(self.model, {})
+
+    @property
+    def dimensions(self) -> int:
+        """Get embedding dimensions for the model."""
+        return self.model_info.get("dimensions", 384)
+
+    @property
+    def requires_api_key(self) -> bool:
+        """Check if model requires an API key."""
+        return self.model_info.get("type") == "api"
+
+    @property
+    def api_key_env_var(self) -> str | None:
+        """Get the environment variable name for the API key."""
+        return self.model_info.get("env_var")
+
+    def validate(self) -> None:
+        """Validate configuration.
+
+        Raises ConfigError if validation fails.
+        """
+        if self.model not in EMBEDDING_MODELS:
+            logger.warning(
+                "Unknown embedding model: %s. Using default settings.", self.model
+            )
+
+        if self.requires_api_key:
+            env_var = self.api_key_env_var
+            if env_var and not os.environ.get(env_var):
+                raise ConfigError(
+                    f"Model {self.model} requires {env_var} environment variable"
+                )
+
+        if self.batch_size < 1:
+            raise ConfigError(f"batch_size must be >= 1, got {self.batch_size}")
+
+        if self.batch_size > 256:
+            logger.warning(
+                "Large batch_size (%d) may cause memory issues", self.batch_size
+            )
+
+
+@dataclass
+class ChunkingConfig:
+    """Document chunking configuration."""
+
+    chunk_size: int = DEFAULT_CHUNK_SIZE
+    chunk_overlap: int = DEFAULT_CHUNK_OVERLAP
+
+    def validate(self) -> None:
+        """Validate configuration.
+
+        Raises ConfigError if validation fails.
+        """
+        if self.chunk_size < 100:
+            raise ConfigError(f"chunk_size must be >= 100, got {self.chunk_size}")
+
+        if self.chunk_size > 10000:
+            raise ConfigError(f"chunk_size must be <= 10000, got {self.chunk_size}")
+
+        if self.chunk_overlap < 0:
+            raise ConfigError(f"chunk_overlap must be >= 0, got {self.chunk_overlap}")
+
+        if self.chunk_overlap >= self.chunk_size:
+            raise ConfigError(
+                f"chunk_overlap ({self.chunk_overlap}) must be < chunk_size ({self.chunk_size})"
+            )
+
+    def to_dict(self) -> dict[str, int]:
+        """Convert to dict for manifest storage."""
+        return {
+            "chunk_size": self.chunk_size,
+            "chunk_overlap": self.chunk_overlap,
+        }
+
+
+@dataclass
+class Config:
+    """Main configuration container."""
+
+    embedding: EmbeddingConfig = field(default_factory=EmbeddingConfig)
+    chunking: ChunkingConfig = field(default_factory=ChunkingConfig)
+
+    def validate(self) -> None:
+        """Validate all configuration."""
+        self.embedding.validate()
+        self.chunking.validate()
+
+
+def load_config(config_path: Path | None = None, data_dir: Path | None = None) -> Config:
+    """
+    Load configuration from file and environment.
+
+    Args:
+        config_path: Explicit path to config file (optional)
+        data_dir: Data directory to look for config.yaml (optional)
+
+    Returns:
+        Validated Config object
+    """
+    config = Config()
+
+    # Determine config file path
+    if config_path is None and data_dir is not None:
+        config_path = data_dir / "config.yaml"
+
+    # Load from file if exists
+    if config_path and config_path.exists():
+        try:
+            config = _load_config_file(config_path)
+            logger.debug("Loaded config from %s", config_path)
+        except Exception as e:
+            logger.warning("Failed to load config from %s: %s", config_path, e)
+            config = Config()
+
+    # Override with environment variables
+    config = _apply_env_overrides(config)
+
+    # Validate
+    config.validate()
+
+    return config
+
+
+def _load_config_file(config_path: Path) -> Config:
+    """Load configuration from YAML file."""
+    # Security: limit file size
+    max_size = 1024 * 1024  # 1MB
+    if config_path.stat().st_size > max_size:
+        raise ConfigError(f"Config file too large: {config_path.stat().st_size} > {max_size}")
+
+    with open(config_path, encoding="utf-8") as f:
+        # Use safe_load to prevent code execution
+        data = yaml.safe_load(f)
+
+    if data is None:
+        return Config()
+
+    if not isinstance(data, dict):
+        raise ConfigError("Config file must be a YAML mapping")
+
+    # Validate keys
+    allowed_keys = {"embedding", "chunking"}
+    unknown_keys = set(data.keys()) - allowed_keys
+    if unknown_keys:
+        logger.warning("Unknown config keys ignored: %s", unknown_keys)
+
+    # Parse embedding config
+    embedding_data = data.get("embedding", {})
+    if not isinstance(embedding_data, dict):
+        raise ConfigError("'embedding' must be a mapping")
+
+    embedding = EmbeddingConfig(
+        model=str(embedding_data.get("model", DEFAULT_EMBEDDING_MODEL)),
+        batch_size=int(embedding_data.get("batch_size", DEFAULT_BATCH_SIZE)),
+    )
+
+    # Parse chunking config
+    chunking_data = data.get("chunking", {})
+    if not isinstance(chunking_data, dict):
+        raise ConfigError("'chunking' must be a mapping")
+
+    chunking = ChunkingConfig(
+        chunk_size=int(chunking_data.get("chunk_size", DEFAULT_CHUNK_SIZE)),
+        chunk_overlap=int(chunking_data.get("chunk_overlap", DEFAULT_CHUNK_OVERLAP)),
+    )
+
+    return Config(embedding=embedding, chunking=chunking)
+
+
+def _apply_env_overrides(config: Config) -> Config:
+    """Apply environment variable overrides to config."""
+    # ETHEREUM_MCP_EMBEDDING_MODEL overrides config file
+    env_model = os.environ.get("ETHEREUM_MCP_EMBEDDING_MODEL")
+    if env_model:
+        config.embedding.model = env_model
+        logger.debug("Using embedding model from env: %s", env_model)
+
+    # ETHEREUM_MCP_BATCH_SIZE
+    env_batch = os.environ.get("ETHEREUM_MCP_BATCH_SIZE")
+    if env_batch:
+        try:
+            config.embedding.batch_size = int(env_batch)
+        except ValueError:
+            logger.warning("Invalid ETHEREUM_MCP_BATCH_SIZE: %s", env_batch)
+
+    return config
+
+
+def save_config(config: Config, config_path: Path) -> None:
+    """
+    Save configuration to YAML file.
+
+    Args:
+        config: Configuration to save
+        config_path: Path to write config file
+    """
+    data = {
+        "embedding": {
+            "model": config.embedding.model,
+            "batch_size": config.embedding.batch_size,
+        },
+        "chunking": {
+            "chunk_size": config.chunking.chunk_size,
+            "chunk_overlap": config.chunking.chunk_overlap,
+        },
+    }
+
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+
+    with open(config_path, "w", encoding="utf-8") as f:
+        yaml.dump(data, f, default_flow_style=False, sort_keys=False)
+
+    logger.info("Saved config to %s", config_path)
+
+
+def get_model_info(model_name: str | None = None) -> str:
+    """Get human-readable info about embedding models.
+
+    Args:
+        model_name: Specific model to get info for (None = all models)
+
+    Returns:
+        Formatted string with model information
+    """
+    if model_name:
+        if model_name not in EMBEDDING_MODELS:
+            return f"Unknown model: {model_name}"
+        info = EMBEDDING_MODELS[model_name]
+        return (
+            f"{model_name}:\n"
+            f"  Dimensions: {info['dimensions']}\n"
+            f"  Max tokens: {info['max_tokens']}\n"
+            f"  Type: {info['type']}\n"
+            f"  Description: {info['description']}"
+        )
+
+    lines = ["Available embedding models:\n"]
+    for name, info in EMBEDDING_MODELS.items():
+        marker = " (default)" if name == DEFAULT_EMBEDDING_MODEL else ""
+        api_note = " [requires API key]" if info["type"] == "api" else ""
+        lines.append(
+            f"  {name}{marker}{api_note}\n"
+            f"    {info['dimensions']} dims, {info['max_tokens']} tokens\n"
+            f"    {info['description']}\n"
+        )
+
+    return "\n".join(lines)

ethereum_mcp/expert/__init__.py

@@ -0,0 +1 @@
+"""Expert guidance system for curated interpretations."""