{
  "markdown": "<p align=\"center\">\n  <img src=\"docs/assets/banner.svg\" alt=\"NATS Trail — the agent-native observability layer for NATS and JetStream\" width=\"880\">\n</p>\n\n<p align=\"center\">\n  <a href=\"https://www.npmjs.com/package/nats-trail\"><img alt=\"npm\" src=\"https://img.shields.io/npm/v/nats-trail?style=flat-square&color=4cc4ff&label=npm\"></a>\n  <a href=\"LICENSE\"><img alt=\"License: Apache-2.0\" src=\"https://img.shields.io/badge/license-Apache--2.0-4cc4ff?style=flat-square\"></a>\n  <a href=\"https://www.npmjs.com/package/nats-trail\"><img alt=\"Node version\" src=\"https://img.shields.io/node/v/nats-trail?style=flat-square&color=8b97a7\"></a>\n  <img alt=\"TypeScript strict\" src=\"https://img.shields.io/badge/TypeScript-strict-8b97a7?style=flat-square\">\n  <img alt=\"Agent surface: read-only\" src=\"https://img.shields.io/badge/agent%20surface-read--only-3fb950?style=flat-square\">\n</p>\n\n<p align=\"center\">\n  <b>Give an AI agent safe access to your production event bus.</b><br>\n  <sub>A web UI, a CLI and an MCP server over one bounded query engine — so humans and agents debug NATS from the same source of truth.</sub>\n</p>\n\n---\n\n## Why this exists\n\nEvery NATS GUI answers *\"what is in this stream?\"*. That is the easy question.\n\nThe hard question in an event-driven system is **\"why did this one flow fail?\"** — and answering it\nmeans following a single `request_id` across four streams, three services and a dead-letter subject.\nToday you do that by hand, with a terminal per stream.\n\nNATS Trail answers that question directly, and exposes the answer to **agents** as a typed, bounded,\nread-only tool contract — so you can point Claude at production and ask.\n\n<p align=\"center\">\n  <img src=\"docs/assets/trace.svg\" alt=\"A single request id traced across four streams, merged chronologically, ending in a dead-letter event\" width=\"880\">\n</p>\n\n```bash\nnats-trail trace --request-id req-0001d --limit 20\n```\n\nOr, from an agent: *\"Why did the refresh for s3-events fail?\"* — and it lands on the message that\nactually broke, with the retry state and the correlation ids already extracted:\n\n<p align=\"center\">\n  <img src=\"docs/assets/screenshot-viewer.png\" alt=\"The message viewer showing a bronze.etl.failed event in tree view, with error, code, attempt count and retries_exhausted\" width=\"880\">\n</p>\n\n---\n\n## The part nobody else does\n\nThere are several NATS MCP servers. They shell out to the `nats` CLI, return raw dumps, and expose\n`publish` and `delete` while describing themselves as read-only.\n\nNATS Trail treats the agent surface as a **contract**, not a wrapper:\n\n| | NATS Trail | Typical NATS MCP server |\n|---|---|---|\n| Tool schemas | Explicit JSON input **and** output schemas per tool | None, or input only |\n| Result size | `limit` is **required**, capped at 200, with cursors | Unbounded |\n| Long scans | `maxScan` budget with explicit truncation warnings | Scans until it dies |\n| Message shape | subject, timestamp, stream/seq, truncation flag, extracted `request_id` / `correlation_id` | Raw payload dump |\n| Errors | Structured envelope with `code` and `retriable` | Stack traces or plain strings |\n| Writes | **Unreachable from the agent runtime** | `publish`, KV and object writes exposed |\n| Audit | Every call logged with origin and token identity; mutations with their arguments | None |\n\n### \"Read-only\" here means unreachable, not disabled\n\n<p align=\"center\">\n  <img src=\"docs/assets/boundary.svg\" alt=\"The UI and CLI reach both read and write paths; the MCP runtime is wired only to the read path\" width=\"880\">\n</p>\n\nNATS Trail *can* write: publish, purge, delete messages, consumers and streams. Those live behind\n`/api/mutate`, reachable from the UI and the CLI.\n\n`executeMcpTool()` receives an `McpRuntimeData` interface that exposes only read functions. There is\nno disabled `publish` behind a feature flag — **there is no `publish` to call.** A misconfigured\nenvironment variable cannot purge your production stream, because the code path does not exist. CLI\nwrite commands additionally refuse to run under `--agent`, and the test suite reads the source to\nassert none of this has been quietly undone.\n\nThis is the only reason it is reasonable to hand an agent a `prod` context.\n\n---\n\n## Install\n\n```bash\nnpx nats-trail serve\n```\n\nOpen **http://127.0.0.1:4000** — one process serves the UI and the API.\n\nPrefer containers? The compose file brings up NATS Trail next to a JetStream-enabled server:\n\n```bash\ndocker compose up\n```\n\n<details>\n<summary>From source</summary>\n\n```bash\ngit clone https://github.com/solsolettidev/nats-trail\ncd nats-trail\nnpm install\nnpm start\n```\n\n</details>\n\n<details>\n<summary>Development with hot reload</summary>\n\n```bash\nnpm run dev\n```\n\n- UI: http://localhost:5173 (proxies `/api` and `/ws` to the bridge)\n- API bridge: http://localhost:4000\n\n`npm run dev` runs the TypeScript watcher, the API bridge and the UI together.\n\n</details>\n\n**Requirements:** Node.js >= 22 (for the built-in SQLite used by the correlation index) and a reachable NATS server (`nats-server -js` is fine).\n\n---\n\n## Use it as an MCP server\n\nPoint any MCP client at the stdio server. For Claude Code:\n\n```bash\nclaude mcp add nats-trail -- npx -y @nats-trail/mcp\n```\n\nOr wire it manually:\n\n```json\n{\n  \"mcpServers\": {\n    \"nats-trail\": {\n      \"command\": \"natstrail-mcp\",\n      \"env\": {\n        \"NATS_TRAIL_API\": \"http://127.0.0.1:4000\",\n        \"NATS_TRAIL_TOKEN\": \"<bearer token>\"\n      }\n    }\n  }\n}\n```\n\nTwenty-five read-only tools, all returning the same envelope:\n\n```\n# start here when the topology is unknown\nnatstrail.discover_subjects        subjects that carry traffic + inferred payload shapes\nnatstrail.get_health_summary       what is broken right now, ranked\nnatstrail.reconstruct_flow         the causal chain for one request_id\nnatstrail.enrich_incident          flat context for an incident: flow + dead letters + health\n\n# messages\nnatstrail.search_messages          natstrail.get_message_detail\nnatstrail.trace_by_request_id      natstrail.trace_by_correlation_id\nnatstrail.search_dlq               natstrail.run_filter\n\n# topology\nnatstrail.list_streams             natstrail.get_stream_info\nnatstrail.list_consumers           natstrail.list_kv_buckets\nnatstrail.list_kv_keys             natstrail.get_kv_history\nnatstrail.list_object_buckets      natstrail.list_objects\n\n# operations\nnatstrail.get_server_health        natstrail.list_server_connections\nnatstrail.list_contexts            natstrail.get_connection_status\nnatstrail.list_filters             natstrail.list_audit\nnatstrail.enrich_sentry\n```\n\nSee [`docs/mcp-agent.md`](docs/mcp-agent.md).\n\n---\n\n## Three surfaces, one engine\n\n```\n                 ┌──  Web UI          explore visually, save filters\nQuery Engine  ───┼──  CLI             scripts, pipelines, humans in a terminal\n  (core)         └──  MCP + HTTP API  agents, Sentry, dashboards\n```\n\nA filter you save in the UI is the same filter `nats-trail filter run` executes, and the same one\n`natstrail.run_filter` hands an agent. Configure a context once; use it everywhere.\n\n- **`packages/ui`** — React + Vite. Presentation only.\n- **`packages/server`** — Express + WebSocket bridge. Owns connections and credentials.\n- **`packages/core`** — the Query Engine: envelopes, limits, truncation, filters, error normalization.\n- **`packages/cli`** — the `nats-trail` binary: query commands, `serve`, and an interactive shell.\n- **`packages/mcp`** — tool contracts and the stdio server.\n\nSee [`docs/architecture.md`](docs/architecture.md).\n\n---\n\n## Features\n\n**Inspect** — context selector (local / dev / staging / prod) with a prod confirmation gate, live\nsubject subscription, JSON pretty print with tree view and in-payload search, stream and consumer\nbrowsing, auto-detected DLQ panel.\n\n<table>\n<tr>\n<td width=\"50%\"><img src=\"docs/assets/screenshot-jetstream.png\" alt=\"JetStream panel listing streams with message counts, sizes and per-stream consumers with pending and ack-pending columns\"><br><sub><b>JetStream</b> — streams, subjects, counts and consumer health.</sub></td>\n<td width=\"50%\"><img src=\"docs/assets/screenshot-core.png\" alt=\"NATS Core panel with a live subscription to orders.> and a selected message rendered as a JSON tree\"><br><sub><b>NATS Core</b> — live subject subscription with filters.</sub></td>\n</tr>\n<tr>\n<td width=\"50%\"><img src=\"docs/assets/screenshot-dlq.png\" alt=\"DLQ panel listing dead-letter events with their original subject and failure reason\"><br><sub><b>DLQ</b> — auto-detected dead letters with reason and origin.</sub></td>\n<td width=\"50%\"><img src=\"docs/assets/screenshot-viewer.png\" alt=\"Message viewer in tree mode with a key filter\"><br><sub><b>Viewer</b> — tree, raw, search, fullscreen, copy-path.</sub></td>\n</tr>\n</table>\n\n**Understand** — subject discovery infers payload shapes from real traffic, flow reconstruction\nturns one `request_id` into a causal chain, and the health summary ranks what is actually broken.\n\n**Query** — bounded stream scans with cursors and time windows, filters by subject, date, text and\nJSON event type, saved filters shared across all three surfaces. Binary payloads (protobuf, msgpack)\nare detected and shown as hex dumps rather than mojibake.\n\n**Browse** — KV buckets with per-key revision history including deletes, Object Store metadata, and\nserver health from the monitoring port (`varz` / `jsz` / `connz`).\n\n**Change** — publish, request/reply, purge, and delete messages, consumers and streams, from the UI\nand the CLI, behind confirmation. Never from the agent surface.\n\n**Integrate** — read-only HTTP API under `/api/integration`, bearer tokens with per-token audit\nidentity, and `POST /api/integration/enrich/sentry` to attach NATS context to an error without\nexposing credentials.\n\nFull list in [`docs/features.md`](docs/features.md) · CLI reference in [`docs/cli.md`](docs/cli.md).\n\n---\n\n## Security\n\nCredentials live in contexts stored locally under `data/` (git-ignored). The UI never holds the NATS\nconnection — it always goes through the bridge, which pools one connection per context.\n\nThe server binds to `127.0.0.1` by default because `/api/contexts` and `/api/connect` are\nunauthenticated local endpoints. To expose the Integration API and the WebSocket, configure bearer\ntokens with `NATS_TRAIL_TOKENS=name:token` or `data/tokens.json`; audit entries then record the\nauthenticated token name per call.\n\n---\n\n## Roadmap\n\nTracked in [`docs/roadmap.md`](docs/roadmap.md).\n\n**Phases 0–2 are complete.** npm release · KV and Object Store browsing · server health · binary\npayload handling · nkey auth · subject discovery · flow reconstruction · health summary · incident\nenrichment for Sentry, Grafana and Datadog · stream, consumer and KV administration — all writes\nhuman-only, behind scoped tokens and audited with their arguments.\n\n**Next** — multi-user access and cluster awareness, both open design questions rather than pending work.\n\n**Deliberately out** — protobuf and msgpack *field* decoding (needs a per-subject schema registry)\nand competing with [NUI](https://github.com/nats-nui/nui) on GUI breadth. See\n[`docs/roadmap.md`](docs/roadmap.md).\n\n**Soon** — for teams that explicitly want agent writes, a **separate opt-in binary**\n(`natstrail-mcp-write`) that has to be installed on purpose. Never a flag on the read-only server:\nthe guarantee above is only worth something if it cannot be switched off by accident.\n\n---\n\n## Contributing\n\nIssues and PRs welcome. See [`docs/development.md`](docs/development.md) for the build layout.\n\n## License\n\n[Apache-2.0](LICENSE) © Sol Soletti\n",
  "bytes": 11543,
  "sha": "5e9038109d7b8aaca30ee1b8da81808e84eb29c6e2d55de03253a390c6e3f8ed",
  "repo_slug": "solsolettidev/nats-trail",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_solsolettidev_nats_trail_4780d6d9/readme"
}