quai-mcp-server

MCP-сервер (Model Context Protocol), который предоставляет данные сети Quai и инструменты для read-only взаимодействия AI-клиентам, таким как Claude Desktop и Claude Code. Создан с использованием официального @modelcontextprotocol/sdk и quais, ethers-подобного SDK для Quai.

Что такое Quai Network простыми словами

Quai — это proof-of-work, EVM-совместимый Layer 1, который масштабируется за счёт шардинга: вместо одной цепи, выполняющей всю работу, он разделяется на множество цепей, организованных в иерархию.

                Prime chain (1)
               /      |       \
        Region      Region      Region      <- "Cyprus", "Paxos", "Hydra"
       /  |  \      /  |  \     /  |  \
     Zone Zone Zone  ...              9 Zone chains total

• Prime — единственная цепь верхнего уровня. Каждый майнер майнит Prime; она урегулирует состояние всей сети, но не обрабатывает пользовательские транзакции напрямую.

• Region-цепи (сейчас Cyprus, Paxos, Hydra) находятся под Prime, агрегируя свои Zone.

• Zone-цепи (Cyprus1/2/3, Paxos1/2/3, Hydra1/2/3 — сегодня 9, их можно добавлять по мере роста сети) — это место, где живёт настоящий EVM: пользовательские транзакции, контракты, балансы, всё.

В отличие от схем шардинга, которые разделяют безопасность вместе с данными, Quai сохраняет безопасность единой во всей иерархии, разделяя только данные/пропускную способность — Prime и Region-цепи merge-mine с Zone-цепями под ними.

Самая важная часть для инструментов: каждый адрес Quai знает своё местоположение. Собственные байты адреса кодируют, в какой единственной Zone он живёт (и находится ли он в реестре QUAI, account-based, как Ethereum, или в реестре Qi, UTXO-based, как Bitcoin). Адрес на Cyprus1 существует только на Cyprus1 — вы не можете спросить о нём Paxos2. Поэтому несколько инструментов ниже либо автоматически определяют зону за вас, либо просят указать её явно.

Related MCP server: Kirha MCP Gateway

Инструменты

Только чтение

Ни один из этих инструментов не может перемещать средства, подписывать что-либо или изменять состояние on-chain.

Кошельки (кастодиальные: зашифрованные, именованные, защищённые паролем)

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

Как работает шифрование: каждый кошелёк — это приватный ключ в стандартном формате Web3 Secret Storage (V3 keystore) — том же формате, который используют geth и MetaMask — через encryptKeystoreJson из quais. Конкретно: пароль растягивается с помощью scrypt (N=2^17, r=8, p=1, стандартные «дорогие» параметры стоимости — это намеренно замедляет каждую попытку подбора пароля), приватный ключ шифруется с помощью AES-128-CTR, а MAC над шифротекстом обнаруживает неверный пароль (или изменённый файл) до того, как из него будет получен какой-либо ключевой материал. Это хорошо проверенная и широко распространённая схема; здесь нет собственной криптографии.

Где хранятся кошельки: по умолчанию ~/.quai-mcp-server/wallets/ (переопределяется через QUAI_WALLET_DIR) — QUAI-кошельки как <name>.json, Qi-кошельки как <name>.qi.json. Каталог создаётся с правами 0700, а каждый файл хранилища — 0600 (только чтение/запись владельцем, best-effort на не-POSIX платформах) — это явно применяется после создания, а не просто оставляется на усмотрение umask процесса. Адрес хранится в открытом виде в обоих случаях (это публичная информация; именно так list_wallets и предпросмотры на стороне QUAI работают без пароля), но приватный ключ (или мнемоника для Qi) никогда не записывается, не логируется и не возвращается в открытом виде ни одним инструментом.

Именование: имя идентифицирует не более одного QUAI-кошелька и не более одного Qi-кошелька — это независимые хранилища (разные файлы, разные секреты, совершенно несвязанный ключевой материал), которые просто имеют общую метку. Нельзя создать два QUAI-кошелька (или два Qi-кошелька) с одним именем, но повторное использование имени QUAI-кошелька для Qi-кошелька — это именно то, как работает связывание в create_wallet, и create_qi_wallet/import_qi_wallet намеренно это разрешают по той же причине.

Qi-кошельки — это HD-кошельки под капотом, но этот сервер хранит только мнемонику — никогда не производное дерево адресов и не состояние UTXO/сканирования. create_qi_wallet/import_qi_wallet шифруют {address, privateKey, mnemonic} с помощью того же вызова encryptKeystoreJson, что и на стороне QUAI (поля address/privateKey там — это просто первый производный адрес кошелька, присутствующий, чтобы файл был обычным, валидным V3 keystore); значимый секрет — мнемоника. Каждая последующая операция (get_qi_balance, convert_qi_to_quai) воссоздаёт свежий QiHDWallet из этой мнемоники и заново выводит тот же адрес получения по требованию -- детерминированно, поскольку HD-деривация для фиксированного аккаунта/зоны всегда даёт один и тот же адрес. Это было проверено напрямую: экспорт мнемоники кошелька и повторный импорт под другим именем воспроизвели идентичный адрес. Компромисс в том, что каждая операция Qi заново выводит данные с нуля, а не читает кэш, что проще для понимания и не может отклониться от того, что на самом деле подразумевает мнемоника, ценой необходимости пароля чаще, чем на стороне QUAI (см. ниже).

Почему Qi требует пароль чаще: get_balance в QUAI читает публичный баланс аккаунта напрямую из цепочки — секрет не нужен. У Qi такого нет: «баланс» — это сумма неизрасходованных выходов транзакций (UTXO), принадлежащих адресам, которые может вывести только мнемоника кошелька, так что само вычисление баланса означает восстановление кошелька. Поэтому get_qi_balance принимает пароль (а get_balance в QUAI — нет), и поэтому шаг предпросмотра в convert_qi_to_quai может показать курс конвертации, но не может подтвердить, что у вас действительно достаточно Qi для траты — эта проверка происходит только когда пароль поступает на шаге подтверждения.

Правила пароля: минимум 8 символов, проверяется до любого шифрования. Отдельного ограничения частоты попыток с неверным паролем нет — стоимостные параметры scrypt уже делают каждую попытку вычислительно дорогой, что является стандартной защитой для такого рода локального хранилища ключей.

Поток подтверждения для send_transaction, convert_qi_to_quai и send_qi: все три всегда требуют два вызова, и только второй требует пароль.

1. Вызов с адресом назначения и суммой (walletName/to/amount для send_transaction; walletName/recipientPaymentCode/amount/destinationZone для send_qi; вариант в форме to для convert_qi_to_quai) — пароль пока не требуется. Ничего не транслируется. Вы получаете предпросмотр — разрешённые зоны, оценку там, где она существует (газ для отправки, конвертированная сумма для конвертации; у send_qi её нет, так как это перевод 1:1), и confirmationToken, действительный в течение 2 минут.

2. Повторный вызов с теми же параметрами, плюс confirm: true, этот confirmationToken и password кошелька. Только тогда ключ/мнемоника расшифровывается и транзакция фактически подписывается и отправляется.

Токен одноразовый и привязан к точным параметрам предпросмотра — если что-то изменилось, токен истёк или уже был использован, шаг 2 завершается с понятной ошибкой, и вы делаете предпросмотр заново. Это работает одинаково независимо от того, есть ли у самого MCP-клиента UI подтверждения инструментов, так что это реальный барьер, а не полагание на клиент. Неверный пароль завершается чисто (Incorrect password for wallet "...") без утечки информации о том, были ли токен/параметры в остальном валидны.

Намеренно нет инструмента export_wallet/«показать приватный ключ или мнемонику» — как только секрет попал в хранилище, единственный способ вывести его через этот сервер — подписать им.

Конвертация QUAI ↔ Qi («своп»): у Quai есть нативная конвертация на уровне протокола между двумя её реестрами — QUAI (на основе аккаунтов) и Qi (на основе UTXO, как Bitcoin) — с ончейн-курсом обмена, а не через сторонний DEX. get_conversion_rate даёт котировку в любом направлении, кошелёк не нужен. Оба направления исполнения теперь реализованы:

• QUAI → Qi: просто обычный send_transaction на адрес Qi-реестра (например, из create_qi_wallet). Инструмент определяет это автоматически (isConversion: true в предпросмотре) и показывает оценку полученного Qi рядом с обычной информацией о газе/балансе.

• Qi → QUAI: convert_qi_to_quai, использующий под капотом QiHDWallet.convertToQuai из quais, по той же схеме предпросмотр/подтверждение/пароль, что и send_transaction.

Отправка Qi → Qi: Qi-кошельки не отправляют напрямую на адреса друг друга. Вместо этого у каждого Qi-кошелька есть переиспользуемый BIP-47 платёжный код (get_qi_payment_code) — делитесь им так же, как адресом, но из него для каждого платежа выводится свежий одноразовый адрес, для приватности. Чтобы отправить, отправитель «открывает канал» с платёжным кодом получателя (send_qi делает это автоматически) — это чистый локальный ECDH между двумя платёжными кодами, детерминированный и воспроизводимый, без ончейн-действий или сохраняемого состояния. Загвоздка на принимающей стороне: эти попарно выведенные адреса не входят в обычную детерминированную последовательность адресов кошелька, так что ничего не найдёт средства, отправленные таким образом, если вы не скажете ему искать. Конкретно: после того как кто-то заплатил вашему Qi-кошельку через платёжный код, передайте его платёжный код в counterpartyPaymentCodes у get_qi_balance — он открывает тот же канал и включает его в баланс. Механизма уведомлений (ончейн или иного) нет, который сообщил бы получателю о платеже через платёжный код; обе стороны должны уже знать друг о друге вне канала, так же как вам нужно знать адрес, прежде чем проверять его баланс. send_qi также поддерживает кросс-зонные отправки (destinationZone, отдельный от собственной зоны отправителя), так же как ETX в send_transaction и собственная зонная модель QiHDWallet.

Один известный недочёт: шаг предпросмотра в send_qi не проверяет формат платёжного кода заранее (нет экспортированного валидатора для проверки), так что некорректный код пройдёт предпросмотр и упадёт только при подтверждении — безопасно (ничего не отправляется, средствам ничего не угрожает), просто позже, чем хотелось бы.

Ещё не реализовано: deploy_contract, request_faucet.

Честность о том, что здесь протестировано, обновлено: полный цикл send_qi / платёжного кода был проверен вживую на мейннете с двумя реальными кошельками — реальный, корректно отформатированный BIP-47 платёжный код (PM8T...) был сгенерирован и подтверждён детерминированным при повторных вызовах, предпросмотр корректно определил, кросс-зонная это отправка или в ту же зону, подтверждение с пустым кошельком упало с настоящей ошибкой SDK (No Qi available in zone), а не с крашем, и get_qi_balance корректно изолировал невалидный платёжный код контрагента в rejectedPaymentCodes, не провалив весь вызов. Что всё ещё не проверено, по той же причине, что и везде в этом документе: фактическое завершение отправки через платёжный код между двумя финансированными кошельками, так как для этого нужны реальные Qi, и это не делалось без запроса.

Честность о том, что здесь протестировано: всё вышеперечисленное было проверено на живом мейннете, включая проверку детерминизма (экспорт мнемоники Qi-кошелька и повторный импорт под другим именем воспроизвёл идентичный адрес) и реальные пути ошибок (неверный пароль, недостаточно QUAI для газа и настоящая ошибка QiHDWallet — No Qi available in zone — при попытке конвертации из пустого Qi-кошелька). Что не было проверено — это фактическое завершение convert_qi_to_quai или конвертации QUAI→Qi против кошелька с реальными средствами, так как это требует траты реальных денег и не делалось без запроса.

Установка

npm install
npm run build

Или запустите напрямую без установки, после публикации:

npx quai-mcp-server

Требования

• Node.js 18+

Конфигурация (переменные окружения)

Все опциональны — разумные значения по умолчанию указывают на мейннет Quai.

Каждый инструмент также принимает аргумент network ("mainnet" или "testnet") при каждом вызове, так что клиент может запрашивать любую сеть без перезапуска сервера.

О ключах: см. «Кошельки» выше. Ключи существуют в открытом виде только в памяти на время вызова create_wallet/import_wallet/send_transaction, которому они нужны — никогда на диске, никогда в логах. Относитесь к QUAI_WALLET_DIR (и к машине, на которой работает этот сервер) как к любому другому локальному хранилищу секретов: любой, у кого есть доступ к файловой системе этого каталога и достаточно вычислительной мощности для перебора слабого пароля, в конечном счёте сможет расшифровать кошелёк, как и локальное хранилище geth или хранилище MetaMask.

Регистрация в Claude Desktop

Добавьте это в ваш MCP-конфиг Claude Desktop (claude_desktop_config.json — на macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "quai": {
      "command": "npx",
      "args": ["quai-mcp-server"]
    }
  }
}

Или, если вы склонировали и собрали этот репозиторий локально вместо использования опубликованного пакета:

{
  "mcpServers": {
    "quai": {
      "command": "node",
      "args": ["/absolute/path/to/quai-mcp-server/dist/index.js"]
    }
  }
}

Чтобы по умолчанию указывать на тестнет, добавьте блок env:

{
  "mcpServers": {
    "quai": {
      "command": "npx",
      "args": ["quai-mcp-server"],
      "env": {
        "QUAI_TESTNET_RPC_URL": "https://orchard.rpc.quai.network"
      }
    }
  }
}

(затем передавайте "network": "testnet" в отдельных вызовах инструментов — переменные окружения задают конечную точку, а не сеть по умолчанию для каждого вызова).

Регистрация в Claude Code

claude mcp add quai -- npx quai-mcp-server

или, для локальной сборки:

claude mcp add quai -- node /absolute/path/to/quai-mcp-server/dist/index.js

Разработка

npm run dev     # tsc --watch
npm run build   # one-shot build to dist/
npm start        # run the built server directly (stdio) -- mainly useful for manual smoke tests

Сервер говорит по MCP через stdio только в v1; HTTP-транспорта нет.

Заметки по дизайну

• quais поверх сырого RPC: каждый инструмент идёт через JsonRpcProvider, Contract и утилиты адресов SDK quais, а не через самодельные JSON-RPC вызовы eth_/quai_, так что разрешение зон, форматирование ответов и формы ошибок остаются согласованными с остальной экосистемой Quai.

• Один провайдер, много зон: один JsonRpcProvider, указывающий на базовый URL шлюза (например, https://rpc.quai.network), автоматически обнаруживает активные зоны из Prime-цепочки и маршрутизирует каждый вызов в нужную — большинству инструментов никогда не нужно конструировать URL для конкретной зоны.

• Хранение — стандартными инструментами, а не самодельной криптографией: кошельки хранятся с использованием реализации quais формата хранилища ключей Ethereum V3 (scrypt + AES-128-CTR + MAC) — той же хорошо проверенной схемы, которую используют geth и MetaMask, — а не чего-то самодельного. См. «Кошельки» выше для полной модели.

• Ошибки — это текст, а не стектрейсы: ошибки RPC/контрактов перехватываются и переписываются в короткие конкретные сообщения (например, «Contract call reverted: ...», «Insufficient funds: ...», «Incorrect password for wallet...», «not a validly checksummed Quai address») вместо утечки сырых объектов исключений модели.

• Подтверждение — реальный барьер, а не просто подсказка клиенту: инструменты записи аннотированы readOnlyHint: false (и destructiveHint: true для отправки), чтобы MCP-клиенты со своим UI одобрения показывали его, но send_transaction дополнительно обеспечивает собственное рукопожатие предпросмотр → токен → пароль на стороне сервера (src/confirmations.ts для токена, src/walletStore.ts + decryptKeystoreJson для пароля), так что его по-прежнему безопасно вызывать из клиента вообще без UI одобрения.

• Пароль нужен только один раз, в последний момент: предпросмотр отправки разрешает адрес кошелька прямо из незашифрованной части его файла хранилища ключей и использует VoidSigner (подписывающий в quais, который может оценить газ, но не подписать) для оценки стоимости — без расшифровки, без пароля. Только финальный вызов confirm: true расшифровывает ключ, и только на время этого одного вызова.

• ETX — не отдельный путь кода: отправка на адрес в другой зоне использует тот же самый вызов send_transaction, что и отправка в ту же зону — сеть Quai обрабатывает кросс-зонную маршрутизацию (как внешнюю транзакцию) прозрачно, как только подписанная транзакция достигает зоны отправителя. Инструмент просто определяет и сообщает задействованные зоны, чтобы вызывающий знал, чего ожидать.

• Qi-кошельки не имеют состояния между вызовами, намеренно: create_qi_wallet/import_qi_wallet только шифруют мнемонику. get_qi_balance и convert_qi_to_quai восстанавливают QiHDWallet с нуля при каждом вызове и заново выводят его адрес (src/qiWallet.ts), а не читают какое-либо кэшированное состояние адресов/UTXO — читать нечего. Это обменяло немного производительности (каждая Qi-операция заново выводит и перезапрашивает, а не бьёт в кэш) на более простую и трудную для ошибок историю безопасности: единственное, что когда-либо находится в покое, — это единственный секрет, который имеет значение.