nats-trail

AI エージェントに、本番イベントバスへの安全なアクセスを提供します。
_{単一の制限付きクエリエンジンを利用する Web UI、CLI、MCP サーバーです。人間とエージェントが同じ信頼できる情報源から NATS をデバッグできます。}

これが必要な理由

どの NATS GUI も、*「このストリームには何があるか？」*には答えてくれます。これは簡単な質問です。

イベント駆動型システムで難しいのは、**「このフローが失敗した原因は何か？」**という質問です。答えるには、4 つのストリーム、3 つのサービス、そしてデッドレターサブジェクトをまたいで単一の request_id を追跡する必要があります。 現在は、ストリームごとにターミナルを開いて手作業で行います。

NATS Trail はこの質問に直接答え、その回答を型付きで制限された読み取り専用のツールコントラクトとしてエージェントに公開します。これにより、本番環境を Claude に指定して質問できます。

nats-trail trace --request-id req-0001d --limit 20

または、エージェントに「s3-events の更新が失敗したのはなぜですか？」と尋ねると、実際に問題を引き起こしたメッセージが表示されます。リトライ状態と相関 ID もすでに抽出されています。

他にはない特長

NATS MCP サーバーはいくつかあります。これらは nats CLI をシェルから実行して生のダンプを返し、読み取り専用と称しながら publish や delete を公開しています。

NATS Trail はエージェント向けの操作範囲をラッパーではなくコントラクトとして扱います。

ここでの「読み取り専用」とは、無効化されているのではなく、アクセスできないという意味です

NATS Trail は書き込みもできます。メッセージ、コンシューマー、ストリームのパブリッシュ、パージ、削除が可能です。これらの機能は /api/mutate の背後にあり、UI と CLI からアクセスできます。

executeMcpTool() が受け取る McpRuntimeData インターフェースには、読み取り関数のみが公開されています。機能フラグで無効化された publish があるわけではありません。呼び出せる publish 自体が存在しません。 環境変数の設定を誤っても、コードパスが存在しないため、本番ストリームをパージすることはできません。CLI の書き込みコマンドは --agent のもとでは実行を拒否し、テストスイートはソースを読み取って、これらの制約がいつの間にか解除されていないことを検証します。

エージェントに prod コンテキストを渡しても問題ないのは、これが唯一の理由です。

インストール

npx nats-trail serve

http://127.0.0.1:4000 を開くと、1 つのプロセスで UI と API の両方が提供されます。

コンテナを使いたい場合は、compose ファイルで NATS Trail と JetStream 対応サーバーを起動できます。

docker compose up

Kubernetes では、Helm チャートでコンテキストと相関キーを values.yaml に宣言し、認証情報を Secret に保存します。

helm install nats-trail ./charts/nats-trail -f my-values.yaml

宣言型設定、単一レプリカの StatefulSet を採用している理由、サービスの前段にあるものへ認証を委譲する方法については、charts/nats-trail/README.md を参照してください。

git clone https://github.com/solsolettidev/nats-trail
cd nats-trail
npm install
npm start

npm run dev

要件： Node.js >= 22（相関インデックスで組み込み SQLite を使用するため）と、接続可能な NATS サーバー（nats-server -js で問題ありません）。

MCP サーバーとして使う

任意の MCP クライアントから stdio サーバーを指定してください。Claude Code の場合：

claude mcp add nats-trail -- npx -y @nats-trail/mcp

または、手動で接続します。

{
  "mcpServers": {
    "nats-trail": {
      "command": "natstrail-mcp",
      "env": {
        "NATS_TRAIL_API": "http://127.0.0.1:4000",
        "NATS_TRAIL_TOKEN": "<bearer token>"
      }
    }
  }
}

読み取り専用ツールが 25 個あり、すべて同じエンベロープを返します。

# start here when the topology is unknown
natstrail.discover_subjects        subjects that carry traffic + inferred payload shapes
natstrail.get_health_summary       what is broken right now, ranked
natstrail.reconstruct_flow         the causal chain for one request_id
natstrail.enrich_incident          flat context for an incident: flow + dead letters + health

# messages
natstrail.search_messages          natstrail.get_message_detail
natstrail.trace_by_request_id      natstrail.trace_by_correlation_id
natstrail.search_dlq               natstrail.run_filter

# topology
natstrail.list_streams             natstrail.get_stream_info
natstrail.list_consumers           natstrail.list_kv_buckets
natstrail.list_kv_keys             natstrail.get_kv_history
natstrail.list_object_buckets      natstrail.list_objects

# operations
natstrail.get_server_health        natstrail.list_server_connections
natstrail.list_contexts            natstrail.get_connection_status
natstrail.list_filters             natstrail.list_audit
natstrail.enrich_sentry

docs/mcp-agent.md を参照してください。

3 つのインターフェース、1 つのエンジン

                 ┌──  Web UI          explore visually, save filters
Query Engine  ───┼──  CLI             scripts, pipelines, humans in a terminal
  (core)         └──  MCP + HTTP API  agents, Sentry, dashboards

UI で保存したフィルターは、nats-trail filter run が実行するフィルターと同じであり、natstrail.run_filter がエージェントに渡すフィルターとも同じです。コンテキストは一度設定するだけで、どこでも使えます。

• packages/ui — React + Vite。プレゼンテーションのみを担当します。
• packages/server — Express + WebSocket ブリッジ。接続と認証情報を管理します。
• packages/core — Query Engine：エンベロープ、上限、切り詰め、フィルター、エラーの正規化を担当します。
• packages/cli — nats-trail バイナリ：クエリーコマンド、serve、対話型シェルを提供します。
• packages/mcp — ツールの契約と stdio サーバーを提供します。

docs/architecture.md を参照してください。

機能

調査 — コンテキストセレクター（local / dev / staging / prod）と prod 確認ゲート、サブジェクトのライブサブスクリプション、ツリービューとペイロード内検索に対応した JSON の整形表示、ストリームとコンシューマーの閲覧、自動検出される DLQ パネルを備えています。

JetStream — ストリーム、サブジェクト、件数、コンシューマーの状態。	NATS Core — フィルターに対応したサブジェクトのライブサブスクリプション。
DLQ — 理由と発生元が自動検出されたデッドレター。	ビューアー — ツリー、raw、検索、全画面表示、パスのコピー。

把握 — サブジェクトの検出では実際のトラフィックからペイロードの形状を推測し、フローの再構成では 1 つの request_id から因果関係の連鎖をたどり、ヘルスサマリーでは実際に問題が起きている箇所を優先順位付けします。

クエリ — カーソルと時間範囲を使った上限付きのストリームスキャン、サブジェクト、日付、テキスト、JSON イベントタイプによるフィルター、3 つすべての画面で共有される保存済みフィルターに対応しています。バイナリペイロード（protobuf、msgpack）は検出され、文字化けではなく 16 進ダンプとして表示されます。

閲覧 — キーごとのリビジョン履歴（削除を含む）を備えた KV バケット、Object Store のメタデータ、モニタリングポート（varz / jsz / connz）から取得するサーバーのヘルス情報に対応しています。

変更 — UI と CLI から、確認を経てメッセージ、コンシューマー、ストリームのパブリッシュ、リクエスト／リプライ、パージ、削除を実行できます。エージェントのインターフェースからは実行できません。

連携 — /api/integration 配下の読み取り専用 HTTP API、トークンごとの監査 ID を持つベアラートークン、認証情報を公開せずにエラーへ NATS のコンテキストを付与する POST /api/integration/enrich/sentry に対応しています。

全機能は docs/features.md、CLI リファレンスは docs/cli.md をご覧ください。

セキュリティ

認証情報はローカルの data/（git-ignore 対象）に保存されるコンテキストに格納されます。UI が NATS 接続を保持することはありません。接続は常にブリッジ経由で行われ、コンテキストごとに 1 つの接続をプールします。

/api/contexts と /api/connect は認証されないローカルエンドポイントであるため、サーバーはデフォルトで 127.0.0.1 にバインドします。Integration API と WebSocket を公開するには、NATS_TRAIL_TOKENS=name:token または data/tokens.json でベアラートークンを設定してください。以降、監査ログには呼び出しごとに認証済みトークン名が記録されます。

共有デプロイメントに組み込みのログイン機能がないのは意図的です。ID はサービスの前段にあるもの（OIDC を備えた ingress、oauth2-proxy、Cloudflare Access、Teleport、またはネットワーク分離）によって決まるため、ここにパスワードは保存されません。NATS_TRAIL_CONFIG を通じて宣言されたコンテキストでは、環境変数から ${VAR} が解決され、API 経由での編集や削除はできません。

ロードマップ

docs/roadmap.mdで管理しています。

フェーズ 0～3 は完了しています。 npm リリース · KV と Object Store の参照 · サーバーの健全性 · バイナリペイロードの処理 · nkey 認証 · サブジェクトの検出 · フローの再構築 · 健全性の概要 · Sentry、Grafana、Datadog、PagerDuty 向けのインシデント情報の拡充 · ストリーム、コンシューマー、KV の管理 · MCP レジストリの一覧表示 · インデックス化された相関検索 · 宣言型設定と Helm チャート。すべての書き込みは人間のみが実行でき、スコープ付きトークンで保護され、引数とともに監査されます。

次の予定： クラスター認識。保留中の作業ではなく、意図的に後回しにしています。

意図的に対象外としています — protobuf と msgpack の フィールド のデコード（サブジェクトごとのスキーマレジストリが必要です）、および GUI の機能の幅広さで NUI と競合すること。詳しくはdocs/roadmap.mdをご覧ください。

計画中ですが、未着手です： エージェントによる書き込みを明示的に希望するチーム向けに、別個のオプトインバイナリ（natstrail-mcp-write）を用意します。これは意図してインストールする必要があります。読み取り専用サーバーにフラグを設けることはありません。上記の保証は、誤操作で無効にできない場合にのみ意味を持つからです。

コントリビュート

Issue と PR を歓迎します。ビルド構成についてはdocs/development.mdをご覧ください。

ライセンス

Apache-2.0 © Sol Soletti