context-saver-mcp 0.0.0-stage → 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [1.0.1] — 2026-11-03
+
+Patch release — hardening found by the CI matrix on real GitHub runners (every fix demonstrated with a failing test first).
+
+### Fixed
+- **Windows / all platforms**: transport-level upstream failures (`McpError` `ConnectionClosed`/`RequestTimeout` — e.g. an upstream that dies before the MCP handshake) are now normalized into the gateway's JSON error envelope instead of surfacing as raw protocol text.
+- **Node 18**: shimmed `globalThis.crypto` (WebCrypto is only default-global since Node 19) — required by the SDK's Streamable HTTP core for SSE stream ids; without it every HTTP-transport POST failed on Node 18 with `ReferenceError: crypto is not defined`.
+- **Cross-version CI**: `npm test` now enumerates test files itself (`tests/run-all.mjs`) — `node --test` glob expansion is a Node-22+ feature, so the glob form broke on Node 18/20 (and cmd.exe never expands globs).
+- **Release workflow**: every job now carries an explicit version-tag guard so Dependabot branch pushes that modify the workflow file can no longer create phantom red runs, and a manual dispatch from a branch can never create a GitHub Release.
+
+## [1.0.0] — 2026-11-03
+
+First public release. One gateway connection instead of dozens; lazy tool schemas kill the 15k–20k token upfront burn.
+
+### Added
+- **Single-file gateway** (`context-saver-mcp.js`): multiplexes stdio, Streamable HTTP and legacy SSE upstream MCP servers behind 8 fixed meta-tools (`list_servers`, `list_tools`, `search_tools`, `suggest_tools`, `get_tool_schema`, `call_tool`, `gateway_status`, `reload_config`) whose schema cost is constant (~1.3k tokens) regardless of upstream count.
+- **Lazy loading**: upstreams connect on first use; schemas are served per-turn (`suggest_tools` returns ranked matches with schemas in one response; `get_tool_schema` loads exactly one). Persisted catalog cache enables instant cold starts.
+- **Resilience**: per-upstream circuit breakers, call/connect timeouts, one reconnect-and-replay on transport death, normalized errors, `did you mean` hints, hot config reload (`reload_config` / SIGHUP) that keeps unchanged connections.
+- **Transports**: stdio (default) and Streamable HTTP + SSE with stateful sessions, idle sweeping, DELETE termination, CORS, `/health`.
+- **Auth**: `none` / `apikey` (constant-time) / built-in **OAuth 2.1 authorization server** (PKCE S256 mandatory, single-use codes, rotating refresh tokens, RFC 8414/9728 discovery, `resource_metadata` WWW-Authenticate, dynamic client registration, popup login page).
+- **Context accounting**: exact in-memory measurement of the gateway's own tools/list footprint, per-tool schema cost estimation, and a live savings report per session.
+- **Tests**: 26 unit, 11 integration (real SDK clients against real spawned upstream servers incl. an HTTP upstream), 5 HTTP/OAuth flow tests, 1 raw JSON-RPC smoke test — 42 passing.
+- **CI/CD**: GitHub Actions lint + test matrix (Node 18/20/22/24 on ubuntu + windows + macos), release workflow building multi-platform standalone binaries (bun compile: linux-x64, linux-arm64, darwin-x64, darwin-arm64, windows-x64) with SHA-256 checksums, plus the universal esbuild bundle.
+- **Docs**: README with architecture + sequence diagrams, real measured token-savings numbers, quick start, demo GIF rendered from a live session; SECURITY.md threat model; CONTRIBUTING.md section map + good-first-issues pipeline.
+
+### Fixed (all demonstrated with failing tests first — see commit history)
+- **bin**: launching through npm/npx symlinks silently exited 0 (invokedDirectly compared unresolved paths) — the shipped binary would have been a no-op for every npm install.
+- **security**: OAuth authorize page embedded query params unescaped into hidden input attributes (XSS); escaping used self-replacing no-op patterns.
+- **auth**: 401s lacked the `resource_metadata` WWW-Authenticate parameter MCP clients require for OAuth discovery.
+- **http**: gateway close hung forever on keep-alive sockets (HTTP suite took 200 s; now 0.46 s).
+- **cli**: bare boolean flags swallowed the following positional word (`--eager stray` → `eager: "stray"`).
+- **repo hygiene**: `.env` was committed to git and `.gitignore` was incomplete in the scaffold; dead placeholder file removed.

package/CONTRIBUTING.md

@@ -0,0 +1,75 @@
+# Contributing to The Context-Saver
+
+Thanks for wanting to help! The whole server is **one readable file** — [context-saver-mcp.js](context-saver-mcp.js) — organized into numbered sections. Read it top to bottom once and you've read the entire product. This guide maps sections → features → starter issues.
+
+## The 3-step loop
+
+```bash
+git clone https://github.com/Gatsuke/context-saver-mcp && cd context-saver-mcp
+npm install
+npm test          # 42 tests, ~20 s — everything must pass
+npm run lint       # eslint; no-console is a hard rule (stdout is the protocol channel in stdio mode)
+npm run smoke      # raw JSON-RPC wire check without the SDK
+```
+
+Node ≥ 18.19. No build step — the file you edit is the file that runs.
+
+## Codebase map (all in one file)
+
+| § | Section | Owns |
+|---|---------|------|
+| 1 | Logging & small utilities | stderr-only logger, `withTimeout`, `parseArgs` |
+| 2 | Token estimation | the context-accounting math |
+| 3 | Configuration | `servers.json` loading, validation, `${ENV}` expansion, globs |
+| 4 | Circuit breaker | per-upstream CLOSED → OPEN → HALF-OPEN state machine |
+| 5 | Relevance scoring | tokenizer, IDF index, `rankTools` (what `suggest_tools` uses) |
+| 6 | Upstream manager & catalog | lazy connection pool, retries, catalog cache, hot reload |
+| 7 | Gateway meta-tools | the 8 `registerTool` handlers the model calls |
+| 8 | OAuth 2.1 provider | PKCE, codes, tokens, login popup rendering |
+| 9 | HTTP transport | Streamable HTTP + SSE, sessions, idle sweeping |
+| 10 | Authenticator | `none` / `apikey` / `oauth` request checking |
+| 11 | stdio transport + CLI | arg parsing, startup, shutdown |
+
+Tests live in `tests/` (`unit/` pure functions, `integration/` real client ↔ real gateway ↔ real upstream servers, `http/` sockets + OAuth). Fixtures in `tests/fixtures/` are genuine SDK-based MCP servers.
+
+## Good first issues
+
+Issues labeled [`good first issue`](https://github.com/Gatsuke/context-saver-mcp/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) are pre-scoped to one section and come with a test hint. Current favorites:
+
+| Idea | Section | Test hint |
+|------|---------|-----------|
+| Pluggable `Scorer` interface (embeddings, BM25…) | §5 | unit: inject a stub scorer into `buildSearchIndex` |
+| `resources` / `prompts` passthrough | §6–7 | integration: new fixture server exposing a resource |
+| Persistent OAuth code/refresh store | §8 | unit: fake store behind the existing `Map` calls |
+| "Continue with GitHub" login option | §8–10 | http: stub the GitHub exchange endpoint |
+| Config schema for `defaults.callTimeoutMs` per-server inheritance | §3 | unit: `loadConfig` precedence cases |
+| OpenTelemetry-style call metrics | §6 | unit: counters on the `callTool` path |
+
+Rules for landing one:
+
+1. Comment on the issue so it's yours (48 h without a PR may re-open it for others)
+2. One issue = one PR = tests included (`"Only include issues that you can demonstrate with a failing test"` is how this repo's own audit trail works)
+3. Keep the server in one file — exports at the bottom are the test surface; everything you add should be sectioned like the above
+4. `npm test && npm run lint` green on Node 18 and 20+
+
+## Commit style
+
+This repo's history doubles as engineering documentation — look at `git log`: every bug fix explains *why the bug was likely written that way* before the fix. Keep that spirit:
+
+```
+fix(<area>): what changed and why
+
+Evidence: <failing test / log / repro>
+
+Why it was like this: <the human reason it slipped through>
+
+Fix: <approach>
+```
+
+## Reporting bugs
+
+Open an issue with: what you ran, what happened, what you expected, and the `gateway_status` output if the gateway is up. Reproductions with a failing test get fixed fastest — the maintainers' audit history treats tests as the primary evidence format.
+
+## Code of conduct
+
+Be kind. Ask questions. "I don't know" and "I was wrong" are respected answers here — the entire audit trail of this repo is the maintainers publicly documenting their own mistakes.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gatsuke
+
+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,289 @@
-# Temporary Holding Version
+<p align="center">
+  <img src="docs/banner.svg" alt="The Context-Saver — Multi-Server Multiplexer (Aggregator) MCP Server" width="720">
+</p>
 
-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.
+**The Context-Saver** is an **MCP Gateway/Router**: one Model Context Protocol server that multiplexes *all* of your other MCP servers, and hands the model **only the tool schemas it needs for the current turn**. Connect one thing. Get everything. Burn almost nothing.
+
+<div align="center">
+
+[![CI](https://github.com/Gatsuke/context-saver-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Gatsuke/context-saver-mcp/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/context-saver-mcp?color=cb3837&label=npm)](https://www.npmjs.com/package/context-saver-mcp)
+[![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+[![node](https://img.shields.io/badge/node-%E2%89%A518.19-339933)](package.json)
+[![MCP](https://img.shields.io/badge/Model%20Context%20Protocol-1.0-5e5ce6)](https://modelcontextprotocol.io)
+
+[Why](#the-pain-point) · [Quick Start (60 s)](#quick-start-in-60-seconds) · [How it works](#how-it-works) · [The 8 meta-tools](#the-8-meta-tools) · [Configuration](#configuration) · [Auth](#zero-friction-auth-oauth-popup-no-keys-in-json) · [Real numbers](#real-numbers-measured-not-marketing) · [FAQ](#faq)
+
+</div>
+
+---
+
+<p align="center">
+  <img src="docs/demo.gif" alt="Context-Saver demo: one gateway, lazy schema loading, 84% context saved" width="860">
+</p>
+<p align="sup"><i>Everything in this GIF is real output — captured from a live 92-tool session with the tests/fixtures servers.</i></p>
+
+---
+
+## The pain point
+
+You installed one MCP server and it was magic. Then you added a second. A third. Ten. Now, **before you type a single word**, every server has injected its full tool schema into your context window:
+
+- 10 servers ≈ **15,000–20,000 tokens burned per session** — you pay for it on *every* request, on *every* provider
+- the model sees **hundreds of tools at once** and starts *hallucinating workflows* that don't exist ("let me just use `db_migrate_hotfix`…")
+- your $200/mo API plan is quietly funding a 20k-token preamble you never asked for
+- add a server, and your *entire team's* prompts get worse
+
+This is one of the most common complaints on developer forums right now. The schemas aren't the problem — *loading them all upfront is*.
+
+## The idea
+
+Don't connect 10 servers to Claude Code / Cursor / whatever. Connect **one**: the Context-Saver gateway.
+
+```mermaid
+flowchart LR
+    subgraph before["❌ Direct: N servers"]
+        L1[Claude Code]
+        S1[Server A<br/>40 tools<br/>~4.7k tok]
+        S2[Server B<br/>25 tools<br/>~2.9k tok]
+        S3[Server C<br/>12 tools<br/>~1.4k tok]
+        SD[Dots ×7 more]
+        L1 -->|full schemas<br/>ALL AT ONCE| S1
+        L1 --> S2
+        L1 --> S3
+        L1 -.-> SD
+    end
+```
+
+```mermaid
+flowchart LR
+    subgraph after["✅ With the Context-Saver gateway"]
+        L2[Claude Code]
+        GW[Context-Saver Gateway<br/>8 fixed meta-tools<br/>~1.3k tok — CONSTANT]
+        U1[Server A]
+        U2[Server B]
+        U3[Server C]
+        U4[Server …]
+        L2 -->|one connection| GW
+        GW -.->|lazy: schemas only<br/>when actually needed| U1
+        GW -.-> U2
+        GW -.-> U3
+        GW -.-> U4
+    end
+```
+
+The gateway speaks MCP on one side and *is* an MCP client on the other. It indexes every upstream's tools, then serves the model a fixed menu of **8 meta-tools**. When a prompt arrives, `suggest_tools` ranks the catalog against the prompt and returns **the matched tools with their schemas in the same response** — so one cheap call replaces the entire upfront burn.
+
+**Why schemas stay fixed but the model still knows what exists:** the 8 meta-tools include a *compact catalog* (`list_tools`: name + one-line description, no schemas) and `search_tools`. The model can see what exists for ~2–3k tokens on a 90-tool setup, then load the exact schema it wants, when it wants it.
+
+## Quick Start in 60 Seconds
+
+**1 — Declare your upstream servers** (the only file you'll ever edit):
+
+```bash
+mkdir -p ~/.context-saver
+cp servers.example.json ~/.context-saver/servers.json
+$EDITOR ~/.context-saver/servers.json   # point at *your* servers
+```
+
+**2 — Connect your host to the gateway instead of N servers.**
+
+Local (stdio — Claude Code, Cursor, VS Code, any MCP host):
+
+```bash
+npx context-saver-mcp            # that's the whole server
+```
+
+```jsonc
+// e.g. Claude Code / claude_desktop_config.json
+{
+  "mcpServers": {
+    "context-saver": { "command": "npx", "args": ["-y", "context-saver-mcp"] }
+  }
+}
+```
+
+Remote (Streamable HTTP + SSE, zero-copy-paste-JSON-for-auth) — **step 3 only if you want the OAuth popup instead of a static key**:
+
+```bash
+npx context-saver-mcp --transport http --port 6480 --auth oauth
+# stderr prints:
+#   OAuth 2.1 (PKCE) ready: /oauth/authorize (popup) · /oauth/token
+#   listening on http://127.0.0.1:6480/mcp
+```
+
+Point any MCP host (or your whole team) at `http://<host>:6480/mcp`. No API keys in client JSON — the host pops the **login page** ([see it rendered](#zero-friction-auth-oauth-popup-no-keys-in-json)), the user enters the access code, PKCE completes, done.
+
+**That's the whole setup.** Ask your agent something and watch it call `suggest_tools` first instead of drowning in 92 schemas.
+
+## How it works
+
+### Architecture
+
+```mermaid
+flowchart TB
+    subgraph client["MCP host (Claude Code, Cursor, VS Code, …)"]
+        M[model]
+    end
+
+    subgraph gw["context-saver-mcp — the single-file gateway"]
+        direction TB
+        T1["stdio transport (local)"]
+        T2["Streamable HTTP + SSE (remote)<br/>sessions · idle sweeping · DELETE"]
+        AUTH["Auth: none | apikey | OAuth 2.1 + PKCE<br/>RFC 8414 / 9728 discovery · popup login"]
+        META["8 fixed meta-tools<br/>(~1.3k tokens, CONSTANT)"]
+        IDX["Catalog index + token accounting<br/>persisted cache (~/.context-saver/cache.json)"]
+        POOL["Lazy connection pool<br/>timeouts · 1 reconnect-replay<br/>circuit breakers · EMA latency"]
+    end
+
+    subgraph upstreams["Your existing MCP servers — unmodified"]
+        U1["stdio<br/>npx … / uvx …"]
+        U2["Streamable HTTP"]
+        U3["legacy SSE"]
+    end
+
+    M --> T1
+    M --> T2
+    T2 --> AUTH
+    T1 --> META
+    T2 --> META
+    META --> IDX
+    META --> POOL
+    POOL --> U1
+    POOL --> U2
+    POOL --> U3
+```
+
+### One turn, end to end
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant U as You
+    participant M as Model
+    participant G as Context-Saver gateway
+    participant W as Upstream (e.g. weather)
+
+    U->>M: "What's the weather forecast for Kuala Lumpur tomorrow?"
+    M->>G: suggest_tools { prompt }
+    Note over G: scores the 92-tool catalog<br/>against the prompt (IDF-weighted)
+    G-->>M: matches + schemas of the top tools<br/>272 tokens — the ONLY schemas loaded
+    M->>G: call_tool { server: "weather", tool: "get_forecast", arguments }
+    G->>W: MCP tools/call (lazy-dials if idle)
+    W-->>G: result
+    G-->>M: result (passed through, errors normalized)
+    Note over M: total context cost this turn: gateway 1.3k + 272<br/>direct-connect would have burned 8.3k
+```
+
+## The 8 meta-tools
+
+| Tool | What it does | Token cost |
+|---|---|---|
+| `list_servers` | Upstream registry + health + circuit state | tiny, fixed |
+| `list_tools` | **Compact catalog** — names + one-liners, *no schemas* | ~30 tok per 10 tools |
+| `search_tools` | Keyword search with reasons and per-tool schema cost | tiny |
+| `suggest_tools` | **The core trick**: prompt → ranked matches **with schemas in one response** | ~200–300 tok |
+| `get_tool_schema` | Load exactly one full JSON schema | the schema, only when needed |
+| `call_tool` | Execute on the upstream (timeout, reconnect, breaker) | passthrough |
+| `gateway_status` | Health + the live **context-savings report** | tiny |
+| `reload_config` | Hot-reload `servers.json` without a restart | tiny |
+
+Fixed menu. The footprint **never grows** as you add upstreams — that's the whole point. (The `instructions` shipped to the host model teaches it this workflow.)
+
+## Configuration
+
+One file, searched in this order: `--config <path>` → `CS_CONFIG` → `~/.context-saver/servers.json` → `./servers.json`. See [`servers.example.json`](servers.example.json) and the machine-checked [`docs/config-schema.schema.json`](docs/config-schema.schema.json).
+
+```jsonc
+{
+  "defaults": { "callTimeoutMs": 60000, "breakerThreshold": 3 },
+  "servers": [
+    { "name": "github",     "type": "http",  "url": "https://mcp.github.com/mcp",
+      "headers": { "authorization": "Bearer ${GITHUB_MCP_TOKEN}" } },   // ${ENV} expanded — no secrets in the file
+    { "name": "filesystem", "type": "stdio", "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "~/projects"],
+      "exclude": ["write_*"] },                                          // glob tool filtering
+    { "name": "sqlite",     "type": "stdio", "command": "uvx",
+      "args": ["mcp-server-sqlite", "--db-path", "~/data/app.db"] },
+    { "name": "legacy",      "type": "sse",  "url": "http://10.0.0.4:8901/sse", "disabled": true }
+  ]
+}
+```
+
+Every upstream gets: per-call timeout (default 60 s), connect timeout (15 s), one automatic reconnect+replay on transport death, and a **circuit breaker** (3 consecutive failures → open → fast-fail for 30 s → half-open probe) so one dead server can never stall your agent's turn. `${VAR}` expansion works in `command`, `args`, `env`, `url`, `headers` and `cwd`.
+
+`reload_config` (or `SIGHUP` in HTTP mode) applies edits live: unchanged upstreams keep their connections, changed ones are swapped, removed ones are disconnected — and a broken file never takes down the running setup.
+
+## Zero-friction auth (OAuth popup, no keys in JSON)
+
+Remote mode supports three auth levels — pick per deployment:
+
+| Mode | Setup | Who it's for |
+|---|---|---|
+| `none` (default) | — | localhost / private network behind a VPN |
+| `apikey` | `CS_API_KEY=…` (checked in constant time) | personal remote, single user |
+| `oauth` | `CS_ACCESS_CODE=…` (+ `CS_TOKEN_SECRET`, `CS_PUBLIC_URL` behind TLS) | teams — the "viral" path: **no API keys in client config files, ever** |
+
+The `oauth` mode is a **built-in OAuth 2.1 authorization server** with everything MCP hosts expect:
+
+- `/.well-known/oauth-protected-resource` (RFC 9728) + `/.well-known/oauth-authorization-server` (RFC 8414) discovery
+- `WWW-Authenticate: Bearer resource_metadata=…` on 401 (so Claude / Cursor auto-discover the flow)
+- **Popup login page** — user types the access code, no API keys, no JSON
+- PKCE (S256) mandatory, single-use 120 s codes, rotating refresh tokens, HMAC-signed access tokens
+- Dynamic client registration (RFC 7591) for hosts that use it
+
+Details and threat model: [`SECURITY.md`](SECURITY.md).
+
+## Real numbers (measured, not marketing)
+
+From the captured demo session (92 tools across 6 upstreams — `scripts/gif-session.mjs` + the `at scale` integration test):
+
+| | Direct-connect | Context-Saver gateway |
+|---|---|---|
+| Tool schemas in context, before first prompt | **8,295 tokens** | **0** (catalog metadata only) |
+| Fixed menu the model always sees | — (grows with every server) | **1,322 tokens**, constant |
+| `suggest_tools` for a weather prompt | — | **272 tokens** incl. the 2 schemas it needed |
+| Session total after a real forecast call | 8,295 | 1,594 → **84 % saved** |
+| Idle turn cost | 8,295 tokens, every request | ~0 marginal |
+
+At ~$3/M input tokens, one heavy user burning 8.3k tokens on *every* request, 50 requests/day pays **≈ $37/month for schemas alone**. The same usage through the gateway: ~$6. **Scaling is linear**: add servers, the direct-connect column grows, the gateway column stays ~1.3k + what you actually load.
+
+## Resilience you get for free
+
+- **Lazy everything** — upstreams that are never called never spawn a process or open a socket; cold starts serve the persisted catalog instantly
+- **One bad server can't hurt you** — timeouts, breakers and normalized errors per upstream; the audit even has a test where a nonexistent binary fast-fails while `weather` keeps answering
+- **`did you mean` UX** — unknown server/tool typos get Levenshtein suggestions instead of dead ends
+- **Sane HTTP server semantics** — session ids, 400/404/405/413 handling, CORS, `/health`, idle-session sweeping, clean shutdown (no hanging keep-alive sockets — that was [a real bug we fixed](https://github.com/Gatsuke/context-saver-mcp/commit/0d038bb))
+- **Stdout is sacred** — in stdio mode all logging goes to stderr; `no-console` is a lint rule because one stray `console.log` corrupts the JSON-RPC stream
+
+## Contributing & Good First Issues
+
+The entire server is [one readable, section-bounded file](context-saver-mcp.js) (~2,000 lines, no build step) — read sections 1–11 top to bottom and you've read the whole product. [`CONTRIBUTING.md`](CONTRIBUTING.md) maps sections to starter issues.
+
+Current [![good-first-issues](https://img.shields.io/badge/good%20first%20issues-open-brightgreen)](https://github.com/Gatsuke/context-saver-mcp/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22):
+
+- **Prompt ranking is TF-IDF, not embeddings** (§5) — deterministic and dependency-free, but a pluggable `Scorer` interface would let people add smarter rankers
+- **`resources` / `prompts` passthrough** (§7) — the gateway multiplexes tools only today
+- **OAuth state persistence** (§8) — codes/refresh tokens are in-memory per process; a pluggable store would enable multi-instance deployments
+- **IdP delegation** (§8) — "Continue with GitHub" login option behind the popup
+- **Upstream `include`/`exclude` tests on Windows** (§3) — glob behavior across path separators
+
+Node ≥ 18.19, zero runtime dependencies beyond `@modelcontextprotocol/sdk` + `zod`, `npm test` runs 42 tests in ~20 s.
+
+## FAQ
+
+**Does this break the host's tool discovery?** No — it replaces it. The model sees 8 stable meta-tools (fewer than most single servers) plus a compact catalog. MCP tools/list pagination is honored upstream; nothing is truncated silently.
+
+**Is the ranking "AI"?** It's honest engineering: tokenization, stopwording, camelCase/snake_case splitting and IDF weighting — deterministic, testable, no API calls. For most prompts it lands the right tool; `search_tools`/`list_tools` cover the rest, and the model always stays in control.
+
+**What about latency?** One extra hop on the LAN/localhost. Lazy connections mean a cold upstream pays its connect time once, on first use; hot calls add ~1 ms of routing.
+
+**Can it multiplex resources and prompts?** Not yet — tools only in 1.0.0 (see good first issues; the section-bounded codebase makes this a contained change).
+
+**Why OAuth instead of just an API key?** Both work (`apikey` mode is one env var). OAuth mode exists because copying bearer tokens into local client JSON is the #1 friction killing MCP tool adoption in teams — the popup flow means a new teammate connects in one click.
+
+**Single file — isn't that bad engineering?** It's a feature: `npx context-saver-mcp` downloads one readable artifact with no build step, every section is exported for testing, and the audit trail shows fixes landing in a single file with full test coverage. The `tests/` tree is where the structure lives.
+
+---
+
+MIT © [Gatsuke](LICENSE) · Built because 20k tokens of schemas before breakfast is 19k too many.

package/SECURITY.md

@@ -0,0 +1,54 @@
+# Security Policy
+
+The Context-Saver gateway is designed to sit between an MCP host (Claude Code, Cursor, VS Code, …) and your collection of upstream MCP servers. This document explains what the 1.0.0 gateway protects, what it deliberately does not, and how to report issues.
+
+## Supported versions
+
+| Version | Supported |
+|---------|-----------|
+| 1.0.x   | ✅        |
+
+## Threat model and controls
+
+### Transport-level (gateway ↔ host)
+
+- **`none`** — no authentication. Intended for localhost or private networks behind a VPN. *Do not expose a `none` gateway to the public internet.*
+- **`apikey`** — static bearer key (`CS_API_KEY`), compared in constant time (`timingSafeEqual`). Suitable for a single user or a tightly held team key.
+- **`oauth`** — built-in OAuth 2.1 authorization server:
+  - Authorization-code flow with **mandatory PKCE (S256)** — RFC 7636; `plain` is rejected
+  - Authorization codes are **single-use** and expire after **120 seconds**; a failed PKCE check burns the code
+  - `redirect_uri` must be `https:` or loopback `http://localhost/127.0.0.1/[::1]` (prevents exfiltration to attacker sites)
+  - Access tokens are HMAC-SHA256-signed with a constant-time signature check; set your own `CS_TOKEN_SECRET` for tokens that survive restarts
+  - Refresh tokens are **rotated on every use** (old token is invalidated immediately)
+  - Login page params are HTML-escaped with numeric character references (no XSS, regression-tested)
+  - Discovery: RFC 8414/9728 metadata and the `WWW-Authenticate: Bearer resource_metadata=…` challenge MCP hosts rely on
+
+### Process-level (gateway ↔ upstreams)
+
+- Upstream stdio servers are spawned with `spawn()` **without a shell** — no shell-injection surface in `command`/`args`
+- Config validation skips malformed entries instead of guessing; `include`/`exclude` globs constrain what the catalog exposes
+- Secrets belong in environment variables (`${VAR}` expansion), not in `servers.json`
+- Per-upstream circuit breakers and timeouts prevent a stuck upstream from stalling the gateway
+
+### Deliberate non-goals in 1.0.0 (tracked as issues)
+
+- Codes and refresh tokens live in **process memory** — a multi-instance deployment behind a load balancer needs a shared store (see good-first-issues)
+- No rate limiting on `/oauth/token` (front it with a proxy for public deployments)
+- Only the access-code login is implemented; delegated IdP login ("Continue with GitHub") is a roadmap item
+- CORS is permissive (`*`) because MCP hosts run in varied origins; constrain it at your reverse proxy if needed
+
+## Hardening checklist for public deployments
+
+1. Terminate TLS at a reverse proxy; set `CS_PUBLIC_URL` so discovery metadata is correct
+2. `--auth oauth` with your own `CS_TOKEN_SECRET` (32+ random bytes) and a real `CS_ACCESS_CODE`
+3. Proxy-rate-limit `/oauth/token` and `/oauth/authorize`
+4. Keep `servers.json` unreadable by other users (`chmod 600`) — it names commands and headers
+
+## Reporting a vulnerability
+
+Please open a private security advisory: **Security → Report a vulnerability** on the GitHub repo, or email the maintainer listed on the npm page. Please include a minimal reproduction. We aim to respond within 72 hours. Please avoid opening public issues for exploitable findings.
+
+## Disclosure policy
+
+- Reports are acknowledged within 72 hours
+- Fix + coordinated disclosure, crediting the reporter unless they prefer anonymity