feat(transport): add Streamable HTTP transport mode (#84)

Adds the http (Streamable HTTP, MCP rev 2025-03-26) transport mode alongside stdio and legacy sse. Includes new CLI flags and config, per-session isolation, DNS-rebinding/Origin defenses, MCP SDK 1.29.0, and full test coverage. Bumps version to 1.3.0 and updates CHANGELOG.

Author: s2005

CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## [1.3.0] - 2026-05-30
+
+### Added
+
+- **`http` (Streamable HTTP) transport mode** (MCP protocol revision 2025-03-26, single `/mcp` endpoint) alongside `stdio` and legacy `sse` transports (#84)
+  - New CLI flags: `--transport http`, `--http-host` (default `127.0.0.1`), `--http-port` (default `9444`), `--http-allowed-origins`
+  - Config support: `transport.httpHost`, `transport.httpPort`, `transport.httpAllowedOrigins` with validation and serialization
+  - Stateful, isolated sessions: each session gets its own server instance seeded from the primary session's working directory
+- **`sse` (HTTP/SSE) transport mode** for the MCP server (#83)
+  - New CLI flags: `--transport sse`, `--sse-host`, `--sse-port` (default `127.0.0.1:9444`)
+  - Config file support via the `transport` section
+- New integration and unit test suites for the Streamable HTTP transport: handshake/lifecycle, sessions, resources, security, and tool execution
+- README documentation for the `http` transport mode, a no-config-file CLI recipe, and a UAT plan
+
+### Changed
+
+- Upgraded MCP SDK to 1.29.0 for `StreamableHTTPServerTransport`
+- Refactored shared HTTP logic (origin validation, CORS echo, socket tracking, graceful close) from `transport.ts` into `httpShared.ts`; `closeSseServer` is now a thin wrapper over `closeHttpServer`, so existing SSE callers are unaffected
+
+### Security
+
+- DNS-rebinding defense via Origin allowlisting (loopback + bind host + explicit `httpAllowedOrigins`)
+- Request body size cap (4 MB); malformed `Host` header returns 400 instead of crashing
+- Per-session isolation prevents one client's `set_current_directory` from affecting another's
+
 ## [1.2.4] - 2026-05-29
 
 ### Fixed

README.md

@@ -483,46 +483,103 @@ To get started with configuration:
   fully unsafe mode disables those restrictions as well. These two flags are
   mutually exclusive; using both at once will fail.
 
-  You can start the server with HTTP/SSE transport instead of the default
-  stdio transport. This allows remote and web-based MCP clients to connect
-  over HTTP:
+  You can start the server with an HTTP-based transport instead of the default
+  stdio transport, so remote and web-based MCP clients can connect over HTTP.
+  Two HTTP transports are available:
+
+- `http` -- the modern **Streamable HTTP** transport (MCP protocol revision
+  2025-03-26), serving a single `/mcp` endpoint. This is what current MCP
+  clients default to and is the recommended HTTP transport.
+- `sse` -- the legacy **HTTP+SSE** transport (MCP protocol revision
+  2024-11-05), using two endpoints (`GET /sse`, `POST /messages`). It is
+  deprecated by the MCP spec in favor of Streamable HTTP and is kept only for
+  compatibility with older clients.
+
+  The modes are mutually exclusive (selected by `--transport`) and use separate
+  bind settings (`--http-*` for `http`, `--sse-*` for `sse`).
 
   ```bash
-  # Start with SSE transport on default host/port (127.0.0.1:9444)
-  npx wcli0 --transport sse
+  # Streamable HTTP on the default host/port (127.0.0.1:9444), serving /mcp
+  npx wcli0 --transport http
 
   # Custom port, still bound to localhost
+  npx wcli0 --transport http --http-host 127.0.0.1 --http-port 3000
+
+  # Legacy HTTP+SSE transport
   npx wcli0 --transport sse --sse-host 127.0.0.1 --sse-port 3000
   ```
 
   | Option | Type | Default | Description |
   | ------ | ---- | ------- | ----------- |
-  | `--transport` | string | stdio | Transport protocol: `stdio` or `sse` |
-  | `--sse-host` | string | 127.0.0.1 | Host address for SSE transport |
-  | `--sse-port` | number | 9444 | Port for SSE transport |
-  | `--sse-allowed-origins` | string | (none) | Comma-separated browser origins allowed in addition to loopback hosts and the bind host (e.g. `https://app.example.com,192.168.1.10`). Only the host component is compared. Required for browser clients on a wildcard (`0.0.0.0`) bind. |
-
-  When SSE mode is active, clients connect via `GET /sse` to open an SSE
-  stream and send messages via `POST /messages?sessionId=<id>`. The server
-  logs the bind address and port on startup. To mitigate DNS-rebinding
-  attacks, the server validates the request `Origin` header: requests whose
-  `Origin` is not a loopback host, the configured bind host, or one of the
-  configured `--sse-allowed-origins` are rejected with `403 Forbidden`, while
-  non-browser clients that send no `Origin` are allowed.
-
-  > **Security:** This transport has no built-in authentication and exposes
-  > command-execution tools. Keep it bound to `127.0.0.1` (the default) for
-  > local use. Binding to `0.0.0.0` or any non-loopback address exposes those
-  > tools to every host that can reach the port; only do so behind an
-  > authenticated reverse proxy or equivalent access control. Origin validation
-  > alone does not authenticate non-browser clients.
+  | `--transport` | string | stdio | Transport protocol: `stdio`, `http` (Streamable HTTP), or `sse` (legacy HTTP+SSE) |
+  | `--http-host` | string | 127.0.0.1 | Host address for the Streamable HTTP transport (`http` mode) |
+  | `--http-port` | number | 9444 | Port for the Streamable HTTP transport (`http` mode) |
+  | `--http-allowed-origins` | string | (none) | Comma-separated browser origins allowed for `http` mode, in addition to loopback hosts and the bind host (e.g. `https://app.example.com,192.168.1.10`). Only the host component is compared. Required for browser clients on a wildcard (`0.0.0.0`) bind. |
+  | `--sse-host` | string | 127.0.0.1 | Host address for the legacy SSE transport (`sse` mode) |
+  | `--sse-port` | number | 9444 | Port for the legacy SSE transport (`sse` mode) |
+  | `--sse-allowed-origins` | string | (none) | Comma-separated browser origins allowed for `sse` mode, in addition to loopback hosts and the bind host. Only the host component is compared. Required for browser clients on a wildcard (`0.0.0.0`) bind. |
+
+  When `http` mode is active, clients use a single `/mcp` endpoint:
+
+- `POST /mcp` carries client-to-server JSON-RPC messages. An `initialize`
+  request with no session id starts a new session; the server returns the
+  assigned id in the `Mcp-Session-Id` response header, and the client must
+  send that header on every subsequent request.
+- `GET /mcp` opens the optional server-to-client SSE stream for an existing
+  session.
+- `DELETE /mcp` terminates an existing session.
+
+  Sessions are stateful and isolated: each session has its own active working
+  directory, so one client's `set_current_directory` cannot affect another.
+  Requests carrying an unknown or terminated `Mcp-Session-Id` are rejected with
+  `404 Not Found`. The server logs the bind address and port on startup (with
+  `--debug`).
+
+  When `sse` mode is active, clients instead connect via `GET /sse` to open an
+  SSE stream and send messages via `POST /messages?sessionId=<id>`.
+
+  **Configuring Streamable HTTP entirely with CLI parameters (no config file).**
+  Every transport and operational setting can be supplied as an input parameter,
+  so the server can run as a Streamable HTTP server without any config file:
+
+  ```bash
+  npx wcli0 \
+    --transport http \
+    --http-host 127.0.0.1 \
+    --http-port 9444 \
+    --http-allowed-origins "https://app.example.com,192.168.1.10" \
+    --shell gitbash \
+    --allowedDir "D:/work/project" \
+    --commandTimeout 60 \
+    --debug
+  ```
+
+  CLI parameters also take precedence over a config file, so the same `--http-*`
+  flags override the corresponding `transport` fields when a `--config` file is
+  also passed (see the [transport config section](#configuration-inheritance)).
+
+  Both HTTP transports validate the request `Origin` header to mitigate
+  DNS-rebinding attacks: requests whose `Origin` is not a loopback host, the
+  configured bind host, or one of the configured allowed origins
+  (`--http-allowed-origins` / `--sse-allowed-origins`) are rejected with
+  `403 Forbidden`, while non-browser clients that send no `Origin` are allowed.
+  Allowed browser origins receive CORS headers, and `OPTIONS` preflight requests
+  are answered with `204`.
+
+  > **Security:** Neither HTTP transport has built-in authentication, and both
+  > expose command-execution tools. Keep the server bound to `127.0.0.1` (the
+  > default) for local use. Binding to `0.0.0.0` or any non-loopback address
+  > exposes those tools to every host that can reach the port; only do so behind
+  > an authenticated reverse proxy or equivalent access control. Origin
+  > validation alone does not authenticate non-browser clients.
   >
   > **Wildcard binds and browser origins:** When binding to a wildcard address
   > (`0.0.0.0` / `::`), the bind host is not a usable origin to compare against,
   > so browser clients reaching the server through its real LAN address (or a
   > reverse proxy whose public hostname differs from the bind host) are rejected
-  > unless their origin is listed in `--sse-allowed-origins` (or the
-  > `transport.sseAllowedOrigins` config array). Non-browser clients are
+  > unless their origin is listed in `--http-allowed-origins` /
+  > `--sse-allowed-origins` (or the `transport.httpAllowedOrigins` /
+  > `transport.sseAllowedOrigins` config arrays). Non-browser clients are
   > unaffected, since they send no `Origin`.
 
 1. **Update your Claude Desktop configuration** to use your config file:
@@ -827,7 +884,21 @@ You can override the mount point at startup using the `--wslMountPoint` CLI flag
 
 ### Configuration Inheritance
 
-The transport section can also be set in the config file:
+The transport section can also be set in the config file. For the Streamable
+HTTP transport (`http` mode):
+
+```json
+{
+  "transport": {
+    "mode": "http",
+    "httpHost": "127.0.0.1",
+    "httpPort": 9444,
+    "httpAllowedOrigins": ["https://app.example.com", "192.168.1.10"]
+  }
+}
+```
+
+For the legacy HTTP+SSE transport (`sse` mode):
 
 ```json
 {
@@ -840,11 +911,23 @@ The transport section can also be set in the config file:
 }
 ```
 
-`sseAllowedOrigins` is optional and defaults to an empty list. Each entry is an
-origin URL or a bare host; only the host component is compared (case-insensitively).
-
-CLI flags (`--transport`, `--sse-host`, `--sse-port`, `--sse-allowed-origins`)
-override config file values.
+| Field | Type | Default | Applies to | Description |
+| ----- | ---- | ------- | ---------- | ----------- |
+| `mode` | string | `stdio` | all | `stdio`, `http`, or `sse` |
+| `httpHost` | string | `127.0.0.1` | `http` | Bind host for the Streamable HTTP transport |
+| `httpPort` | number | `9444` | `http` | Bind port for the Streamable HTTP transport (integer `1..65535`) |
+| `httpAllowedOrigins` | string[] | `[]` | `http` | Browser origins allowed in addition to loopback hosts and `httpHost` |
+| `sseHost` | string | `127.0.0.1` | `sse` | Bind host for the legacy SSE transport |
+| `ssePort` | number | `9444` | `sse` | Bind port for the legacy SSE transport (integer `1..65535`) |
+| `sseAllowedOrigins` | string[] | `[]` | `sse` | Browser origins allowed in addition to loopback hosts and `sseHost` |
+
+The `*AllowedOrigins` lists are optional and default to an empty list. Each
+entry is an origin URL or a bare host; only the host component is compared
+(case-insensitively).
+
+CLI flags override config-file values: `--transport`, `--http-host`,
+`--http-port`, `--http-allowed-origins`, `--sse-host`, `--sse-port`, and
+`--sse-allowed-origins`.
 
 The inheritance system works as follows: