Add remote mcp server and demo

V2.13

Author: writePerfectCode

CMakeLists.txt

@@ -80,6 +80,7 @@ if(BUILD_TESTING)
         tests/test_main.cpp
         tests/func_registry_tests.cpp
         tests/json_invoke_tests.cpp
+        tests/mcp_http_gateway_tests.cpp
         tests/json_stateful_tests.cpp
         tests/mcp_stdio_tests.cpp
         tests/runtime_tests.cpp
@@ -99,12 +100,50 @@ if(BUILD_TESTING)
 endif()
 
 if(LLM_INVOKE_CPP_BUILD_EXAMPLES)
+    set(CPP_HTTPLIB_VERSION v0.18.6)
+    set(CPP_HTTPLIB_DIR ${CMAKE_CURRENT_BINARY_DIR}/_deps/cpp_httplib)
+    set(CPP_HTTPLIB_HEADER ${CPP_HTTPLIB_DIR}/httplib.h)
+
+    file(MAKE_DIRECTORY ${CPP_HTTPLIB_DIR})
+    set(CPP_HTTPLIB_NEEDS_DOWNLOAD ON)
+    if(EXISTS ${CPP_HTTPLIB_HEADER})
+        file(SIZE ${CPP_HTTPLIB_HEADER} CPP_HTTPLIB_HEADER_SIZE)
+        if(CPP_HTTPLIB_HEADER_SIZE GREATER 0)
+            set(CPP_HTTPLIB_NEEDS_DOWNLOAD OFF)
+        endif()
+    endif()
+
+    if(CPP_HTTPLIB_NEEDS_DOWNLOAD)
+        file(DOWNLOAD
+            https://raw.githubusercontent.com/yhirose/cpp-httplib/${CPP_HTTPLIB_VERSION}/httplib.h
+            ${CPP_HTTPLIB_HEADER}
+            STATUS cpp_httplib_download_status
+            TLS_VERIFY ON
+        )
+
+        list(GET cpp_httplib_download_status 0 cpp_httplib_download_code)
+        list(GET cpp_httplib_download_status 1 cpp_httplib_download_message)
+        if(NOT cpp_httplib_download_code EQUAL 0)
+            message(FATAL_ERROR "Failed to download cpp-httplib header: ${cpp_httplib_download_message}")
+        endif()
+    endif()
+
     add_executable(func_registry_demo examples/func_registry/func_registry_demo.cpp)
     target_link_libraries(func_registry_demo PRIVATE llm_invoke_cpp::func_registry)
 
     add_executable(mcp_stdio_server_demo examples/mcp_stdio/mcp_stdio_server_demo.cpp)
     target_link_libraries(mcp_stdio_server_demo PRIVATE llm_invoke_cpp::mcp)
 
+    add_executable(mcp_http_gateway_demo examples/mcp_http/mcp_http_gateway_demo.cpp)
+    target_include_directories(mcp_http_gateway_demo PRIVATE ${CPP_HTTPLIB_DIR})
+    target_link_libraries(mcp_http_gateway_demo PRIVATE llm_invoke_cpp::mcp)
+    if(MINGW)
+        target_compile_options(mcp_http_gateway_demo PRIVATE -Wa,-mbig-obj)
+    endif()
+    if(WIN32)
+        target_link_libraries(mcp_http_gateway_demo PRIVATE ws2_32)
+    endif()
+
     add_executable(json_invoke_demo examples/json_invoke/json_invoke_demo.cpp)
     target_link_libraries(json_invoke_demo PRIVATE llm_invoke_cpp::json_invoke)
 

README.md

@@ -11,7 +11,7 @@ It is split into eight public modules:
 - `include/json_session_invoke`: higher-level session/runtime APIs built on top of `json_invoke` for stateful create/call/destroy flows.
 - `include/task_scheduler`: task classification and scheduling helpers built on top of `json_session_invoke`.
 - `include/runtime`: protocol-neutral runtime facade built on top of `task_scheduler` for normalized tool listing and unary invocation.
-- `include/mcp`: MCP-specific adapters built on top of `runtime` for protocol-facing transports such as stdio.
+- `include/mcp`: MCP-specific adapters built on top of `runtime` for protocol-facing transports such as stdio and a framework-agnostic HTTP gateway core.
 
 Project layout
 
@@ -35,7 +35,9 @@ Project layout
 - `include/task_scheduler/task_scheduler.hpp`: scheduler-side task abstractions, including a minimal `ITaskScheduler` interface and a keyed scheduler that enforces session-wide and per-object exclusivity.
 - `include/runtime/runtime_facade.hpp`: protocol-neutral facade that projects exported tool schemas into normalized descriptors and turns scheduler-backed JSON requests into normalized invoke results.
 - `include/mcp/mcp_stdio_server.hpp`: minimal MCP stdio server that handles JSON-RPC framing plus `initialize`, `ping`, `tools/list`, and `tools/call` on top of the runtime facade.
+- `include/mcp/mcp_http_gateway.hpp`: framework-agnostic HTTP request/session gateway core for one MCP endpoint backed by session objects.
 - `examples/func_registry/func_registry_demo.cpp`: core-only registry example.
+- `examples/mcp_http/mcp_http_gateway_demo.cpp`: cpp-httplib demo that mounts one `/mcp` endpoint and routes HTTP requests through the framework-agnostic gateway core.
 - `examples/mcp_stdio/mcp_stdio_server_demo.cpp`: standalone MCP stdio server process that exposes demo tools and can be launched directly by an MCP host.
 - `examples/json_invoke/json_invoke_demo.cpp`: JSON invocation example.
 - `examples/json_stateful/json_stateful_demo.cpp`: stateful object-handle example for create/call/destroy flows.
@@ -162,6 +164,7 @@ API notes
 - `runtime::RuntimeFacadeThreadSafe`: protocol-neutral entry point above `task_scheduler`; `listTools()` returns normalized tool descriptors, `submitInvoke(...)` schedules one unary call and returns `std::future<runtime::InvokeResult>`, and `invoke(...)` gives the same normalized result synchronously.
 - `runtime::InvokeResult`: normalized invoke envelope with `ok`, `value`, optional `error`, and the original `raw_response`; classification-time failures such as unknown tools are converted into the same error shape instead of leaking exceptions to protocol adapters.
 - `mcp::McpStdioServerThreadSafe`: thin MCP adapter over `runtime::RuntimeFacadeThreadSafe`; it reads and writes `Content-Length` framed JSON-RPC messages and `serveConcurrent(...)` keeps multiple `tools/call` requests in flight on one stdio session while `initialize`, `ping`, and `tools/list` remain ordered.
+- `mcp::HttpMcpGateway`: framework-agnostic POST `/mcp` core that validates basic HTTP semantics, allocates MCP sessions on `initialize`, requires `Mcp-Session-Id` afterwards, and leaves server startup/routing to whichever HTTP framework hosts it.
 - `mcp::McpStdioServerThreadSafe::handleMessage(...)`: useful when you want protocol handling without a real stdio loop, for example in tests or when embedding the MCP adapter into another transport shim.
 
 MCP stdio demo
@@ -170,6 +173,13 @@ MCP stdio demo
 - The demo server registers `sum`, `slow_sum`, `echo_text`, `create_counter`, `counter_add`, `counter_value`, and `destroy_counter`.
 - The process writes only framed MCP responses to stdout; startup notes, `slow_sum` overlap logs, and fatal errors go to stderr.
 - `examples/mcp_stdio/test_mcp.ps1` now runs a fuller smoke test against the demo executable: initialize, tools/list, one stateless `sum` call, then a stateful `create_counter -> counter_add -> counter_value -> destroy_counter` flow.
+
+MCP HTTP demo
+
+- Build `mcp_http_gateway_demo` when you want a single `/mcp` HTTP endpoint hosted by cpp-httplib while keeping MCP/HTTP semantics inside `mcp::HttpMcpGateway`.
+- The demo keeps one stdio child-process MCP session per `Mcp-Session-Id`; initialize launches `mcp_stdio_server_demo`, later requests reuse that backend process, and clients must send the returned session header.
+- Pass `--backend-executable <path>` when the stdio backend is not discoverable next to the HTTP gateway binary or under `build/`.
+- On Windows, `mcp_stdio_server_demo` switches stdin/stdout to binary mode so MCP `Content-Length` framing survives stdio transport without CRLF expansion.
 - The fluent builder also supports `.options(...)`, so object type selection and session object options can be expressed separately: `.stateful<T>("counter").options(opts)...`.
 - When `.stateful<T>("counter")` uses `.create(...)` without an explicit tool name, the builder defaults to `create_counter`.
 - If a stateful builder creates an object but omits `.destroy()`, the adapter auto-registers the default `destroy_<object_type>` tool unless `setStatefulDefaults(...)` disables `auto_register_destroy`.