Skip to content

README.ru.md

Latest commit

 

History

History
126 lines (90 loc) · 14.5 KB

README.ru.md

File metadata and controls

126 lines (90 loc) · 14.5 KB
Raw

@tonnode/mcp

mcp MCP server

English version

MCP-сервер, который даёт ИИ-агентам прямой доступ к The Open Network (TON) через лайтсерверы — без HTTP-шлюзов посередине. Балансы, состояние аккаунтов, история транзакций и get-методы контрактов по нативному протоколу ADNL.

Разработан TONNode — приватные лайтсерверы TON, архивные ноды, мемпул-стрим и индексированный API.

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

Добавьте в Claude Desktop, Claude Code, ChatGPT, Cursor, Codex или любой другой MCP-клиент:

{
  "mcpServers": {
    "ton": {
      "command": "npx",
      "args": ["-y", "@tonnode/mcp"]
    }
  }
}

Это вся интеграция. По умолчанию сервер подключается к мейннету TON через публичный глобальный конфиг. Готовые конфиги для всех клиентов — плюс программное использование из Node.js — в examples/.

Инструменты

О названиях: в июне 2026 нативная монета переименована из Toncoin в GRAM; сама сеть по-прежнему называется TON. В ответах инструментов используются поля *_gram.

Инструмент Что делает Типичный вопрос
get_balance Баланс GRAM по адресу «Сколько GRAM на EQ…?»
get_jetton_balance Баланс жетона/токена (USDT и любой TEP-74) «Сколько USDT на этом кошельке?»
get_jetton_info Метаданные токена: имя, символ, decimals, эмиссия «Сколько decimals у этого жетона?»
get_transactions Последние транзакции: суммы, отправители, комиссии «Пришёл ли мой платёж?»
get_account_state Статус, флаги деплоя, указатель последней транзакции «Этот контракт задеплоен?»
run_get_method Read-only get-методы контрактов «Вызови get_jetton_data у мастера»
parse_address Конвертация/проверка форм EQ…/UQ…/raw, офлайн «Это один и тот же адрес?»
get_masterchain_info Вершина мастерчейна: seqno, шард, хэши «Жива ли сеть (и мой эндпоинт)?»
get_swap_quote Твёрдая DEX-котировка (GRAM ⇄ любой жетон) через Omniston «Сколько USDT дадут за 100 GRAM прямо сейчас?»
build_swap_tx Неподписанная swap-транзакция, готовая для TonConnect «Собери этот своп — кошелёк сам подпишет»
get_crosschain_quote Котировка TON → Ethereum/Arbitrum/Base/BNB/Polygon/Avalanche «Сколько USDT на Ethereum за мой TON-USDT?»
build_crosschain_swap_tx Неподписанная HTLC-эскроу транзакция + её секрет «Начни кроссчейн-своп»
track_crosschain_swap Фазы кроссчейн-сделки на обеих сетях «Резолвер уже залочил мой USDT в Ethereum?»
disclose_crosschain_secret Раскрыть секрет — атомарно завершает обе стороны «Заверши своп»
build_crosschain_refund Неподписанная отмена, возвращающая средства из эскроу «Сделка зависла — верни деньги»
generate_wallet Создать новый TON-кошелёк (мнемоника + ключи + адрес) «Создай кошелёк для моего агента»

Генерация кошелька

generate_wallet создаёт новый кошелёк — мнемонику из 24 слов, ed25519-пару ключей и адрес для выбранной версии контракта (v4 по умолчанию, а также v3r2, v5r1 и highload_v3 для массовых выплат). Адреса v3r2/v4/v5r1 берутся из канонических контрактов @ton/ton; highload_v3 выводится из официального кода контракта и сверен с поддерживаемой референс-реализацией.

⚠️ Инструмент возвращает секретный ключевой материал. В hosted-режиме ключи генерируются на сервере и передаются по TLS — считай любой такой кошелёк горячим: годится для программного/временного использования, но крупные суммы переводи в холодное хранилище, а ответ держи вне логов и общих переписок. Сервер никогда не сохраняет и не логирует мнемонику или приватный ключ (только публичный адрес). Оператор может задать TONNODE_DISABLE_WALLET_GEN=1, чтобы полностью убрать инструмент.

Свапы — агенты, которые умеют торговать

get_swap_quote и build_swap_tx работают через Omniston — RFQ-протокол STON.fi, агрегирующий ликвидность STON.fi и DeDust. API-ключ не нужен.

Флоу строго некастодиальный — сервер никогда не видит приватный ключ, ничего не подписывает и не отправляет:

  1. get_swap_quote фиксирует твёрдую котировку (суммы в неделимых единицах; в ответе — минимум с учётом слиппеджа, влияние на цену, бюджет газа и маршрут по DEX).
  2. build_swap_tx превращает котировку в неподписанные сообщения ровно той формы, которую ждёт tonConnectUi.sendTransaction() — подпись и отправка остаются за владельцем кошелька.

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

Кроссчейн

Инструменты *_crosschain_* переносят ту же идею между блокчейнами: платишь в GRAM или любом жетоне TON — получаешь USDT/USDC/нативные монеты в Ethereum, Arbitrum, Base, BNB, Polygon или Avalanche через атомарный HTLC-эскроу Omniston, обычно меньше чем за минуту. TON всегда исходная сеть (подписывает TON-кошелёк).

Агент ведёт полный цикл атомарного свапа: котировка → сборка (инструмент генерирует HTLC-секрет и отдаёт его вызывающему — сервер ничего не хранит) → подпись и отправка → трекинг обеих сетей → раскрытие секрета для расчёта, либо refund, если сделка зависла. Ни сервер, ни резолвер, ни кто-либо ещё не может перенаправить средства: секрет лишь завершает сделку по котировке, а незаполненный эскроу всегда возвращается кошельку-владельцу.

Hosted / self-hosted HTTP-режим

В пакете есть и Streamable-HTTP-режим для удалённого развёртывания (именно он работает на mcp.tonnode.io):

TONNODE_KEYS=tn_live_abc,tn_live_def PORT=8808 npx -y @tonnode/mcp --http

Нужен готовый hosted-эндпоинт вместо собственного? Ключи для mcp.tonnode.io выдаются на tonnode.io/mcp. Клиенты подключаются без установки чего-либо:

{
  "mcpServers": {
    "ton": {
      "url": "https://your-host/mcp",
      "headers": { "Authorization": "Bearer tn_live_abc" }
    }
  }
}

Запросы аутентифицируются Bearer-ключами и ограничиваются по частоте на каждый ключ (RATE_LIMIT_RPM, по умолчанию 300). Кроме Authorization: Bearer <key> сервер принимает голый Authorization: <key> и X-API-Key: <key> — для шлюзов (например, Smithery), которые резервируют заголовок Authorization под себя. Ключи берутся либо из TONNODE_KEYS (через запятую, фиксированный список), либо из TONNODE_KEYS_FILE — JSON-массива {"key", "label"?, "rpm"?, "expires"?}, который горячо перечитывается при изменении файла и по SIGHUP: добавляйте и отзывайте клиентские ключи без рестарта, задавайте индивидуальные лимиты и срок действия ключей для тарифов по подписке. Живые сессии отозванного ключа закрываются немедленно. GLOBAL_RATE_LIMIT_RPM добавляет общий потолок по всем ключам, защищая бэкенд-лайтсервер. Сессии приватны для открывшего их ключа, простаивающие закрываются после SESSION_TTL_MIN (по умолчанию 30 минут), число одновременных сессий ограничено на ключ и глобально. Без ключей сервер откажется стартовать; для работы без ключей за собственным файрволом задайте TONNODE_ALLOW_OPEN=1 явно. Мониторинг — GET /healthz, управление ключами — deploy/tonnode-keys.sh.

По умолчанию сервер слушает 127.0.0.1 — поставьте перед ним TLS-прокси (Caddy, nginx) и задавайте HOST=0.0.0.0 только если прокси стоит на другой машине. Готовые конфиги systemd + Caddy — в deploy/.

Конфигурация

Переменная Значение
TON_LITESERVERS Свои лайтсерверы вместо публичного конфига: [{"ip":"1.2.3.4","port":40004,"key":"<base64 ed25519>"}]
TON_CONFIG_URL Альтернативный URL глобального конфига
TON_NETWORK=testnet Использовать тестнет (или флаг --testnet)
TONNODE_KEYS HTTP-режим: Bearer-ключи через запятую (просто, фиксированный список)
TONNODE_KEYS_FILE HTTP-режим: JSON-файл ключей с label, индивидуальными rpm и expires — горячая перезагрузка
HOST HTTP-режим: адрес для прослушивания (по умолчанию 127.0.0.1)
PORT HTTP-режим: порт (по умолчанию 8808)
RATE_LIMIT_RPM HTTP-режим: базовый лимит запросов в минуту на ключ (по умолчанию 300)
GLOBAL_RATE_LIMIT_RPM HTTP-режим: общий потолок по всем ключам (по умолчанию выключен)
SESSION_TTL_MIN HTTP-режим: минут простоя до закрытия сессии (по умолчанию 30)
MAX_SESSIONS / MAX_SESSIONS_PER_KEY HTTP-режим: лимиты одновременных сессий (по умолчанию 500 / 50)
OMNISTON_API_URL Свапы: альтернативный WebSocket-эндпоинт Omniston (по умолчанию wss://omni-ws.ston.fi)
OMNISTON_INTEGRATOR_ADDRESS / OMNISTON_INTEGRATOR_FEE_BPS Свапы: необязательная интеграторская комиссия в bps от выхода — всегда видна вызывающему как integrator_fee_units в каждой котировке (по умолчанию выключена)
TONNODE_DISABLE_WALLET_GEN Задай 1, чтобы убрать инструмент generate_wallet (например, на общем hosted-эндпоинте, где не нужно генерировать ключи на сервере)

О публичных лайтсерверах

Лайтсерверы из публичного конфига — общие, с жёсткими лимитами и без глубокой истории: get_transactions дальше последних блоков ответит lt not in db. Агенты к тому же запрашивают данные пачками, и публичные шлюзы это режут.

Для гарантированной пропускной способности, архивной глубины и мемпул-стрима на уровне ноды укажите в TON_LITESERVERS приватный эндпоинт — tonnode.io выдаёт его за минуту, оплата в TON.

Лицензия

MIT © TONNode