@winstonsayno/mcp-gateway 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -9,6 +9,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.1.0] - 2026-10-07
+
+### Added
+- **Dashboard v2** (`/dashboard`, still one self-contained HTML file: no build step, no CDN, no runtime dependencies):
+  - First-run **guided onboarding** (dismissible, reopen with **?**): connect with an API key (tested live), see the upstream servers, try a tool (`tools` list → form generated from the tool's JSON schema, or raw JSON → call → result), and copy-paste snippets for Claude Desktop (via `mcp-remote`), Cursor, Claude Code, the JS and Kotlin clients and curl, all pointing at this gateway's `/mcp` URL.
+  - **Live overview**: requests/min, p50 / p95 / p99 latency, error rate and servers-online cards with sparklines; hand-drawn SVG charts for request rate, latency and error rate (5 m / 15 m / 1 h / 6 h windows, hover / touch tooltips); top tools; usage per API key; live request stream; server health.
+  - Servers page with tool chips and one-click reconnect; Playground; request history with filters and cursor paging (cards on phones); Connect page.
+  - English / 中文 toggle, dark / light theme, responsive down to phone widths with a bottom tab bar, keyboard navigation (arrow-key tabs, focus-trapped dialog, Esc), `prefers-reduced-motion`, View Transitions, skeleton loaders; animations use transform / opacity only.
+- `GET /api/v1/stats`: windowed time series (count, errors, p50 / p95 per bucket), summary, top tools, per-server and per-client usage (`?window=`, `?bucket=`).
+- `GET /api/v1/events`: Server-Sent Events stream with a `request` event per recorded call and a `snapshot` (server health + summary) every 2 s; heartbeats, max 50 concurrent streams, closed on shutdown. Both new endpoints require auth and show restricted clients only their own calls. The dashboard falls back to polling every 2 s when the stream is unavailable.
+
+## [1.0.1] - 2026-10-07
+
+Bug-fix release; no API or configuration changes.
+
+### Fixed
+- A server whose MCP handshake (`initialize` → `notifications/initialized` → `tools/list`) was still in progress was already reported as connected: `mcp_gateway_server_up` / `up` in `/api/v1/metrics` showed `1`, `/health/ready` counted it, and REST / `/mcp` calls could be forwarded to it before `initialize` had been answered. `McpProxy#isConnected` and `McpProxy#request` now require a completed handshake (calls during it get the usual "not connected" / `503`).
+- Flaky tests: `GET /api/v1/tools?format=mcp` assertion depended on server connect order; the reconnect-metrics test could observe a handshaking server as up (fixed by the above).
+
+### Changed (maintenance)
+- Dependabot ignores semver-major updates (npm root + JS client, Gradle) and keeps the Docker base image on Node 22; majors are adopted deliberately.
+
 ## [1.0.0] - 2026-10-07
 
 First stable release. From here on mcp-gateway follows semver: `/api/v1`, `/mcp`, configuration keys, CLI and

package/README.md

@@ -228,6 +228,8 @@ What the endpoint does:
 | `GET` | `/api/v1/prompts` | Prompts of all servers (`?server=`) |
 | `POST` | `/api/v1/prompts/get` | Get a prompt: `{"name": "...", "server"?: "...", "arguments"?: {...}}` |
 | `GET` | `/api/v1/requests` | Request history, newest first (`?limit=` max 500, `server`, `tool`, `client`, `success`, `via`, `kind`, `since`, `until`, `cursor`) |
+| `GET` | `/api/v1/stats` | Live dashboard data: time series (count, errors, p50/p95 per bucket), summary, top tools, per-server and per-key usage (`?window=`, `?bucket=` ms) |
+| `GET` | `/api/v1/events` | Server-Sent Events: a `request` event per call, a `snapshot` (health + summary) every 2 s |
 | `POST` `GET` `DELETE` | `/mcp` | MCP Streamable HTTP endpoint (see [above](#use-the-gateway-as-an-mcp-server-mcp)) |
 
 `/health` and `/metrics` are unauthenticated by default; set `auth.protect.health` / `auth.protect.metrics`
@@ -538,10 +540,18 @@ readinessProbe:
 
 ## Dashboard
 
-Open `http://localhost:4000/dashboard`. When auth is enabled, paste an API key (or JWT) in the header:
-it is kept in the browser tab (`sessionStorage`, or `localStorage` with “remember”) and sent as
-`Authorization: Bearer …` on every API call. The page itself contains no data; set `dashboard.enabled: false`
-to stop serving it.
+Open `http://localhost:4000/dashboard`. The first visit opens a short guided setup: connect with an API key,
+see the upstream servers, call a tool from a form generated from its JSON schema, and copy a ready-made
+config for Claude Desktop, Cursor, Claude Code, the JS / Kotlin clients or curl. Reopen it any time with the
+**?** button. After that the dashboard shows live request rate, p50 / p95 latency, error rate, top tools,
+usage per key, a live request stream, server health (with reconnect) and the filterable request history.
+It is one static file with no build step and no CDN; English / 中文, dark / light, and it works on phones.
+
+![Dashboard overview](docs/images/dashboard-overview.png)
+
+When auth is enabled the key is kept in the browser tab (`sessionStorage`, or `localStorage` with
+“remember”) and sent as `Authorization: Bearer …` on every API call. The page itself contains no data; set
+`dashboard.enabled: false` to stop serving it. See [dashboard/README.md](dashboard/README.md).
 
 ## Embed as a Library
 

package/dashboard/README.md

@@ -1,27 +1,72 @@
 # mcp-gateway Dashboard
 
-A lightweight, zero-dependency web dashboard for monitoring your mcp-gateway instance in real time.
+A guided, real-time web dashboard for mcp-gateway. It is **one self-contained file** (`index.html`):
+no build step, no CDN, no runtime dependencies. Charts are hand-drawn SVG.
 
-## Features
-
-- Live server status (online / degraded / reconnecting / offline) with next retry and reconnect count
-- Tool inventory across all registered servers
-- Request log with method, tool name, duration, and HTTP status
-- Aggregate metrics: total requests, error rate, average / p95 latency, uptime
-- Works with auth enabled: paste an API key or JWT in the header (kept in `sessionStorage`, or `localStorage` with “remember”), sent as `Authorization: Bearer …`
-- Auto-refreshes every 10 seconds; manual refresh button available
+![Overview](../docs/images/dashboard-overview.png)
 
 ## Access
 
-When the gateway is running, the dashboard is served at:
-
 ```
 http://localhost:4000/dashboard
 ```
 
-It reads data exclusively from the gateway's own REST API (`/api/v1/*`), so no additional backend is needed.
-The page itself is a static shell without data; disable it with `dashboard: { enabled: false }`.
+The page itself contains no data. It reads everything from the gateway's own API (`/api/v1/*`), so no extra
+backend is needed. Disable it with `dashboard: { enabled: false }`. Add `?guide` to the URL to force the
+onboarding guide open.
+
+## Guided onboarding
+
+Shown on the first visit (and whenever a key is required but missing). Dismiss it with **Skip**, **Esc** or ✕;
+reopen it any time from the **?** button.
+
+1. **Connect**: paste an API key or JWT and test it (leave empty when auth is off).
+2. **Upstream servers**: what is behind the gateway, with status, transport and tool count.
+3. **Try a tool**: pick any tool your key may use; a form is generated from its JSON schema (strings, numbers,
+   integers, booleans, enums, arrays / objects as JSON, required fields, defaults, descriptions), or switch to
+   raw JSON. Call it and see the result.
+4. **Connect your client**: copy-paste config for Claude Desktop (through `mcp-remote`), Cursor, Claude Code,
+   the TypeScript client (`clients/js`), the Kotlin client (`clients/kotlin`) and curl, all pointing at this
+   gateway's `/mcp` URL. Snippets use `<YOUR_API_KEY>` unless you choose to insert your key.
+
+## Pages
+
+| Page | What it shows |
+|---|---|
+| **Overview** | Requests/min, p50 / p95 / p99 latency, error rate and servers online (with sparklines); request-rate, latency and error-rate charts (5 m – 6 h windows, hover / touch tooltips); top tools; usage per API key; live request stream (pausable); server health |
+| **Servers** | One card per upstream server: status, transport, last ping, tools (click to try one), last error and next retry, **Reconnect** |
+| **Playground** | The same schema-driven tool runner as the guide, with search and *copy as curl* |
+| **History** | `GET /api/v1/requests` with server / tool / client / result / via / kind filters and cursor paging (audit log when enabled) |
+| **Connect** | The client snippets from the guide |
+
+## Live data
+
+- `GET /api/v1/events` (Server-Sent Events) pushes every request as it happens plus a health / summary
+  snapshot every 2 s. The dashboard reads it with `fetch()` so the API key travels in the `Authorization`
+  header (`EventSource` cannot send headers). If the stream is unavailable it polls every 2 s and keeps
+  retrying the stream with backoff. The header pill shows **Live**, **Polling** or **Offline**.
+- `GET /api/v1/stats?window=…` provides the time series and breakdowns.
+
+See [docs/api-reference.md](../docs/api-reference.md#live-data-dashboard).
+
+## Auth
+
+When auth is enabled, the key is kept in the browser tab (`sessionStorage`) or, with “Remember on this device”,
+in `localStorage`, and sent as `Authorization: Bearer …`. Scoped keys only see their own calls and in-scope
+servers and tools.
+
+## Accessibility & UX
+
+- English / 中文 toggle (defaults to the browser language), dark / light theme (defaults to the OS setting).
+- Responsive down to phone widths, with a bottom tab bar on small screens; safe-area aware.
+- Keyboard: arrow keys move between tabs, the guide is a focus-trapped modal, **Esc** closes dialogs,
+  visible focus rings, a skip link.
+- Respects `prefers-reduced-motion`. Animations only use `transform` / `opacity`; page and theme switches use
+  View Transitions where the browser supports them; skeleton loaders while data loads.
 
-## Screenshot
+## Screenshots
 
-The dashboard uses a GitHub-dark colour scheme and is fully responsive down to mobile widths.
+| | |
+|---|---|
+| ![Onboarding](../docs/images/dashboard-onboarding-try-tool.png) | ![Playground (中文)](../docs/images/dashboard-playground-zh.png) |
+| ![Light theme](../docs/images/dashboard-overview-light.png) | ![Mobile](../docs/images/dashboard-mobile-zh.png) |