docs: view reverse proxy guide and examples

README.md

@@ -54,6 +54,8 @@ We provide official SDKs to integrate and interact with the TN network:
 
 Learn how to query data through AI Clients: [TRUF.NETWORK MCP](./docs/mcp-server.md)
 
+For production deployments behind reverse proxies: [MCP Reverse Proxy Configuration](./docs/mcp-reverse-proxy.md)
+
 ## Development Guide
 
 For contributors and developers building on top of TN:

docs/examples/mcp-reverse-proxy/Caddyfile.example

@@ -0,0 +1,123 @@
+# Caddy configuration example for TRUF.NETWORK MCP Server with SSE transport
+#
+# Caddy automatically handles many SSE requirements, making configuration simpler
+# compared to other reverse proxies.
+#
+# Usage:
+# 1. Copy this file to your Caddy configuration directory
+# 2. Update domain name and backend address
+# 3. Test: caddy validate --config Caddyfile
+# 4. Reload: caddy reload --config Caddyfile
+
+# Production HTTPS configuration with automatic TLS
+mcp.your-domain.com {
+    # MCP Server SSE endpoint
+    reverse_proxy /sse/* localhost:8000 {
+        # Caddy handles SSE automatically, but these settings ensure optimal performance
+        flush_interval -1
+
+        # Headers
+        header_up Host {http.reverse_proxy.upstream.hostport}
+        header_up X-Real-IP {http.request.remote}
+        header_up X-Forwarded-Proto {http.request.scheme}
+        header_up X-Forwarded-Port {http.request.port}
+
+        # Optional: Health checks
+        health_uri /health
+        health_interval 30s
+        health_timeout 5s
+    }
+
+    # Security headers
+    header {
+        # Security headers
+        X-Frame-Options DENY
+        X-Content-Type-Options nosniff
+        X-XSS-Protection "1; mode=block"
+        Strict-Transport-Security "max-age=31536000; includeSubDomains"
+        Referrer-Policy "strict-origin-when-cross-origin"
+
+        # CORS headers for browser-based clients (optional)
+        Access-Control-Allow-Origin "*"
+        Access-Control-Allow-Headers "Origin, X-Requested-With, Content-Type, Accept, Authorization"
+        Access-Control-Allow-Methods "GET, POST, OPTIONS"
+    }
+
+    # Handle preflight requests
+    @options method OPTIONS
+    respond @options 204
+
+    # Rate limiting (optional; requires a Caddy plugin such as mholt/caddy-ratelimit)
+    # rate_limit {
+    #     zone static
+    #     key {remote}
+    #     events 10
+    #     window 1m
+    # }
+
+    # Access control (optional) - restrict to trusted networks
+    # @denied not remote_ip 192.168.1.0/24 10.0.0.0/8
+    # respond @denied 403
+
+    # Logging
+    log {
+        output file /var/log/caddy/mcp-access.log
+        format json
+    }
+
+    # Error handling
+    handle_errors {
+        respond "MCP Server Error: {http.error.status_code}" {http.error.status_code}
+    }
+}
+
+# Development configuration (HTTP only)
+# mcp-dev.your-domain.com:80 {
+#     reverse_proxy /sse/* localhost:8000 {
+#         flush_interval -1
+#         header_up Host {http.reverse_proxy.upstream.hostport}
+#     }
+# }
+
+# Advanced configuration with load balancing (for high availability)
+# mcp-ha.your-domain.com {
+#     reverse_proxy /sse/* {
+#         to localhost:8000
+#         to localhost:8001
+#         to localhost:8002
+#         
+#         lb_policy least_conn
+#         health_uri /health
+#         health_interval 10s
+#         
+#         flush_interval -1
+#         header_up Host {http.reverse_proxy.upstream.hostport}
+#     }
+# }
+
+# Global options (place at the top of your Caddyfile)
+{
+    # Email for Let's Encrypt (update with your email)
+    email admin@your-domain.com
+
+    # Optional: Enable admin API
+    admin localhost:2019
+
+    # Logging
+    log {
+        level INFO
+    }
+
+    # ACME CA for certificates (default is Let's Encrypt production)
+    # acme_ca https://acme-staging-v02.api.letsencrypt.org/directory  # staging
+}
+
+# Example with custom TLS certificates
+# mcp-custom-tls.your-domain.com {
+#     tls /path/to/cert.pem /path/to/key.pem
+#     
+#     reverse_proxy /sse/* localhost:8000 {
+#         flush_interval -1
+#         header_up Host {http.reverse_proxy.upstream.hostport}
+#     }
+# }

docs/examples/mcp-reverse-proxy/Caddyfile.windows.example

@@ -0,0 +1,54 @@
+# Caddyfile for Windows MCP Server Testing
+# This configuration is optimized for Windows development and testing
+# with IPv4 addressing and local development considerations
+# Different OS may require different configurations
+
+# Basic HTTP configuration for local testing
+:8080 {
+    # Route all SSE traffic to the MCP server
+    # Using IPv4 (127.0.0.1) to avoid Windows IPv6/IPv4 issues
+    @sse path /sse /sse/*
+    reverse_proxy @sse 127.0.0.1:8000 {
+        # Optional for SSE; Caddy streams text/event-stream by default.
+        # flush_interval -1
+        # Rely on Caddy defaults for Host/X-Forwarded-*.
+    }
+
+    # Optional: Health check endpoint
+    reverse_proxy /health 127.0.0.1:8000
+
+    # Enable access logging for debugging
+    log {
+        output file caddy-access.log
+        format single_field common_log
+    }
+}
+
+# Production HTTPS configuration with domain
+# Replace your-domain.com with your actual domain
+# your-domain.com {
+#     reverse_proxy /sse* 127.0.0.1:8000 {
+#         flush_interval -1
+#         header_up Host {http.reverse_proxy.upstream.hostport}
+#         header_up Connection {>Connection}
+#         header_up Cache-Control {>Cache-Control}
+#         header_up X-Real-IP {http.request.remote}
+#         header_up X-Forwarded-For {http.request.remote}
+#         header_up X-Forwarded-Proto https
+#     }
+#     
+#     # Security headers for production
+#     header {
+#         X-Frame-Options DENY
+#         X-Content-Type-Options nosniff
+#         X-XSS-Protection "1; mode=block"
+#         Strict-Transport-Security "max-age=31536000; includeSubDomains"
+#     }
+# }
+
+# Usage Instructions:
+# 1. Save this file as "Caddyfile" (no extension)
+# 2. Start MCP server: postgres-mcp --transport=sse --sse-host=127.0.0.1 --sse-port=8000
+# 3. Start Caddy: caddy run
+# 4. Test: curl.exe -H "Accept: text/event-stream" http://127.0.0.1:8080/sse
+# 5. Configure Claude Desktop with: npx mcp-remote http://127.0.0.1:8080/sse