torjus/labmcp
Archived
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feature/streamable-http-transport #1

Merged
torjus merged 8 commits from feature/streamable-http-transport into master 2026-02-03 21:23:39 +00:00
Conversation 0 Commits 8 Files Changed 12 +2180 -202
torjus commented 2026-02-03 21:14:30 +00:00
Owner
Copy Link

Summary

Add support for running the MCP server over HTTP with Server-Sent Events (SSE) using the MCP Streamable HTTP
specification (2025-03-26), alongside the existing STDIO transport.

Features

  • Transport abstraction - Clean Transport interface allowing multiple transport implementations
  • HTTP transport - Full MCP Streamable HTTP spec support
    • POST /mcp - JSON-RPC requests with session management
    • GET /mcp - SSE stream for server-initiated notifications
    • DELETE /mcp - Session termination
  • Session management - Cryptographically secure session IDs with TTL-based cleanup
  • CORS security - Configurable allowed origins (localhost-only by default)
  • TLS support - Optional TLS certificate configuration
  • SSE keepalive - Periodic heartbeat messages to maintain connection health

Security Hardening

Protection Default Description
Request body limit 1 MB Prevents memory exhaustion via large requests
Read timeout 30s Prevents slowloris attacks
Write timeout 30s Prevents slow client attacks
Idle timeout 120s Cleans up idle connections
Header read timeout 10s Prevents slow header attacks
Max sessions 10,000 Prevents session flooding
Origin validation localhost CORS protection enabled by default

CLI Usage

# STDIO transport (default, backward compatible)                                                              
nixos-options serve                                                                                           
                                                                                                              
# HTTP transport                                                                                              
nixos-options serve --transport http                                                                          
                                                                                                              
# With custom configuration                                                                                   
nixos-options serve --transport http \                                                                        
  --http-address 0.0.0.0:8080 \                                                                               
  --http-endpoint /mcp \                                                                                      
  --allowed-origins https://example.com \                                                                     
  --session-ttl 1h \                                                                                          
  --tls-cert /path/to/cert.pem \                                                                              
  --tls-key /path/to/key.pem                                                                                  
                                                                                                              
NixOS Module                                                                                                  
                                                                                                              
The module now uses HTTP transport for the systemd service with full configuration support:                   
                                                                                                              
services.nixos-options-mcp = {                                                                                
  enable = true;                                                                                              
  http.address = "127.0.0.1:8080";                                                                            
  http.allowedOrigins = [ "https://example.com" ];                                                            
  http.tls.enable = true;                                                                                     
  http.tls.certFile = "/path/to/cert.pem";                                                                    
  http.tls.keyFile = "/path/to/key.pem";                                                                      
  openFirewall = true;                                                                                        
};                                                                                                            
                                                                                                              
Files Changed                                                                                                 
                                                                                                              
- New: internal/mcp/transport.go - Transport interface                                                        
- New: internal/mcp/transport_stdio.go - STDIO transport (extracted from server.go)                           
- New: internal/mcp/transport_http.go - HTTP/SSE transport                                                    
- New: internal/mcp/session.go - Session management                                                           
- New: internal/mcp/session_test.go - Session tests                                                           
- New: internal/mcp/transport_http_test.go - HTTP transport tests                                             
- Modified: internal/mcp/server.go - Exposed HandleRequest/HandleMessage                                      
- Modified: cmd/nixos-options/main.go - Added HTTP transport flags                                            
- Modified: nix/module.nix - Added HTTP configuration options                                                 
                                                                                                              
Test Plan                                                                                                     
                                                                                                              
- All 53 unit tests pass                                                                                      
- STDIO transport backward compatibility verified                                                             
- HTTP transport tested with curl                                                                             
- Nix build succeeds
## Summary Add support for running the MCP server over HTTP with Server-Sent Events (SSE) using the MCP Streamable HTTP specification (2025-03-26), alongside the existing STDIO transport. ### Features - **Transport abstraction** - Clean `Transport` interface allowing multiple transport implementations - **HTTP transport** - Full MCP Streamable HTTP spec support - `POST /mcp` - JSON-RPC requests with session management - `GET /mcp` - SSE stream for server-initiated notifications - `DELETE /mcp` - Session termination - **Session management** - Cryptographically secure session IDs with TTL-based cleanup - **CORS security** - Configurable allowed origins (localhost-only by default) - **TLS support** - Optional TLS certificate configuration - **SSE keepalive** - Periodic heartbeat messages to maintain connection health ### Security Hardening | Protection | Default | Description | |------------|---------|-------------| | Request body limit | 1 MB | Prevents memory exhaustion via large requests | | Read timeout | 30s | Prevents slowloris attacks | | Write timeout | 30s | Prevents slow client attacks | | Idle timeout | 120s | Cleans up idle connections | | Header read timeout | 10s | Prevents slow header attacks | | Max sessions | 10,000 | Prevents session flooding | | Origin validation | localhost | CORS protection enabled by default | ### CLI Usage ```bash # STDIO transport (default, backward compatible) nixos-options serve # HTTP transport nixos-options serve --transport http # With custom configuration nixos-options serve --transport http \ --http-address 0.0.0.0:8080 \ --http-endpoint /mcp \ --allowed-origins https://example.com \ --session-ttl 1h \ --tls-cert /path/to/cert.pem \ --tls-key /path/to/key.pem NixOS Module The module now uses HTTP transport for the systemd service with full configuration support: services.nixos-options-mcp = { enable = true; http.address = "127.0.0.1:8080"; http.allowedOrigins = [ "https://example.com" ]; http.tls.enable = true; http.tls.certFile = "/path/to/cert.pem"; http.tls.keyFile = "/path/to/key.pem"; openFirewall = true; }; Files Changed - New: internal/mcp/transport.go - Transport interface - New: internal/mcp/transport_stdio.go - STDIO transport (extracted from server.go) - New: internal/mcp/transport_http.go - HTTP/SSE transport - New: internal/mcp/session.go - Session management - New: internal/mcp/session_test.go - Session tests - New: internal/mcp/transport_http_test.go - HTTP transport tests - Modified: internal/mcp/server.go - Exposed HandleRequest/HandleMessage - Modified: cmd/nixos-options/main.go - Added HTTP transport flags - Modified: nix/module.nix - Added HTTP configuration options Test Plan - All 53 unit tests pass - STDIO transport backward compatibility verified - HTTP transport tested with curl - Nix build succeeds
torjus added 6 commits 2026-02-03 21:14:30 +00:00
docs: update CLAUDE.md to reflect current project state 0b7333844a 
The file was still showing "Planning phase" with outdated next steps.
Updated to reflect the complete implementation:

- Changed status to "Complete and maintained"
- Updated repository structure to match actual layout
- Documented all 6 MCP tools as implemented
- Added key implementation details (database, indexing, security)
- Added CLI command reference
- Consolidated development notes
- Removed obsolete planning sections

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
feat: add Streamable HTTP transport support cbe55d6456 
Add support for running the MCP server over HTTP with Server-Sent Events
(SSE) using the MCP Streamable HTTP specification, alongside the existing
STDIO transport.

New features:
- Transport abstraction with Transport interface
- HTTP transport with session management
- SSE support for server-initiated notifications
- CORS security with configurable allowed origins
- Optional TLS support
- CLI flags for HTTP configuration (--transport, --http-address, etc.)
- NixOS module options for HTTP transport

The HTTP transport implements:
- POST /mcp: JSON-RPC requests with session management
- GET /mcp: SSE stream for server notifications
- DELETE /mcp: Session termination
- Origin validation (localhost-only by default)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
security: add request body size limit to prevent DoS 149832e4e5 
Add MaxRequestSize configuration to HTTPConfig with a default of 1MB.
Use http.MaxBytesReader to enforce the limit, returning 413 Request
Entity Too Large when exceeded.

This prevents memory exhaustion attacks where an attacker sends
arbitrarily large request bodies.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
security: add HTTP server timeouts to prevent slowloris attacks 1565cb5e1b 
Configure HTTP server with sensible timeouts:
- ReadTimeout: 30s (time to read entire request)
- WriteTimeout: 30s (time to write response)
- IdleTimeout: 120s (keep-alive connection timeout)
- ReadHeaderTimeout: 10s (time to read request headers)

For SSE connections, use http.ResponseController to extend write
deadlines before each write, preventing timeout on long-lived streams
while still protecting against slow clients.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
security: add maximum session limit to prevent memory exhaustion 684baf63da 
Add configurable MaxSessions limit (default: 10000) to SessionStore.
When the limit is reached, new session creation returns ErrTooManySessions
and HTTP transport responds with 503 Service Unavailable.

This prevents attackers from exhausting server memory by creating
unlimited sessions through repeated initialize requests.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
feat: add SSE keepalive messages for connection health 08f8b2cd83 
Add configurable SSEKeepAlive interval (default: 15s) that sends SSE
comment lines (`:keepalive`) to maintain connection health.

Benefits:
- Keeps connections alive through proxies/load balancers that timeout
  idle connections
- Detects stale connections earlier (write failures terminate the
  handler)
- Standard SSE pattern - comments are ignored by compliant clients

Configuration:
- SSEKeepAlive > 0: send keepalives at specified interval
- SSEKeepAlive = 0: use default (15s)
- SSEKeepAlive < 0: disable keepalives

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
torjus added 2 commits 2026-02-03 21:23:03 +00:00
docs: add HTTP transport documentation 921005179e 
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>
docs: fix flake URL and add nix run MCP example e6315eb94b 
- Update flake URL from github:torjus/labmcp to the correct
  git+https://git.t-juice.club/torjus/labmcp
- Add alternative MCP client configuration using nix run with
  the flake URL directly (no installation required)
- Fix NixOS module example to use correct flake URL

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
torjus merged commit 6b6be83e50 into master 2026-02-03 21:23:39 +00:00
torjus deleted branch feature/streamable-http-transport 2026-02-03 21:23:39 +00:00
This repo is archived. You cannot comment on pull requests.
Reviewers
No Reviewers
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
torjus
No Assignees
1 Participants
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: torjus/labmcp#1
Delete Branch "feature/streamable-http-transport"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?