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:
45
CLAUDE.md
45
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
|
||||
|
||||
34
README.md
34
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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user