docs: add HTTP transport documentation

Update README.md:
- Add HTTP transport usage section with examples
- Document HTTP endpoints (POST/GET/DELETE)
- Add HTTP-related NixOS module options to the table

Update CLAUDE.md:
- Update protocol description to include HTTP/SSE
- Add new transport files to repository structure
- Add Transports section explaining STDIO vs HTTP
- Add HTTP security hardening details
- Update CLI commands with HTTP transport examples

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
2026-02-03 22:16:46 +01:00
parent 08f8b2cd83
commit 921005179e
2 changed files with 66 additions and 13 deletions

View File

@@ -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