Prep v0.2.0 release: PyPI/MCP packaging + hero GIF + refreshed README

- pyproject: hatchling build, full PyPI metadata, web3-docs-mcp script
  entry point, bump to 0.2.0
- server.py: data dir resolves via WEB3_DOCS_DATA_DIR / platformdirs
  cache instead of writing inside the install root
- README: centred hero with badges + animated terminal demo, install
  snippets for Claude Code / Cursor, "Why not …" positioning section,
  requirements line, troubleshooting
- docs/assets: VHS-rendered demo.gif (regenerated from demo.py + .tape),
  static hero.svg fallback
- server.json: MCP Registry manifest pointing at PyPI package
- .github/workflows/ci.yml: pytest on 3.11/3.12/3.13
- CHANGELOG.md, .gitignore (build/, dist/)

Author: Dennis

.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --extra test
+
+      - name: Run tests
+        run: uv run pytest -q

.gitignore

@@ -4,6 +4,8 @@ __pycache__/
 .venv/
 .pytest_cache/
 *.egg-info/
+build/
+dist/
 
 # Data (large, cloned on setup)
 data/repos/

CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] — 2026-04-26
+
+### Added
+- Cardano CIP support (`cardano-foundation/CIPs`).
+- Tezos TZIP support (`tezos/tzip` on GitLab).
+- Sui SIP support (`sui-foundation/sips`).
+- `[project.scripts]` entry point — install via `uvx --from git+https://github.com/dioptx/web3-docs web3-docs-mcp`.
+- `WEB3_DOCS_DATA_DIR` env var to override the index location.
+- Hatchling-based wheel/sdist build, PyPI-ready metadata.
+- CHANGELOG.
+
+### Changed
+- Default data directory moved from `./data/` to the platform user cache directory (`~/.cache/web3-docs-mcp/` on macOS/Linux) so installed packages can write to it.
+- README now lists 11 sources / 10 chains / 1,767 proposals and shows MCP install snippets for Claude Code and Cursor.
+
+## [0.1.0] — 2026-04-07
+
+### Added
+- Initial standalone release.
+- Sources: EIPs, ERCs, BIPs, SIMDs, Cosmos ADRs, Polkadot RFCs, Stacks SIPs, Avalanche ACPs.
+- SQLite + FTS5 backed index, FastMCP stdio transport.
+- Tools: `resolve_proposal`, `query_protocol_docs`, `resolve_contract`.
+- Canonical contract registry covering 19 protocols across major EVM chains.
+- BDD test suite under `tests/`.
+
+[0.2.0]: https://github.com/dioptx/web3-docs/releases/tag/v0.2.0
+[0.1.0]: https://github.com/dioptx/web3-docs/releases/tag/v0.1.0

README.md

@@ -1,79 +1,149 @@
+<div align="center">
+
 # web3-docs
 
-MCP server for Web3 protocol documentation — EIPs, ERCs, BIPs, SIMDs, Cosmos ADRs, Polkadot RFCs, Stacks SIPs, Avalanche ACPs, plus a canonical contract registry.
+**One MCP server, eleven protocol-spec repos.**
+Ask Claude about EIPs, BIPs, ADRs, CIPs, RFCs and canonical contract addresses — without ever leaving your editor.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![MCP](https://img.shields.io/badge/MCP-stdio-green.svg)](https://modelcontextprotocol.io/)
+[![CI](https://github.com/dioptx/web3-docs/actions/workflows/ci.yml/badge.svg)](https://github.com/dioptx/web3-docs/actions/workflows/ci.yml)
+
+![web3-docs MCP demo](docs/assets/demo.gif)
+
+</div>
+
+## Why
+
+Specs for blockchain protocols live across **eleven different upstream repos** on three different forges. Every time you need to look up EIP-4844, BIP-340, CIP-25, or which fork shipped `PUSH0`, you're tab-hunting through GitHub. This MCP indexes them all locally with FTS5 ranking — **1,767 proposals across 10 chains** plus addresses for 19 protocols on Ethereum, Arbitrum, Base, Optimism, Polygon, and more — so Claude can answer with the *actual spec text*, not a hallucinated paraphrase.
+
+## Install
 
-## What it does
+> **Requires:** Python 3.11+ · [`uv`](https://docs.astral.sh/uv/) (provides `uvx`) · ~500 MB free disk for the index · `git` on PATH (used by `--sync`).
 
-A queryable MCP for blockchain protocol specs and canonical contract addresses. Stop digging through eight different GitHub repos when you need to look up EIP-4844, BIP-340, or which fork shipped PUSH0 — ask one tool that has them all indexed locally with FTS5 ranking. Bundles 1,500+ proposals across 7 chains plus addresses for 19 protocols on Ethereum, Arbitrum, Base, Optimism, Polygon, and more.
+### Claude Code
 
-## Quick Start
+```bash
+claude mcp add web3-docs -- uvx --from git+https://github.com/dioptx/web3-docs web3-docs-mcp
+```
 
-Clone, install, and build the local index:
+Build the index (one-time, ~2 min, ~500 MB in `~/.cache/web3-docs-mcp/`):
 
 ```bash
-git clone https://github.com/dioptx/web3-docs.git
-cd web3-docs
-uv sync           # or: pip install -e .
-python3 server.py --sync   # one-time: clones source repos and builds proposals.db
+uvx --from git+https://github.com/dioptx/web3-docs web3-docs-mcp --sync
 ```
 
-Register the server in `~/.claude.json` (or your project `.mcp.json`):
+That's it. Restart Claude Code and try **"Use web3-docs to look up EIP-1559."**
+
+### Cursor / Windsurf / generic MCP client
+
+Add to your client's MCP config (`~/.cursor/mcp.json`, etc.):
 
 ```json
 {
   "mcpServers": {
     "web3-docs": {
-      "command": "python3",
-      "args": ["/absolute/path/to/web3-docs/server.py"],
-      "type": "stdio"
+      "command": "uvx",
+      "args": ["--from", "git+https://github.com/dioptx/web3-docs", "web3-docs-mcp"]
     }
   }
 }
 ```
 
-If you use `uv`, swap `python3` for `uv` and prepend `["run", "--directory", "/absolute/path/to/web3-docs", "python3", "server.py"]`.
+### From source
+
+```bash
+git clone https://github.com/dioptx/web3-docs.git && cd web3-docs
+uv sync
+uv run python server.py --sync   # build index
+uv run python server.py          # run stdio server
+```
 
-## Example queries
+## What you can ask
 
-The server exposes three tools: `resolve_proposal`, `query_protocol_docs`, and `resolve_contract`.
+| Ask Claude… | Tool chain |
+|---|---|
+| "What's the fee market in EIP-4844?" | `resolve_proposal` → `query_protocol_docs(query="fee")` |
+| "Show me Cosmos ADR-001." | `resolve_proposal` → `query_protocol_docs` |
+| "Uniswap router on Base?" | `resolve_contract(protocol="uniswap", chain_id="8453")` |
+| "Which BIPs activated with Taproot?" | `resolve_proposal("Taproot")` |
+| "Cardano CIP for native tokens?" | `resolve_proposal("native tokens")` → cip-25 |
+| "ERC-4337 EntryPoint address on Arbitrum?" | `resolve_contract("erc4337", "42161")` |
 
-**1. Look up EIP-4844 (proto-danksharding)**
+## Tools
 
-> "Use web3-docs to find the EIP for blob transactions and explain the fee market."
+| Tool | What it does |
+|---|---|
+| `resolve_proposal(query)` | Fuzzy-find a proposal by keyword, fork name, opcode, or ID. Returns top-5 ranked hits with chain/status/fork. |
+| `query_protocol_docs(proposal_id, query?)` | Read the full spec body. With `query`, returns only the most relevant sections (token-budgeted). Includes metadata header (status, fork, activation date, authors). |
+| `resolve_contract(protocol, chain_id?)` | Look up canonical deployed addresses. 19 protocols × major EVM chains. Omit `chain_id` for all chains. |
 
-Claude calls `resolve_proposal(query="blob transactions")` → `eip-4844`, then `query_protocol_docs(proposal_id="eip-4844", query="blob fee")` and returns the relevant spec section with metadata (status, fork, activation date).
+## Sources
 
-**2. Fetch a Cosmos ADR**
+11 upstream repos, all synced via `--sync`:
 
-> "Show me Cosmos ADR-001."
+| Chain | Source |
+|---|---|
+| Ethereum (EIPs) | [`ethereum/EIPs`](https://github.com/ethereum/EIPs) |
+| Ethereum (ERCs) | [`ethereum/ERCs`](https://github.com/ethereum/ERCs) |
+| Bitcoin | [`bitcoin/bips`](https://github.com/bitcoin/bips) |
+| Solana | [`solana-foundation/solana-improvement-documents`](https://github.com/solana-foundation/solana-improvement-documents) |
+| Cosmos | [`cosmos/cosmos-sdk`](https://github.com/cosmos/cosmos-sdk) (`docs/architecture`) |
+| Polkadot | [`polkadot-fellows/RFCs`](https://github.com/polkadot-fellows/RFCs) |
+| Stacks | [`stacksgov/sips`](https://github.com/stacksgov/sips) |
+| Avalanche | [`avalanche-foundation/ACPs`](https://github.com/avalanche-foundation/ACPs) |
+| Cardano | [`cardano-foundation/CIPs`](https://github.com/cardano-foundation/CIPs) |
+| Tezos | [`tezos/tzip`](https://gitlab.com/tezos/tzip) |
+| Sui | [`sui-foundation/sips`](https://github.com/sui-foundation/sips) |
 
-Claude calls `resolve_proposal(query="ADR-001")` → `query_protocol_docs(proposal_id="cosmos-adr-001")`. Returns the architectural decision record body with its status header.
+Fork mappings come from [`ethereum/execution-specs`](https://github.com/ethereum/execution-specs) plus canonical Bitcoin soft-fork activations (P2SH, SegWit, Taproot, …).
 
-**3. Get the canonical Uniswap address on Base**
+Contract registry covers: `aave`, `across`, `chainlink`, `compound`, `create2_deployer`, `curve`, `ens`, `erc4337`, `gnosis_safe`, `lido`, `maker`, `multicall`, `oneinch`, `permit2`, `seaport`, `uniswap`, `usdc`, `usdt`, `weth`.
 
-> "What's the Uniswap router on Base?"
+## Why not …
 
-Claude calls `resolve_contract(protocol="uniswap", chain_id="8453")` and returns the deployed router/factory addresses for the matching Uniswap version on Base.
+**…just `gh search` or WebFetch each spec on demand?** You'd burn tokens on HTML markup and pay a network round-trip per query. `web3-docs` indexes everything once into local SQLite + FTS5 — sub-millisecond ranked search, plain-text bodies, no rate limits, works offline.
 
-## Supported sources
+**…one MCP per chain?** You'd manage eleven separate servers and Claude wouldn't know which to call. One unified tool with a single `resolve_proposal` entry point lets the model find the right doc by *concept* (e.g. "blob transactions" → `eip-4844`) rather than guessing the source.
 
-Protocol specs (synced from upstream Git repos via `python3 server.py --sync`):
+**…ask Claude directly without an MCP?** Models hallucinate spec details — wrong fork, wrong gas costs, wrong opcode numbers. This server returns the *actual* upstream text with metadata (status, fork, activation date) so Claude can quote it verbatim.
 
-- **EIPs** — [ethereum/EIPs](https://github.com/ethereum/EIPs)
-- **ERCs** — [ethereum/ERCs](https://github.com/ethereum/ERCs)
-- **BIPs** — [bitcoin/bips](https://github.com/bitcoin/bips)
-- **SIMDs** — [solana-foundation/solana-improvement-documents](https://github.com/solana-foundation/solana-improvement-documents)
-- **Cosmos ADRs** — [cosmos/cosmos-sdk](https://github.com/cosmos/cosmos-sdk) (`docs/architecture`)
-- **Polkadot RFCs** — [polkadot-fellows/RFCs](https://github.com/polkadot-fellows/RFCs)
-- **Stacks SIPs** — [stacksgov/sips](https://github.com/stacksgov/sips)
-- **Avalanche ACPs** — [avalanche-foundation/ACPs](https://github.com/avalanche-foundation/ACPs)
+**…use a vector DB?** Spec corpora are small (≈ 1.7K docs), domain vocabulary is precise (`PUSH0`, `BLOBHASH`, `taproot`), and exact-term matching beats embeddings here. FTS5 gives BM25 ranking with zero infrastructure.
 
-Fork mappings come from [ethereum/execution-specs](https://github.com/ethereum/execution-specs) plus canonical Bitcoin soft-fork activations (P2SH, SegWit, Taproot, …).
+## Configuration
 
-Contract registry (`contracts.json`) covers 19 protocols across major EVM chains:
+| Env var | Default | Purpose |
+|---|---|---|
+| `WEB3_DOCS_DATA_DIR` | `~/.cache/web3-docs-mcp` (macOS/Linux) | Where source repos and the SQLite index live |
 
-`aave`, `across`, `chainlink`, `compound`, `create2_deployer`, `curve`, `ens`, `erc4337`, `gnosis_safe`, `lido`, `maker`, `multicall`, `oneinch`, `permit2`, `seaport`, `uniswap`, `usdc`, `usdt`, `weth`.
+## Troubleshooting
+
+**"No proposals found" on any query.** You haven't run `--sync` yet. Run:
+
+```bash
+uvx --from git+https://github.com/dioptx/web3-docs web3-docs-mcp --sync
+```
+
+**`uvx: command not found`.** Install [uv](https://docs.astral.sh/uv/getting-started/installation/): `curl -LsSf https://astral.sh/uv/install.sh | sh`.
+
+**Want to free disk space?** Source repos (`~/.cache/web3-docs-mcp/repos/`) can be deleted after sync; only `proposals.db` is needed at runtime. Re-run `--sync` to update.
+
+**Stale data?** Re-run `--sync` — it does a fast `git pull` and reindexes incrementally.
+
+## Development
+
+```bash
+git clone https://github.com/dioptx/web3-docs.git && cd web3-docs
+uv sync --extra test
+uv run pytest                  # 90 tests, BDD + unit
+uv build                       # build wheel + sdist
+```
 
 ## Status
 
-v0.1.0 — initial standalone release (2026-04-07). SQLite + FTS5 backed, FastMCP stdio transport, BDD test suite under `tests/`.
+v0.2.0 — adds Cardano CIPs, Tezos TZIPs, Sui SIPs (10 chains, 1,767 proposals). SQLite + FTS5, FastMCP stdio transport. See [CHANGELOG.md](CHANGELOG.md) for release history.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

docs/assets/demo.gif

@@ -0,0 +1,48 @@
+#!/usr/bin/env python3
+"""Pretty terminal demo for the README hero GIF. Used by demo.tape (VHS)."""
+
+from __future__ import annotations
+import sys
+import time
+
+R = "\033[0m"
+DIM = "\033[90m"
+BOLD = "\033[1m"
+BLUE = "\033[34m"
+GREEN = "\033[32m"
+YELLOW = "\033[33m"
+CYAN = "\033[36m"
+ORANGE = "\033[38;5;215m"
+
+
+def out(s: str = "", *, end: str = "\n", pause: float = 0.0) -> None:
+    sys.stdout.write(s + end)
+    sys.stdout.flush()
+    if pause:
+        time.sleep(pause)
+
+
+def main() -> None:
+    out(f"{DIM}$ claude mcp add web3-docs -- uvx --from git+https://github.com/dioptx/web3-docs web3-docs-mcp{R}", pause=0.6)
+    out(f"{GREEN}✔{R}  Added MCP server {BOLD}web3-docs{R} {DIM}(stdio){R}", pause=1.2)
+
+    out("", pause=0.3)
+    out(f"{ORANGE}▸ You{R}     What fork shipped PUSH0 and why?", pause=1.4)
+
+    out(f"{CYAN}▸ Claude{R}  → resolve_proposal({BOLD}\"PUSH0\"{R})", pause=0.5)
+    out(f"           → query_protocol_docs({BOLD}\"eip-3855\"{R}, query={BOLD}\"rationale\"{R})", pause=1.6)
+
+    out("", pause=0.2)
+    out(f"{BOLD}{CYAN}eip-3855{R} — PUSH0 instruction", pause=0.3)
+    out(f"chain: {BLUE}ethereum{R}   status: {GREEN}Final{R}   fork: {YELLOW}Shanghai{R} (2023-04-12)", pause=0.3)
+    out(f"{DIM}──────────────────────────────────────────────{R}", pause=0.3)
+    out("PUSH1 0x00 currently accounts for ~11% of all", pause=0.4)
+    out("deployed bytecode. A dedicated PUSH0 opcode shrinks", pause=0.4)
+    out("contracts and saves 2 gas/byte + 3 gas per call.", pause=2.5)
+
+    out("", pause=0.2)
+    out(f"{DIM}11 spec sources · 1,767 proposals · 19 contract registries{R}", pause=2.5)
+
+
+if __name__ == "__main__":
+    main()

docs/assets/demo.py

@@ -0,0 +1,23 @@
+# VHS tape — animated demo for the README hero.
+# Render with:  vhs docs/assets/demo.tape
+# Output:       docs/assets/demo.gif
+#
+# All visible content is produced by demo.py so the recording stays clean
+# (no shell prompts, no typed commands).
+
+Output docs/assets/demo.gif
+
+Set Theme "nord"
+Set FontSize 14
+Set Width 880
+Set Height 480
+Set Padding 24
+Set Framerate 24
+Set TypingSpeed 1ms
+Set Shell "bash"
+
+Hide
+Type "clear && python3 docs/assets/demo.py"
+Enter
+Show
+Sleep 16s