eth-mcp 0.2.0__py3-none-any.whl

eth_mcp-0.2.0.dist-info/METADATA

@@ -0,0 +1,332 @@
+Metadata-Version: 2.4
+Name: eth-mcp
+Version: 0.2.0
+Summary: RAG-powered MCP server for Ethereum consensus specs and EIPs
+Project-URL: Homepage, https://github.com/be-nvy/ethereum-mcp
+Project-URL: Documentation, https://github.com/be-nvy/ethereum-mcp#readme
+Project-URL: Repository, https://github.com/be-nvy/ethereum-mcp.git
+Project-URL: Issues, https://github.com/be-nvy/ethereum-mcp/issues
+Project-URL: Changelog, https://github.com/be-nvy/ethereum-mcp/blob/main/CHANGELOG.md
+Author: be.nvy
+License-Expression: MIT
+Keywords: consensus,eip,embeddings,ethereum,llm,mcp,model-context-protocol,rag,search
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: click>=8.0
+Requires-Dist: fastmcp>=0.4.0
+Requires-Dist: gitpython>=3.1.0
+Requires-Dist: lancedb>=0.6.0
+Requires-Dist: langchain-text-splitters>=0.0.1
+Requires-Dist: langchain>=0.1.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: sentence-transformers>=2.2.0
+Provides-Extra: clients
+Requires-Dist: tree-sitter-go>=0.20.0; extra == 'clients'
+Requires-Dist: tree-sitter-rust>=0.20.0; extra == 'clients'
+Requires-Dist: tree-sitter>=0.20.0; extra == 'clients'
+Provides-Extra: dev
+Requires-Dist: build>=1.0.0; extra == 'dev'
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Requires-Dist: twine>=4.0.0; extra == 'dev'
+Provides-Extra: voyage
+Requires-Dist: voyageai>=0.2.0; extra == 'voyage'
+Description-Content-Type: text/markdown
+
+# ethereum-mcp
+
+RAG-powered MCP server for Ethereum consensus specs, EIPs, and client source code.
+
+[![PyPI version](https://badge.fury.io/py/ethereum-mcp.svg)](https://badge.fury.io/py/ethereum-mcp)
+[![CI](https://github.com/be-nvy/ethereum-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/be-nvy/ethereum-mcp/actions/workflows/ci.yml)
+
+## What It Does
+
+Indexes and searches across:
+- **Consensus Specs** - Official beacon chain specifications
+- **EIPs** - Ethereum Improvement Proposals
+- **Builder Specs** - MEV-boost and PBS specifications
+- **Client Source Code** - All major EL and CL implementations
+
+## Installation
+
+```bash
+# From PyPI
+pip install ethereum-mcp
+
+# From source
+pip install -e .
+
+# With client code parsing support
+pip install -e ".[clients]"
+
+# With Voyage API embeddings (best quality)
+pip install -e ".[voyage]"
+```
+
+## Quick Start
+
+```bash
+# Build the index (downloads specs + creates embeddings)
+ethereum-mcp build
+
+# Search the specs
+ethereum-mcp search "slashing penalty"
+
+# Check status
+ethereum-mcp status
+```
+
+## Features
+
+### Incremental Indexing
+
+The v0.2.0 release introduces **incremental indexing** - only re-embeds changed files instead of rebuilding the entire index. This reduces update time from minutes to seconds.
+
+```bash
+# Update repos and incrementally re-index (fast!)
+ethereum-mcp update
+
+# Incremental index (default behavior)
+ethereum-mcp index
+
+# Preview what would change without indexing
+ethereum-mcp index --dry-run
+
+# Force full rebuild
+ethereum-mcp index --full
+```
+
+**How it works:**
+1. Tracks file hashes and modification times in a manifest
+2. Detects which files changed since last index
+3. Only re-embeds the changed content
+4. Updates LanceDB incrementally (add/delete operations)
+
+### Configurable Embedding Models
+
+Choose from multiple embedding models based on your quality/speed tradeoff:
+
+```bash
+# List available models
+ethereum-mcp models
+
+# Use a specific model
+ethereum-mcp index --model codesage/codesage-large
+```
+
+| Model | Dims | Quality | Speed | Notes |
+|-------|------|---------|-------|-------|
+| `all-MiniLM-L6-v2` | 384 | Fair | Fast | Default, good for quick searches |
+| `all-mpnet-base-v2` | 768 | Good | Medium | Better quality |
+| `codesage/codesage-large` | 1024 | Good | Medium | Code-specialized |
+| `voyage:voyage-code-3` | 1024 | Excellent | API | Best quality, requires API key |
+
+Configure in `~/.ethereum-mcp/config.yaml`:
+
+```yaml
+embedding:
+  model: "codesage/codesage-large"
+  batch_size: 32
+
+chunking:
+  chunk_size: 1000
+  chunk_overlap: 200
+```
+
+### Expert Guidance
+
+Curated knowledge beyond what's in the specs:
+
+```bash
+# Via CLI (when running as MCP server)
+eth_expert_guidance("slashing")
+eth_expert_guidance("mev")
+eth_expert_guidance("maxeb")
+```
+
+Topics include: `churn`, `slashing`, `maxeb`, `withdrawals`, `mev`, `pbs`, `epbs`, `mev_boost`, `flashbots`
+
+## CLI Commands
+
+```bash
+# Full build pipeline
+ethereum-mcp build                    # Specs + EIPs only
+ethereum-mcp build --include-clients  # Include client source code
+ethereum-mcp build --full             # Force full rebuild
+
+# Individual steps
+ethereum-mcp download                 # Clone consensus-specs, EIPs, builder-specs
+ethereum-mcp download --include-clients
+ethereum-mcp compile                  # Extract specs to JSON
+ethereum-mcp index                    # Build vector embeddings
+ethereum-mcp index --dry-run          # Preview changes
+ethereum-mcp index --full             # Force full rebuild
+ethereum-mcp index --model MODEL      # Use specific embedding model
+
+# Update (git pull + incremental index)
+ethereum-mcp update
+ethereum-mcp update --full            # Update + force rebuild
+
+# Search
+ethereum-mcp search "slashing penalty"
+ethereum-mcp search "attestation" --fork electra
+ethereum-mcp search "EIP-4844" --limit 10
+
+# Info
+ethereum-mcp status                   # Index status, manifest info
+ethereum-mcp models                   # List embedding models
+```
+
+## MCP Tools
+
+When running as an MCP server:
+
+| Tool | Purpose |
+|------|---------|
+| `eth_search` | Unified search across specs + EIPs |
+| `eth_search_specs` | Specs-only search (no EIPs) |
+| `eth_search_eip` | EIP-specific search |
+| `eth_grep_constant` | Fast constant lookup |
+| `eth_analyze_function` | Get Python implementation from specs |
+| `eth_get_current_fork` | Current fork (Electra/Pectra) |
+| `eth_list_forks` | All upgrades with dates/epochs |
+| `eth_get_spec_version` | Index metadata |
+| `eth_expert_guidance` | Curated expert interpretations |
+| `eth_list_clients` | List all EL/CL clients |
+| `eth_get_client` | Details on specific client |
+| `eth_get_client_diversity` | Diversity stats and health |
+| `eth_get_recommended_client_pairs` | EL+CL pairing recommendations |
+
+## Client Source Code
+
+### Execution Layer Clients
+
+| Client | Language | Organization |
+|--------|----------|--------------|
+| Geth | Go | Ethereum Foundation |
+| Reth | Rust | Paradigm |
+| Nethermind | C# | Nethermind |
+| Besu | Java | Hyperledger/ConsenSys |
+| Erigon | Go | Erigon |
+
+### Consensus Layer Clients
+
+| Client | Language | Organization |
+|--------|----------|--------------|
+| Prysm | Go | Offchain Labs |
+| Lighthouse | Rust | Sigma Prime |
+| Teku | Java | ConsenSys |
+| Nimbus | Nim | Status |
+| Lodestar | TypeScript | ChainSafe |
+
+```bash
+# Download specific clients
+ethereum-mcp download-clients --client reth --client lighthouse
+
+# Download MEV infrastructure
+ethereum-mcp download-clients --client mev-boost --client flashbots-builder
+```
+
+## Project Structure
+
+```
+src/ethereum_mcp/
+├── server.py               # MCP server (FastMCP)
+├── cli.py                  # CLI commands
+├── config.py               # Configuration management
+├── clients.py              # Client tracking and diversity
+├── indexer/
+│   ├── downloader.py       # Git clone specs + clients
+│   ├── compiler.py         # Spec extraction
+│   ├── client_compiler.py  # Multi-language client parsing
+│   ├── chunker.py          # Document chunking + chunk IDs
+│   ├── embedder.py         # Embeddings + LanceDB + incremental
+│   └── manifest.py         # File tracking for incremental updates
+└── expert/
+    └── guidance.py         # Curated interpretations
+```
+
+## Data Location
+
+```
+~/.ethereum-mcp/
+├── config.yaml             # Configuration (optional)
+├── manifest.json           # Index state tracking
+├── consensus-specs/        # Cloned specs repo
+├── EIPs/                   # Cloned EIPs repo
+├── builder-specs/          # Cloned builder-specs repo
+├── clients/                # Client source code (optional)
+├── compiled/               # Extracted JSON
+└── lancedb/                # Vector index
+```
+
+## Fork History
+
+| Fork | Epoch | Date | Description |
+|------|-------|------|-------------|
+| Phase0 | 0 | 2020-12-01 | Beacon chain genesis |
+| Altair | 74240 | 2021-10-27 | Light clients, sync committees |
+| Bellatrix | 144896 | 2022-09-06 | Merge preparation |
+| Capella | 194048 | 2023-04-12 | Withdrawals enabled |
+| Deneb | 269568 | 2024-03-13 | Proto-danksharding (EIP-4844) |
+| Electra | 364032 | 2025-05-07 | MaxEB, consolidations |
+| Fulu | 411392 | 2025-11-15 | PeerDAS, verkle prep |
+
+## Development
+
+```bash
+# Install with dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Run tests with coverage
+pytest --cov=ethereum_mcp
+
+# Lint
+ruff check src/
+```
+
+## Running as MCP Server
+
+```bash
+# Start the server
+eth-mcp
+
+# Or with uvicorn for development
+uvicorn ethereum_mcp.server:mcp --reload
+```
+
+Add to your Claude Code MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "ethereum": {
+      "command": "eth-mcp"
+    }
+  }
+}
+```
+
+## Documentation
+
+- [Incremental Indexing](docs/INCREMENTAL_INDEXING.md) - How the incremental update system works
+- [CLAUDE.md](CLAUDE.md) - Quick reference for Claude Code
+
+## License
+
+MIT

eth_mcp-0.2.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+ethereum_mcp/__init__.py,sha256=kdB3a2OWIoB1oTsSx0oHm_u6GDnxuAl-QdurBkEDuZQ,89
+ethereum_mcp/cli.py,sha256=mXLlV5ywYrdKrellfGH0v35o7gdUrTga1NRqo6IV0c4,21654
+ethereum_mcp/clients.py,sha256=WLp8-8o1jFsEA-MPEvaYCWvypZEsovecM6nyX3TB-_w,12083
+ethereum_mcp/config.py,sha256=CCTSmzAr__3Q59VBtbbgNCOyOiVMzNWqjsjjGUlu-d0,9783
+ethereum_mcp/logging.py,sha256=Wt5nYveOgIBakGnlgvGZ_o_BGBJgbyGpYTki9wEC2Ec,2043
+ethereum_mcp/models.py,sha256=V5NMk5kdqcKgLHcZGE9G5nOYz6tZUvq4HXpTa145I10,3893
+ethereum_mcp/server.py,sha256=7-T6YrQFb7CLTxQ3cfq-8pFvkbojokdO44GFK-UF8Yw,15661
+ethereum_mcp/expert/__init__.py,sha256=19vU-7Arc1qM5EDIZkLg87VnyI4T-aQS9XswtRI_86g,58
+ethereum_mcp/expert/guidance.py,sha256=YeBRRu8Mz7vMc7NHcSLeCwy92X2GlHioRY9_p06KpB8,14681
+ethereum_mcp/indexer/__init__.py,sha256=wlQ4Kk0fe5jn6TyQm9KPs7BDs1oeBYef3-g0a7Xb_Pk,280
+ethereum_mcp/indexer/chunker.py,sha256=2qtMAT-C98TnUjdfjVI5w5xcUJJbV9lxiIBYm7jbdOc,18134
+ethereum_mcp/indexer/client_compiler.py,sha256=Jyl5AgKAce4WTdXq2sXkRhyMmnKbOOqtLKJT5uHoi3E,23062
+ethereum_mcp/indexer/compiler.py,sha256=a7TIjs4r1ZUG-QA8c4CRasOW0QviJNH_x_DdplrApH4,7990
+ethereum_mcp/indexer/downloader.py,sha256=6bIB-koNxJV53vyMlRBoaINsgLfPLc0BgVb7WkwKIdM,15986
+ethereum_mcp/indexer/embedder.py,sha256=v9op5hBxL9tg2V58VuArytFCcTLQt97IQoH_krKc3Us,20723
+ethereum_mcp/indexer/manifest.py,sha256=jqZRa9oqmWnnczry16BjlK5mwB8gssCuulkMbVjlG0g,12666
+ethereum_mcp/tools/__init__.py,sha256=A8hnajphJkWgABS7OY5lxD3XgQ5tDLZqTizi_kTJba8,43
+eth_mcp-0.2.0.dist-info/METADATA,sha256=zL669WPV1832rJZzS1lSUwPotQdowvuZy4MZkdA5hAU,9986
+eth_mcp-0.2.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+eth_mcp-0.2.0.dist-info/entry_points.txt,sha256=5boNJJtsh5bkbJ-kzfYQNNDvWL44yTGk9h-sDZbE_qI,89
+eth_mcp-0.2.0.dist-info/RECORD,,

eth_mcp-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

eth_mcp-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+eth-mcp = ethereum_mcp.server:run
+ethereum-mcp = ethereum_mcp.cli:main

ethereum_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""Ethereum MCP - RAG-powered Ethereum consensus specs search."""
+
+__version__ = "0.1.0"