lazy-mcp 2.2.6 → 2.3.0

package/README.md

@@ -12,9 +12,11 @@ A client-agnostic proxy that converts normal MCP servers to use a lazy-loading p
   - [How It Works](#how-it-works)
   - [Installation](#installation)
   - [Usage](#usage)
+    - [Streamable HTTP Transport](#streamable-http-transport)
   - [Integration (Claude Desktop, OpenCode, Cursor, VS Code, and more)](#integration-claude-desktop-opencode-cursor-vs-code-and-more)
   - [Example](#example)
   - [Development](#development)
+    - [Running from Local Source](#running-from-local-source)
   - [Releases](#releases)
     - [How It Works](#how-it-works)
     - [Required CI/CD Variables](#required-cicd-variables)
@@ -27,6 +29,8 @@ A client-agnostic proxy that converts normal MCP servers to use a lazy-loading p
     - [OAuth 2.0 Authentication](#oauth-20-authentication)
     - [Command Format](#command-format)
     - [Environment Variables](#environment-variables)
+    - [Transport Configuration](#transport-configuration)
+    - [Logging Configuration](#logging-configuration)
     - [Health Monitoring](#health-monitoring)
     - [Config Reload (SIGHUP)](#config-reload-sighup)
   - [Benefits](#benefits)
@@ -43,6 +47,7 @@ A client-agnostic proxy that converts normal MCP servers to use a lazy-loading p
 - **Built-in OAuth 2.0 + PKCE**: Authenticate with OAuth-protected remote servers without a browser — works in sandboxed agent environments
 - **Background Health Monitoring**: Probes all servers on startup and periodically; `list_servers` shows accurate health from the first call
 - **Hot Config Reload**: Send `SIGHUP` to reload config without restarting — add, remove, or update servers on the fly
+- **Streamable HTTP Transport**: Run as an HTTP server — expose lazy-mcp over the network so remote clients can connect via `POST /mcp`
 
 ## How It Works
 
@@ -86,6 +91,24 @@ Or install globally (locks to specific version):
 npm install -g lazy-mcp
 ```
 
+**Docker / Podman**:
+
+```bash
+docker build -t lazy-mcp .
+docker compose up
+```
+
+The image compiles the TypeScript CLI during `docker build`, so this works from a clean checkout without a prebuilt `dist/` directory.
+
+Or with Podman:
+
+```bash
+podman build -t lazy-mcp .
+podman compose up
+```
+
+This runs lazy-mcp in HTTP mode on port 8080 with config mounted from `~/.config/lazy-mcp/servers.json`. See `docker-compose.yml` for configuration options.
+
 ## Usage
 
 Create a configuration file at `~/.config/lazy-mcp/servers.json`:
@@ -133,6 +156,60 @@ LAZY_MCP_CONFIG=~/.config/lazy-mcp/servers.json npx lazy-mcp@latest
 lazy-mcp --config ~/.config/lazy-mcp/servers.json
 ```
 
+### Streamable HTTP Transport
+
+By default, lazy-mcp communicates over **stdio** (standard MCP transport). You can also run it as an **HTTP server** using the Streamable HTTP transport, allowing remote clients to connect over the network:
+
+**Via config file** — add a `transport` block to `servers.json`:
+
+```json
+{
+  "servers": [
+    { "name": "my-server", "description": "My MCP server", "command": ["python", "server.py"] }
+  ],
+  "transport": {
+    "type": "http",
+    "port": 3000,
+    "host": "localhost",
+    "path": "/mcp",
+    "authToken": "${MY_API_KEY}"
+  }
+}
+```
+
+**Via CLI flags** (override config values):
+
+```bash
+# Start HTTP server on port 3000
+lazy-mcp --config servers.json --transport http --port 3000
+
+# With custom host, path, and auth
+lazy-mcp --config servers.json --transport http --port 3000 --host 127.0.0.1 --path /mcp --auth-token "my-secret"
+```
+
+**Security note:** `--host 0.0.0.0` exposes the HTTP server on all network interfaces. Use it only inside Docker or trusted networks.
+
+**Via environment variables** (lowest precedence):
+
+```bash
+LAZY_MCP_TRANSPORT=http LAZY_MCP_PORT=3000 LAZY_MCP_AUTH_TOKEN=my-secret lazy-mcp
+```
+
+**Precedence**: CLI flags > config file > environment variables > defaults.
+
+Once running, clients connect as a remote MCP server:
+
+```bash
+# Quick test with curl
+curl -X POST http://localhost:3000/mcp \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -H "Authorization: Bearer ${MY_API_KEY}" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
+```
+
+> **Note**: Server-initiated notifications via GET/SSE are not supported in stateless mode. Use POST for all requests.
+
 ## Integration (Claude Desktop, OpenCode, Cursor, VS Code, and more)
 
 Replace multiple MCP server entries with one aggregated proxy:
@@ -163,6 +240,24 @@ Replace multiple MCP server entries with one aggregated proxy:
 }
 ```
 
+**HTTP mode** — for clients that support remote MCP servers:
+
+Start lazy-mcp in HTTP mode (e.g. `lazy-mcp --config servers.json --transport http --port 3000`), then configure your client:
+
+```json
+{
+  "mcp": {
+    "lazy-mcp": {
+      "type": "remote",
+      "url": "http://localhost:3000/mcp",
+      "headers": {
+        "Authorization": "Bearer ${LAZY_MCP_AUTH_TOKEN}"
+      }
+    }
+  }
+}
+```
+
 Where `~/.config/lazy-mcp/servers.json` contains all 5 servers:
 ```json
 {
@@ -196,6 +291,51 @@ npm run build
 npm test
 ```
 
+### Running from Local Source
+
+Instead of `npx lazy-mcp@latest` (which downloads the published package), you can run directly from the cloned repo:
+
+**Without building** — using `ts-node` (picks up source changes immediately):
+
+```bash
+npm run dev -- --config ~/.config/lazy-mcp/servers.json
+```
+
+**After building** — run the compiled output:
+
+```bash
+npm run build
+node dist/cli.js --config ~/.config/lazy-mcp/servers.json
+# or equivalently:
+npm start -- --config ~/.config/lazy-mcp/servers.json
+```
+
+**In an MCP client config** — point directly at the local build:
+
+```json
+{
+  "mcp": {
+    "lazy-mcp": {
+      "command": "node",
+      "args": ["/path/to/lazy-mcp/dist/cli.js", "--config", "~/.config/lazy-mcp/servers.json"]
+    }
+  }
+}
+```
+
+Or with `ts-node` (no build needed, always reflects latest source):
+
+```json
+{
+  "mcp": {
+    "lazy-mcp": {
+      "command": "npx",
+      "args": ["ts-node", "/path/to/lazy-mcp/src/cli.ts", "--config", "~/.config/lazy-mcp/servers.json"]
+    }
+  }
+}
+```
+
 ## Releases
 
 Releases are fully automated via [semantic-release](https://semantic-release.gitbook.io/) on every push to `main`.
@@ -393,6 +533,80 @@ Use `${VAR_NAME}` to reference environment variables:
 }
 ```
 
+### Transport Configuration
+
+Configure how lazy-mcp exposes its MCP endpoint. By default, it uses stdio (for subprocess-based clients). Set `type: "http"` to run as an HTTP server.
+
+**Top-level configuration** (in `servers.json`):
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `transport.type` | `"stdio"` \| `"http"` | `"stdio"` | Transport mode |
+| `transport.port` | number | `8080` | HTTP server port |
+| `transport.host` | string | `"127.0.0.1"` | HTTP server bind address |
+| `transport.path` | string | `"/mcp"` | MCP endpoint URL path |
+| `transport.authToken` | string | — | Bearer token for HTTP auth (supports `${VAR}` expansion) |
+| `transport.allowedOrigins` | string[] | — | List of allowed Origin header values for request-origin validation / CSRF protection (e.g. `["https://example.com"]`). Full origins including scheme and port. Does not send CORS response headers. |
+| `transport.allowedHosts` | string[] | — | List of explicitly allowed host domains for DNS rebinding protection |
+| `transport.maxPayloadSize` | number | `4194304` | Maximum request body size in bytes. Requests exceeding this limit return HTTP 413 |
+
+**CLI flags** (override config values):
+
+| Flag | Env Variable | Description |
+|------|-------------|-------------|
+| `--transport` | `LAZY_MCP_TRANSPORT` | Transport type (`stdio` or `http`) |
+| `--port` | `LAZY_MCP_PORT` | HTTP server port |
+| `--host` | `LAZY_MCP_HOST` | HTTP server bind address |
+| `--path` | `LAZY_MCP_PATH` | MCP endpoint URL path |
+| `--auth-token` | `LAZY_MCP_AUTH_TOKEN` | Bearer token for HTTP auth |
+| `--request-timeout` | `LAZY_MCP_REQUEST_TIMEOUT` | Request timeout in ms for server calls, including MCP handshake requests and remote response parsing (default: 10000) |
+| `--max-payload-size` | `LAZY_MCP_MAX_PAYLOAD_SIZE` | Maximum request body size in bytes (default: 4194304) |
+
+When `authToken` is set, all HTTP requests must include `Authorization: Bearer <token>` — unauthenticated requests receive `401 Unauthorized`.
+
+### Logging Configuration
+
+lazy-mcp now emits structured logs to **stderr** (stdout remains reserved for MCP protocol traffic).
+
+**Top-level configuration** (in `servers.json`):
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `logging.level` | `"error"` \| `"info"` \| `"debug"` | `"info"` | Minimum log level |
+| `logging.format` | `"json"` \| `"plain"` | `"json"` | Log output format |
+| `logging.dumpBodies` | boolean | `false` | Enable debug request/response body dumps |
+| `logging.maxBodyLogBytes` | number | `8192` | Max body-dump size in bytes before truncation |
+| `logging.redactKeys` | string[] | — | Additional case-insensitive keys to redact (merged with built-in defaults) |
+
+Built-in redaction includes common secret keys like `authorization`, `token`, `access_token`, `refresh_token`, `client_secret`, and `headers.authorization`.
+
+Example:
+
+```json
+{
+  "servers": [
+    {
+      "name": "my-server",
+      "description": "Example",
+      "command": ["npx", "-y", "my-mcp-server"]
+    }
+  ],
+  "logging": {
+    "level": "debug",
+    "format": "json",
+    "dumpBodies": true,
+    "maxBodyLogBytes": 4096,
+    "redactKeys": ["my_custom_secret"]
+  }
+}
+```
+
+Typical access log event fields include:
+- client source (`clientIp`, optional `forwardedFor`)
+- request shape (`httpMethod`, `path`, `mcpMethod`, `lazyTool`)
+- downstream routing (`downstreamServer`, `downstreamCommand`)
+- outcome (`status`, `reason`, `durationMs`)
+
 ### Health Monitoring
 
 lazy-mcp includes a background health monitor that probes all servers periodically. The monitor is **activity-driven**: it sleeps on startup and only begins probing after the first user tool call (`list_servers`, `list_commands`, etc.). After a configurable idle timeout (default: 5 minutes) with no tool calls, the monitor goes back to sleep. This prevents OAuth-protected servers (e.g. GitLab via `mcp-remote`) from opening browser windows when no one is using the tools.
@@ -407,8 +621,9 @@ Successful probes populate the discovery cache, so subsequent `list_commands` ca
 | `healthMonitor.interval` | number | `30000` | Interval between health checks (ms) |
 | `healthMonitor.timeout` | number | `10000` | Timeout per server probe (ms) |
 | `healthMonitor.idleTimeout` | number | `300000` | Stop probing after this much inactivity (ms). `0` = never sleep (legacy) |
+| `requestTimeout` | number | `10000` | Timeout for individual server requests. For remote HTTP servers, this includes waiting for headers, reading response bodies, and SSE response parsing. Override via `--request-timeout` or `LAZY_MCP_REQUEST_TIMEOUT` |
 
-To disable:
+To disable health monitoring:
 ```json
 {
   "servers": [...],
@@ -416,6 +631,14 @@ To disable:
 }
 ```
 
+To increase the request timeout (e.g. for slow remote servers):
+```json
+{
+  "servers": [...],
+  "requestTimeout": 30000
+}
+```
+
 ### Config Reload (SIGHUP)
 
 You can reload the configuration without restarting the process by sending a `SIGHUP` signal:
@@ -446,6 +669,7 @@ If the new config is invalid, the reload is rejected and the current config cont
 - **Flexible configuration** - Enable/disable servers on demand
 - **Environment variable support** - Secure credential management
 - **Both local and remote** - Support for subprocess and HTTP servers
+- **Streamable HTTP transport** - Run as an HTTP server for remote client access
 - **Health monitoring** - Background probes detect broken servers before you hit them
 
 ## Documentation
@@ -454,4 +678,5 @@ If the new config is invalid, the reload is rejected and the current config cont
 - **[AGENTS.md](./AGENTS.md)** - Development guide for AI coding agents (build commands, code style, testing patterns)
 - **[doc/ARCHITECTURE.md](./doc/ARCHITECTURE.md)** - Architecture overview and design patterns
 - **[doc/CONTRIBUTING.md](./doc/CONTRIBUTING.md)** - Contributing guide with common development tasks
+- **[doc/requests/](./doc/requests/)** - [Bruno](https://www.usebruno.com/) API collection for testing the Streamable HTTP transport. Open the `doc/requests/` folder as a collection in Bruno, select the `local` or `local-with-auth` environment, and run requests against a locally running `lazy-mcp --transport http` instance.
 - **[Configuration Reference](#configuration-reference)** - Server configuration options (above)