midnight-cast

midnight-cast

メモ

このプロジェクトは、開発者向けツールを追加してMidnight Networkを拡張します。

Midnightネットワーク向けの読み取り専用CLIおよびMCPサーバーです。ネットワークの健全性、エラーのデコード、トランザクション、コントラクト、DUST、Midnight公式サンプルの動作するコードを確認できます。Midnight版の**Foundry cast**を目指しており、ウォレットやアプリのひな型ではありません。

npx midnight-cast@latest health preview
# or: npm i -g midnight-cast@latest && midnight-cast health preview

プレビュー環境では、ほかに何も必要ありません。PreprodとmainnetではBlockfrostを経由し、それぞれ無料のプロジェクトIDが必要です。詳しくはクイックスタートをご覧ください。

注： midnight-castは、同じコマンドを実行する短縮エイリアスmnもインストールします。ほかのグローバルCLI（例：@mermaid-js/mermaid-cli、midnight-wallet-cli）もmnをインストールするため、このドキュメント、ヒント、JSON出力では常にmidnight-castと表記します。

midnight-cast health preview

手順を追って実行する場合：midnight-cast ping preview && midnight-cast tip preview && midnight-cast versions preview

Node.js 20+（22+を推奨）が必要です。Node.jsがない場合は、リリースバイナリがチェックサムを検証したうえで同じコマンドをインストールします。

curl -fsSL https://github.com/Kanasjnr/midnight-cast/releases/latest/download/install.sh | sh

WindowsのPowerShellでは、irm https://github.com/Kanasjnr/midnight-cast/releases/latest/download/install.ps1 | iexを実行します。curlがない環境では、wget -qO- <same URL> | shも使用できます。Alpineでは、最初にlibstdc++とlibgccが必要です（apk add libstdc++ libgcc）。MIDNIGHT_CAST_VERSION=0.2.0でリリースを固定し、MIDNIGHT_CAST_INSTALL_DIRでディレクトリを指定できます（デフォルトは~/.local/bin）。各アーカイブにはビルドの来歴情報が含まれます：gh attestation verify <archive> --repo Kanasjnr/midnight-cast。

主な機能

• RPC、インデクサー、プルーフサーバーの健全性と、ネットワークが稼働するノードでMidnight公式サンプルが通るかどうかを確認します
• 実行中のスタックのシグナルと、プロジェクトのMidnightパッケージをサポートマトリックスと照合します
• 台帳、パレット、Substrate 1010、JSON-RPCのエラーと、現在のツールおよびBlockfrostからのメッセージをデコードします
• 最初のトランザクションを実行する前に、ネットワーク、プルーフサーバー、ウォレットの準備状況を確認します（preflight）
• トランザクション、デプロイ済みコントラクト、DUSTの生成、DUSTイベントストリームを調べます
• 自分の言葉でトピックを指定して、Midnight公式サンプルの動作するコードを見つけます（examples）
• すべてを読み取り専用MCPサーバーとしてAIエージェントに提供し、Claude Code、Codex、Gemini CLI、Cursorなど向けのガイダンスも提供します
• スクリプトを書かずに、ブロックヘッダーと生のJSON-RPCを照会します
• スタンドアロンバイナリを使って、Node.jsなしで実行できます

機能

領域	コマンド
健全性	health、ping、tip、versions、preflight
チェーン	block latest、block <height>、rpc
エラー	decode（ledger、pallet、1010、jsonrpc、--raw）
インデクサー	tx、contract、dust-status、dust-event、dust-events
動作するコードと背景情報	examples、explain（dust、1010、versions、transcript、sync）
エージェント	mcp、agents init
設定	config init、config show

ウォレットキーは扱いません。署名や証明の生成は行いません。

よくあるワークフロー

ネットワークは正常ですか？

midnight-cast health preprod

出力例：

Network: preprod
Healthy: yes

Services:
  rpc: OK (668ms)
  indexer: OK (1215ms)
  proof-server: OK (1053ms) (optional) — version=8.1.0 (matches matrix 8.1.0)

Sync:
  RPC height:      2805470
  Indexer height:  2805468
  Delta:           2 (threshold 100)
  In sync:         yes

txが失敗したのはなぜですか？

midnight-cast tx <hash> --network preprod
midnight-cast decode --raw "<wallet-or-node-error>"

出力例：

Type:     RegularTransaction
ID:       232830
Hash:     e5c86fcd43eb9707e8f23d940e59a6c12ca7ad3ca7e9d2f1232843cc62de1b8c
Block:    909000 (428660a6154a27cee57af3527cb3370ad3bbce94f461f433533b1413e24b71f4)
Protocol: 22000
Status:   PARTIAL_SUCCESS
Fees:     paid=1
Segments: 0:ok, 20003:ok, 35012:fail
Failure:  indexer v4 exposes segment success only (no failure reason)
Hint:     paste wallet/node error → midnight-cast decode --raw "<error>"
Actions:  ContractCall
DUST:     665110:DustSpendProcessed
          → midnight-cast dust-event 665110

ローカルスタックはネットワークと整合していますか？

midnight-cast versions preprod

出力例：

Checks:
  node: expected=>=1.0.400 live=1.0.400 → OK (recommended 1.0.400)
  runtimeSpec: expected=1000300 live=1000300 → OK (node runtime spec_version vs matrix)
  indexer-api: expected=v4 live=v4 → OK (from configured indexer URL path)
  protocolVersion: expected=1000300 live=1000300 → OK (RPC specVersion vs indexer latest block)
  proof-server: expected=8.1.0 live=8.1.0 → OK (GET /version on configured proof server URL)

Summary: live stack matches matrix checks ✓

クイックスタート

npm i -g midnight-cast          # or: npx midnight-cast …
midnight-cast config init                  # ~/.config/midnight-cast/config.toml
midnight-cast health preview
midnight-cast decode 170
midnight-cast examples "dust sponsorship"

ネットワーク： preview、preprod、mainnet、local — --networkまたはMN_NETWORKを使用します。

PreprodとmainnetではBlockfrostを経由します。Midnightがホスト型のpreprodおよびmainnetエンドポイントを廃止したためです（mainnetは2026年9月30日、preprodは10月9日）。BlockfrostのプロジェクトIDはネットワークごとに必要です。blockfrost.ioで、無料のMidnight Preprodプロジェクト、Midnight Mainnetプロジェクト、またはその両方を作成してから、次を実行します。

export BLOCKFROST_PREPROD_PROJECT_ID=<your Midnight Preprod project ID>
export BLOCKFROST_MAINNET_PROJECT_ID=nightmainnet...
npx midnight-cast health preprod

Previewは引き続きMidnightがホストしており、プロジェクトIDは不要です。プロジェクトIDが出力されることはありません。docs/COMMANDS.mdをご覧ください。

デバッグの手順

問題が発生したら、次のコマンドを順番に実行してください。

1. midnight-cast health — ping、同期状態、バージョンを一度に確認します（初回のトランザクションの前に preflight --address <wallet> を実行してください）
2. midnight-cast ping — サービスは稼働していますか？
3. midnight-cast tip — インデクサーは同期されていますか？
4. midnight-cast versions — スタックのバージョンはサポートマトリックスに適合していますか？
5. midnight-cast decode — エラーの意味は何ですか？
6. midnight-cast tx — チェーン上で何が起きましたか？

よく使うワンライナー

midnight-cast health preprod --json
midnight-cast ping preprod
midnight-cast versions preprod
midnight-cast decode --raw "1010: Invalid Transaction: Custom error: 186"
midnight-cast decode 179 --network preview          # ledger map stamped per network
midnight-cast tx <hash> --network preprod           # status, fees, segments; links dust-event ids
midnight-cast block 909000 preprod                  # header at height (+ hash)
midnight-cast dust-events --from 565900 --limit 10 --network preprod
midnight-cast rpc chain_getHeader --json
midnight-cast versions preprod --fail-on-mismatch   # CI; local Midnight packages (either npm scope) vs matrix pins
midnight-cast preflight preprod --address mn_addr_preprod1…   # ready for a first transaction?
midnight-cast contract <address> preprod            # latest action, circuit, deploy block, balances
midnight-cast examples "send shielded tokens"       # working code from Midnight's official examples
midnight-cast explain sync                          # why a first wallet sync takes so long

AI エージェントとの使用

Midnight プロジェクトに取り組むエージェントは、ネットワークで現在何が起きているか、エラーの意味、そして動作するコードの例を把握する必要があります。midnight-cast は、ライブデータと Midnight 独自の情報源からこの3つすべてに答え、エージェントが解析できる形式で返します。また、その MCP サーバーから何かを変更することはできません。

エージェントがすでに利用している可能性のある、ほかの2つの情報源と併用できます。Kapa answer engine は、Midnight のドキュメントとサンプルに基づいて質問に答えます。Midnight Expert は、Compact と SDK のコードの作成や検証に使えるスキルと MCP ツールをエージェントに提供します。midnight-cast は、どちらもカバーしていない部分を担います。preview、preprod、mainnet のライブ状態、ネットワークが稼働する台帳における特定のエラーコードの意味、プロジェクトのバージョンがネットワークに適合しているかどうか、そして Midnight の公式サンプルのうち、どれがそのパターンを示しているかを確認できます。

JSON の仕様

任意のコマンドに --json を追加すると、安定した形式のエンベロープが返されます。内容は ok、data、kind と hint を含む構造化された error、任意の warnings、および専門家が次に実行するコマンドを示す next です。midnight-cast explain --json は、すべてのコマンド、オプション、終了コード、エラー種別を1回の呼び出しで説明します。また、schemas/ には、各コマンドの出力に対応する JSON Schema があります。終了コードは、成功時が 0、チェック失敗時が 1、使用方法のエラー時が 2 です。JSON 出力を参照してください。

midnight-cast decode --raw "1010: Invalid Transaction: Custom error: 186" --json
midnight-cast explain --json

MCP サーバー

MCP に対応したエージェントは、midnight-cast を直接使用できます。midnight-cast mcp は、stdio 上で14個のツールを備えた MCP サーバーを実行します。各ツール（health、preflight、ping、tip、versions、block、tx、dust_event、dust_events、contract、dust_status、decode、explain、examples）は、同じエンベロープを返します。たとえば、Claude Code では次のようにします。

claude mcp add --transport stdio midnight-cast -- npx -y midnight-cast mcp

Node.js のないサンドボックスや CI イメージでは、スタンドアロンバイナリから同じサーバーを実行できます。midnight-cast mcp

エージェントができること、できないこと

• すべての MCP ツールは読み取り専用で、クライアントに対しても読み取り専用として設定されています。トランザクションへの署名や送信は行わず、ウォレット、キー、シードも必要ありません。ノードに任意の JSON-RPC メソッドを渡す CLI の rpc コマンドは、MCP ツールではありません。
• MIDNIGHT_CAST_NETWORKS を使って、モデルがクエリできるネットワークを制限できます。たとえば preview,preprod のように指定します。
• ネットワークにアクセスするツールには、デフォルトで1分あたり30回（MIDNIGHT_CAST_MAX_CALLS_PER_MINUTE）のレート制限があります。そのため、ループするエージェントがパブリックエンドポイントや Blockfrost のプランを使い切ることはありません。
• 保持されるシークレットは、preprod と mainnet 用の任意の Blockfrost プロジェクト ID のみです。これらは Blockfrost にのみ送信され、すべての応答から秘匿されるため、モデルに表示されることはありません。
• decode、explain、examples は、リリースに同梱されたデータを使ってオフラインで動作します。

ガイダンス、スキル、プラグイン

コーディングエージェントに midnight-cast を使うタイミングと方法を教えるには、プロジェクトにガイダンスを追加します。midnight-cast agents init --write は AGENTS.md にマーカー付きのセクションを追記します（Codex、Cursor、Copilot、Gemini CLI、Windsurf、Aider などが読み込みます。Claude Code の場合は --file CLAUDE.md を使用してください）。または、ポータブルなスキルを npx skills add Kanasjnr/midnight-cast --skill midnight-cast でインストールします。スニペットは docs/agents にあります。

Claude Code では、1つのプラグインでスキル、MCP サーバー、/midnight-cast:diagnose <network> [tx or error] コマンドをインストールできます。プラグインを有効にすると、Claude Code は preprod と mainnet 用の Blockfrost プロジェクト ID（任意）の入力を求め、安全なストレージに保存します。空欄のままにした場合は、エクスポート済みの BLOCKFROST_PREPROD_PROJECT_ID または BLOCKFROST_MAINNET_PROJECT_ID が使用されます。以前に claude mcp add でサーバーを追加した場合は、プラグインのサーバーだけが実行されるよう、claude mcp remove midnight-cast で削除してください。

claude plugin marketplace add Kanasjnr/midnight-cast
claude plugin install midnight-cast@midnight-cast

docs/MCP.md には、Codex、Gemini CLI、Cursor、VS Code などのセットアップ、ネットワークの許可リスト、Blockfrost プロジェクト ID をモデルに見せない方法が記載されています。

コミュニティとサポート

必要なサポート	場所
Midnight のエラー、ネットワークの問題、開発に関する質問	Midnight Discord
midnight-cast のバグ、または正常に動作しない場合	GitHub Issues
新しいコマンドや機能のアイデア	GitHub Issues（機能リクエスト）

midnight-cast decode --raw "…" は、貼り付けたエラーから 1010 envelopes、Custom(N)、台帳エラー名、pallet モジュールエラー、JSON-RPC コードを自動検出します。台帳マップが preview と preprod で一致するよう、--network を使用してください。Pallet の Transaction ヒントは内部の Custom(N) を示し、コード 179～181 ではグループ化されたトランスクリプトのコンテキストが表示されます。コードが見つからない場合やプロトコルに関する質問は、Discord と Midnight docs をご利用ください。

ドキュメント

• ワークフロー — 出力例付きのシナリオガイド
• コマンドリファレンス — 例付きのコマンド別リファレンス
• ドキュメント一覧

Cast ↔ midnight-cast

cast block  →  midnight-cast block latest | midnight-cast block <height>
cast rpc    →  midnight-cast rpc
cast logs   →  midnight-cast dust-events
cast 4byte  →  midnight-cast decode
cast send   →  wallet / Lace (not midnight-cast)
doctor      →  midnight-cast health

開発

git clone https://github.com/Kanasjnr/midnight-cast.git
cd midnight-cast && npm install && npm run build
npm link                        # global midnight-cast
npm run cli -- decode 170       # without link
npm test
BLOCKFROST_PREPROD_PROJECT_ID=<id> INTEGRATION=1 npm run test:integration   # live tests; mainnet ones also need BLOCKFROST_MAINNET_PROJECT_ID

ライセンス

Apache-2.0