mcp-tenderly

Сервер MCP, который даёт ИИ-ассистенту возможность симулировать EVM-транзакции и выяснять, почему они откатываются, используя бесплатный API симуляции Tenderly.

Спросите «сработает ли эта транзакция?» или «почему это не удалось?» — и получите ответ, основанный на реальном состоянии форкнутой цепи: декодированный call trace, причину отката, точную строку исходного кода — вместо догадки.

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

Зачем это существует

Ассистент, рассуждающий об ончейн-транзакции, обычно работает вслепую: он может прочитать исходный код контракта, но не может сказать, откатится ли вызов против текущего состояния, сколько реально стоит газ, или какой из восьми вложенных delegatecall'ов не сработал. Tenderly может ответить на все три вопроса, и его API симуляции доступен на бесплатном аккаунте.

Сложность не в вызове API — а в том, что ответ simulation_type: "full" для реальной DeFi-транзакции часто представляет собой более мегабайта JSON: state diff по каждой затронутой ячейке хранилища, дерево вызовов глубиной в сотни фреймов. Передавать это модели — и дорого, и бесполезно, потому что ответ на вопрос «почему это откатилось» — это четыре строки, погребённые внутри.

Поэтому настоящая работа этого сервера — форматтер: он ставит результат на первое место, затем причину отката и фрейм с привязкой к исходному коду, затем декодированные события, затем дерево вызовов в виде отступающей ASCII-диаграммы — и всегда сообщает, когда что-то было обрезано, потому что молчаливый лимит читается как «это всё».

Related MCP server: evmscope

Быстрый старт

Требуется Node.js 22.12 или новее.

1. Получите учётные данные Tenderly

Все три берутся из бесплатного аккаунта Tenderly:

Оба слага — это URL-слаги, а не отображаемые имена — проект, показанный как «My Project», обычно имеет слаг my-project. Сервер проверяет это при запуске и сообщает, какая переменная неверна, вместо того чтобы позволить ошибке всплыть позже как 404.

2. Зарегистрируйте сервер в вашем клиенте

Claude Code

claude mcp add tenderly \
  -e TENDERLY_API_KEY=your-token \
  -e TENDERLY_ACCOUNT_SLUG=your-account \
  -e TENDERLY_PROJECT_SLUG=your-project \
  -- npx -y mcp-tenderly

Claude Desktop, Cursor или любой другой MCP-хост — добавьте в конфигурационный файл MCP клиента:

{
  "mcpServers": {
    "tenderly": {
      "command": "npx",
      "args": ["-y", "mcp-tenderly"],
      "env": {
        "TENDERLY_API_KEY": "your-token",
        "TENDERLY_ACCOUNT_SLUG": "your-account",
        "TENDERLY_PROJECT_SLUG": "your-project"
      }
    }
  }
}

Запуск из локального клона

git clone https://github.com/py-zoid/mcp-tenderly.git
cd mcp-tenderly
npm install
npm run build

Затем укажите клиенту на результат сборки, заменив <repo> на абсолютный путь к вашему клону:

{
  "mcpServers": {
    "tenderly": {
      "command": "node",
      "args": ["<repo>/dist/index.js"],
      "env": { "TENDERLY_API_KEY": "…", "TENDERLY_ACCOUNT_SLUG": "…", "TENDERLY_PROJECT_SLUG": "…" }
    }
  }
}

Инструменты

tenderly_simulate_transaction

Симулирует одну транзакцию против форкнутого состояния цепи. Возвращает успех или откат, использованный газ, причину отката с трассировкой стека, привязанной к исходному коду (если контракт верифицирован), декодированные события, переводы токенов и декодированный call trace.

Принимает network как имя (base, arbitrum, polygon, sepolia, …) или числовой id цепи, обычные поля транзакции (from, to, data, value, gas, gas_price), необязательный block_number для форка, а также state_overrides для подделки балансов, nonce, ячеек хранилища или байткода.

tenderly_simulate_bundle

Симулирует до 20 транзакций по порядку против общего состояния, так что каждая видит эффекты предыдущих. Это инструмент для сценариев, которые нельзя проверить по одной транзакции — approve затем swap, деплой затем инициализация, или воспроизведение последовательности эксплойта. Сообщает, на каком шаге последовательность сломалась.

tenderly_get_simulation

Ищет сохранённую симуляцию по id и отображает её результат и полный call trace. Используйте его, чтобы глубже изучить обрезанный trace, получить state diff, который по умолчанию опущен, или просмотреть симуляцию, созданную ранее или из интерфейса Tenderly.

Одна важная деталь, которая определяет поведение этого инструмента: запись сохранённой симуляции в Tenderly хранит только метаданные — входные данные, газ, статус, сообщение об ошибке. Call trace не сохраняется. Поэтому trace воспроизводится повторным запуском записанных входных данных на записанном блоке, что точно (тот же форк, тот же результат), но стоит одну симуляцию против вашего rate limit. Повторный запуск не сохраняется, поэтому не расходует квоту сохранённых симуляций. Передайте reconstruct_trace: false для дешёвого просмотра только метаданных.

tenderly_list_simulations

Список недавних сохранённых симуляций в проекте, по одной строке на каждую, чтобы найти id.

Управление размером вывода

Каждый инструмент чтения принимает одинаковые параметры управления выводом. Значения по умолчанию настроены так, чтобы типичный ответ оставался доступным:

Полный trace Tenderly перемежает op-коды хранилища и логов с реальными вызовами — обычный перевод USDC даёт дюжину SLOAD вокруг четырёх реальных вызовов, а DeFi-транзакция — сотни. Если их оставить, они съедают бюджет фреймов и вытесняют из вывода вызовы, объясняющие откат, поэтому они скрыты по умолчанию, а их количество сообщается. Внутренние фреймы Solidity-функций (JUMPDEST) сохраняются: именно они позволяют проследить откат через библиотеку или прокси.

Заметки о бесплатном тарифе

Этот сервер намеренно использует только v1 REST-эндпоинты симуляции, которые работают на бесплатном плане: /simulate, /simulate-bundle, /simulations и /simulations/{id}. Он никогда не обращается к Web3 Gateway, DevNets, Virtual TestNets, Alerts или Actions API — они платные или требуют OAuth, и обращение к ним привело бы к непонятным сбоям именно для тех пользователей, на которых сервер рассчитан.

Две вещи о квотах:

• Сохранённые симуляции расходуют квоту. По умолчанию симуляции сохраняются, потому что URL в панели управления очень ценен при отладке. Установите TENDERLY_SAVE_SIMULATIONS=false или передайте save: false в каждом вызове, чтобы они оставались эфемерными.

• Ограничение скорости даёт 429. Клиент повторяет запросы с экспоненциальной задержкой, учитывая Retry-After, а затем сообщает о лимите прямо, а не зависает.

Дополнительная конфигурация

Модель безопасности и доверия

Симуляции никогда не транслируются. Каждый вызов — только чтение против форка Tenderly. Ни одна транзакция не подписывается и не отправляется, и сервер не хранит ключей, кроме вашего токена доступа Tenderly.

Один исходящий хост. Сервер общается только с api.tenderly.co. Больше ни с чем не связывается, и никакая телеметрия не собирается.

Ваш токен доступа не попадает в вывод. Он отправляется только как заголовок X-Access-Key, никогда не логируется ни на каком уровне, и исключается из сообщений об ошибках и путей. Тест проверяет, что его нет ни в stdout, ни в stderr.

Вывод симуляции рассматривается как недоверенный ввод. Это стоит понять, потому что легко упустить. Имена контрактов, символы токенов, имена функций, декодированные строки, строки верифицированного исходного кода и причины отката — всё это контролируется тем, кто развернул контракт — а смысл этого сервера в том, чтобы направлять его на контракты, которым вы ещё не доверяете. Контракт может вызвать revert() с любой строкой, которая попадёт в самое заметное место вывода.

Поэтому весь такой текст пропускается через санитайзер перед отображением: пробелы схлопываются в одну строку, нулевой ширины и символы смены направления удаляются, длина ограничивается с явным указанием обрезки. Это предотвращает подделку враждебными данными цепи markdown-заголовка, элемента списка или чего-то ещё, что модель могла бы прочитать как инструкции, а не как данные. Это структурная защита, а не попытка обнаружить злой умысел — недоверенный текст просто не может выйти за пределы своего поля. Обычные строки отката не затрагиваются.

Это не делает вывод враждебного контракта истинным, а лишь инертным. Относитесь к результату симуляции как к отчёту о недоверенном коде — чем он и является.

Устранение неполадок

Сервер немедленно завершается с сообщением о конфигурации. Это задумано — он отказывается запускаться, а не падает внутри вашего первого вызова инструмента. Сообщение называет переменную, которая виновата. Код выхода — 78 (EX_CONFIG).

401 или 403. Токен должен быть Access Token из Account Settings, а не секретом проекта или RPC-ключом, и он должен принадлежать аккаунту с доступом к TENDERLY_ACCOUNT_SLUG.

404. Почти всегда проблема со слагом: отображаемое имя вместо слага, или account/project вставлены в одну переменную.

Нет причины отката при ошибке. Контракт, вероятно, не верифицирован, или использовал кастомную ошибку. Call trace всё равно определяет упавший фрейм, и показывается селектор, чтобы вы могли его найти.

Всё выглядит пустым. Повторите с include_raw_response: true, чтобы увидеть, что Tenderly на самом деле вернул.

Логи сервера идут в stderr в формате JSON — проверьте представление логов сервера вашего MCP-клиента. API-ключ никогда не логируется.

Разработка

npm install        # also installs the git hooks via core.hooksPath
npm run verify     # everything CI runs: format, lint, types, unit, stdio smoke
npm test           # unit tests only
npm run test:smoke # builds, then drives dist/index.js over real stdio

npm run verify — это ровно то, что выполняет CI — YAML workflow вызывает только .github/scripts/verify.sh, так что нет ничего, что нельзя воспроизвести локально.

См. CLAUDE.md для архитектуры и проектных решений, которые стоит знать перед внесением изменений.

Лицензия

MIT