midnight-cast

Name: midnight-cast
Author: Kanasjnr

本地服务

github.com开发工具16 天前更新

代码仓库访问官网

关于 midnight-cast

midnight-cast 是面向 Midnight 开发者的只读命令行工具和 MCP 服务，可检查网络状态、交易、错误、合约与 DUST。它还提供版本兼容性检查，并从 Midnight 官方示例中查找可用代码。

主要功能

01检查网络、索引器和证明服务健康状态
02比较实时版本与支持矩阵
03解码账本和 JSON-RPC 错误
04检查交易、合约与 DUST 数据
05搜索官方示例中的代码

适用场景

01交易前检查网络和服务是否就绪
02排查交易失败和错误代码
03核对项目依赖与网络版本
04为 Midnight 项目查找示例代码

MCP 相关

命令 `midnight-cast mcp` 通过 stdio 启动 MCP 服务，向 Agent 提供 14 个只读工具，用于查询网络、交易、合约、DUST、错误解释和示例代码；不签名或提交交易。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "kanasjnr-midnight-cast": {
      "command": "npx",
      "args": [
        "-y",
        "midnight-cast"
      ],
      "env": {
        "BLOCKFROST_PREPROD_PROJECT_ID": "<BLOCKFROST_PREPROD_PROJECT_ID>",
        "BLOCKFROST_MAINNET_PROJECT_ID": "<BLOCKFROST_MAINNET_PROJECT_ID>",
        "MIDNIGHT_CAST_NETWORKS": "<MIDNIGHT_CAST_NETWORKS>"
      }
    }
  }
}

启动命令npx -y midnight-cast

需要配置的环境变量

BLOCKFROST_PREPROD_PROJECT_ID密钥Blockfrost project ID for a Midnight Preprod project, needed only to query preprod. It is never shown to the model.

BLOCKFROST_MAINNET_PROJECT_ID密钥Blockfrost project ID for a Midnight Mainnet project, needed only to query mainnet. It is never shown to the model.

MIDNIGHT_CAST_NETWORKSComma-separated networks the model may query, such as preview,preprod. Default: every built-in network.

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npmmidnight-cast0.2.1stdio

工具

收录的工具列表 · 更新于 6 天前

参数	类型	必填	说明
network	enum	是	要查询的 Midnight 网络：preview、preprod、mainnet、localpreview \| preprod \| mainnet \| local
threshold	integer	否	计为不同步的索引器延迟区块数（默认值为 100）

详细介绍

midnight-cast

说明

此项目为 Midnight Network 扩展了其他开发者工具。

适用于 Midnight 网络的只读命令行工具和 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 软件包与支持矩阵
解码账本、pallet、Substrate 1010 和 JSON-RPC 错误，以及当前工具和 Blockfrost 返回的消息
在首次交易前检查网络、证明服务和钱包是否就绪（preflight）
检查交易、已部署的合约、DUST 生成情况和 DUST 事件流
根据你用自己的话描述的主题，在 Midnight 官方示例中查找可用代码（examples）
通过只读 MCP 服务将上述功能提供给 AI Agent，并提供适用于 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`）
Agent	`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

我的交易为什么失败了？

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。

调试步骤

出现问题时，请按顺序运行以下命令：

midnight-cast health — 一次完成 ping、同步状态和版本检查（首次交易前运行 preflight --address <wallet>）
midnight-cast ping — 服务是否正常运行？
midnight-cast tip — 索引器是否已同步？
midnight-cast versions — 技术栈是否符合支持矩阵？
midnight-cast decode — 错误是什么意思？
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 Agent 搭配使用

处理 Midnight 项目的 Agent 需要了解网络当前状态、错误含义，以及可正常运行的代码示例。midnight-cast 从实时数据和 Midnight 自有资料中提供这三类信息，格式便于 Agent 解析；其 MCP 服务无法进行任何更改。

它与 Agent 可能已经在使用的另外两种信息来源并列。Kapa 答案引擎根据 Midnight 的文档和示例回答问题。Midnight Expert 为 Agent 提供用于编写和验证 Compact 与 SDK 代码的技能和 MCP 工具。midnight-cast 则负责提供两者都不涵盖的信息：preview、preprod 和 mainnet 的实时状态，网络所运行的账本上特定错误代码的含义，项目版本是否与网络匹配，以及 Midnight 的哪个官方示例展示了某种模式。

JSON 契约

为任何命令添加 --json，即可获得一个稳定的统一结构，其中包含 ok、data、含有 kind 和 hint 的结构化 error、任何 warnings，以及包含专家后续会运行的命令的 next。midnight-cast explain --json 一次调用即可描述每条命令、选项、退出代码和错误类型；schemas/ 中则为每条命令的输出提供了 JSON Schema。成功时退出代码为 0，检查失败时为 1，用法错误时为 2。参见 JSON 输出。

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

MCP 服务

支持 MCP 的 Agent 可以直接使用 midnight-cast：midnight-cast mcp 会通过 stdio 运行 MCP 服务，该服务提供 14 种工具：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。

Agent 能做和不能做的事

每种 MCP 工具都只读取信息，并标记为对客户端只读。它们都不会签署或提交交易，也不需要钱包、密钥或种子。CLI 的 rpc 命令可将任意 JSON-RPC 方法传递给节点，但它不是 MCP 工具。
MIDNIGHT_CAST_NETWORKS 可限制模型能够查询的网络，例如 preview,preprod。
访问网络的工具受到速率限制，默认每分钟 30 次调用（MIDNIGHT_CAST_MAX_CALLS_PER_MINUTE），因此循环运行的 Agent 无法耗尽公共端点或 Blockfrost 计划的配额。
它仅持有 preprod 和 mainnet 的可选 Blockfrost 项目 ID。这些 ID 只会发送给 Blockfrost，并会从每条响应中删除，因此模型永远不会看到它们。
decode、explain 和 examples 使用随发行版捆绑的数据，可离线运行。

指引、技能和插件

要教编码 Agent 何时以及如何使用 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 中，一个插件即可安装技能、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 信封、Custom(N)、账本错误名称、pallet 模块错误和 JSON-RPC 代码。使用 --network，以确保账本映射与 preview 或 preprod 相匹配。pallet Transaction 提示会指向内部的 Custom(N)，代码 179–181 会显示分组的 transcript 上下文。若遇到缺失的代码或协议相关问题，请前往 Discord，或查阅 Midnight 文档。

文档

工作流 — 包含示例输出的场景指南
命令参考 — 按命令整理的参考文档，附带示例
文档索引

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

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。

midnight-cast

关于 midnight-cast

主要功能

适用场景

MCP 相关

配置

工具

详细介绍

midnight-cast

主要功能

功能说明

常见工作流

网络健康吗？

我的交易为什么失败了？

我的本地技术栈与网络保持一致吗？

快速入门

调试步骤

常用单行命令

与 AI Agent 搭配使用

JSON 契约

MCP 服务

Agent 能做和不能做的事

指引、技能和插件

社区与支持

文档

Cast ↔ midnight-cast

开发

许可证

评论

第一次接触 MCP？

MCP（Model Context Protocol）是什么？

MCP 服务和客户端有什么区别？

本地服务与远程服务怎么选？

如何在 Claude、Cursor 等客户端中安装服务？

收录的项目经过审核吗？“认证”标识代表什么？

我维护的项目已被收录，怎样认领？