chain-reader — сервер MCP для Ethereum только для чтения

MCP-сервер, позволяющий LLM читать Ethereum на естественном языке. Не хранит закрытых ключей, не подписывает и не отправляет транзакции. К каждому результату прилагается «источник, из которого получен этот ответ».

Написан как учебный прототип, превращающий в работающий код схему из последней главы «Блокчейн и ИИ» книги Тима Вайнгартнера (HSLU) «Ethereum & Smart Contracts».

  LLM         ← 自然言語（「このアドレスは何者？」）
   ↓
  MCP         ← src/server.js
   ↓          ← コード／構造化言語（ABI エンコード）
  RPC         ← src/rpc.js
   ↓
ブロックチェーン

Зависимостей всего две: @modelcontextprotocol/sdk и zod. Keccak-256 и ABI-кодировщик написаны с нуля (см. ниже «Почему написано с нуля»).

Запуск

git clone <this repo> && cd chain-reader-mcp
npm ci --ignore-scripts
npm test        # 単体 13 件（ネットワーク不要）
npm run smoke   # 実チェーンに対して全ツールを 1 回ずつ

Зарегистрируйте в Claude Code.

claude mcp add chain-reader -- node "$PWD/src/server.js"

Если запускать claude из этого каталога, регистрация не нужна, так как здесь есть .mcp.json. Однако в первый раз потребуется подтверждение (в claude mcp list будет ⏸ Pending approval). Чтобы не паниковать в день лекции, заранее запустите и подтвердите один раз.

Для Claude Desktop впишите то же самое в mcpServers в claude_desktop_config.json. В этом случае args укажите абсолютным путём.

Целевую сеть можно переключать переменными окружения. По умолчанию — mainnet.

В обоих случаях используются публичные конечные точки без API-ключей. local обращается к http://127.0.0.1:8545 от anvil / hardhat node.

Соответствие инструментов и лекций

Сами слайды лекции лежат в отдельном репозитории (частный японский перевод), но по названиям разделов соответствие легко проследить.

Если выбрать промпт lecture_walkthrough, будут даны инструкции последовательно пройти пункты 1–6.

Вопросы, которые можно сразу использовать на лекции

このネットワークはいま混んでいますか？
0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 は EOA ですか、コントラクトですか？
USDC の総供給量は？ その数字は誰が保証していますか？
transfer(address,uint256) のセレクタはなぜ 0xa9059cbb になるのですか？
私のアドレスから 0.001 ETH を送る取引を組み立ててください

На последний вопрос ИИ возвращает собранный JSON, но отправить его не может. Если попросить объяснить «почему не может», содержимое слайда «Меры предосторожности при использовании MCP» прозвучит из уст самого ИИ.

Два принципа в архитектуре

1. Никаких ключей

ALLOWED_METHODS в src/rpc.js — это явный белый список методов только для чтения. eth_sendRawTransaction / eth_sendTransaction / eth_sign в нём отсутствуют, и попытка их вызвать упадёт ещё до выхода в сеть (зафиксировано модульными тестами).

Ни реализации подписи, ни загрузки закрытого ключа в этом репозитории нет. Как бы ни направляли LLM, отсюда нельзя перевести средства.

prepare_unsigned_transaction существует, чтобы показать эту границу в действии, а не как «то, что нельзя». Он возвращает готовый результат с заполненными nonce, оценкой газа и комиссией, оставляя человеку только подпись. Это прямая реализация тезиса из слайдов лекции: «MCP может безопасно выполнять только два типа операций: вызовы только для чтения и ретрансляцию подписанных транзакций».

2. Не выбрасывать источник ответа

К каждому результату прилагается _provenance.

"_provenance": {
  "endpoint": "https://ethereum-rpc.publicnode.com",
  "network": "mainnet (Ethereum Mainnet)",
  "rpc_calls": ["eth_blockNumber (1309ms)", "eth_gasPrice (1416ms)", "eth_chainId (1769ms)", "eth_getBlockByNumber (1023ms)"],
  "note": "これは単一の RPC エンドポイントの応答であり、独立に検証したものではない。"
}

Это механизм, не позволяющий остановиться на «это же блокчейн, значит, верно». У LLM есть привычка уверенно называть числа, поэтому в сам результат зашито, какое утверждение на каком уровне находится. В instructions сервера также указано различать факты, гарантированные цепочкой, и то, что кто-то заявил.

Возможность атрибуции ≠ возможность проверки

Выходной дизайн этого сервера исходит из контекста управления записями и цифровых архивов. Разница между тем, что можно сказать, и тем, что истинно, встроена в вывод инструментов.

self_reported_note в read_token — факт, что name() вернул "USD Coin", гарантирует цепочка. Но то, что этот контракт действительно принадлежит Circle, она не гарантирует. Контракт с таким же именем и символом может развернуть кто угодно. Цепочка гарантирует лишь «код по этому адресу ответил так», а не истинность этого утверждения.

what_this_does_not_prove в verify_anchor — анкерование даёт «кто, когда и что заявил», а не «верно ли это заявление». Хэш ошибочного измерения выжигается так же, как и хэш верного. Это ровно то различие из дипломатики: подлинность (authenticity) — это не истинность (truth).

_provenance — минимальная реализация идеи, что качество записи — это форма её графа происхождения. Какая конечная точка, каким RPC-вызовом и за сколько миллисекунд ответила. Состояние, в котором можно позже решить, кому присвоить prov:wasAttributedTo из PROV-O.

Если подниматься по уровням — подписанные заявления / сверка с публичной информацией / TEE-аттестация / институциональная аутентификация, — сила проверки растёт, но, сколько ни поднимайся, «сам измерительный прибор» проверить нельзя. Этот прототип демонстрирует самый нижний уровень — область, где атрибуция возможна, а проверка — нет. Именно поэтому в записи фиксируется, на каком уровне находится то или иное значение.

Почему Keccak и ABI написаны с нуля

С viem или ethers хватило бы трёх строк. Причин писать самому две.

1. Это учебный материал. Если ABI останется магией, невозможно объяснить, «почему именно 4 байта». src/keccak.js и src/abi.js вместе — около 300 строк, студенты смогут их прочитать.

2. Можно ограничиться двумя зависимостями. Чем меньше площадь атаки в цепочке поставок, тем выше вероятность, что через 3 года npm ci сработает.

sha3-256 из Node crypto — это NIST SHA-3, и он не подходит, так как отличается паддинг (там 0x06, а не 0x01) от Keccak-256 в Ethereum. Здесь остаётся только реализовывать.

Поддерживаются address / uintN / intN / bool / bytesN / string / bytes и их динамические массивы. Кортежи и вложенные динамические массивы не поддерживаются. Для прототипа этого достаточно, но для работы с произвольными контрактами в проде замените на viem.

Известные ограничения

• Доверие одному RPC. Если отправлять один и тот же запрос на несколько конечных точек и сверять ответы, уровень доверия вырастет. Не реализовано.

• Нет поддержки кортежей. Такие возвращаемые значения, как slot0() у Uniswap V3, декодировать нельзя.

• read_events по умолчанию сканирует 200 блоков. Публичные конечные точки могут отклонять слишком широкие eth_getLogs.

• verify_anchor ищет по частичному совпадению строк. Если ABI контракта-якоря известен, нужно корректно декодировать аргументы и сверять их.

• Кроме сети local, всё зависит от публичных конечных точек. Учитывая, что в день лекции они могут лечь, безопаснее заранее сделать локальный форк через anvil --fork-url.

Структура файлов

src/keccak.js   Keccak-256（既知ベクタで固定）
src/abi.js      ABI エンコード／デコード
src/rpc.js      JSON-RPC クライアント + 読み取り専用ホワイトリスト
src/tools.js    ツール 10 個の実体。MCP から独立していて単体で呼べる
src/server.js   MCP サーバ（stdio）
test/unit.test.js      ネットワーク不要の単体テスト
test/smoke.mjs         実チェーンに対する疎通確認
test/mcp-handshake.mjs MCP プロトコルの往復確認