CometBFT validator ops

CometBFT ノードおよびバリデーター運用者向けの読み取り専用 MCP サーバーです。

エージェントに 「バリデーターは署名していますか？」、「ジャイルまであとどれくらいですか？」、「チェーンが停止したのはなぜですか？」、「アップグレードの準備はできていますか？」 と尋ねると、自分のノードとチェーン固有のスラッシング状態に基づく回答が得られます。運用者と同じ視点で状況を判断し、何も変更することはできません。

あらゆる CometBFT チェーン（Cosmos Hub、Osmosis、あらゆる Cosmos SDK チェーン、非 SDK の CometBFT アプリ）と、あらゆる MCP クライアント（Claude Code、Claude Desktop、Cursor、VS Code、Codex、Gemini CLI、…）で動作します。

警告

初期リリース（v0.4）です。ツール API は今後変更される可能性があります。

_{同梱のローカルネットに対する実際のツール出力です。ノードは実際に停止され、待ち時間は短縮されています。再現する。}

目次： 質問できること · クイックスタート · インストール · クライアントの接続 · 設定 · ツール · セキュリティモデル · 判定方法 · トラブルシューティング · FAQ · 開発

質問できること

同梱のローカルネットワークからの実際の出力です。

バリデーターは署名していますか — ジャイルまでどれくらいですか？

「val3 は署名していますか？ジャイルされるまでどれくらいですか？」

val3 [critical]: signed 26/30 blocks (88–117), missed 4 (13.33%), 4 missed in a row at the head;
21 more misses until downtime jail (~37s at the current rate)

コミット署名（バリデーター自体が停止している間も機能します）と、チェーン固有の x/slashing カウンターを読み取り、SDK とまったく同じ方法でジャイルのしきい値を計算します。

ブロックが停止したのはなぜですか？

「チェーンがブロックを生成していません。なぜですか？」

height 115 round 0 (Prevote) for 60s [critical]: prevotes 50.1%, precommits 0.0% of power —
no_quorum; not voting: val3, val2

「オンラインの投票力が足りない — そして応答していないのは誰か」と、「バリデーターはオンラインだがコミットしていない」（アップグレードによる停止、アプリハッシュエラーなど）を区別して伝えます。50.1%は誤植ではありません。この実行中に val2 は以前、ダウンタイムにより1%のスラッシングを受けていました。

アップグレードの準備はできていますか？

「アップグレードは予定されていますか？ すべてのノードが同じバージョンですか？」

localnet-1 [ok]: upgrade <untrusted>v2-e2e</untrusted> at height 10000000 in ~164d20h (9999969 blocks)

測定したブロック時間に基づくETA付きのx/upgrade計画、投票中のアップグレード提案、ノード間のバージョン差を確認できます。<untrusted>は、チェーンに由来するテキスト（ここではガバナンス提案）を示すため、エージェントはこれをデータとして扱います。

すべて問題ありませんか？

「毎日のチェックを実行して」 — またはdaily_checkプロンプトを使用してください。

[critical] 5 nodes (4 ok, 1 critical), 4 validators (3 ok, 1 critical); localnet-1 [ok]: no upgrade scheduled — needs attention: val3

ほかにも、「val0は本当にセンチネルの背後にいますか？」（peer_healthは、パブリックアドレスのピアを持つバリデーターを検出します）、「遅れ始めているノードはありますか？」、そして1つのノードを証拠優先で診断するincident_triageがあります。

クイックスタート（1分、パブリックRPC）

ノードへのアクセスは不要です。パブリックRPCを指定し、コンセンサスアドレスを使って任意のバリデーターを監視できます。

go install github.com/wookja-0/cometbft-mcp/cmd/cometbft-mcp@latest

cat > hub.yaml <<'EOF'
cosmos:
  rest: https://cosmos-rest.publicnode.com
nodes:
  - name: public
    role: full
    rpc: https://cosmos-rpc.publicnode.com:443
  - name: my-validator
    role: validator
    validator_address: cosmosvalcons1...   # yours, or any validator's
EOF

cometbft-mcp check --config hub.yaml
claude mcp add cometbft -- cometbft-mcp --config "$PWD/hub.yaml" --concurrency 8

次に、*「my-validatorは署名していますか？ ジェイルまでどのくらいですか？」*と尋ねます。

validator_addressはコンセンサスアドレス（…valcons1…または40文字の16進数）です。ウォレット（cosmos1…）やオペレーター（cosmosvaloper1…）のアドレスではありません。バリデーター上で<appd> comet show-addressを実行するか、/status → validator_info.addressから、またはエクスプローラーで確認できます。

インストール

クライアントを接続する

絶対パスを使用してください。ほとんどのクライアントは~を展開しません。

claude mcp add cometbft -- cometbft-mcp --config /Users/you/.config/cometbft-mcp/config.yaml

{
  "mcpServers": {
    "cometbft": {
      "command": "cometbft-mcp",
      "args": ["--config", "/Users/you/.config/cometbft-mcp/config.yaml"]
    }
  }
}

{
  "mcpServers": {
    "cometbft": {
      "command": "cometbft-mcp",
      "args": ["--config", "/Users/you/.config/cometbft-mcp/config.yaml"]
    }
  }
}

{
  "servers": {
    "cometbft": {
      "type": "stdio",
      "command": "cometbft-mcp",
      "args": ["--config", "/Users/you/.config/cometbft-mcp/config.yaml"]
    }
  }
}

[mcp_servers.cometbft]
command = "cometbft-mcp"
args = ["--config", "/Users/you/.config/cometbft-mcp/config.yaml"]

{
  "mcpServers": {
    "cometbft": {
      "command": "cometbft-mcp",
      "args": ["--config", "/Users/you/.config/cometbft-mcp/config.yaml"]
    }
  }
}

{
  "mcpServers": {
    "cometbft": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
               "--mount", "type=bind,src=/Users/you/.config/cometbft-mcp/config.yaml,dst=/config/config.yaml,readonly",
               "ghcr.io/wookja-0/cometbft-mcp:0.4.2"]
    }
  }
}

設定の読み込み元は、次の順に確認され、最初に見つかったものが使われます。

1. --config <path>
2. $COMETBFT_MCP_CONFIG_YAML — ファイルではなく環境変数を受け取る環境（コンテナ、ホスト型の MCP ランナーなど）向けの YAML そのものです。フロースタイルなら 1 行に収まります。

   COMETBFT_MCP_CONFIG_YAML='{cosmos: {rest: "https://cosmos-rest.publicnode.com"}, nodes: [{name: public, role: full, rpc: "https://cosmos-rpc.publicnode.com:443"}]}'
   

3. $COMETBFT_MCP_CONFIG — パス
4. ~/.config/cometbft-mcp/config.yaml

コメント付きの config.example.yaml をひな形として使用してください。

# Optional: the Cosmos SDK layer (jail status, slashing margin, upgrades, monikers).
# Chain state is the same on every node: use a sentry's or full node's REST API.
cosmos:
  rest: http://127.0.0.1:1317

nodes:
  - name: sentry-1
    role: sentry                     # validator | sentry | full
    rpc: http://127.0.0.1:26657      # CometBFT RPC
  - name: val-1
    role: validator
    rpc: http://127.0.0.1:36657
    validator_address: cosmosvalcons1...   # keeps validator_health working while it is down
  - name: val-2
    role: validator                  # no rpc: watched by address only
    validator_address: cosmosvalcons1...

キー、ニーモニック、トークンを指定する場所は意図的に設けていません。シークレットに見えるフィールドは拒否されます。

ノードへの接続。 使用するのはポート 26657（および 1 台のノードのポート 1317、任意）のみです。CometBFT の RPC はデフォルトで 127.0.0.1 にバインドされるため、SSH トンネルを使えばノードの変更もポートの開放も不要です：ssh -N -L 36657:127.0.0.1:26657 val-1。このために RPC をインターネットに公開しないでください。

cometbft-mcp check は、設定を検証するために MCP クライアントを介さず、ローカルで node_status レポートを出力します。

使用可能な設定がなくてもサーバーは起動します。ツールは一覧に表示されたままになり、各呼び出しで作成すべき内容が説明されます（内部アドレスが含まれている可能性があるため、設定の内容がそのまま出力されることはありません）。ファイルを修正して、MCP サーバーを再起動してください。

ツール

すべてのツールは読み取り専用です（readOnlyHint）。各結果には、summary、level（ok / warn / critical / unknown）、および安定したコードを持つfindingsが含まれます。

プロンプト： daily_check（全体を確認し、フラグが立った項目を詳しく調べ、オペレーター向けブリーフィングとして報告）とincident_triage（引数はnode、任意のsymptom：証拠を優先して診断し、最後にホスト上で確認すべき項目を提示します）。

セキュリティモデル

バリデーターの運用者が、インフラストラクチャについて LLM を信頼しなくても済むように、このサーバーは「問題を起こさない」と約束するのではなく、問題を起こせないように構築されています。

• 鍵は一切扱いません。 priv_validator_key.json、キ―リング、ニーモニックを指す設定項目はありません。秘密情報に見える項目名は拒否されます。設定以外のファイルシステムは読み取りません。
• 設計上、読み取り専用です。 1 つの HTTP クライアントが、ハードコードされた許可リストにある CometBFT の /status、/net_info、/validators、/commit、/consensus_state、/abci_info、/health と、Cosmos SDK のスラッシング、ステーキング、アップグレード、ガバナンス関連クエリに対してのみ GET を実行します。broadcast_*、unsafe_*、dial_*、check_tx、ピアアドレスを列挙する /dump_consensus_state、および /cosmos/tx/ は全面的に拒否されます。パスパラメーターはパターンチェックされ、リダイレクトは追跡されず、レスポンスのサイズには上限が設けられています。
• ネットワークの詳細はマスクされます。 ピアの IP は private-ipv4、public-ipv4 などのクラスとしてのみ表示され、ノード ID は一部が省略されます。また、エラーにアドレスが含まれることはありません。そのため、セントリーで保護されたバリデーターの IP が LLM プロバイダーのログに残ることはありません。--reveal-network を指定すると、明示的にこの機能が無効になります。
• ノードからのテキストは信頼されません。 モニカー、バージョン、エラーメッセージ、アップグレード計画など、ノードまたは REST サーバーが制御するすべての内容は <untrusted> タグで囲むか、想定される形式と一致する必要があります。これにより、悪意のあるピアや公開 RPC がエージェントに指示を注入することを防ぎます。
• ノードに負荷をかけません。 全体の同時実行数に上限を設け、ブロックスキャンの範囲を制限しています。コミットはまずセントリーまたはフルノードから読み取ります。
• サプライチェーン。 リリースアーカイブとイメージにはビルド来歴の証明が付属し、CI のアクションとベースイメージはダイジェストで固定されています。

脅威モデルと報告方法については、SECURITY.md を参照してください。

判定方法

ライブネス。 CometBFT のコミットには、その高さにおけるバリデーターセットの全バリデーターが投票力順に列挙されますが、署名がない場合、その署名にはアドレスが含まれません。 そこで、このツールは各コミット内でバリデーターのアドレスを探します。見つからない場合は、その高さのバリデーターセットと、バリデーターのインデックスに対応する署名を読み取ります。署名がなければ missed、インデックスがなければ not in the set です。スキャン対象は latest − 1 までの正規コミットのみです。ノードが最新の高さに対して返すコミットは seen commit で、+2/3 より前に到着したプリコミットのみを含みます。そのため、セントリーの背後にいるバリデーターは通常、存在しないように見えます。ダウンタイムによるスラッシングの計算にも、正規コミットが使用されます。

ジャイルのリスク。 Cosmos SDK レイヤーでは、チェーン自体の入力である x/slashing のパラメーターと署名情報、およびコンセンサスキーを使って照合した x/staking を読み取り、x/slashing とまったく同じ方法でしきい値を計算します。つまり、猶予期間である start_height + window までの期間も含めて、window − round_half_even(window × min_signed_per_window) を計算します。ステーキング情報の照会に失敗しても、未来の jailed_until はジャイル中として扱われます。ジャイルされるとミスカウンターがリセットされるため、そうしないと問題のない記録に見えてしまうからです。

停止。 CometBFT でプリボートとプリコミットを行うには、投票力の 2/3 を超える支持が必要です。consensus_diagnosis は現在のラウンドの投票を読み取ります。CometBFT は次のラウンドも列挙しますが、まだ空なのでスキップされます。各投票をその位置に対応するバリデーターと照合し、投票済みの投票力を合計します。

互換性

トラブルシューティング

よくある質問

バリデーターのアンジェイル、ノードの再起動、トランザクションの送信はできますか？ いいえ。設計上できません。署名や書き込みを行うコードパスはありません。セキュリティモデルをご覧ください。

バリデーターの RPC は必要ですか？ いいえ。バリデーターは validator_address だけで監視できます。署名はセンティネル、フルノード、またはパブリック RPC から読み取ります。

自分のマシンから送信される情報は何ですか？ ツールの結果は MCP クライアントに送られ、クライアントを介して LLM プロバイダーに送信されます。送信される情報は、ノード名、ロール、高さ、ピア数、バリデーターアドレスです。IP とノード ID はマスクされます。本番環境のノードで使用する場合は、事前に所属組織の承認を得てください。

gno.land に対応していますか？ まだ対応していません。Tendermint2 の RPC は CometBFT のものとは異なります。gno.land 自体については、gnoverse/gno-mcpをご覧ください。

ディスクやメモリのチェックがないのはなぜですか？ 意図的なものです。ホストのメトリクスは node_exporter と既存のアラート機能で確認できます。cometbft-mcp は、チェーンルールが必要な判定に特化しています。

開発

make test           # unit tests, no network
make lint
make localnet-up    # 4 validators + 1 sentry (simd) in Docker; writes localnet/config.yaml
make e2e            # MCP over stdio: downtime, a real jail + unjail, an upgrade proposal, a chain halt (~5 min)
go test -tags mainnet -v ./test/mainnet/   # read-only smoke test on Cosmos Hub public endpoints

ローカルネットのジェネシスは、問題が数秒で発生するように調整されています（スラッシング期間は50ブロック、最低署名率は50％、ジェイル期間は60秒、投票時間は30秒）。対話形式で試すには、次を実行します。

make build
claude mcp add cometbft-local -- "$PWD/bin/cometbft-mcp" --config "$PWD/localnet/config.yaml"
make localnet-stop VAL=val3           # "is val3 signing? how long until it's jailed?"
make localnet-stop VAL="val2 val3"    # halt the chain; wait a minute: "why did blocks stop?"
make localnet-down

CI では、プッシュとプルリクエストのたびに lint とユニットテストが実行されます（ドキュメントのみの変更ではスキップされます）。E2E テストスイートは毎日、手動実行時、および e2e ラベルが付いたプルリクエストで実行されます。コントリビューションについては、CONTRIBUTING.mdをご覧ください。コードの構成と、決して壊してはならない不変条件については、AGENTS.mdをご覧ください。

ロードマップ

• ICS コンシューマーチェーン（スラッシングとジェイルはプロバイダー上で実行）
• secp256k1 コンセンサスキー
• Tendermint2（gno.land）アダプター

ライセンス

Apache-2.0