eth-mcp 0.2.0__tar.gz

eth_mcp-0.2.0/.github/workflows/bump.yml

@@ -0,0 +1,81 @@
+name: Bump Version
+
+on:
+  workflow_dispatch:
+    inputs:
+      bump_type:
+        description: 'Version bump type'
+        required: true
+        default: 'patch'
+        type: choice
+        options:
+          - patch
+          - minor
+          - major
+
+permissions:
+  contents: write
+
+jobs:
+  bump:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install toml
+        run: pip install toml
+
+      - name: Bump version
+        id: bump
+        run: |
+          python << 'EOF'
+          import toml
+          import re
+          import os
+
+          # Read current version
+          with open('pyproject.toml', 'r') as f:
+              data = toml.load(f)
+
+          current = data['project']['version']
+          major, minor, patch = map(int, current.split('.'))
+
+          bump_type = '${{ inputs.bump_type }}'
+          if bump_type == 'major':
+              major += 1
+              minor = 0
+              patch = 0
+          elif bump_type == 'minor':
+              minor += 1
+              patch = 0
+          else:
+              patch += 1
+
+          new_version = f'{major}.{minor}.{patch}'
+          data['project']['version'] = new_version
+
+          with open('pyproject.toml', 'w') as f:
+              toml.dump(data, f)
+
+          print(f'Bumped {current} -> {new_version}')
+
+          with open(os.environ['GITHUB_OUTPUT'], 'a') as f:
+              f.write(f'version={new_version}\n')
+              f.write(f'tag=v{new_version}\n')
+          EOF
+
+      - name: Commit and tag
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add pyproject.toml
+          git commit -m "chore: bump version to ${{ steps.bump.outputs.version }}"
+          git tag ${{ steps.bump.outputs.tag }}
+          git push origin main --tags

eth_mcp-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,59 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.11', '3.12']
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run linter
+        run: ruff check src/
+
+      - name: Run tests
+        run: pytest tests/ -v --cov=ethereum_mcp --cov-report=xml
+
+      - name: Upload coverage
+        uses: codecov/codecov-action@v4
+        if: matrix.python-version == '3.11'
+        with:
+          files: coverage.xml
+          fail_ci_if_error: false
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install build dependencies
+        run: pip install build twine
+
+      - name: Build package
+        run: python -m build
+
+      - name: Check package
+        run: twine check dist/*

eth_mcp-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,72 @@
+name: Release to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: read
+  id-token: write  # Required for OIDC
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest tests/ -v
+
+      - name: Run linter
+        run: ruff check src/
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install build dependencies
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/eth-mcp
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        # No password needed - uses OIDC trusted publishing

eth_mcp-0.2.0/.gitignore

@@ -0,0 +1,63 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+venv/
+ENV/
+env/
+.venv/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Data (downloaded repos and indices - large, user-specific)
+# Users should run `ethereum-mcp build` to generate these
+# Uncomment if you want to track compiled data:
+# !data/compiled/
+
+# Misc
+.DS_Store
+*.log
+
+# Secrets and sensitive files (defense in depth)
+.env
+.env.*
+*.env
+!.env.example
+.envrc
+*.pem
+*.key
+*.p12
+*.secret
+*.credentials
+credentials.json
+secrets.json
+*_private.*
+*.private.*

eth_mcp-0.2.0/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "gateway": {
+      "command": "mcpmon",
+      "args": ["--config", "/Users/be.nvy/.mcpmon.yaml"]
+    }
+  }
+}

eth_mcp-0.2.0/CLAUDE.md

@@ -0,0 +1,118 @@
+# ethereum-mcp
+
+RAG-powered MCP server for Ethereum consensus specs and EIPs.
+
+## Quick Reference
+
+```bash
+# Full build (download + compile + index)
+ethereum-mcp build
+
+# Individual steps
+ethereum-mcp download    # Clone consensus-specs and EIPs
+ethereum-mcp compile     # Extract constants/functions to JSON
+ethereum-mcp index       # Build vector embeddings in LanceDB
+
+# Incremental updates (fast)
+ethereum-mcp update      # Git pull + incremental re-index
+ethereum-mcp index       # Incremental by default
+ethereum-mcp index --full    # Force full rebuild
+ethereum-mcp index --dry-run # Preview what would change
+
+# Search
+ethereum-mcp search "slashing penalty"
+ethereum-mcp status      # Check index status
+ethereum-mcp models      # List available embedding models
+```
+
+## MCP Tools
+
+| Tool | Purpose |
+|------|---------|
+| `eth_search` | Unified search across specs + EIPs (default: current fork) |
+| `eth_get_current_fork` | Returns active fork name |
+| `eth_list_forks` | All upgrades with dates/epochs |
+| `eth_search_specs` | Specs-only search (no EIPs) |
+| `eth_grep_constant` | Fast constant lookup |
+| `eth_analyze_function` | Get Python implementation from specs |
+| `eth_get_spec_version` | Index metadata |
+| `eth_expert_guidance` | Curated expert interpretations |
+| `eth_search_eip` | EIP-specific search |
+
+## Project Structure
+
+```
+src/ethereum_mcp/
+├── server.py           # MCP server (FastMCP)
+├── cli.py              # CLI commands
+├── config.py           # Configuration management
+├── indexer/
+│   ├── downloader.py   # Git clone specs/EIPs
+│   ├── compiler.py     # Extract to JSON
+│   ├── chunker.py      # Markdown chunking + chunk IDs
+│   ├── embedder.py     # Embeddings + LanceDB + IncrementalEmbedder
+│   └── 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 repo
+├── EIPs/               # Cloned repo
+├── builder-specs/      # Cloned repo
+├── compiled/           # JSON extracts per fork
+└── lancedb/            # Vector index
+```
+
+## Configuration
+
+Create `~/.ethereum-mcp/config.yaml` to customize:
+
+```yaml
+embedding:
+  model: "all-MiniLM-L6-v2"  # Or codesage/codesage-large
+  batch_size: 32
+
+chunking:
+  chunk_size: 1000
+  chunk_overlap: 200
+```
+
+Available models: `all-MiniLM-L6-v2`, `all-mpnet-base-v2`, `codesage/codesage-large`, `voyage:voyage-code-3`
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check src/
+```
+
+## Incremental Indexing
+
+See [docs/INCREMENTAL_INDEXING.md](docs/INCREMENTAL_INDEXING.md) for detailed documentation.
+
+Key concepts:
+- **Manifest**: Tracks file hashes and chunk IDs
+- **Chunk IDs**: Deterministic IDs based on content hash
+- **Change detection**: Fast mtime check, then hash verification
+- **Delta updates**: Only re-embed changed content
+
+## Adding Expert Guidance
+
+Edit `src/ethereum_mcp/expert/guidance.py` to add entries:
+
+```python
+GUIDANCE_DB["topic"] = GuidanceEntry(
+    topic="Topic Name",
+    summary="Brief summary",
+    key_points=["point 1", "point 2"],
+    gotchas=["gotcha 1", "gotcha 2"],
+    references=["specs/fork/file.md"],
+)
+```