feat: Prioritize HTTP transport over SSE (CFOS-43)

.claude/implementations/http_primary_transport.md

@@ -0,0 +1,114 @@
+# HTTP as Primary Transport for MCP Server
+
+## Overview
+
+As of the current MCP specification, HTTP is the primary transport protocol for the Model Context Protocol. SSE (Server-Sent Events) is an optional enhancement for specific streaming use cases only.
+
+## Transport Hierarchy
+
+1. **HTTP (Primary)**: Simple request/response pattern for all MCP operations
+2. **SSE (Optional)**: Only for real-time streaming scenarios like progress updates and subscriptions
+3. **stdio**: For local/embedded usage
+
+## HTTP-First Implementation
+
+### Primary Endpoint
+
+The main MCP endpoint handles all standard operations with simple JSON responses:
+
+```
+POST /mcp/v1/jsonrpc
+Content-Type: application/json
+Accept: application/json
+
+{
+  "jsonrpc": "2.0",
+  "method": "tools/call",
+  "params": {...},
+  "id": 1
+}
+```
+
+Response:
+```json
+{
+  "jsonrpc": "2.0",
+  "result": {...},
+  "id": 1
+}
+```
+
+### Optional SSE Endpoints
+
+SSE is ONLY used for specific streaming scenarios:
+
+1. **Operation Progress** - `/mcp/v1/sse/progress/{operation_id}`
+   - Used when tracking long-running operations
+   - Optional - clients can poll instead
+
+2. **Subscriptions** - `/mcp/v1/sse/subscribe`
+   - Used for real-time dataset change notifications
+   - Optional - clients can poll for changes
+
+## Migration from SSE-Focused Usage
+
+If you were previously using SSE for all operations:
+
+### Before (SSE-focused):
+```python
+# Opening SSE connection for all operations
+async with sse_client.connect() as stream:
+    response = await stream.send_request({"method": "tools/list"})
+```
+
+### After (HTTP-first):
+```python
+# Simple HTTP request
+response = requests.post(
+    "http://localhost:8000/mcp/v1/jsonrpc",
+    json={"jsonrpc": "2.0", "method": "tools/list", "id": 1}
+)
+```
+
+## When to Use Each Transport
+
+### Use HTTP for:
+- Tool calls
+- Resource operations
+- Initialization
+- All synchronous operations
+- Any request expecting a single response
+
+### Use SSE only for:
+- Tracking progress of long-running operations
+- Subscribing to real-time dataset changes
+- Scenarios requiring server-to-client push
+
+## Configuration
+
+Default transport should be HTTP:
+
+```python
+# Recommended
+config = MCPConfig(transport="http")
+
+# Only use SSE when specifically needed
+# for streaming scenarios
+```
+
+## Client Implementation Guidelines
+
+1. **Start with HTTP**: Always implement HTTP client first
+2. **Add SSE selectively**: Only add SSE support for specific features
+3. **Graceful degradation**: SSE features should be optional enhancements
+
+## Performance Considerations
+
+- HTTP has lower overhead for single request/response
+- SSE only beneficial for multiple server-initiated messages
+- HTTP supports better caching and proxying
+- HTTP has simpler authentication and rate limiting
+
+## Summary
+
+The MCP server implementation prioritizes HTTP as the primary transport, with SSE available as an optional enhancement for specific streaming use cases. This aligns with the latest MCP specification and provides better compatibility, simpler implementation, and clearer separation of concerns.

contextframe/mcp/TRANSPORT_GUIDE.md

@@ -0,0 +1,146 @@
+# MCP Transport Guide
+
+## Transport Protocol Priority
+
+As of the current MCP specification, the recommended transport protocols are:
+
+1. **HTTP (Primary)** - Simple request/response for all standard operations
+2. **stdio** - For local/embedded integrations
+3. **SSE** - Optional enhancement for specific streaming scenarios only
+
+## HTTP Transport (Recommended)
+
+The HTTP transport is the primary and recommended way to interact with the MCP server. It provides:
+
+- Simple request/response pattern
+- Better compatibility with existing infrastructure
+- Easier authentication and authorization
+- Standard HTTP caching and proxying support
+- Lower overhead for single operations
+
+### Starting the Server
+
+```python
+from contextframe.mcp import ContextFrameMCPServer, MCPConfig
+
+# HTTP is now the default transport
+config = MCPConfig(
+    server_name="my-contextframe-server",
+    http_host="localhost",
+    http_port=8080
+)
+
+server = ContextFrameMCPServer("path/to/dataset", config)
+await server.run()
+```
+
+### Client Usage
+
+See `http_client_example.py` for a complete example. Basic pattern:
+
+```python
+# Standard HTTP POST to /mcp/v1/jsonrpc
+response = requests.post(
+    "http://localhost:8080/mcp/v1/jsonrpc",
+    json={
+        "jsonrpc": "2.0",
+        "method": "tools/call",
+        "params": {"name": "search", "arguments": {"query": "test"}},
+        "id": 1
+    }
+)
+result = response.json()
+```
+
+## SSE (Server-Sent Events) - Optional
+
+SSE is available as an optional enhancement for specific use cases:
+
+### When to Use SSE
+
+Only use SSE for:
+- Progress tracking of long-running operations (`/mcp/v1/sse/progress/{id}`)
+- Real-time dataset change subscriptions (`/mcp/v1/sse/subscribe`)
+
+### When NOT to Use SSE
+
+Do not use SSE for:
+- Standard tool calls
+- Resource operations
+- Any operation expecting a single response
+
+## stdio Transport
+
+The stdio transport is still supported for:
+- Local command-line tools
+- Embedded integrations
+- Development and testing
+
+### Usage
+
+```python
+config = MCPConfig(transport="stdio")
+```
+
+## Migration from SSE-Focused Implementation
+
+If you have existing code that uses SSE for all operations:
+
+### Old Pattern (Deprecated)
+```python
+# Opening SSE connection for everything
+async with sse_client.stream() as conn:
+    response = await conn.send_and_receive(request)
+```
+
+### New Pattern (Recommended)
+```python
+# Simple HTTP request
+response = requests.post(url, json=request)
+```
+
+## Transport Selection Guide
+
+| Use Case | Recommended Transport | Why |
+|----------|----------------------|-----|
+| Web API | HTTP | Standard REST-like interface |
+| Tool calls | HTTP | Single request/response |
+| Resource reads | HTTP | Cacheable, simple |
+| Progress tracking | HTTP + SSE (optional) | SSE only for the progress stream |
+| Real-time updates | HTTP + SSE (optional) | SSE only for subscriptions |
+| CLI tools | stdio | Direct process communication |
+| Embedded usage | stdio | No network overhead |
+
+## Configuration Examples
+
+### HTTP Only (Recommended)
+```python
+config = MCPConfig(
+    transport="http",
+    http_host="0.0.0.0",
+    http_port=8080
+)
+```
+
+### HTTP with Optional SSE
+The HTTP transport automatically includes SSE endpoints.
+Clients can choose to use them only when needed.
+
+### Local Development
+```python
+config = MCPConfig(
+    transport="stdio"  # For local CLI usage
+)
+```
+
+## Best Practices
+
+1. **Default to HTTP**: Always use HTTP unless you have a specific reason not to
+2. **Use SSE Sparingly**: Only for actual streaming needs
+3. **Design for HTTP**: Structure your operations to work well with request/response
+4. **Cache When Possible**: HTTP allows standard caching mechanisms
+5. **Monitor Performance**: HTTP has better observability tooling
+
+## Summary
+
+The MCP server prioritizes HTTP as the primary transport protocol. SSE remains available as an optional feature for specific streaming scenarios, but should not be the default choice for general operations.