CLAUDE.md

@@ -15,7 +15,7 @@ The first MCP server provides search and query capabilities for NixOS configurat
 - **Language**: Go 1.24+
 - **Build System**: Nix flakes
 - **Databases**: PostgreSQL and SQLite (both fully supported)
-- **Protocol**: MCP (Model Context Protocol) - JSON-RPC over stdio
+- **Protocol**: MCP (Model Context Protocol) - JSON-RPC over STDIO or HTTP/SSE
 - **Module Path**: `git.t-juice.club/torjus/labmcp`
 
 ## Project Status
@@ -42,10 +42,14 @@ labmcp/
 │   │   ├── sqlite.go           # SQLite implementation
 │   │   └── *_test.go           # Database tests
 │   ├── mcp/
-│   │   ├── server.go           # MCP server loop
+│   │   ├── server.go           # MCP server core
 │   │   ├── handlers.go         # Tool implementations
 │   │   ├── types.go            # Protocol types
-│   │   └── server_test.go      # MCP tests
+│   │   ├── transport.go        # Transport interface
+│   │   ├── transport_stdio.go  # STDIO transport
+│   │   ├── transport_http.go   # HTTP/SSE transport
+│   │   ├── session.go          # HTTP session management
+│   │   └── *_test.go           # MCP tests
 │   └── nixos/
 │       ├── indexer.go          # Nixpkgs indexing
 │       ├── parser.go           # options.json parsing
@@ -91,24 +95,41 @@ All tools are implemented and functional:
 - File indexing enabled by default (use `--no-files` to skip)
 - Skips already-indexed revisions (use `--force` to re-index)
 
+### Transports
+- **STDIO**: Default transport, line-delimited JSON-RPC (for CLI/desktop MCP clients)
+- **HTTP**: Streamable HTTP transport with SSE (for web-based MCP clients)
+  - Session management with cryptographically secure IDs
+  - Configurable CORS (localhost-only by default)
+  - Optional TLS support
+  - SSE keepalive messages (15s default)
+
 ### Security
 - Revision parameter validated against strict regex to prevent Nix injection
 - Path traversal protection using `filepath.Clean()` and `filepath.IsAbs()`
 - NixOS module supports `connectionStringFile` for PostgreSQL secrets
 - Systemd service runs with extensive hardening options
+- HTTP transport hardening:
+  - Request body size limit (1MB default)
+  - Server timeouts (read: 30s, write: 30s, idle: 120s, header: 10s)
+  - Maximum session limit (10,000 default)
+  - Origin validation for CORS
 
 ## CLI Commands
 
 ```bash
-nixos-options serve              # Run MCP server on stdio
-nixos-options index <revision>   # Index a nixpkgs revision
-nixos-options index --force <r>  # Force re-index existing revision
-nixos-options index --no-files   # Skip file content indexing
-nixos-options list               # List indexed revisions
-nixos-options search <query>     # Search options
-nixos-options get <option>       # Get option details
-nixos-options delete <revision>  # Delete indexed revision
-nixos-options --version          # Show version
+nixos-options serve                    # Run MCP server on STDIO (default)
+nixos-options serve --transport http   # Run MCP server on HTTP
+nixos-options serve --transport http \
+  --http-address 0.0.0.0:8080 \
+  --allowed-origins https://example.com  # HTTP with custom config
+nixos-options index <revision>         # Index a nixpkgs revision
+nixos-options index --force <r>        # Force re-index existing revision
+nixos-options index --no-files         # Skip file content indexing
+nixos-options list                     # List indexed revisions
+nixos-options search <query>           # Search options
+nixos-options get <option>             # Get option details
+nixos-options delete <revision>        # Delete indexed revision
+nixos-options --version                # Show version
 ```
 
 ## Notes for Claude

README.md

@@ -34,7 +34,7 @@ go install git.t-juice.club/torjus/labmcp/cmd/nixos-options@latest
 
 ## Usage
 
-### As MCP Server
+### As MCP Server (STDIO)
 
 Configure in your MCP client (e.g., Claude Desktop):
 
@@ -58,6 +58,30 @@ Then start the server:
 nixos-options serve
 ```
 
+### As MCP Server (HTTP)
+
+The server can also run over HTTP with Server-Sent Events (SSE) for web-based MCP clients:
+
+```bash
+# Start HTTP server on default address (127.0.0.1:8080)
+nixos-options serve --transport http
+
+# Custom address and CORS configuration
+nixos-options serve --transport http \
+  --http-address 0.0.0.0:8080 \
+  --allowed-origins https://example.com
+
+# With TLS
+nixos-options serve --transport http \
+  --tls-cert /path/to/cert.pem \
+  --tls-key /path/to/key.pem
+```
+
+HTTP transport endpoints:
+- `POST /mcp` - JSON-RPC requests (returns `Mcp-Session-Id` header on initialize)
+- `GET /mcp` - SSE stream for server notifications (requires `Mcp-Session-Id` header)
+- `DELETE /mcp` - Terminate session
+
 ### CLI Examples
 
 **Index a nixpkgs revision:**
@@ -187,6 +211,14 @@ A NixOS module is provided for running the MCP server as a systemd service.
 | `user` | string | `"nixos-options-mcp"` | User to run the service as |
 | `group` | string | `"nixos-options-mcp"` | Group to run the service as |
 | `dataDir` | path | `/var/lib/nixos-options-mcp` | Directory for data storage |
+| `http.address` | string | `"127.0.0.1:8080"` | HTTP listen address |
+| `http.endpoint` | string | `"/mcp"` | HTTP endpoint path |
+| `http.allowedOrigins` | list of string | `[]` | Allowed CORS origins (empty = localhost only) |
+| `http.sessionTTL` | string | `"30m"` | Session timeout (Go duration format) |
+| `http.tls.enable` | bool | `false` | Enable TLS |
+| `http.tls.certFile` | path | `null` | TLS certificate file |
+| `http.tls.keyFile` | path | `null` | TLS private key file |
+| `openFirewall` | bool | `false` | Open firewall for HTTP port |
 
 ### PostgreSQL Example