@winstonsayno/mcp-gateway 0.4.0 → 1.0.1

package/CHANGELOG.md

@@ -9,6 +9,52 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+root library exports only change in backward-compatible ways within 1.x (see
+[docs/api-reference.md#stability-and-versioning](docs/api-reference.md#stability-and-versioning)).
+This release contains everything developed as v0.5 – v0.8.
+
+### Added
+- **Documentation** in `docs/`: API reference (REST, `/mcp`, error codes, stability policy), configuration reference and deployment guide (Docker, Kubernetes manifests, reverse proxy, security checklist, systemd).
+- **Container image** workflow `.github/workflows/docker.yml`: on release publish, builds `linux/amd64` + `linux/arm64` and pushes `ghcr.io/<owner>/mcp-gateway` tagged `<version>`, `<major>.<minor>`, `<major>` and `latest` (with provenance + SBOM).
+- Dependabot config (npm root + JS client, Gradle Kotlin client, GitHub Actions, Docker), pull-request template, issue-template links, `SECURITY.md`.
+- **Resources & prompts passthrough**: resources, resource templates and prompts of servers announcing those capabilities are listed at connect time and refreshed on `notifications/resources|prompts/list_changed`. REST: `GET /api/v1/resources`, `GET /api/v1/resources/templates`, `POST /api/v1/resources/read`, `GET /api/v1/prompts`, `POST /api/v1/prompts/get` (auto-routing, `409` on ambiguous prompt names, `403` out of scope, `502` / `503` / `504` like tool calls). `/mcp`: `resources/list`, `resources/templates/list`, `resources/read`, `prompts/list`, `prompts/get` (paginated; prompt names follow `toolNaming`; duplicate resource URIs collapsed, lowest server id wins; reads routed by URI, then template, then the only resource server), `resources` / `prompts` capabilities with `list_changed` notifications. Scopes apply by server. Rate limited and recorded with `kind: "resource" | "prompt"`.
+- **Persistent audit log** (`audit: { enabled, path, retentionDays }`, default off): every request record is also written to SQLite through the built-in `node:sqlite` (Node 22.5+, no new dependency; clear startup error on older Node). Metadata only, never arguments or results. Hourly retention pruning.
+- `GET /api/v1/requests` filters (`server`, `tool`, `client`, `success`, `via`, `kind`, `since`, `until`) and cursor paging (`nextCursor`), from the audit log when enabled, else the in-memory log; responses carry `source`. The dashboard's *Request History* panel has filters and *Load older*.
+- JS client: `history()` (filters + cursor), `listResources`, `listResourceTemplates`, `readResource`, `listPrompts`, `getPrompt`.
+- `SessionInfo.capabilities`; `McpProxy#getCatalog`, `#hasCapability`; registry `setCatalog` / `getAllResources` / `getAllResourceTemplates` / `getAllPrompts`; `MetricsCollector#setAuditStore` / `#queryRequests`; exports `SqliteAuditStore`, `sqliteAvailable`, `AuditStore`, catalog helpers and resource / prompt types.
+- **LLM tool schemas**: `GET /api/v1/tools?format=openai|openai-responses|anthropic` returns function-calling definitions (`tools`) plus a `mapping` from LLM tool name to `{ server, tool }`. Names follow `mcp.toolNaming`, are sanitised to `^[a-zA-Z0-9_-]{1,64}$` and de-duplicated; scopes and `?server=` / `?tag=` apply. Exports `toLlmToolSchemas`, `sanitizeToolName`, `LLM_SCHEMA_FORMATS`.
+- **TypeScript client** `@winstonsayno/mcp-gateway-client` in `clients/js` (not published): zero dependencies, `fetch`-based (browser + Node 18+), typed `health`, `ready`, `metrics`, `servers`, `server`, `reconnect`, `listTools`, `toolSchemas`, `callTool`, `callLlmTool`, `requests`, `GatewayError`; `connectMcp()` / `McpSession` helper for `/mcp` (pagination, SSE replies, cancellation). Own tests + an integration test against a real gateway.
+- **Kotlin client** in `clients/kotlin` (not published): OkHttp 4.12 + kotlinx.serialization 1.6, Java 11 bytecode (Android-friendly), same API surface, `McpSession`; Gradle 8.7 wrapper and MockWebServer tests.
+- CI jobs for both clients.
+- **Per-key scopes**: `auth.apiKeys` entries may be objects `{ key, name?, servers?, tools?, rateLimit? }` (plain strings still mean full access). `servers` / `tools` are glob allow-lists (`tools` patterns containing `/` match `<serverId>/<tool>`); `rateLimit` gives the key its own bucket; `name` makes the client id `key:<name>`; `${VAR}` is expanded in object keys. JWTs carry scopes in the `mcp_servers` / `mcp_tools` claims. Enforced on REST (`/tools`, `/servers`, `/servers/:id` hide; `/tools/call`, `/servers/:id/reconnect` → `403`; auto-routing only among allowed servers; restricted keys see only their own `/requests`) and on `/mcp` (`tools/list` hides, `tools/call` → `-32003`, key rate limits). Hot reloadable: open `/mcp` sessions are notified, sessions of removed keys closed. Exports: `isServerInScope`, `isToolInScope`, `filterToolsByScope`, `scopeFromJwt`, types `AccessScope`, `ApiKeyConfig`.
+- **Downstream MCP endpoint** `POST/GET/DELETE /mcp`: the gateway is now an MCP server over Streamable HTTP (protocol `2025-06-18`, `2025-03-26` accepted). Sessions via `Mcp-Session-Id` (bound to the authenticated key / JWT subject, idle expiry, LRU eviction at `maxSessions`), `initialize`, `ping`, aggregated and paginated `tools/list`, `tools/call` routed upstream, `notifications/tools/list_changed` on the `GET` SSE stream whenever the aggregated list changes, and `notifications/cancelled` propagated to the upstream server. JSON-RPC batches are accepted. Reuses auth, the rate limiter (per `tools/call`), `maxConcurrency`, timeouts, metrics and the request log. Origin validation (`mcp.allowedOrigins`, default `corsOrigins`) against DNS rebinding.
+- `mcp` config block: `enabled`, `path`, `toolNaming` (`auto` — prefix `<serverId>__` only on name collisions — or `prefix`), `pageSize`, `sessionIdleTimeoutSeconds`, `maxSessions`, `allowedOrigins`, `instructions`. Everything except `enabled` / `path` hot reloads.
+- `McpProxy.request()` for arbitrary upstream methods and an optional `AbortSignal` on `callTool()` (`ERR_CANCELLED`).
+- Tool `title`, `outputSchema` and `annotations` are kept from upstream `tools/list` and exposed on `/api/v1/tools` and `/mcp`.
+- Request records carry `via: "rest" | "mcp"`.
+- Library exports: `McpEndpoint`, `buildToolIndex`, `prefixedName`, `DOWNSTREAM_PROTOCOL_VERSIONS`, `ERR_RATE_LIMITED`, types `McpEndpointConfig`, `ToolNaming`, `McpSessionSummary`; `Gateway#getMcpEndpoint()`.
+- Conformance tests with the official `@modelcontextprotocol/sdk` client (list, call, ping, `list_changed`, cancellation, session termination, auth).
+- CORS allows the `Mcp-Session-Id`, `MCP-Protocol-Version` and `Last-Event-ID` request headers and exposes `Mcp-Session-Id`.
+
+### Changed
+- Docker image is based on `node:22-alpine` (was 20) so the optional audit log works; it has a writable `/app/data` volume and OCI labels. The npm package still supports Node 20+.
+- README: npm badge points at `@winstonsayno/mcp-gateway`, CI badge, ghcr image name lowercased (`ghcr.io/harrisoncn/mcp-gateway`), library import uses the scoped package name, API-stability section.
+- `AuthConfig.apiKeys` is typed `Array<string | ApiKeyConfig>` (was `string[]`); existing configs are unchanged. `createAuthMiddleware()` returns an `AuthMiddleware` (a `RequestHandler` with an optional `resolveClient`).
+
 ## [0.4.0] - 2026-10-07
 
 ### Added

package/README.md

@@ -11,10 +11,11 @@ Route · Authenticate · Rate-limit · Monitor — all your [Model Context Proto
 [![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)
+[![npm version](https://img.shields.io/npm/v/@winstonsayno/mcp-gateway.svg)](https://www.npmjs.com/package/@winstonsayno/mcp-gateway)
+[![CI](https://github.com/HarrisonCN/mcp-gateway/actions/workflows/ci.yml/badge.svg)](https://github.com/HarrisonCN/mcp-gateway/actions/workflows/ci.yml)
+[![Docker](https://img.shields.io/badge/docker-ghcr.io-blue.svg)](https://github.com/HarrisonCN/mcp-gateway/pkgs/container/mcp-gateway)
 
-[English](#) · [中文](docs/README.zh-CN.md) · [Docs](docs/) · [Examples](examples/)
+[English](#) · [中文](docs/README.zh-CN.md) · [API reference](docs/api-reference.md) · [Configuration](docs/configuration.md) · [Deployment](docs/deployment.md) · [Examples](examples/)
 
 </div>
 
@@ -62,20 +63,26 @@ As [MCP](https://modelcontextprotocol.io) becomes the standard protocol for AI a
 ## Features
 
 - **Unified API endpoint** — one URL for all your MCP tools, auto-routed by tool name
+- **MCP endpoint for clients** — `/mcp` speaks MCP Streamable HTTP (2025-06-18 / 2025-03-26), so Claude Code, Cursor or any MCP client sees every upstream tool through one server, with the same auth, limits and metrics
 - **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
+- **Per-key scopes** — restrict an API key (or a JWT via claims) to some servers / tools and give it its own rate limit; enforced on REST and `/mcp`
 - **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
+- **Resources & prompts** — `resources/*` and `prompts/*` from every server, aggregated on REST and `/mcp`
+- **Persistent audit log** — optional SQLite history (built-in `node:sqlite`, no dependency) queryable via `GET /api/v1/requests` and the dashboard
 - **Tool filtering** — per-server `tools.allow` / `tools.deny` glob patterns hide tools you don't want exposed (and block calls to them)
 - **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
+- **Client libraries** — a dependency-free TypeScript client ([`clients/js`](clients/js), browser + Node) and a Kotlin/JVM/Android client ([`clients/kotlin`](clients/kotlin))
+- **LLM tool schemas** — `GET /api/v1/tools?format=openai|anthropic` returns ready-to-use function-calling definitions
 
 ## Quick Start
 
@@ -143,6 +150,65 @@ curl -X POST http://localhost:4000/api/v1/tools/call \
   -d '{"tool": "create_issue", "server": "github", "arguments": {"title": "Bug report", "body": "..."}}'
 ```
 
+## Use the gateway as an MCP server (`/mcp`)
+
+The gateway is itself an MCP server: `http://<host>:4000/mcp` implements the
+[Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports)
+(protocol `2025-06-18`, `2025-03-26` accepted). Clients get one aggregated, filtered tool list; calls are
+routed to the right upstream server with the gateway's auth, rate limit, `maxConcurrency`, timeouts,
+metrics and request log.
+
+**Claude Code**
+
+```bash
+claude mcp add --transport http gateway http://localhost:4000/mcp \
+  --header "Authorization: Bearer your-secret-key"
+```
+
+**Cursor** (`~/.cursor/mcp.json` or `.cursor/mcp.json`)
+
+```json
+{
+  "mcpServers": {
+    "gateway": {
+      "url": "http://localhost:4000/mcp",
+      "headers": { "Authorization": "Bearer your-secret-key" }
+    }
+  }
+}
+```
+
+**Clients that only speak stdio** (e.g. older Claude Desktop builds) can bridge with
+[`mcp-remote`](https://www.npmjs.com/package/mcp-remote):
+`npx mcp-remote http://localhost:4000/mcp --header "Authorization: Bearer your-secret-key"`.
+
+**Any SDK client**
+
+```ts
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+
+const client = new Client({ name: 'my-app', version: '1.0.0' });
+await client.connect(new StreamableHTTPClientTransport(new URL('http://localhost:4000/mcp'), {
+  requestInit: { headers: { Authorization: 'Bearer your-secret-key' } },
+}));
+const { tools } = await client.listTools();
+```
+
+What the endpoint does:
+
+| | |
+|---|---|
+| `POST /mcp` | JSON-RPC: `initialize`, `ping`, `tools/list` (paginated), `tools/call`, `resources/list`, `resources/templates/list`, `resources/read`, `prompts/list`, `prompts/get`, notifications (incl. `notifications/cancelled`). Batches are accepted. Responses are `application/json`. |
+| `GET /mcp` | SSE stream for server→client notifications: `notifications/tools/list_changed`, `notifications/resources/list_changed` and `notifications/prompts/list_changed` are sent when the aggregated list a session sees changes (a server announces changes, connects, is removed by hot reload, …). |
+| Resources & prompts | Resource URIs are passed through unchanged; when two servers list the same URI the lowest server id wins. `resources/read` is routed by exact URI, then by resource template, then to the only server with resources. Prompt names follow `toolNaming` like tools. `resources/subscribe` is not offered. |
+| `DELETE /mcp` | Ends the session. |
+| Sessions | `initialize` returns `Mcp-Session-Id`; later requests must send it (`400` if missing, `404` if unknown or expired). A session is bound to the API key / JWT subject that created it. Idle sessions expire after `mcp.sessionIdleTimeoutSeconds`. |
+| Tool names | `toolNaming: auto` (default) keeps a tool's name unless two servers expose the same name; then every copy becomes `<serverId>__<tool>`. `prefix` always uses `<serverId>__<tool>`. Ordering is deterministic (server id, then tool name). In `auto` mode the prefixed form is also accepted by `tools/call`. |
+| Errors | Unknown tool / bad params → JSON-RPC `-32602`; rate limit → `-32029` with `data.retryAfter`; server offline or timed out → a normal result with `isError: true` (so the model sees it); upstream JSON-RPC errors are forwarded unchanged; cancelled → `-32800`. |
+| Cancellation | `notifications/cancelled` (or the client dropping the HTTP request) cancels the upstream call, which receives its own `notifications/cancelled`. |
+| Security | Same `auth` as the REST API (`Authorization: Bearer …` or `X-API-Key`). Requests with an `Origin` header are rejected (`403`) unless it matches `mcp.allowedOrigins` (default: `corsOrigins`) — set this when the gateway listens on a reachable address. |
+
 ## API Reference
 
 | Method | Path | Description |
@@ -150,13 +216,19 @@ curl -X POST http://localhost:4000/api/v1/tools/call \
 | `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=`) |
+| `GET` | `/api/v1/tools` | List all tools (filterable by `?server=` or `?tag=`; `?format=openai\|openai-responses\|anthropic` for LLM schemas) |
 | `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/health/ready` | Readiness probe — always public; `200` when servers are ready, else `503` (`?min=N`) |
 | `GET` | `/api/v1/metrics` | Aggregated metrics (JSON or Prometheus) |
-| `GET` | `/api/v1/requests` | Recent request log (`?limit=`, max 500) |
+| `GET` | `/api/v1/resources` | Resources of all servers (`?server=`), duplicate URIs collapsed |
+| `GET` | `/api/v1/resources/templates` | Resource templates (`?server=`) |
+| `POST` | `/api/v1/resources/read` | Read a resource: `{"uri": "...", "server"?: "..."}` |
+| `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`) |
+| `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`
 to require auth for them too (`/health/live` and `/health/ready` always stay public for Docker / Kubernetes probes).
@@ -164,13 +236,42 @@ 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`.
 
+### LLM tool schemas
+
+`GET /api/v1/tools?format=openai` (Chat Completions), `openai-responses` (Responses API) or `anthropic` (Messages API)
+returns the tools the caller may use as function-calling definitions, plus a `mapping` from each LLM tool
+name back to the gateway server and tool:
+
+```json
+{
+  "format": "anthropic",
+  "tools": [{ "name": "github__create_issue", "description": "…", "input_schema": { "type": "object", "properties": { … } } }],
+  "mapping": { "github__create_issue": { "server": "github", "tool": "create_issue" } },
+  "total": 1
+}
+```
+
+Pass `tools` straight to the provider; when the model calls a tool, look it up in `mapping` and
+`POST /api/v1/tools/call` with that `server` / `tool` (the clients' `callLlmTool()` does this).
+Names follow `mcp.toolNaming`, are sanitised to `^[a-zA-Z0-9_-]{1,64}$` and de-duplicated; `$schema` is stripped and
+`parameters` is always an object schema. Scopes and `?server=` / `?tag=` filters apply.
+
+### Client libraries
+
+| | |
+|---|---|
+| **TypeScript / JavaScript** — [`clients/js`](clients/js) | `@winstonsayno/mcp-gateway-client`: zero dependencies, `fetch`-based (browser, Node 18+, Deno, Bun, React Native), typed `health`, `servers`, `listTools`, `toolSchemas`, `callTool`, `callLlmTool`, plus a small MCP-over-`/mcp` session helper |
+| **Kotlin / JVM / Android** — [`clients/kotlin`](clients/kotlin) | OkHttp + kotlinx.serialization, Java 11 bytecode; same API surface, `McpSession` for `/mcp` |
+
+Both are in this repository and not yet published to npm / Maven Central.
+
 `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 |
-| `403` | The tool is hidden by the server's `tools` filter (also when `"server"` is passed explicitly) |
+| `403` | The tool is hidden by the server's `tools` filter (also when `"server"` is passed explicitly), or outside the caller's scope |
 | `404` | Unknown tool or server |
 | `409` | Tool name is exposed by several servers — pass `"server"` to choose |
 | `429` | Rate limited (see `Retry-After`) |
@@ -188,7 +289,12 @@ 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"
+    - "your-secret-key"       # full access
+    - key: "${APP_KEY}"       # scoped key (see "Per-key scopes")
+      name: app
+      servers: ["github"]
+      tools: ["read_*"]
+      rateLimit: { limit: 30, windowSeconds: 60 }
   protect:
     health: false             # true → /api/v1/health requires auth
     metrics: false            # true → /api/v1/metrics requires auth (configure your scraper)
@@ -218,6 +324,21 @@ monitor:
 corsOrigins:
   - "https://your-app.com"
 
+audit:                        # persistent request history (SQLite, Node 22.5+; default off)
+  enabled: false
+  path: mcp-gateway-audit.db
+  retentionDays: 30           # 0 = keep forever
+
+mcp:                          # downstream MCP endpoint (Streamable HTTP)
+  enabled: true               # restart required to change
+  path: /mcp                  # restart required to change; not "/" or under /api, /dashboard
+  toolNaming: auto            # auto | prefix  ("<serverId>__<tool>")
+  pageSize: 500               # tools per tools/list page
+  sessionIdleTimeoutSeconds: 1800
+  maxSessions: 1000           # least recently used idle session is evicted beyond this
+  # allowedOrigins: ["https://your-app.com"]   # browser origins allowed on /mcp (default: corsOrigins)
+  # instructions: "Tools for the ACME workspace"  # returned from initialize
+
 servers:
   - id: my-server             # Unique identifier
     name: My Server           # Display name
@@ -265,10 +386,80 @@ With `mcp-gateway start` the config file is watched (disable with `--no-watch`).
 | `auth` (strategy, keys, JWT secret, `protect`) | `monitor.retentionHours` |
 | `rateLimit` (counters reset when it changes) | `healthCheckIntervalMs` |
 | `corsOrigins`, `monitor.requestLog`, `monitor.prometheus` | `dashboard` |
-| `reconnect`, `logLevel` | |
+| `reconnect`, `logLevel` | `mcp.enabled`, `mcp.path`, `audit` |
+| `mcp.toolNaming`, `mcp.pageSize`, session limits, `mcp.allowedOrigins` | |
 
 An invalid file is rejected and the running config is kept. `MCP_GATEWAY_*` env overrides keep precedence.
 
+### Per-key scopes
+
+Give each app its own key and only the tools it needs. Plain string keys keep full access;
+object entries can be restricted (all fields except `key` are optional):
+
+```yaml
+auth:
+  strategy: api-key
+  apiKeys:
+    - "admin-key"                       # unrestricted
+    - key: ${AURA_GATEWAY_KEY}          # ${VAR} is expanded in object keys
+      name: aura                        # client id "key:aura" in logs, metrics and sessions (unique)
+      servers: ["github", "fs-*"]       # server id globs
+      tools: ["read_*", "github/create_issue"]   # tool globs; "server/tool" when the pattern has a "/"
+      rateLimit: { limit: 30, windowSeconds: 60 } # own bucket instead of the global rateLimit
+```
+
+- A tool must pass the server's own `tools` filter **and** the key's `servers` **and** `tools` lists.
+  An absent list means no restriction; an empty list allows nothing.
+- **Discovery hides** what a key may not use: `GET /tools`, `GET /servers`, `GET /servers/:id` (→ `404`), `/mcp` `tools/list`.
+- **Calls are refused**: `POST /tools/call` and `POST /servers/:id/reconnect` → `403`; `/mcp` `tools/call` → JSON-RPC error `-32003`.
+  Auto-routing only considers servers the key may use, so a name that collides elsewhere can still be called without `"server"`.
+- On `/mcp`, collision prefixes are computed from what the key can see (a key scoped to one server sees bare names).
+- Restricted keys only see their own entries in `GET /requests`.
+- **JWT**: put globs in the `mcp_servers` / `mcp_tools` claims (array, or a space/comma-separated string), e.g.
+  `{"sub": "user-1", "mcp_servers": ["github"], "mcp_tools": "read_* github/create_issue"}`. A malformed claim allows nothing.
+- Hot reloadable: changing scopes applies to the next request; open `/mcp` sessions get `notifications/tools/list_changed`,
+  and sessions of removed keys are closed.
+
+### Resources & prompts
+
+Servers that announce the `resources` / `prompts` capabilities have their resources, resource templates and
+prompts listed at connect time (and refreshed on `notifications/*/list_changed`). They are available on REST
+(`/api/v1/resources`, `/resources/templates`, `/resources/read`, `/prompts`, `/prompts/get`) and on `/mcp`.
+Reads and gets are forwarded live with the server's `timeout`, counted against the rate limit and recorded in
+metrics / history with `kind: "resource"` or `"prompt"`. Key scopes apply by **server** (`servers` globs);
+`tools` globs and `servers[].tools` filters only concern tools.
+
+```bash
+curl -s localhost:4000/api/v1/resources
+curl -s -X POST localhost:4000/api/v1/resources/read -H 'content-type: application/json' -d '{"uri":"file:///notes/todo.md"}'
+curl -s -X POST localhost:4000/api/v1/prompts/get -H 'content-type: application/json' \
+  -d '{"name":"review-code","server":"github","arguments":{"pr":"42"}}'
+```
+
+### Persistent audit log
+
+By default request history lives in memory (`monitor.retentionHours`). Enable the audit log to keep it in SQLite
+across restarts:
+
+```yaml
+audit:
+  enabled: true
+  path: ./data/mcp-gateway-audit.db   # default mcp-gateway-audit.db (WAL mode)
+  retentionDays: 30                   # pruned hourly; 0 = keep forever
+```
+
+- Uses Node's built-in [`node:sqlite`](https://nodejs.org/api/sqlite.html) (**Node 22.5+**): no extra dependency and
+  nothing native to compile. On Node 20 the gateway refuses to start with `audit.enabled: true` and says why. Node may
+  print an `ExperimentalWarning` for `node:sqlite`.
+- Only metadata is stored: time, server, tool / URI / prompt, kind, duration, success, error message, client id, `via`
+  (`rest` / `mcp`). Arguments and results are never stored.
+- `GET /api/v1/requests` then reads from the database (`"source": "audit"`) and supports filters
+  (`server`, `tool`, `client`, `success=true|false`, `via=rest|mcp`, `kind=tool|resource|prompt`, `since` / `until` as ISO
+  or epoch ms) and paging (`nextCursor` → `?cursor=`). Restricted keys only ever see their own records.
+  The dashboard's *Request History* panel has the same filters and a *Load older* button.
+- Library users can plug in any store: `metrics.setAuditStore(myStore)` with the `AuditStore` interface.
+- Changing `audit` requires a restart.
+
 ### Tool filtering
 
 Expose only part of a server's tools — e.g. make a filesystem server read-only, or drop tools that
@@ -310,7 +501,7 @@ Prometheus series added: `mcp_gateway_server_up`, `mcp_gateway_server_status{sta
 docker run -p 4000:4000 \
   -v $(pwd)/mcp-gateway.yml:/app/mcp-gateway.yml \
   -e GITHUB_TOKEN=ghp_... \
-  ghcr.io/harrisonCN/mcp-gateway:latest
+  ghcr.io/harrisoncn/mcp-gateway:latest
 
 # Or with Docker Compose (gateway + Prometheus; see examples/docker)
 cd examples/docker
@@ -355,7 +546,7 @@ to stop serving it.
 ## Embed as a Library
 
 ```typescript
-import { Gateway, loadConfig } from 'mcp-gateway';
+import { Gateway, loadConfig } from '@winstonsayno/mcp-gateway';
 
 const config = await loadConfig('./mcp-gateway.yml');
 const gateway = new Gateway(config);
@@ -367,16 +558,18 @@ await gateway.start();
 process.on('SIGTERM', () => gateway.stop());
 ```
 
-## What's New (unreleased)
+## What's New in v1.0
 
 | 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 |
+| **Stable API** | Semver from 1.0: `/api/v1`, `/mcp`, config keys, CLI and root exports are stable (see [stability](#api-stability)) |
+| **Docs** | [API reference](docs/api-reference.md), [configuration reference](docs/configuration.md), [deployment guide](docs/deployment.md) (Docker, Kubernetes, reverse proxy) |
+| **Container image** | Multi-arch `ghcr.io/harrisoncn/mcp-gateway` built on every release (Node 22) |
+| **Resources & prompts** | `resources/list`, `resources/templates/list`, `resources/read`, `prompts/list`, `prompts/get` aggregated on REST and `/mcp`, with list-changed notifications and scopes |
+| **Audit log** | Optional persistent request history in SQLite (`node:sqlite`), filterable / pageable `GET /api/v1/requests`, dashboard history |
+| **Clients & LLM schemas** | TypeScript client (`clients/js`), Kotlin client (`clients/kotlin`), `GET /api/v1/tools?format=openai\|openai-responses\|anthropic` |
+| **Per-key scopes** | API keys can carry `servers` / `tools` globs and their own `rateLimit`; JWTs carry `mcp_servers` / `mcp_tools` claims. Enforced on REST and `/mcp`, hot reloadable |
+| **`/mcp` endpoint** | The gateway is an MCP server (Streamable HTTP, 2025-06-18): sessions, aggregated + paginated `tools/list`, deterministic collision naming, routed `tools/call`, `list_changed` notifications, cancellation |
 
 ## What's New in v0.2.0
 
@@ -390,6 +583,14 @@ process.on('SIGTERM', () => gateway.stop());
 | **Web Dashboard** | Live monitoring UI at `/dashboard` |
 | **4 Bug Fixes** | Concurrency, id collision, handle leaks, timeouts |
 
+## API stability
+
+mcp-gateway follows [Semantic Versioning](https://semver.org/) since **1.0.0**. Within 1.x the REST API under
+`/api/v1`, the `/mcp` endpoint behaviour, configuration keys, CLI commands / flags, root library exports and Prometheus
+metric names only change in backward-compatible ways (new fields, endpoints and options may be added — ignore
+unknown fields). Deep imports, log format, the dashboard and the audit database schema are not covered. Details:
+[docs/api-reference.md#stability-and-versioning](docs/api-reference.md#stability-and-versioning).
+
 ## Roadmap
 
 | Feature | Status |
@@ -401,10 +602,15 @@ process.on('SIGTERM', () => gateway.stop());
 | Automatic reconnect with backoff | ✅ Done |
 | Config hot reload | ✅ Done (v0.2.0) |
 | Web dashboard UI | ✅ Done (v0.2.0) |
+| Downstream MCP endpoint (`/mcp`) | ✅ Done (v1.0) |
+| Per-key scopes and limits | ✅ Done (v1.0) |
+| JS / Kotlin clients, OpenAI / Anthropic tool schemas | ✅ Done (v1.0) |
+| Resources & prompts passthrough, persistent audit log | ✅ Done (v1.0) |
+| Stable API, docs, container image | ✅ Done (v1.0) |
 | Redis-backed rate limiting | 📋 Planned |
 | OAuth2 / OIDC auth | 📋 Planned |
-| Tool-level access control (RBAC) | 📋 Planned |
-| Request replay & debugging | 📋 Planned |
+| Tool-level access control | ✅ Done via per-key scopes (v0.6) |
+| Request replay & debugging | 📋 Planned (history is available via the audit log) |
 | Multi-tenant mode | 📋 Planned |
 | OpenTelemetry tracing | 📋 Planned |
 

package/dashboard/index.html

@@ -94,6 +94,13 @@
     .method { font-size: 10px; font-weight: 700; padding: 2px 6px; border-radius: 4px; font-family: monospace; }
     .method.post { background: rgba(63,185,80,.15); color: var(--green); }
     .method.get { background: rgba(88,166,255,.15); color: var(--accent); }
+    .filters { display: flex; flex-wrap: wrap; gap: 8px; align-items: center; margin-bottom: 10px; font-size: 12px; color: var(--muted); }
+    .filters input, .filters select { background: var(--surface, #161b22); color: inherit; border: 1px solid var(--border, #30363d); border-radius: 6px; padding: 4px 8px; font-size: 12px; }
+    .filters .source { margin-left: auto; }
+    .filters button, .more { background: var(--surface); border: 1px solid var(--border); color: var(--text); padding: 4px 12px; border-radius: 6px; cursor: pointer; font-size: 12px; }
+    .filters button:hover, .more:hover { border-color: var(--accent); color: var(--accent); }
+    .more { display: block; margin: 10px auto 0; }
+    .more[hidden] { display: none; }
 
     /* ── Code ── */
     code { font-family: "SFMono-Regular", Consolas, monospace; font-size: 12px; color: var(--purple); }
@@ -189,15 +196,25 @@
     </div>
   </div>
 
-  <!-- Recent Requests -->
+  <!-- Request history -->
   <div class="section">
-    <div class="section-title">Recent Requests</div>
+    <div class="section-title">Request History</div>
+    <form class="filters" id="req-filters" onsubmit="event.preventDefault(); loadRequests(true)">
+      <input id="f-server" placeholder="server id" aria-label="Filter by server" size="12" />
+      <input id="f-tool" placeholder="tool / URI / prompt" aria-label="Filter by tool" size="16" />
+      <select id="f-status" aria-label="Filter by status"><option value="">any status</option><option value="true">ok</option><option value="false">error</option></select>
+      <select id="f-via" aria-label="Filter by interface"><option value="">REST + MCP</option><option value="rest">REST</option><option value="mcp">MCP</option></select>
+      <select id="f-since" aria-label="Time range"><option value="">all time</option><option value="3600000">last hour</option><option value="86400000">last 24 h</option><option value="604800000">last 7 days</option></select>
+      <button class="refresh-btn" type="submit">Apply</button>
+      <span class="source" id="req-source"></span>
+    </form>
     <div class="table-wrap">
       <table>
-        <thead><tr><th>Time</th><th>Method</th><th>Tool</th><th>Server</th><th>Duration</th><th>Status</th></tr></thead>
-        <tbody id="requests-tbody"><tr><td colspan="6" class="loader"><span class="spinner"></span></td></tr></tbody>
+        <thead><tr><th>Time</th><th>Via</th><th>Tool / resource / prompt</th><th>Server</th><th>Client</th><th>Duration</th><th>Status</th></tr></thead>
+        <tbody id="requests-tbody"><tr><td colspan="7" class="loader"><span class="spinner"></span></td></tr></tbody>
       </table>
     </div>
+    <button class="refresh-btn more" id="req-more" type="button" hidden onclick="loadRequests(false)">Load older</button>
   </div>
 </main>
 
@@ -373,36 +390,76 @@
     } catch { /* shown via other panels */ }
   }
 
-  async function loadRequests() {
+  // History comes from the persistent audit log when it is enabled
+  // (audit.enabled), otherwise from the in-memory log; paged with a cursor.
+  let reqCursor;
+  let reqPaged = false;
+
+  function requestQuery() {
+    const q = new URLSearchParams({ limit: '25' });
+    const v = (id) => document.getElementById(id).value.trim();
+    if (v('f-server')) q.set('server', v('f-server'));
+    if (v('f-tool')) q.set('tool', v('f-tool'));
+    if (v('f-status')) q.set('success', v('f-status'));
+    if (v('f-via')) q.set('via', v('f-via'));
+    if (v('f-since')) q.set('since', String(Date.now() - Number(v('f-since'))));
+    return q;
+  }
+
+  function requestRow(r) {
+    const color = r.success ? 'green' : 'red';
+    const err = r.errorMessage ? ` title="${esc(r.errorMessage)}"` : '';
+    const kind = r.kind && r.kind !== 'tool' ? `<span style="color:var(--muted)">${esc(r.kind)}</span> ` : '';
+    const via = (r.via ?? 'rest') === 'mcp' ? '<span class="method get">MCP</span>' : '<span class="method post">REST</span>';
+    const t = new Date(r.timestamp);
+    const today = t.toDateString() === new Date().toDateString();
+    return `<tr>
+      <td style="color:var(--muted)" title="${esc(t.toISOString())}">${esc(today ? t.toLocaleTimeString() : t.toLocaleString())}</td>
+      <td>${via}</td>
+      <td>${kind}<code>${esc(r.toolName ?? '—')}</code></td>
+      <td>${esc(r.serverId ?? '—')}</td>
+      <td style="color:var(--muted)">${esc(r.clientId ?? '—')}</td>
+      <td>${fmtDuration(r.durationMs)}</td>
+      <td style="color:var(--${color})"${err}>${r.success ? 'ok' : 'error'}</td>
+    </tr>`;
+  }
+
+  async function loadRequests(reset = true) {
     const tbody = document.getElementById('requests-tbody');
+    const more = document.getElementById('req-more');
+    if (reset) {
+      reqCursor = undefined;
+      reqPaged = false;
+    } else {
+      reqPaged = true;
+    }
     try {
-      const data = await fetchJSON('/api/v1/requests?limit=20');
+      const q = requestQuery();
+      if (!reset && reqCursor) q.set('cursor', reqCursor);
+      const data = await fetchJSON('/api/v1/requests?' + q.toString());
       const reqs = data.requests ?? [];
-      if (!reqs.length) {
-        tbody.innerHTML = '<tr><td colspan="6" class="empty">No requests yet</td></tr>';
+      document.getElementById('req-source').textContent =
+        data.source === 'audit' ? 'source: persistent audit log' : data.source === 'memory' ? 'source: in-memory (since start)' : '';
+      reqCursor = data.nextCursor;
+      more.hidden = !reqCursor;
+      if (reset && !reqs.length) {
+        tbody.innerHTML = '<tr><td colspan="7" class="empty">No requests</td></tr>';
         return;
       }
-      tbody.innerHTML = reqs.map(r => {
-        const color = r.success ? 'green' : 'red';
-        const err = r.errorMessage ? ` title="${esc(r.errorMessage)}"` : '';
-        return `<tr>
-          <td style="color:var(--muted)">${esc(new Date(r.timestamp).toLocaleTimeString())}</td>
-          <td><span class="method post">CALL</span></td>
-          <td><code>${esc(r.toolName ?? '—')}</code></td>
-          <td>${esc(r.serverId ?? '—')}</td>
-          <td>${fmtDuration(r.durationMs)}</td>
-          <td style="color:var(--${color})"${err}>${r.success ? 'ok' : 'error'}</td>
-        </tr>`;
-      }).join('');
+      const html = reqs.map(requestRow).join('');
+      if (reset) tbody.innerHTML = html;
+      else tbody.insertAdjacentHTML('beforeend', html);
     } catch (e) {
-      tbody.innerHTML = `<tr><td colspan="6" class="empty">${e instanceof AuthError ? 'API key required' : 'Failed to load requests'}</td></tr>`;
+      more.hidden = true;
+      tbody.innerHTML = `<tr><td colspan="7" class="empty">${e instanceof AuthError ? 'API key required' : 'Failed to load requests'}</td></tr>`;
     }
   }
 
   async function loadAll() {
     authMissing = false;
     await loadMetrics(); // tool call counts feed the tools table
-    await Promise.allSettled([loadHealth(), loadServers(), loadTools(), loadRequests()]);
+    // Don't throw away older pages the user loaded on auto-refresh.
+    await Promise.allSettled([loadHealth(), loadServers(), loadTools(), reqPaged ? Promise.resolve() : loadRequests(true)]);
     notice.classList.toggle('show', authMissing);
     keyInput.classList.toggle('needed', authMissing);
   }

package/dist/auth/middleware.d.ts

@@ -12,13 +12,32 @@
  *    /requests endpoint, and keys sharing a prefix shared a rate-limit bucket).
  */
 import type { Request, RequestHandler } from 'express';
-import type { AuthConfig } from '../utils/types.js';
+import type { ApiKeyConfig, AuthConfig } from '../utils/types.js';
+import { type AccessScope } from './scopes.js';
 export type AuthedRequest = Request & {
     clientId?: string;
     jwtPayload?: unknown;
+    /** Servers / tools / rate limit this client is restricted to (absent = unrestricted). */
+    scope?: AccessScope;
 };
-export declare function createAuthMiddleware(config?: AuthConfig): RequestHandler;
+/** An auth middleware that can also look up the current scope of a known client id (api keys). */
+export type AuthMiddleware = RequestHandler & {
+    /**
+     * Current scope for `clientId`: `{ known: false }` when no configured key
+     * produces that id any more. Undefined for strategies whose scopes travel
+     * with the credential (JWT).
+     */
+    resolveClient?: (clientId: string | undefined) => {
+        known: boolean;
+        scope?: AccessScope;
+    };
+};
+/** Normalise `auth.apiKeys` entries (plain strings or objects). */
+export declare function normalizeApiKeys(keys: AuthConfig['apiKeys']): ApiKeyConfig[];
+export declare function createAuthMiddleware(config?: AuthConfig): AuthMiddleware;
 export declare function fingerprint(key: string): string;
 /** Constant-time membership check against a pre-hashed key list. */
 export declare function matchesAnyKey(candidate: string, keyDigests: Buffer[]): boolean;
+/** Constant-time lookup: index of the matching key digest, or -1. */
+export declare function matchKeyIndex(candidate: string, keyDigests: Buffer[]): number;
 //# sourceMappingURL=middleware.d.ts.map

package/dist/auth/middleware.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../src/auth/middleware.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,OAAO,EAA0B,cAAc,EAAE,MAAM,SAAS,CAAC;AAE/E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAGpD,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAIlF,wBAAgB,oBAAoB,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,cAAc,CA2BxE;AAMD,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED,oEAAoE;AACpE,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,OAAO,CAQ9E"}
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../src/auth/middleware.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,OAAO,EAA0B,cAAc,EAAE,MAAM,SAAS,CAAC;AAE/E,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAElE,OAAO,EAAgB,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAE7D,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG;IACpC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,yFAAyF;IACzF,KAAK,CAAC,EAAE,WAAW,CAAC;CACrB,CAAC;AAEF,kGAAkG;AAClG,MAAM,MAAM,cAAc,GAAG,cAAc,GAAG;IAC5C;;;;OAIG;IACH,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,KAAK;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,WAAW,CAAA;KAAE,CAAC;CAC3F,CAAC;AAEF,mEAAmE;AACnE,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,UAAU,CAAC,SAAS,CAAC,GAAG,YAAY,EAAE,CAI5E;AAaD,wBAAgB,oBAAoB,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,cAAc,CAmCxE;AAMD,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED,oEAAoE;AACpE,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,OAAO,CAE9E;AAED,qEAAqE;AACrE,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,MAAM,CAQ7E"}