initial release: local MCP gateway with lazy schema loading

Ship v0.1.0:
- fans out to N downstream MCP servers over stdio
- namespaces tools with <server>__<tool> to prevent collisions
- alwaysExpose: true | false | string[] — only pre-load what you actually use
- token-report subcommand estimates context cost per downstream
- init / validate / status / add-server / start / help-agents CLI
- agent-friendly: --json envelope, stable exit codes, machine catalog
- 11 vitest tests, incl. in-memory transport integration tests

Author: waydelyle

.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node: [20, 22]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node }}
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm run typecheck
+      - run: pnpm run build
+      - run: pnpm run test

.gitignore

@@ -0,0 +1,10 @@
+spec.md
+dist/
+*.tsbuildinfo
+node_modules/
+coverage/
+.vitest/
+.env
+.env.*
+!.env.example
+.DS_Store

.npmignore

@@ -0,0 +1,12 @@
+spec.md
+src/
+tests/
+examples/
+tsup.config.ts
+tsconfig.json
+vitest.config.ts
+.github/
+.gitignore
+.vitest/
+coverage/
+*.tsbuildinfo

AGENTS.md

@@ -0,0 +1,119 @@
+# mcp-gateway — agent-facing reference
+
+Machine-friendly spec for driving `mcp-gateway` from a coding agent (Claude Code, Codex, Cursor, Cline, Aider, Copilot, etc.).
+
+**Tip:** Run `mcp-gateway help-agents` (or any other command with `--json`) for the full catalog in one line of JSON.
+
+## Global flags
+
+| Flag | Type | Effect |
+|---|---|---|
+| `--json` | boolean | Emit a one-line JSON envelope on stdout |
+| `--quiet` | boolean | Suppress stderr logs |
+| `--verbose` | boolean | More detail on stderr |
+| `--cwd <path>` | path | Override the working directory |
+| `--config <path>` | path | Config file (default `./mcp-gateway.config.json`) |
+
+## JSON envelope
+
+```json
+{"ok": true, "data": {...}}
+```
+
+Error:
+
+```json
+{"ok": false, "error": {"code": "E_VALIDATION", "message": "...", "hint": "..."}}
+```
+
+Stable error codes: `E_VALIDATION`, `E_INTERNAL`.
+
+Exit codes: `0` success, `1` user error, `2` internal error.
+
+## Config schema
+
+```ts
+{
+  version: 1,
+  namespaceSeparator: string,  // default "__"
+  servers: [
+    {
+      name: string,                   // lowercase alphanumeric + underscore, used as namespace prefix
+      command: string,                // executable
+      args?: string[],
+      env?: Record<string,string>,
+      cwd?: string,
+      alwaysExpose: boolean | string[], // true | false | list of tool names to pre-expose
+      enabled?: boolean,              // default true
+      description?: string
+    }
+  ]
+}
+```
+
+## Commands
+
+### `start`
+
+Run the gateway as a stdio MCP server. Your upstream client (Claude Code, Cursor, etc.) connects to this single process instead of each individual downstream server. Returns a streaming MCP session, not JSON.
+
+### `status`
+
+Connect to each enabled downstream, list tools, then disconnect. Emit a snapshot.
+
+```json
+{
+  "ok": true,
+  "data": {
+    "config": {"path": "...", "servers": 3},
+    "downstreams": [
+      {"name": "fs", "status": "ready", "enabled": true, "alwaysExpose": true, "tools": 12, "lastError": null}
+    ]
+  }
+}
+```
+
+### `token-report`
+
+Estimate tokens per downstream's tool schemas.
+
+```json
+{
+  "ok": true,
+  "data": {
+    "totalExposedTokens": 4800,
+    "totalAvailableTokens": 61200,
+    "servers": [
+      {"name": "fs", "exposed": true, "alwaysExposed": true, "tokens": 4800, "tools": [{"name": "fs__read_file", "tokens": 380}]}
+    ]
+  }
+}
+```
+
+### `validate`
+
+Validate the config without connecting to downstreams. Exits `1` on any schema or file error.
+
+### `add-server <name> <command> [args...]`
+
+Append a server to the config. With `--write` it modifies the file; without, it prints the resulting config to stdout.
+
+Flags: `--always-expose <tools>` (`all` | `none` | comma-separated tool names), `--write`.
+
+### `init`
+
+Create a starter `mcp-gateway.config.json`. `--write` writes to disk (refuses to overwrite existing file); without, prints to stdout.
+
+### `help-agents`
+
+Returns the full CLI catalog as JSON. Preferred discovery entry point for agents.
+
+## Tool namespacing
+
+Every downstream tool is exposed as `<server_name><separator><tool_name>` — e.g. `fs__read_file`. This prevents collisions and lets the gateway route `call_tool` by looking at the prefix. The separator is configurable (`namespaceSeparator`) but must be consistent across the gateway's lifetime.
+
+## Lazy exposure semantics
+
+- `alwaysExpose: true` — gateway connects at startup and exposes every tool.
+- `alwaysExpose: false` — gateway does not expose any tool from the server until the upstream client calls `call_tool` with that server's prefix. At that moment the gateway connects, fetches the schema, and fulfills the call.
+- `alwaysExpose: [tool_a, tool_b]` — only the listed tools appear in `tools/list` replies, even though the server is connected. This is useful for large servers (like GitHub's) where most of the surface is noise for a specific project.

CONTRIBUTING.md

@@ -0,0 +1,41 @@
+# Contributing
+
+## Local dev
+
+```bash
+pnpm install
+pnpm run build
+pnpm run test
+pnpm run typecheck
+```
+
+## Testing strategy
+
+- **Unit tests** cover config validation and token math.
+- **Integration tests** exercise the `DownstreamManager` against real MCP servers via `@modelcontextprotocol/sdk`'s `InMemoryTransport`. No child processes are spawned during tests — the test plants a real `Server` and `Client` in memory.
+
+If you're adding code that interacts with downstream servers, prefer writing the test as an in-memory integration test rather than mocking the SDK.
+
+## Adding a new exposure mode
+
+Today we support `alwaysExpose: true | false | string[]`. If you add a new mode (e.g. `alwaysExpose: { match: "regex" }`):
+
+1. Extend `serverSpecSchema` in `src/config.ts`.
+2. Update `resolvedServerAlwaysExposed` and the gateway's `tokenReport` logic.
+3. Cover the new shape in `tests/config.test.ts` + `tests/gateway.test.ts`.
+4. Document in `AGENTS.md`.
+
+## Style
+
+- Stderr for logs, stdout for data.
+- Every command must support `--json` and update the `help-agents` catalog.
+- Keep the CLI non-interactive.
+- Don't call into the real MCP SDK transport layer from unit tests — use `InMemoryTransport`.
+
+## Commit style
+
+```
+config: allow regex match on alwaysExpose
+server: fix double-connect on lazy prefix hit
+tokens: bump chars/token ratio to match Claude tokenizer
+```

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SwarmClaw AI
+
+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.

README.md

@@ -0,0 +1,156 @@
+# mcp-gateway
+
+> Local MCP gateway that fans out to N downstream MCP servers, namespaces their tools, and lazy-loads their schemas — so your coding agent's context isn't eaten by MCP boilerplate.
+
+[![npm version](https://img.shields.io/npm/v/@swarmclawai/mcp-gateway.svg)](https://www.npmjs.com/package/@swarmclawai/mcp-gateway)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
+[![CI](https://github.com/swarmclawai/mcp-gateway/actions/workflows/ci.yml/badge.svg)](https://github.com/swarmclawai/mcp-gateway/actions/workflows/ci.yml)
+
+## Why this exists
+
+Install more than a handful of MCP servers and something ugly happens: every one of them dumps its full tool schema into your coding agent's context at startup. People routinely report **30,000 – 60,000 tokens** of MCP boilerplate consumed before they've typed a single message. The 1M-context upgrade makes this worse, not better — people just install more servers.
+
+Existing tooling solves the wrong half:
+
+- Registries (wong2/awesome-mcp-servers, mcp.so, smithery, glama) solve **discovery**.
+- Docker's own gateway is great at **multi-tenancy** and **auth**.
+- Nobody owns the **local runtime** problem: "I have 15 MCP servers installed. I want 3 of them exposed by default and the other 12 to only show up when I actually ask for them."
+
+`mcp-gateway` is that tool. You point your upstream client (Claude Code, Cursor, Cline, Aider, Windsurf, etc.) at one MCP endpoint — the gateway. It fans out to all your downstream servers, prefixes their tool names to prevent collisions, and only exposes the tools you've explicitly chosen to pre-load.
+
+## 30-second demo
+
+```bash
+# Generate a starter config
+npx @swarmclawai/mcp-gateway@latest init --write
+
+# Edit mcp-gateway.config.json — set alwaysExpose per server
+
+# See how many tokens each server is spending
+npx @swarmclawai/mcp-gateway token-report
+
+# Point Claude Code at the gateway instead of at each server individually
+claude mcp add gateway -- npx -y @swarmclawai/mcp-gateway@latest start
+```
+
+## Config
+
+A single `mcp-gateway.config.json` at your project root (or `--config <path>`):
+
+```json
+{
+  "version": 1,
+  "namespaceSeparator": "__",
+  "servers": [
+    {
+      "name": "fs",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
+      "alwaysExpose": true
+    },
+    {
+      "name": "github",
+      "command": "docker",
+      "args": ["run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server"],
+      "alwaysExpose": false
+    },
+    {
+      "name": "sentry",
+      "command": "npx",
+      "args": ["-y", "@sentry/mcp-server@latest"],
+      "alwaysExpose": ["issue_details"]
+    }
+  ]
+}
+```
+
+- `alwaysExpose: true` — every tool from this server is in your agent's context on startup.
+- `alwaysExpose: false` — tools aren't exposed at first; the gateway connects to the server when the agent calls a tool whose name begins with `<prefix>__`.
+- `alwaysExpose: ["tool_a", "tool_b"]` — only the listed tools are pre-exposed.
+
+The gateway prefixes every downstream tool with its server name and the namespace separator (`__` by default) so two servers can both expose a tool called `read_file` without collision — your agent sees `fs__read_file` and `github__read_file`.
+
+## Install
+
+```bash
+pnpm add -g @swarmclawai/mcp-gateway
+# or
+npm i -g @swarmclawai/mcp-gateway
+# or run on demand
+npx @swarmclawai/mcp-gateway@latest --help
+```
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `init` | Create a starter config |
+| `validate` | Validate the config file without connecting to any downstream |
+| `status` | Connect to every enabled downstream and report status + tool counts |
+| `token-report` | Estimate how many tokens each downstream's schemas cost |
+| `add-server <name> <command> [args...]` | Append a server to the config |
+| `start` | Start the gateway (stdio MCP server for an upstream client) |
+| `help-agents` | Print the machine-readable command catalog |
+
+Every command accepts `--json` and returns a one-line JSON envelope. Exit codes: `0` success, `1` user error, `2` internal error.
+
+## How token-report works
+
+The report walks every downstream server, connects to it over stdio, calls `tools/list`, and estimates the token cost of each tool's name + description + input schema. We don't call a real tokenizer — that'd introduce a heavy dep for a directional number. Chars / 3.5 is close enough to tell you which server is blowing up your window.
+
+## Wiring it into your agent
+
+### Claude Code
+
+```bash
+claude mcp add gateway -- npx -y @swarmclawai/mcp-gateway@latest start
+```
+
+Remove your individual server entries — the gateway replaces them.
+
+### Cursor
+
+In `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "gateway": {
+      "command": "npx",
+      "args": ["-y", "@swarmclawai/mcp-gateway@latest", "start"]
+    }
+  }
+}
+```
+
+### Cline, Aider, Windsurf
+
+Same pattern: one `mcp-gateway start` entry in place of N individual server entries. See [`awesome-mcp-for-coding-agents`](https://github.com/swarmclawai/awesome-mcp-for-coding-agents#how-to-install) for the exact config syntax per agent.
+
+## Built for coding agents
+
+Every swarmclawai CLI follows the same agent conventions so Claude Code, Cursor, Cline, Aider, Codex et al can drive them without guessing:
+
+- `--json` everywhere, one-line envelope on stdout
+- Stderr for logs, stdout for data
+- Stable exit codes: `0` / `1` / `2`
+- Non-interactive by default
+- `mcp-gateway help-agents` returns the entire command catalog as JSON
+
+See [`AGENTS.md`](./AGENTS.md) for the full machine-readable reference.
+
+## Roadmap
+
+- Session-scoped explicit exposure: an agent can ask the gateway "expose github__* for the rest of this session" without restarting
+- Schema compression: strip optional descriptions on lazy-exposed tools to shrink `tools/list` replies further
+- Observability endpoint: count tool calls per server to justify what should actually be alwaysExpose
+- Remote (HTTP/SSE) transport for upstream clients, not just stdio
+- Per-tool deny/allow list beyond the name prefix
+
+## Contributing
+
+See [`CONTRIBUTING.md`](./CONTRIBUTING.md).
+
+## License
+
+[MIT](./LICENSE)