feat: complete MCP parity slice and docker validation

Author: vparla

Dockerfile.demo

@@ -34,7 +34,7 @@ RUN bash -lc 'set -euo pipefail; \
     -DCMAKE_VERBOSE_MAKEFILE=ON \
     -DCMAKE_CXX_FLAGS="-Wfatal-errors -fdiagnostics-color=always" \
     -DCMAKE_C_FLAGS="-Wfatal-errors -fdiagnostics-color=always"; \
-  cmake --build build --parallel 1 --'
+  cmake --build build --parallel "${CMAKE_BUILD_PARALLEL_LEVEL:-6}" --'
 
 # 1b) Test stage: run unit tests inside the build environment
 FROM build AS test
@@ -58,7 +58,9 @@ ENV CTEST_PARALLEL_LEVEL=4
 #     mcp-cpp-build \
 #     bash -lc 'cd /src && ctest --test-dir build -R TransportDemo.Run -VV --output-on-failure'
 # Docker build stages cannot mount host devices; SHM demos may fail here without a host-IPC setup.
-RUN ctest --test-dir build -VV --progress --timeout 180
+# Architecture checks are the first gate before the full suite.
+RUN ctest --test-dir build -VV --progress --timeout 180 -R "^Architecture" \
+ && ctest --test-dir build -VV --progress --timeout 180
 
 # 2) Demo runtime stage
 FROM ubuntu:24.04 AS demo

README.md

@@ -27,22 +27,23 @@ docker run --rm --name mcp-cpp-demo --mount type=bind,src=$(pwd),dst=/work mcp-c
 
 - Windows (PowerShell via WSL2 Ubuntu):
 ```powershell
-wsl -d Ubuntu -- bash -lc "cd /mnt/c/Work/mcp-cpp && docker buildx build -f Dockerfile.demo --target test --progress=plain --pull --load -t mcp-cpp-test ."
-wsl -d Ubuntu -- bash -lc "cd /mnt/c/Work/mcp-cpp && docker buildx build -f Dockerfile.demo --target demo --progress=plain --pull --load -t mcp-cpp-demo ."
-wsl -d Ubuntu -- bash -lc "docker run --rm --name mcp-cpp-demo --mount type=bind,src=/mnt/c/Work/mcp-cpp,dst=/work mcp-cpp-demo"
+wsl -d Ubuntu -- bash -lc "cd /mnt/c/<path-to-repo>/mcp-cpp && docker buildx build -f Dockerfile.demo --target test --progress=plain --pull --load -t mcp-cpp-test ."
+wsl -d Ubuntu -- bash -lc "cd /mnt/c/<path-to-repo>/mcp-cpp && docker buildx build -f Dockerfile.demo --target demo --progress=plain --pull --load -t mcp-cpp-demo ."
+wsl -d Ubuntu -- bash -lc "docker run --rm --name mcp-cpp-demo --mount type=bind,src=/mnt/c/<path-to-repo>/mcp-cpp,dst=/work mcp-cpp-demo"
 ```
 
 ## API Reference
 
 This section summarizes the primary SDK interfaces and feature-specific APIs.
 
-- Client API header: [include/mcp/Client.h](c:/Work/mcp-cpp/include/mcp/Client.h)
-- Server API header: [include/mcp/Server.h](c:/Work/mcp-cpp/include/mcp/Server.h)
-- Transport headers: [include/mcp/Transport.h](c:/Work/mcp-cpp/include/mcp/Transport.h),
-  [include/mcp/InMemoryTransport.hpp](c:/Work/mcp-cpp/include/mcp/InMemoryTransport.hpp),
-  [include/mcp/StdioTransport.hpp](c:/Work/mcp-cpp/include/mcp/StdioTransport.hpp),
-  [include/mcp/SharedMemoryTransport.hpp](c:/Work/mcp-cpp/include/mcp/SharedMemoryTransport.hpp),
-  [include/mcp/HTTPTransport.hpp](c:/Work/mcp-cpp/include/mcp/HTTPTransport.hpp)
+- Client API header: [include/mcp/Client.h](./include/mcp/Client.h)
+- Server API header: [include/mcp/Server.h](./include/mcp/Server.h)
+- Transport headers: [include/mcp/Transport.h](./include/mcp/Transport.h),
+  [include/mcp/InMemoryTransport.hpp](./include/mcp/InMemoryTransport.hpp),
+  [include/mcp/StdioTransport.hpp](./include/mcp/StdioTransport.hpp),
+  [include/mcp/SharedMemoryTransport.hpp](./include/mcp/SharedMemoryTransport.hpp),
+  [include/mcp/HTTPTransport.hpp](./include/mcp/HTTPTransport.hpp),
+  [include/mcp/HTTPServer.hpp](./include/mcp/HTTPServer.hpp)
 
 ### Client API (IClient / Client)
 
@@ -54,6 +55,8 @@ This section summarizes the primary SDK interfaces and feature-specific APIs.
 - Subscriptions: `SubscribeResources()`, `SubscribeResources(optional<string> uri)`,
   `UnsubscribeResources()`, `UnsubscribeResources(optional<string> uri)`
 - Prompts: `ListPrompts()`, `ListPromptsPaged(cursor, limit)`, `GetPrompt(name, args)`
+- Utilities: `Complete(params)`, `Ping()`
+- Roots and elicitation: `SetRootsListHandler(handler)`, `NotifyRootsListChanged()`, `SetElicitationHandler(handler)`
 - Sampling (server → client): `SetSamplingHandler(handler)`
 - Notifications & progress: `SetNotificationHandler(method, handler)`, `RemoveNotificationHandler(method)`,
   `SetProgressHandler(handler)`, `SetErrorHandler(handler)`
@@ -74,7 +77,8 @@ ClientCapabilities caps; auto serverCaps = client->Initialize(info, caps).get();
 - Resources: `RegisterResource(uri, handler)`, `UnregisterResource(uri)`, `ListResources()`, `ReadResource(uri)`
 - Resource templates: `RegisterResourceTemplate(t)`, `UnregisterResourceTemplate(template)`, `ListResourceTemplates()`
 - Prompts: `RegisterPrompt(name, handler)`, `UnregisterPrompt(name)`, `ListPrompts()`, `GetPrompt(name, args)`
-- Sampling: `SetSamplingHandler(handler)`, `RequestCreateMessage(params)`
+- Utilities: `SetCompletionHandler(handler)`, `RequestCreateMessage(params)`, `RequestElicitation(request)`, `RequestRootsList()`, `Ping()`
+- Sampling: `SetSamplingHandler(handler)`
 - Keepalive: `SetKeepaliveIntervalMs(intervalMs)`
 - Logging: `LogToClient(level, message, data)`
 - Notifications: `NotifyResourcesListChanged()`, `NotifyResourceUpdated(uri)`, `NotifyToolsListChanged()`, `NotifyPromptsListChanged()`
@@ -87,10 +91,11 @@ ClientCapabilities caps; auto serverCaps = client->Initialize(info, caps).get();
 - Messaging: `SendRequest(req)`, `SendNotification(note)`
 - Handlers: `SetNotificationHandler(h)`, `SetErrorHandler(h)`, `SetRequestHandler(h)`
 - Implementations:
-  - In-memory: [include/mcp/InMemoryTransport.hpp](c:/Work/mcp-cpp/include/mcp/InMemoryTransport.hpp)
-  - Stdio: [include/mcp/StdioTransport.hpp](c:/Work/mcp-cpp/include/mcp/StdioTransport.hpp)
-  - Shared Memory: [include/mcp/SharedMemoryTransport.hpp](c:/Work/mcp-cpp/include/mcp/SharedMemoryTransport.hpp)
-  - HTTP client: [include/mcp/HTTPTransport.hpp](c:/Work/mcp-cpp/include/mcp/HTTPTransport.hpp)
+  - In-memory: [include/mcp/InMemoryTransport.hpp](./include/mcp/InMemoryTransport.hpp)
+  - Stdio: [include/mcp/StdioTransport.hpp](./include/mcp/StdioTransport.hpp)
+  - Shared Memory: [include/mcp/SharedMemoryTransport.hpp](./include/mcp/SharedMemoryTransport.hpp)
+  - HTTP client: [include/mcp/HTTPTransport.hpp](./include/mcp/HTTPTransport.hpp)
+  - HTTP server/acceptor: [include/mcp/HTTPServer.hpp](./include/mcp/HTTPServer.hpp)
 
 #### HTTP Authentication (Bearer/OAuth2)
 
@@ -207,8 +212,8 @@ Tests use GoogleTest via CMake FetchContent (build-time only). See [BUILD+TEST.M
 
 Build and run the client/server demo using stdio transport (WSL2 PowerShell example below):
 ```powershell
-wsl -d Ubuntu -- bash -lc "cd /mnt/c/Work/mcp-cpp && docker buildx build -f Dockerfile.demo --target demo --progress=plain --pull --load -t mcp-cpp-demo ."
-wsl -d Ubuntu -- bash -lc "docker run --rm --name mcp-cpp-demo --mount type=bind,src=/mnt/c/Work/mcp-cpp,dst=/work mcp-cpp-demo"
+wsl -d Ubuntu -- bash -lc "cd /mnt/c/<path-to-repo>/mcp-cpp && docker buildx build -f Dockerfile.demo --target demo --progress=plain --pull --load -t mcp-cpp-demo ."
+wsl -d Ubuntu -- bash -lc "docker run --rm --name mcp-cpp-demo --mount type=bind,src=/mnt/c/<path-to-repo>/mcp-cpp,dst=/work mcp-cpp-demo"
 ```
 
 ## Examples

docs/parity-matrix.md

@@ -29,6 +29,12 @@ This matrix tracks the MCP C++ SDK feature coverage relative to the MCP spec.
   - Get prompt: Implemented (returns `PromptResult.messages`)
   - List-changed notifications: Implemented
 
+- Utilities
+  - `ping`: Implemented
+  - `completion/complete`: Implemented
+  - `roots/list` and `notifications/roots/list_changed`: Implemented
+  - `elicitation/create`: Implemented
+
 - Sampling
   - Client-registered sampling handler: Implemented (client API)
   - Server-initiated `sampling/createMessage`: Implemented (`tests/test_server_initiated_sampling.cpp`)
@@ -56,6 +62,7 @@ This matrix tracks the MCP C++ SDK feature coverage relative to the MCP spec.
 - Transports
   - InMemory: Implemented (unit-test transport)
   - Stdio: Implemented (demo integration test in CTest)
+  - HTTP streamable transport/session lifecycle: Implemented (`tests/test_http_streamable.cpp`)
   - Stdio hardening negative tests: Implemented (idle read timeout, write queue overflow, write timeout, bad Content-Length)
 
 - CI
@@ -69,10 +76,10 @@ Notes:
 
 ---
 
-## Detailed Parity by Spec Area (MCP 2025-06-18)
+## Detailed Parity by Spec Area (MCP 2025-11-25)
 
 - **[Protocol Version]**
-  - Version constant: `PROTOCOL_VERSION = "2025-06-18"`.
+  - Version constant: `PROTOCOL_VERSION = "2025-11-25"`.
   - Source: [include/mcp/Protocol.h](../include/mcp/Protocol.h)
 
 - **[Initialize Handshake & Post-Init Notifications]**
@@ -81,9 +88,10 @@ Notes:
   - Tests: [tests/test_initialize_notifications.cpp](../tests/test_initialize_notifications.cpp)
 
 - **[Capabilities Advertisement]**
-  - `ServerCapabilities` includes `tools`, `resources`, `prompts`, `sampling`, `logging`, and `experimental` map.
+  - `ServerCapabilities` includes `tools`, `resources`, `prompts`, `sampling`, `completions`, `logging`, and `experimental` map.
+  - `ClientCapabilities` includes `roots`, `sampling`, `elicitation`, `experimental`, and `extensions`.
   - Source: [include/mcp/Protocol.h](../include/mcp/Protocol.h)
-  - Logging capability explicitly advertised; parsed by client.
+  - Logging and completion capabilities are explicitly advertised; roots and elicitation are negotiated from the client.
   - Tests: [tests/test_capabilities_logging.cpp](../tests/test_capabilities_logging.cpp)
 
 - **[Tools]**
@@ -106,6 +114,14 @@ Notes:
   - Sources: [include/mcp/Protocol.h](../include/mcp/Protocol.h)
   - Tests: [tests/test_prompts_get.cpp](../tests/test_prompts_get.cpp), [tests/test_client_paging.cpp](../tests/test_client_paging.cpp)
 
+- **[Utilities: Ping, Completion, Roots, Elicitation]**
+  - `ping`: Implemented for client->server and server->client flows.
+  - `completion/complete`: Implemented with strict validation and typed result parsing.
+  - `roots/list` + `notifications/roots/list_changed`: Implemented.
+  - `elicitation/create`: Implemented with strict validation and typed request/result parsing.
+  - Sources: [include/mcp/Protocol.h](../include/mcp/Protocol.h), [src/mcp/Client.cpp](../src/mcp/Client.cpp), [src/mcp/Server.cpp](../src/mcp/Server.cpp)
+  - Tests: [tests/test_completion_ping.cpp](../tests/test_completion_ping.cpp), [tests/test_roots.cpp](../tests/test_roots.cpp), [tests/test_elicitation.cpp](../tests/test_elicitation.cpp)
+
 - **[Sampling (Server → Client)]**
   - Server-initiated `sampling/createMessage` with optional cancelable handler on client.
   - Cancellation via `notifications/cancelled` supported end-to-end.
@@ -146,14 +162,18 @@ Notes:
 - **[Validation (Opt‑In)]**
   - Toggle Off/Strict for runtime shape checks; docs describe API.
   - Sources: [docs/api/validation.md](./api/validation.md)
+  - Strict validators accept richer non-text content blocks, structured tool outputs, and richer prompt/resource payloads.
+  - Tests: [tests/test_content_parity.cpp](../tests/test_content_parity.cpp), [tests/test_validation_strict.cpp](../tests/test_validation_strict.cpp)
 
 - **[Transports]**
   - InMemory: Implemented — [include/mcp/InMemoryTransport.hpp](../include/mcp/InMemoryTransport.hpp)
   - Stdio: Implemented — [include/mcp/StdioTransport.hpp](../include/mcp/StdioTransport.hpp), hardening tests driven by scripts.
   - Shared Memory: Implemented — [include/mcp/SharedMemoryTransport.hpp](../include/mcp/SharedMemoryTransport.hpp)
   - HTTP client: Implemented — [include/mcp/HTTPTransport.hpp](../include/mcp/HTTPTransport.hpp)
   - HTTP server acceptor: Implemented — [include/mcp/HTTPServer.hpp](../include/mcp/HTTPServer.hpp)
+  - Streamable HTTP (`POST` endpoint + `GET` SSE stream + session lifecycle): Implemented.
   - Integration demo test: `TransportDemo.Run` — defined in [tests/CMakeLists.txt](../tests/CMakeLists.txt)
+  - Streamable HTTP tests: [tests/test_http_streamable.cpp](../tests/test_http_streamable.cpp)
 
 - **[OAuth]**
   - Status: Implemented

include/mcp/Client.h

@@ -1,7 +1,7 @@
 //==========================================================================================================
 // SPDX-License-Identifier: MIT
 // Copyright (c) 2025 Vinny Parla
-// File: Client.h
+// File: include/mcp/Client.h
 // Purpose: MCP client interface - COM-style abstraction for MCP client operations
 //==========================================================================================================
 
@@ -236,6 +236,24 @@ class IClient {
     virtual std::future<JSONValue> GetPrompt(const std::string& name,
                                              const JSONValue& arguments) = 0;
 
+    ////////////////////////////////////////// Completion ///////////////////////////////////////////////
+    //==========================================================================================================
+    // Requests argument completions from the server.
+    // Args:
+    //   params: Completion reference and argument context.
+    // Returns:
+    //   Future with typed completion values/metadata.
+    //==========================================================================================================
+    virtual std::future<CompletionResult> Complete(const CompleteParams& params) = 0;
+
+    ////////////////////////////////////////////// Ping //////////////////////////////////////////////////////
+    //==========================================================================================================
+    // Pings the connected server using the MCP ping utility method.
+    // Returns:
+    //   Future that completes once a successful ping response is received.
+    //==========================================================================================================
+    virtual std::future<void> Ping() = 0;
+
     /////////////////////////////////////////// Roots operations ////////////////////////////////////////////////
     //==========================================================================================================
     // Registers a handler for server-initiated roots/list requests.
@@ -282,6 +300,17 @@ class IClient {
         std::stop_token st)>;
     virtual void SetSamplingHandlerCancelable(SamplingHandlerCancelable handler) = 0;
 
+    ///////////////////////////////////////////// Elicitation /////////////////////////////////////////////////
+    //==========================================================================================================
+    // Registers a handler to service server-initiated elicitation/create requests.
+    // Args:
+    //   handler: Async callback returning accept/decline/cancel plus optional content.
+    // Returns:
+    //   (none)
+    //==========================================================================================================
+    using ElicitationHandler = std::function<std::future<ElicitationResult>(const ElicitationRequest&)>;
+    virtual void SetElicitationHandler(ElicitationHandler handler) = 0;
+
     ////////////////////////////////////////// Notification handlers ///////////////////////////////////////////
     //==========================================================================================================
     // Registers a notification handler for a specific method name.
@@ -399,12 +428,15 @@ class Client : public IClient {
                                                     const std::optional<int>& limit) override;
     std::future<JSONValue> GetPrompt(const std::string& name,
                                      const JSONValue& arguments) override;
+    std::future<CompletionResult> Complete(const CompleteParams& params) override;
+    std::future<void> Ping() override;
 
     void SetRootsListHandler(RootsListHandler handler) override;
     std::future<void> NotifyRootsListChanged() override;
 
     void SetSamplingHandler(SamplingHandler handler) override;
     void SetSamplingHandlerCancelable(SamplingHandlerCancelable handler) override;
+    void SetElicitationHandler(ElicitationHandler handler) override;
 
     void SetNotificationHandler(const std::string& method, NotificationHandler handler) override;
     void RemoveNotificationHandler(const std::string& method) override;

include/mcp/HTTPServer.hpp

@@ -1,7 +1,7 @@
 //==========================================================================================================
 // SPDX-License-Identifier: MIT
 // Copyright (c) 2025 Vinny Parla
-// File: HTTPServer.hpp
+// File: include/mcp/HTTPServer.hpp
 // Purpose: Coroutine-based HTTP/HTTPS JSON-RPC server using Boost.Beast (TLS 1.3 only for HTTPS)
 //==========================================================================================================
 
@@ -17,23 +17,27 @@
 
 namespace mcp {
 
-  // Note: HTTPServer implements the server-side acceptor role (ITransportAcceptor)
-  class HTTPServer : public ITransportAcceptor {
+  // Note: HTTPServer implements both the server-side acceptor role and the single-session ITransport role.
+  class HTTPServer : public ITransportAcceptor, public ITransport {
   public:
     //==========================================================================================================
     // Options
     // Purpose: Configuration for bind address/port, JSON-RPC paths, and TLS files.
     // Fields:
     //   address: Bind address (default: 0.0.0.0)
     //   port: Listen port (default: 9443)
-    //   rpcPath: JSON-RPC request path
-    //   notifyPath: JSON-RPC notification path
+    //   endpointPath: Streamable HTTP endpoint path (single POST + GET SSE endpoint). Empty keeps legacy mode.
+    //   streamPath: Optional override for GET SSE. Defaults to endpointPath when empty.
+    //   rpcPath: Legacy JSON-RPC request path
+    //   notifyPath: Legacy JSON-RPC notification path
     //   scheme: "http" or "https" (TLS 1.3 only for https)
     //   certFile/keyFile: PEM files required when scheme == https
     //==========================================================================================================
     struct Options {
         std::string address{"0.0.0.0"};
         std::string port{"9443"};
+        std::string endpointPath;
+        std::string streamPath;
         std::string rpcPath{"/mcp/rpc"};
         std::string notifyPath{"/mcp/notify"};
         std::string scheme{"https"}; // "http" or "https"
@@ -58,6 +62,13 @@ namespace mcp {
     //==========================================================================================================
     std::future<void> Stop() override;
 
+    ////////////////////////////////////////// ITransport //////////////////////////////////////////
+    std::future<void> Close() override;
+    bool IsConnected() const override;
+    std::string GetSessionId() const override;
+    std::future<std::unique_ptr<JSONRPCResponse>> SendRequest(std::unique_ptr<JSONRPCRequest> request) override;
+    std::future<void> SendNotification(std::unique_ptr<JSONRPCNotification> notification) override;
+
     //==========================================================================================================
     // Sets the request handler (JSON-RPC request -> response).
     // Args:
@@ -109,6 +120,7 @@ namespace mcp {
   //          string. The configuration format is uri format, intentionally simple and stable:
   //            - "http://<address>:<port>" (e.g., http://127.0.0.1:0)
   //            - "https://<address>:<port>?cert=<pem>&key=<pem>"
+  //            - optional query params: endpointPath, streamPath, rpcPath, notifyPath
   //          Unknown parameters are ignored. If scheme is omitted, defaults to http.
   //==========================================================================================================
   class HTTPServerFactory : public ITransportAcceptorFactory {