@winstonsayno/mcp-gateway 0.0.0-stage → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,124 @@
+# Changelog
+
+All notable changes to mcp-gateway will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [Unreleased]
+
+## [0.3.0] - 2026-10-07
+
+### Added
+- **Remote upstream transports are routable**: `streamable-http` (MCP 2025-03-26+: `Mcp-Session-Id`, `MCP-Protocol-Version`, JSON or SSE responses, `DELETE` on close), `sse` (MCP 2024-11-05 HTTP+SSE) and `websocket` (`mcp` subprotocol). Per-server `headers` (with `${VAR}` expansion) and `subprotocol` options.
+- The proxy is now a transport-independent session layer over small channels (`src/transport/*`), so timeouts, upstream cancellation, `maxConcurrency` and server→client `ping` work identically on every transport. `notifications/tools/list_changed` refreshes the tool registry.
+- **Automatic reconnect** of crashed / disconnected / never-connected servers with exponential backoff and jitter (`reconnect` block, per-server overrides). New `reconnecting` status, `health.reconnect` and `session` details in `/servers`, `POST /api/v1/servers/:id/reconnect`, `503` responses carry `status` and `Retry-After`.
+- Health checks send a real MCP `ping` and record latency; a connected server that stops answering is `degraded`. Interval configurable via `healthCheckIntervalMs`.
+- Prometheus: `mcp_gateway_server_up`, `mcp_gateway_server_status`, `mcp_gateway_server_reconnects_total`, `mcp_gateway_server_reconnect_attempt`, `mcp_gateway_server_ping_ms`. JSON `/metrics` includes a `servers` array.
+- **Optional auth for `/health` and `/metrics`** (`auth.protect.health`, `auth.protect.metrics`, default off); always-public `GET /api/v1/health/live` liveness probe; `dashboard.enabled` switch.
+- **Dashboard works with auth on**: API key / JWT field (sessionStorage, optional localStorage) sent as a Bearer token; shows reconnect state; fields aligned with the actual API.
+- **Hot reload** now also applies `auth` (strategy, keys, secret, protect flags), `rateLimit`, `corsOrigins`, `monitor.requestLog` / `monitor.prometheus` and `reconnect`. An unusable auth config is rejected and the current one kept.
+- Conformance tests against the official `@modelcontextprotocol/sdk` servers (Streamable HTTP, SSE, WebSocket adapter); supervisor, hot-reload and auth-protection tests.
+- `examples/docker/prometheus.yml` (the compose file referenced it but it was missing) and `examples/remote-servers/`.
+
+### Changed
+- `initialize` requests protocol `2025-06-18` and accepts `2025-03-26` / `2024-11-05` answers (the version the server picks is used).
+- `@modelcontextprotocol/sdk` moved to `devDependencies` (used only by tests); no runtime dependency was added.
+- `/health` reports `degraded` while any server is `reconnecting`; its `servers` summary has a `reconnecting` count.
+- `/servers` redacts `headers` values and URL credentials / query values in addition to `env`.
+- Docker `HEALTHCHECK` and the compose example use `/api/v1/health/live`.
+- The SSE / WebSocket classes in `src/transport/` were rewritten as channels; they no longer reconnect on their own (the supervisor re-runs the full MCP handshake instead).
+
+### Security
+- API-key comparison is now constant-time; client ids are key fingerprints instead of key prefixes.
+- Unsupported auth strategies (`oauth2`, unknown values) and `api-key`/`jwt` without keys/secret now refuse to start instead of silently disabling auth.
+- JWT verification is pinned to HS256/384/512.
+- `/servers` responses redact `env` values.
+- Client-supplied `X-Request-Id` values are validated; tool-call arguments are no longer logged.
+
+### Fixed
+- `${VAR}` references in stdio `args` are now expanded (the multi-server and Docker examples relied on it; only `env` was expanded before).
+- Docker compose example referenced a missing `prometheus.yml` and `mcp-gateway.yml`; both are now included.
+- Dashboard read fields the API never returned (`healthy`, `uptimeSeconds`, `errorRate`, `p50LatencyMs`, …), could not authenticate, and inserted server-provided strings as raw HTML.
+- Project did not compile (`tsc` errors in transports, watcher and JWT auth); `npm start` pointed at `dist/cli.ts`.
+- Failed `initialize` left the child process running and the server reported as connected.
+- Reconnecting a server id leaked the previous process; an old process' exit could remove the new session.
+- SIGKILL escalation never ran (`proc.killed` check); EPIPE on a dead child's stdin crashed the gateway.
+- Multi-byte UTF-8 split across stdout chunks was corrupted; server→client requests with colliding ids were taken as responses.
+- `maxConcurrency` was ignored; timed-out calls are now cancelled upstream; `tools/list` pagination is followed.
+- CORS with several origins produced an invalid `Access-Control-Allow-Origin` header.
+- The SSE parser lost events split across chunks, ignored the MCP `endpoint` event and dropped the `sessionId` query; SSE/WS reconnected after an intentional disconnect.
+- WebSocket transport relied on a global `WebSocket` missing on Node 20; now uses `ws`.
+- Rate limiter was fixed-window (README said sliding) and its timer kept the process alive.
+- Prometheus `*_total` series were last-minute counts (not counters); `*/*` requests got Prometheus text, breaking the dashboard.
+- Listen errors (EADDRINUSE) hung startup; `stop()` hung on keep-alive sockets and was not idempotent.
+- Malformed JSON bodies returned 500/HTML; upstream errors now map to 502 and timeouts to 504; ambiguous tool names return 409.
+- Hard-coded `0.1.0` version strings; startup summary always reported 0 failed servers.
+- Config hot reload, request ids, CORS, error handler and `/dashboard` were implemented but never wired in.
+- Docker: `npm ci` needed a lockfile (now committed), dashboard copied, runs as non-root; compose healthcheck used `curl` (not in image).
+
+### Added
+- Test suite (vitest) with a fake stdio MCP server; GitHub Actions CI on Node 20 and 22.
+- Config validation: unique server ids, `command` for stdio, `url` for sse/websocket.
+
+---
+
+## [0.2.0] - 2026-03-27
+
+### New Features
+
+**SSE Transport (`src/transport/sse.ts`)**
+Full Server-Sent Events transport implementation for MCP servers that expose an SSE endpoint. Supports automatic reconnection with exponential back-off (up to `maxReconnectAttempts`), pending-request correlation by JSON-RPC id, and a companion POST `/message` endpoint for sending requests.
+
+**WebSocket Transport (`src/transport/websocket.ts`)**
+Full-duplex WebSocket transport for lower-latency MCP server communication. Includes automatic reconnection, keep-alive pings at a configurable interval, and the same pending-request correlation model as the SSE transport.
+
+**Config Hot Reload (`src/config/watcher.ts`)**
+The gateway now watches its config file for changes and applies new server registrations without requiring a restart. A 500 ms debounce prevents thrashing on rapid saves. Invalid configs are rejected with a clear error log while the previous config remains active.
+
+**Request Tracing (`src/middleware/request-id.ts`)**
+Every request now carries a unique `X-Request-Id` header. The middleware honours existing `X-Request-Id` or `X-Correlation-Id` headers sent by clients, falling back to a generated UUID v4. The id is reflected in the response and included in all log lines for that request.
+
+**CORS Middleware (`src/middleware/cors.ts`)**
+Configurable CORS support with wildcard, exact-origin, and regex-pattern matching. Exposes `X-Request-Id` and `X-RateLimit-*` headers to browsers by default.
+
+**Web Dashboard (`dashboard/index.html`)**
+A zero-dependency, single-file HTML dashboard served at `/dashboard`. Displays server health, tool inventory, recent requests, and aggregate metrics. Auto-refreshes every 10 seconds.
+
+### Bug Fixes
+
+**[BUG-001] Concurrent restart race condition**
+When multiple requests arrived simultaneously while a server process was restarting, the proxy could spawn duplicate processes. Fixed by introducing a per-server `Mutex` that serialises all `connect()` calls for the same server id.
+
+**[BUG-002] JSON-RPC id collision under high concurrency**
+`Date.now()` was used as the JSON-RPC request id, which could produce collisions when multiple requests were dispatched within the same millisecond. Replaced with a monotonic integer counter (`_idSeq`).
+
+**[BUG-003] Leaked stdio handles on process crash**
+When an MCP server process crashed, its `stdin` and `stdout` streams were not explicitly destroyed, leaving file-descriptor leaks. The `exit` and `error` handlers now call `.destroy()` on both streams before removing the session.
+
+**[BUG-004] Silent spawn failures**
+A `spawn error` event (e.g., command not found) was logged but did not reject pending requests, leaving callers hanging until their timeout fired. The `error` handler now immediately rejects all pending requests for that session.
+
+**[BUG-005] Unhandled errors leaked raw stack traces**
+Express errors were passed through without a centralised handler, causing raw `Error` objects (including stack traces) to be serialised into responses in production. A new `errorHandler` middleware normalises all errors into a consistent `{ error: { code, message, requestId } }` envelope and suppresses stack traces outside of development mode.
+
+**[BUG-006] Requests hung indefinitely on slow servers**
+Tool-call requests to unresponsive MCP servers could block the event loop indefinitely. A new `timeoutMiddleware` enforces a per-request deadline (default: 30 s) and returns a `504 Gateway Timeout` with a `Retry-After` header.
+
+### Internal Changes
+
+- Added `src/utils/mutex.ts` — lightweight async mutex with no external dependencies
+- Added `src/middleware/error-handler.ts` — centralised error normalisation and `GatewayError` class
+- Added `src/middleware/timeout.ts` — per-request timeout enforcement
+- Updated `src/proxy/index.ts` — incorporates all bug fixes above; private methods renamed with `_` prefix for clarity
+- Updated client info version string from `0.1.0` to `0.2.0` in MCP `initialize` handshake
+
+---
+
+## [0.1.0] - 2026-03-24
+
+### Added
+
+Initial public release. See the [v0.1.0 release notes](https://github.com/HarrisonCN/mcp-gateway/releases/tag/v0.1.0) for the full feature list.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HarrisonCN
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,378 @@
-# Temporary Holding Version
+<div align="center">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<img src="https://raw.githubusercontent.com/HarrisonCN/mcp-gateway/main/docs/assets/logo.svg" alt="mcp-gateway" width="120" />
+
+# mcp-gateway
+
+**A lightweight, open-source gateway for your MCP servers.**
+
+Route · Authenticate · Rate-limit · Monitor — all your [Model Context Protocol](https://modelcontextprotocol.io) servers from a single endpoint.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen.svg)](https://nodejs.org)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.5-blue.svg)](https://www.typescriptlang.org)
+[![npm version](https://img.shields.io/badge/npm-v0.2.0-blue.svg)](https://www.npmjs.com/package/mcp-gateway)
+[![Docker](https://img.shields.io/badge/docker-ghcr.io-blue.svg)](https://ghcr.io/HarrisonCN/mcp-gateway)
+
+[English](#) · [中文](docs/README.zh-CN.md) · [Docs](docs/) · [Examples](examples/)
+
+</div>
+
+---
+
+## The Problem
+
+As [MCP](https://modelcontextprotocol.io) becomes the standard protocol for AI agents to interact with tools, teams are running **dozens of MCP servers** — filesystem, GitHub, databases, Slack, search, and more. Managing them is chaos:
+
+- Every AI client connects to every server independently
+- No central authentication or access control
+- No visibility into which tools are being called, by whom, and how often
+- No rate limiting to prevent runaway agents from hammering your APIs
+
+**mcp-gateway solves this.** It sits between your AI clients and your MCP servers, acting as a single, observable, secure entry point.
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                      AI Clients                         │
+│   Claude Code · Cursor · Copilot · Your App · Scripts   │
+└─────────────────────┬───────────────────────────────────┘
+                      │  HTTP / REST
+                      ▼
+┌─────────────────────────────────────────────────────────┐
+│                   mcp-gateway                           │
+│                                                         │
+│  ┌──────────┐  ┌──────────┐  ┌──────────────────────┐  │
+│  │   Auth   │  │  Router  │  │  Metrics / Monitor   │  │
+│  │ API Key  │  │ Tool →   │  │  Prometheus · Logs   │  │
+│  │   JWT    │  │ Server   │  │  Dashboard           │  │
+│  └──────────┘  └──────────┘  └──────────────────────┘  │
+│                                                         │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐              │
+│  │Rate Limit│  │ Registry │  │  Health  │              │
+│  └──────────┘  └──────────┘  └──────────┘              │
+└──────┬──────────────┬──────────────┬────────────────────┘
+       │              │              │  stdio / SSE / WS
+       ▼              ▼              ▼
+┌──────────┐  ┌──────────┐  ┌──────────┐
+│Filesystem│  │  GitHub  │  │PostgreSQL│  ... more
+│  Server  │  │  Server  │  │  Server  │
+└──────────┘  └──────────┘  └──────────┘
+```
+
+## Features
+
+- **Unified API endpoint** — one URL for all your MCP tools, auto-routed by tool name
+- **Every MCP transport** — `stdio`, `streamable-http` (current spec), legacy `sse` (HTTP+SSE) and `websocket` upstream servers, with per-server headers for upstream auth
+- **Automatic reconnect** — crashed or disconnected servers are reconnected with exponential backoff + jitter; state is visible in `/servers`, `/health`, the dashboard and Prometheus
+- **Authentication** — API key (constant-time compare), JWT (HS256/384/512), or no-auth; misconfiguration fails closed
+- **Rate limiting** — per-key sliding-window counter, with standard `X-RateLimit-*` headers
+- **Concurrency limits** — per-server `maxConcurrency`, queued requests count against `timeout`
+- **Health monitoring** — periodic MCP `ping` health checks with latency (every 30 s, configurable)
+- **Metrics** — Prometheus-compatible `/metrics` endpoint (monotonic counters) + JSON aggregation
+- **Config hot reload** — servers, API keys / auth, rate limits, CORS and reconnect policy apply without a restart (disable with `--no-watch`)
+- **Optional auth for health & metrics** — keep `/health` and `/metrics` public (default) or put them behind auth; the dashboard asks for a key
+- **Tool discovery** — `GET /api/v1/tools` lists all tools across all servers
+- **YAML/JSON config** — simple, declarative configuration with env var overrides
+- **Docker-ready** — official Docker image, Compose examples included
+- **TypeScript SDK** — embed the gateway as a library in your own project
+
+## Quick Start
+
+### Install
+
+```bash
+npm install -g @winstonsayno/mcp-gateway
+# or
+npx @winstonsayno/mcp-gateway init
+```
+
+### Configure
+
+```bash
+# Generate a default config file
+mcp-gateway init
+
+# Edit mcp-gateway.yml to add your servers
+```
+
+```yaml
+# mcp-gateway.yml
+port: 4000
+
+servers:
+  - id: filesystem
+    name: Filesystem
+    transport: stdio
+    command: npx
+    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
+
+  - id: github
+    name: GitHub
+    transport: stdio
+    command: npx
+    args: ["-y", "@modelcontextprotocol/server-github"]
+    env:
+      GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_TOKEN}"
+```
+
+### Run
+
+```bash
+mcp-gateway start
+# → mcp-gateway listening on http://0.0.0.0:4000
+# → ✓ Filesystem — 8 tools available
+# → ✓ GitHub — 26 tools available
+```
+
+### Call a Tool
+
+```bash
+# List all available tools
+curl http://localhost:4000/api/v1/tools
+
+# Call a tool (auto-routes to the right server)
+curl -X POST http://localhost:4000/api/v1/tools/call \
+  -H "Content-Type: application/json" \
+  -d '{"tool": "read_file", "arguments": {"path": "/tmp/hello.txt"}}'
+
+# With authentication
+curl -X POST http://localhost:4000/api/v1/tools/call \
+  -H "Authorization: Bearer your-api-key" \
+  -H "Content-Type: application/json" \
+  -d '{"tool": "create_issue", "server": "github", "arguments": {"title": "Bug report", "body": "..."}}'
+```
+
+## API Reference
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/api/v1/health` | Gateway health and server summary |
+| `GET` | `/api/v1/servers` | List all registered servers |
+| `GET` | `/api/v1/servers/:id` | Get server details and tools |
+| `GET` | `/api/v1/tools` | List all tools (filterable by `?server=` or `?tag=`) |
+| `POST` | `/api/v1/tools/call` | Invoke a tool |
+| `POST` | `/api/v1/servers/:id/reconnect` | Reconnect a server now (resets backoff) |
+| `GET` | `/api/v1/health/live` | Liveness probe — always public, returns only `{"status":"ok"}` |
+| `GET` | `/api/v1/metrics` | Aggregated metrics (JSON or Prometheus) |
+| `GET` | `/api/v1/requests` | Recent request log (`?limit=`, max 500) |
+
+`/health` and `/metrics` are unauthenticated by default; set `auth.protect.health` / `auth.protect.metrics`
+to require auth for them too (`/health/live` always stays public for Docker / Kubernetes probes).
+Every other route requires auth when it is enabled.
+`/metrics` returns JSON by default (`?window=<ms>`); with `monitor.prometheus: true` it returns the
+Prometheus text format when the client asks for `text/plain` (as Prometheus does) or passes `?format=prometheus`.
+
+`POST /api/v1/tools/call` responses:
+
+| Status | Meaning |
+|--------|---------|
+| `200` | Tool returned a result |
+| `400` | Invalid body (`tool` must be a string, `arguments` an object) or malformed JSON |
+| `404` | Unknown tool or server |
+| `409` | Tool name is exposed by several servers — pass `"server"` to choose |
+| `429` | Rate limited (see `Retry-After`) |
+| `502` | The MCP server returned an error |
+| `503` | Server is not connected (body has `status`, e.g. `reconnecting`; `Retry-After` when a retry is scheduled) |
+| `504` | The MCP server did not answer within `timeout` |
+
+## Configuration Reference
+
+```yaml
+port: 4000                    # HTTP port (env: MCP_GATEWAY_PORT)
+host: 0.0.0.0                 # Bind address (env: MCP_GATEWAY_HOST)
+logLevel: info                # debug | info | warn | error
+
+auth:
+  strategy: api-key           # none | api-key | jwt   (oauth2 is not implemented and is rejected)
+  apiKeys:
+    - "your-secret-key"
+  protect:
+    health: false             # true → /api/v1/health requires auth
+    metrics: false            # true → /api/v1/metrics requires auth (configure your scraper)
+
+reconnect:                    # automatic reconnect of crashed / disconnected servers
+  enabled: true
+  initialDelayMs: 1000        # first retry delay
+  maxDelayMs: 60000           # backoff cap
+  multiplier: 2               # delay *= multiplier after each failure
+  jitter: 0.2                 # ±20 % randomisation
+  maxAttempts: 0              # 0 = retry forever; else give up (status: offline)
+
+healthCheckIntervalMs: 30000  # MCP ping interval
+dashboard:
+  enabled: true               # serve /dashboard
+
+rateLimit:
+  limit: 100                  # Max requests per window
+  windowSeconds: 60           # Window duration
+  perKey: true                # Per-key or global
+
+monitor:
+  requestLog: true            # Log all requests
+  prometheus: true            # Enable Prometheus /metrics
+  retentionHours: 24          # Metrics retention
+
+corsOrigins:
+  - "https://your-app.com"
+
+servers:
+  - id: my-server             # Unique identifier
+    name: My Server           # Display name
+    transport: stdio          # stdio | streamable-http | sse | websocket
+    command: npx
+    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
+    env:
+      MY_VAR: "${ENV_VAR}"    # Environment variable substitution
+    tags: [files, local]
+    enabled: true
+    timeout: 30000            # ms, includes time queued behind maxConcurrency
+    maxConcurrency: 10        # max in-flight tool calls for this server
+    reconnect:                # optional per-server override of the reconnect block
+      maxAttempts: 5
+
+  - id: remote
+    name: Remote server
+    transport: streamable-http   # MCP 2025-03-26+ (POST + optional SSE responses, Mcp-Session-Id)
+    url: https://mcp.example.com/mcp
+    headers:
+      Authorization: "Bearer ${REMOTE_MCP_TOKEN}"   # ${VAR} expanded from the gateway's env
+
+  - id: legacy
+    name: Legacy SSE server
+    transport: sse            # MCP 2024-11-05 HTTP+SSE (GET stream + POST to the announced endpoint)
+    url: http://localhost:8080/sse
+
+  - id: socket
+    name: WebSocket server
+    transport: websocket      # one JSON-RPC message per frame, "mcp" subprotocol
+    url: ws://localhost:8081
+    subprotocol: mcp          # "" to request no subprotocol
+```
+
+### Hot reload
+
+With `mcp-gateway start` the config file is watched (disable with `--no-watch`). On save:
+
+| Applied immediately | Needs a restart |
+|---------------------|-----------------|
+| `servers` (added / changed / removed / disabled) | `port`, `host` |
+| `auth` (strategy, keys, JWT secret, `protect`) | `monitor.retentionHours` |
+| `rateLimit` (counters reset when it changes) | `healthCheckIntervalMs` |
+| `corsOrigins`, `monitor.requestLog`, `monitor.prometheus` | `dashboard` |
+| `reconnect`, `logLevel` | |
+
+An invalid file is rejected and the running config is kept. `MCP_GATEWAY_*` env overrides keep precedence.
+
+### Reconnect & server status
+
+Each server's `health.status` is one of `online`, `degraded` (connected, but the health ping failed),
+`reconnecting` (lost — a retry is scheduled or running), `offline` (gave up, or reconnect disabled) or `unknown`.
+`GET /api/v1/servers/:id` also returns `health.reconnect` (`state`, `attempt`, `nextAttemptAt`, `lastError`,
+`reconnects`) and `session` (`transport`, negotiated `protocolVersion`, `serverInfo`, `connectedAt`).
+
+Prometheus series added: `mcp_gateway_server_up`, `mcp_gateway_server_status{status=…}`,
+`mcp_gateway_server_reconnects_total`, `mcp_gateway_server_reconnect_attempt`, `mcp_gateway_server_ping_ms`.
+
+## Docker
+
+```bash
+# Pull and run
+docker run -p 4000:4000 \
+  -v $(pwd)/mcp-gateway.yml:/app/mcp-gateway.yml \
+  -e GITHUB_TOKEN=ghp_... \
+  ghcr.io/harrisonCN/mcp-gateway:latest
+
+# Or with Docker Compose (gateway + Prometheus; see examples/docker)
+cd examples/docker
+GATEWAY_API_KEY=change-me docker compose up
+```
+
+The image's `HEALTHCHECK` uses the always-public `/api/v1/health/live`, so it keeps working when
+`auth.protect.health` is on.
+
+## 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.
+
+## Embed as a Library
+
+```typescript
+import { Gateway, loadConfig } from 'mcp-gateway';
+
+const config = await loadConfig('./mcp-gateway.yml');
+const gateway = new Gateway(config);
+
+await gateway.start();
+// Gateway is now running at http://localhost:4000
+
+// Graceful shutdown
+process.on('SIGTERM', () => gateway.stop());
+```
+
+## What's New (unreleased)
+
+| Feature | Description |
+|---------|-------------|
+| **Remote transports** | `streamable-http`, `sse` and `websocket` servers are now routable (checked against the official MCP SDK servers in the test suite) |
+| **Auto reconnect** | Exponential backoff with jitter, `reconnecting` status, manual `POST /servers/:id/reconnect`, Prometheus series |
+| **Health pings** | Real MCP `ping` health checks with latency; `degraded` when a connected server stops answering |
+| **Tool list updates** | `notifications/tools/list_changed` refreshes the tool registry |
+| **Protected health/metrics** | `auth.protect.health` / `auth.protect.metrics`, public `/health/live`, dashboard API-key support |
+| **More hot reload** | Auth, API keys, rate limits, CORS, reconnect policy |
+
+## What's New in v0.2.0
+
+| Feature | Description |
+|---------|-------------|
+| **SSE Transport** | Transport class (`src/transport/sse.ts`); routable since the unreleased version |
+| **WebSocket Transport** | Transport class (`src/transport/websocket.ts`); routable since the unreleased version |
+| **Config Hot Reload** | Edit the server list in `mcp-gateway.yml` without restarting |
+| **Request Tracing** | `X-Request-Id` on every request & response |
+| **CORS Middleware** | Configurable cross-origin support |
+| **Web Dashboard** | Live monitoring UI at `/dashboard` |
+| **4 Bug Fixes** | Concurrency, id collision, handle leaks, timeouts |
+
+## Roadmap
+
+| Feature | Status |
+|---------|--------|
+| stdio transport | ✅ Done |
+| SSE transport | ✅ Done |
+| WebSocket transport | ✅ Done |
+| Streamable HTTP transport | ✅ Done (standalone GET notification stream not yet used) |
+| Automatic reconnect with backoff | ✅ Done |
+| Config hot reload | ✅ Done (v0.2.0) |
+| Web dashboard UI | ✅ Done (v0.2.0) |
+| Redis-backed rate limiting | 📋 Planned |
+| OAuth2 / OIDC auth | 📋 Planned |
+| Tool-level access control (RBAC) | 📋 Planned |
+| Request replay & debugging | 📋 Planned |
+| Multi-tenant mode | 📋 Planned |
+| OpenTelemetry tracing | 📋 Planned |
+
+## Contributing
+
+Contributions are welcome! See [CONTRIBUTING.md](docs/CONTRIBUTING.md).
+
+```bash
+git clone https://github.com/HarrisonCN/mcp-gateway.git
+cd mcp-gateway
+npm install
+npm run typecheck && npm test
+npm run dev -- start -c examples/basic/mcp-gateway.yml
+```
+
+## License
+
+MIT © 2026 [HarrisonCN](https://github.com/HarrisonCN)
+
+---
+
+<div align="center">
+  <sub>
+    Built for the agentic era · If this helps you, please ⭐ star the repo
+  </sub>
+</div>

package/dashboard/README.md

@@ -0,0 +1,27 @@
+# mcp-gateway Dashboard
+
+A lightweight, zero-dependency web dashboard for monitoring your mcp-gateway instance in real time.
+
+## 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
+
+## 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 }`.
+
+## Screenshot
+
+The dashboard uses a GitHub-dark colour scheme and is fully responsive down to mobile widths.