{"id":49747102,"url":"https://github.com/dioptx/web3-docs","last_synced_at":"2026-06-17T14:04:10.569Z","repository":{"id":354039859,"uuid":"1204009445","full_name":"dioptx/web3-docs","owner":"dioptx","description":"MCP server for Web3 protocol documentation — EIPs, ERCs, BIPs, SIMDs, Cosmos ADRs, Polkadot RFCs, contract registry","archived":false,"fork":false,"pushed_at":"2026-05-01T11:45:59.000Z","size":402,"stargazers_count":8,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-08T03:13:22.295Z","etag":null,"topics":["ai-agents","bips","bitcoin","blockchain","cardano","claude-code","cosmos","cursor","eips","ercs","ethereum","fastmcp","mcp","mcp-server","model-context-protocol","polkadot","smart-contracts","solana","tezos","web3"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dioptx.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-07T15:49:54.000Z","updated_at":"2026-06-06T07:19:39.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/dioptx/web3-docs","commit_stats":null,"previous_names":["dioptx/web3-docs"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/dioptx/web3-docs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dioptx%2Fweb3-docs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dioptx%2Fweb3-docs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dioptx%2Fweb3-docs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dioptx%2Fweb3-docs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dioptx","download_url":"https://codeload.github.com/dioptx/web3-docs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dioptx%2Fweb3-docs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34451358,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-17T02:00:05.408Z","response_time":127,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","bips","bitcoin","blockchain","cardano","claude-code","cosmos","cursor","eips","ercs","ethereum","fastmcp","mcp","mcp-server","model-context-protocol","polkadot","smart-contracts","solana","tezos","web3"],"created_at":"2026-05-10T06:00:23.838Z","updated_at":"2026-06-17T14:04:10.549Z","avatar_url":"https://github.com/dioptx.png","language":"Python","funding_links":[],"categories":["AI \u0026 LLM \u0026 MCP"],"sub_categories":["x402 Payments Protocol"],"readme":"\u003c!-- mcp-name: io.github.dioptx/web3-docs --\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n# web3-docs\n\n**One MCP server, eleven protocol-spec repos.**\nAsk your coding agent about EIPs, BIPs, ADRs, CIPs, RFCs and canonical contract addresses — without ever leaving your editor. Works with any [MCP](https://modelcontextprotocol.io/)-compatible client: Claude Code, Cursor, Windsurf, Cline, Zed, Continue, OpenCode, Codex, and more.\n\n[![PyPI version](https://img.shields.io/pypi/v/web3-docs-mcp.svg)](https://pypi.org/project/web3-docs-mcp/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)\n[![MCP](https://img.shields.io/badge/MCP-stdio-green.svg)](https://modelcontextprotocol.io/)\n[![CI](https://github.com/dioptx/web3-docs/actions/workflows/ci.yml/badge.svg)](https://github.com/dioptx/web3-docs/actions/workflows/ci.yml)\n\n![web3-docs MCP demo](docs/assets/demo.gif)\n\n\u003csub\u003eOr replay in your own terminal: \u003ccode\u003easciinema play \u003ca href=\"docs/assets/demo.cast\"\u003edocs/assets/demo.cast\u003c/a\u003e\u003c/code\u003e\u003c/sub\u003e\n\n\u003c/div\u003e\n\n## Why\n\nSpecs 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 your agent answers with the *actual spec text*, not a hallucinated paraphrase.\n\n## Install\n\n\u003e **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`).\n\n### Step 1 — build the index (one-time, ~2 min, ~500 MB in `~/.cache/web3-docs-mcp/`)\n\n```bash\nuvx web3-docs-mcp --sync\n```\n\n### Step 2 — register the server with your agent\n\nThe launch command is identical across clients:\n\n```text\nuvx web3-docs-mcp\n```\n\n\u003cdetails\u003e\u003csummary\u003e\u003cb\u003eClaude Code\u003c/b\u003e\u003c/summary\u003e\n\n```bash\nclaude mcp add web3-docs -- uvx web3-docs-mcp\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e\u003cb\u003eCursor · Windsurf · Cline · Continue · Zed · generic stdio MCP client\u003c/b\u003e\u003c/summary\u003e\n\nAdd to the client's MCP config (`~/.cursor/mcp.json`, `~/.codeium/windsurf/mcp_config.json`, `cline_mcp_settings.json`, the `mcpServers` block in your Zed `settings.json`, etc.):\n\n```json\n{\n  \"mcpServers\": {\n    \"web3-docs\": {\n      \"command\": \"uvx\",\n      \"args\": [\"web3-docs-mcp\"]\n    }\n  }\n}\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e\u003cb\u003eOpenAI Codex CLI\u003c/b\u003e\u003c/summary\u003e\n\n```bash\ncodex mcp add web3-docs -- uvx web3-docs-mcp\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e\u003cb\u003epip / pipx\u003c/b\u003e\u003c/summary\u003e\n\n```bash\npip install web3-docs-mcp\n# or:\npipx install web3-docs-mcp\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e\u003cb\u003eFrom source (development)\u003c/b\u003e\u003c/summary\u003e\n\n```bash\ngit clone https://github.com/dioptx/web3-docs.git \u0026\u0026 cd web3-docs\nuv sync\nuv run python server.py --sync   # build index\nuv run python server.py          # run stdio server\n```\n\n\u003c/details\u003e\n\nRestart your agent, then try **\"Use web3-docs to look up EIP-1559.\"**\n\n## What you can ask\n\n| Ask your agent… | Tool chain |\n|---|---|\n| \"What's the fee market in EIP-4844?\" | `resolve_proposal` → `query_protocol_docs(query=\"fee\")` |\n| \"Show me Cosmos ADR-001.\" | `resolve_proposal` → `query_protocol_docs` |\n| \"What's in Cancun?\" | `list_fork_proposals(\"Cancun\")` |\n| \"Which BIPs activated with Taproot?\" | `list_fork_proposals(\"Taproot\")` |\n| \"Uniswap router on Base?\" | `resolve_contract(protocol=\"uniswap\", chain_id=\"8453\")` |\n| \"Cardano CIP for native tokens?\" | `resolve_proposal(\"native tokens\", chain=\"cardano\")` → cip-25 |\n| \"ERC-4337 EntryPoint address on Arbitrum?\" | `resolve_contract(\"erc4337\", \"42161\")` |\n| \"Staking on Cosmos vs Polkadot?\" | `resolve_proposal(\"staking\", chain=\"cosmos\")` then `chain=\"polkadot\"` |\n\n\u003cdiv align=\"center\"\u003e\n\n![web3-docs contract lookup demo](docs/assets/demo2.gif)\n\n\u003csub\u003eMulti-chain canonical addresses, no etherscan tabs.\u003c/sub\u003e\n\n\u003c/div\u003e\n\n## Tools\n\n| Tool | What it does |\n|---|---|\n| `resolve_proposal(query, chain?)` | Fuzzy-find a proposal by keyword, fork name, opcode, or ID. Returns top-5 ranked hits with chain/status/fork. Pass `chain=` (`ethereum`, `bitcoin`, `cosmos`, …) to disambiguate when keywords match multiple chains. |\n| `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). |\n| `list_fork_proposals(fork_name)` | List every proposal activated by a named fork. Answers \"what's in Cancun?\" / \"BIPs activated with Taproot?\". Handles aliases (Pectra → Prague, Dencun → Cancun, Shapella → Shanghai, The Merge → Paris). |\n| `resolve_contract(protocol, chain_id?)` | Look up canonical deployed addresses. 19 protocols × major EVM chains. Omit `chain_id` for all chains. |\n\n\u003cdiv align=\"center\"\u003e\n\n![web3-docs fork lookup demo](docs/assets/demo3.gif)\n\n\u003csub\u003eFork → all proposals it shipped, then drill into one. Two tool calls instead of an afternoon of tab-hunting.\u003c/sub\u003e\n\n\u003c/div\u003e\n\n## Sources\n\n11 upstream repos, all synced via `--sync`:\n\n| Chain | Source |\n|---|---|\n| Ethereum (EIPs) | [`ethereum/EIPs`](https://github.com/ethereum/EIPs) |\n| Ethereum (ERCs) | [`ethereum/ERCs`](https://github.com/ethereum/ERCs) |\n| Bitcoin | [`bitcoin/bips`](https://github.com/bitcoin/bips) |\n| Solana | [`solana-foundation/solana-improvement-documents`](https://github.com/solana-foundation/solana-improvement-documents) |\n| Cosmos | [`cosmos/cosmos-sdk`](https://github.com/cosmos/cosmos-sdk) (`docs/architecture`) |\n| Polkadot | [`polkadot-fellows/RFCs`](https://github.com/polkadot-fellows/RFCs) |\n| Stacks | [`stacksgov/sips`](https://github.com/stacksgov/sips) |\n| Avalanche | [`avalanche-foundation/ACPs`](https://github.com/avalanche-foundation/ACPs) |\n| Cardano | [`cardano-foundation/CIPs`](https://github.com/cardano-foundation/CIPs) |\n| Tezos | [`tezos/tzip`](https://gitlab.com/tezos/tzip) |\n| Sui | [`sui-foundation/sips`](https://github.com/sui-foundation/sips) |\n\nFork mappings come from [`ethereum/execution-specs`](https://github.com/ethereum/execution-specs) plus canonical Bitcoin soft-fork activations (P2SH, SegWit, Taproot, …).\n\nContract registry covers: `aave`, `across`, `chainlink`, `compound`, `create2_deployer`, `curve`, `ens`, `erc4337`, `gnosis_safe`, `lido`, `maker`, `multicall`, `oneinch`, `permit2`, `seaport`, `uniswap`, `usdc`, `usdt`, `weth`.\n\n## Why not …\n\n**…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.\n\n**…one MCP per chain?** You'd manage eleven separate servers and your agent 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.\n\n**…ask the model 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 the agent can quote it verbatim.\n\n**…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.\n\n## Configuration\n\n| Env var | Default | Purpose |\n|---|---|---|\n| `WEB3_DOCS_DATA_DIR` | `~/.cache/web3-docs-mcp` (macOS/Linux) | Where source repos and the SQLite index live |\n\n## Troubleshooting\n\n**\"Index is empty\" on any tool call.** You haven't run `--sync` yet. Run:\n\n```bash\nuvx web3-docs-mcp --sync\n```\n\n**`uvx: command not found`.** Install [uv](https://docs.astral.sh/uv/getting-started/installation/): `curl -LsSf https://astral.sh/uv/install.sh | sh`.\n\n**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.\n\n**Stale data?** Re-run `--sync` — it does a fast `git pull` and reindexes incrementally.\n\n## Development\n\n```bash\ngit clone https://github.com/dioptx/web3-docs.git \u0026\u0026 cd web3-docs\nuv sync --extra test\nuv run pytest                  # 98 tests, BDD + unit\nuv build                       # build wheel + sdist\n```\n\n## Status\n\nv0.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.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdioptx%2Fweb3-docs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdioptx%2Fweb3-docs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdioptx%2Fweb3-docs/lists"}