Update docs

V2.21

Author: writePerfectCode

README.md

@@ -0,0 +1,34 @@
+# mcp_stdio demo
+
+This example builds a standalone MCP stdio server process that an MCP host can launch directly.
+
+## What it demonstrates
+
+- `initialize`, `tools/list`, and `tools/call` over MCP stdio
+- `Content-Length` framed JSON-RPC request and response handling
+- one process that exposes both stateless and stateful tools
+- concurrent `tools/call` handling through the MCP stdio server
+
+## Key files
+
+- `mcp_stdio_server_demo.cpp`: demo executable that registers tools and serves MCP over stdio
+- `test_mcp.ps1`: smoke test that drives initialize, tools/list, one stateless call, and one stateful create/call/destroy flow
+
+## Typical use
+
+```powershell
+cmake -S . -B build
+cmake --build build --target mcp_stdio_server_demo
+.\build\mcp_stdio_server_demo.exe
+```
+
+To run the smoke test:
+
+```powershell
+.\examples\mcp_stdio\test_mcp.ps1
+```
+
+## Related guides
+
+- MCP component overview: `../../include/mcp/README.md`
+- top-level project overview: `../../README.md`

examples/mcp_stdio/README.md

@@ -0,0 +1,36 @@
+# func_registry
+
+`func_registry` is the lowest-level public module in `llm_invoke_cpp`.
+
+Use it when you want native function registration and local dispatch without JSON, schema export, scheduling, or protocol adapters.
+
+## What this component does
+
+- registers native free functions, lambdas, and other callables under stable names
+- dispatches calls by name at runtime
+- exposes lightweight function metadata and concise human-readable summaries
+- stays dependency-free apart from the C++ standard library
+
+## Public headers
+
+- `func_registry.hpp`: main registry API and registration entry point
+- `any_callable.hpp`: callable type erasure used by the registry
+- `call_result.hpp`: normalized result wrapper for registry calls
+- `function_traits.hpp`: callable signature extraction helpers
+- `function_summary.hpp`: concise summary rendering for registered functions
+
+## When to stop at this layer
+
+Stay at `func_registry` if your caller already knows C++ types and you only need in-process function lookup and dispatch.
+
+Move up the stack when you need:
+
+- tool-facing metadata: see `include/tool_meta`
+- enum/schema/type metadata: see `include/type_meta`
+- JSON invocation: see `include/json_invoke`
+
+## Related guides
+
+- top-level overview: `../../README.md`
+- tool metadata: `../tool_meta/README.md`
+- type metadata: `../type_meta/README.md`

include/func_registry/README.md

@@ -0,0 +1,35 @@
+# json_invoke
+
+`json_invoke` is the stateless JSON-callable tool layer.
+
+Use it when your caller already speaks JSON and your tools do not need session-scoped object handles.
+
+## What this component does
+
+- registers stateless native functions as JSON-callable tools
+- converts between JSON payloads and native C++ argument and return types
+- exports tool summaries, tool specs, and JSON schemas
+- exposes tracing hooks for invocation-level observability
+
+## Public headers
+
+- `json_invoke.hpp`: main stateless JSON invocation adapter
+- `json_introspection.hpp`: standalone JSON tool and schema export helpers
+- `json_error.hpp`: `JsonInvokeError` definition
+- `json_tool_execution_semantics.hpp`: execution semantics metadata helpers
+- `json_trace.hpp`: tracing event model and JSON serialization helpers
+- `json_traits.hpp`: custom JSON binding hook for user types
+
+## Choose this layer when
+
+- your request envelope is already JSON-based
+- tools are stateless
+- you want schema export but do not need session object lifecycles or scheduling
+
+Move up to `json_session_invoke` when you need `create -> method -> destroy` flows.
+
+## Related guides
+
+- type metadata: `../type_meta/README.md`
+- session tools: `../json_session_invoke/README.md`
+- tracing helper utilities: `../tools/README.md`

include/json_invoke/README.md

@@ -0,0 +1,33 @@
+# json_session_invoke
+
+`json_session_invoke` is the high-level session and stateful-tool layer.
+
+Use it when one JSON-facing adapter should host both stateless tools and stateful object lifecycles such as `create -> method -> destroy`.
+
+## What this component does
+
+- composes `json_invoke` into one session-oriented adapter
+- models opaque session object handles and object options
+- registers factories, stateful methods, and destroy tools
+- overlays tool schemas so LLM-facing contracts stay handle-oriented
+- exposes readonly metadata that upper scheduling layers use for classification
+
+## Public headers
+
+- `json_session_invoke.hpp`: main session-oriented adapter and fluent stateful builder
+- `session_objects.hpp`: public handle and object option types
+
+`detail/` contains implementation internals and is not part of the public surface.
+
+## Choose this layer when
+
+- tools need per-session state
+- one adapter should mix stateless and stateful tools
+- you want scheduler-facing metadata without building scheduling policy here
+
+Move up to `task_scheduler` when multiple requests must be classified and coordinated safely.
+
+## Related guides
+
+- stateless JSON tools: `../json_invoke/README.md`
+- scheduling layer: `../task_scheduler/README.md`

include/json_session_invoke/README.md

@@ -61,10 +61,10 @@ class BasicJsonSessionInvokeAdapter {
     class StatefulRegistrationBuilder {
     public:
         StatefulRegistrationBuilder(
-            BasicJsonSessionInvokeAdapter& adapter,
+            BasicJsonSessionInvokeAdapter& json_session_invoke_adapter,
             std::string configured_object_type_name,
             ObjectOptions options)
-            : adapter_(adapter)
+            : json_session_invoke_adapter_(json_session_invoke_adapter)
             , configured_object_type_name_(std::move(configured_object_type_name))
             , options_(std::move(options))
         {
@@ -74,7 +74,7 @@ class BasicJsonSessionInvokeAdapter {
         StatefulRegistrationBuilder& operator=(const StatefulRegistrationBuilder&) = delete;
 
         StatefulRegistrationBuilder(StatefulRegistrationBuilder&& other) noexcept
-            : adapter_(other.adapter_)
+            : json_session_invoke_adapter_(other.json_session_invoke_adapter_)
             , configured_object_type_name_(std::move(other.configured_object_type_name_))
             , options_(std::move(other.options_))
             , created_(other.created_)
@@ -304,7 +304,8 @@ class BasicJsonSessionInvokeAdapter {
         {
             return registerDestroyWithMetadata(
                 destroy_tool_name,
-                BasicJsonSessionInvokeAdapter::makeDestroyMetadata(adapter_.defaultDestroyDescription()),
+                BasicJsonSessionInvokeAdapter::makeDestroyMetadata(
+                    json_session_invoke_adapter_.defaultDestroyDescription()),
                 scheduling_scope);
         }
 
@@ -369,7 +370,7 @@ class BasicJsonSessionInvokeAdapter {
             func_registry::FunctionMetadata metadata,
             ToolSchedulingScope scheduling_scope)
         {
-            adapter_.template registerFactory<T>(
+            json_session_invoke_adapter_.template registerFactory<T>(
                 factory_tool_name,
                 std::forward<Fn>(fn),
                 std::move(metadata),
@@ -388,7 +389,7 @@ class BasicJsonSessionInvokeAdapter {
             ToolSchedulingScope scheduling_scope)
         {
             validateMethodType<Fn>();
-            adapter_.template registerStatefulMethod<T>(
+            json_session_invoke_adapter_.template registerStatefulMethod<T>(
                 method_tool_name,
                 std::forward<Fn>(fn),
                 std::move(metadata),
@@ -401,21 +402,25 @@ class BasicJsonSessionInvokeAdapter {
             func_registry::FunctionMetadata metadata,
             ToolSchedulingScope scheduling_scope)
         {
-            adapter_.template registerDestroy<T>(destroy_tool_name, std::move(metadata), scheduling_scope);
+            json_session_invoke_adapter_.template registerDestroy<T>(
+                destroy_tool_name,
+                std::move(metadata),
+                scheduling_scope);
             destroy_registered_ = true;
             return *this;
         }
 
         void ensureDefaultDestroyRegistered() noexcept
         {
-            if (!active_ || !created_ || destroy_registered_ || !adapter_.stateful_defaults_.auto_register_destroy)
+            if (!active_ || !created_ || destroy_registered_
+                || !json_session_invoke_adapter_.stateful_defaults_.auto_register_destroy)
             {
                 return;
             }
 
             destroy_registered_ = true;
             const std::string destroy_tool_name = defaultDestroyToolName();
-            if (adapter_.isFunctionRegistered(destroy_tool_name))
+            if (json_session_invoke_adapter_.isFunctionRegistered(destroy_tool_name))
             {
                 return;
             }
@@ -424,7 +429,8 @@ class BasicJsonSessionInvokeAdapter {
             {
                 registerDestroyWithMetadata(
                     destroy_tool_name,
-                    BasicJsonSessionInvokeAdapter::makeDestroyMetadata(adapter_.defaultDestroyDescription()),
+                    BasicJsonSessionInvokeAdapter::makeDestroyMetadata(
+                        json_session_invoke_adapter_.defaultDestroyDescription()),
                     ToolSchedulingScope::object_lane);
             }
             catch (...)
@@ -458,7 +464,7 @@ class BasicJsonSessionInvokeAdapter {
             return BasicJsonSessionInvokeAdapter::defaultDestroyToolName(configured_object_type_name_);
         }
 
-        BasicJsonSessionInvokeAdapter& adapter_;
+        BasicJsonSessionInvokeAdapter& json_session_invoke_adapter_;
         std::string configured_object_type_name_;
         ObjectOptions options_;
         bool created_{false};

include/json_session_invoke/json_session_invoke.hpp

@@ -0,0 +1,28 @@
+# mcp
+
+`mcp` contains the protocol-facing adapters that expose the native tool runtime to real MCP clients.
+
+Use it when you want to serve tools over MCP stdio or host MCP semantics behind an HTTP endpoint.
+
+## What this component does
+
+- implements MCP stdio request/response handling with `Content-Length` framing
+- maps normalized runtime results into MCP response shapes
+- provides a framework-agnostic HTTP gateway core for one MCP endpoint
+
+## Public headers
+
+- `mcp_stdio_server.hpp`: stdio JSON-RPC MCP server built on top of `tool_runtime`
+- `mcp_http_gateway.hpp`: framework-agnostic HTTP MCP core
+
+## Choose this layer when
+
+- a real MCP-capable host or client should talk to your native tools
+- transport concerns should stay above the runtime and scheduling layers
+
+## Related guides
+
+- protocol-neutral runtime: `../tool_runtime/README.md`
+- stdio demo: `../../examples/mcp_stdio/README.md`
+- HTTP demo: `../../examples/mcp_http/README.md`
+- LLM-host demo: `../../examples/mcp_llm/README.md`

include/mcp/README.md

@@ -21,7 +21,7 @@
 #include <utility>
 #include <vector>
 
-#include <runtime/runtime_facade.hpp>
+#include <tool_runtime/tool_runtime_facade.hpp>
 
 namespace mcp {
 
@@ -258,11 +258,6 @@ class BasicMcpStdioServer {
                 return makeSuccessResponse(id, handleToolsList(params));
             }
 
-            if (method == "tools/call")
-            {
-                return handleToolsCall(id, params);
-            }
-
             return makeErrorResponse(id, -32601, "Method not found: " + method);
         }
         catch (const json_invoke::JsonInvokeError& e)

include/mcp/mcp_stdio_server.hpp

@@ -0,0 +1,30 @@
+# task_scheduler
+
+`task_scheduler` separates request classification and execution policy from the session adapter.
+
+Use it when JSON tool requests may overlap and you need predictable concurrency rules.
+
+## What this component does
+
+- classifies requests into scheduling categories such as free-read, object-exclusive, tool-exclusive, factory-lane, and session-barrier
+- queues and runs classified tasks with keyed exclusivity rules
+- exposes a one-step facade for submit-and-wait style callers
+
+## Public headers
+
+- `request_classifier.hpp`: derives scheduling plans from tool metadata and request shape
+- `task_scheduler.hpp`: scheduler-side abstractions and keyed scheduler implementation
+- `task_scheduler_facade.hpp`: one-object facade that hides classify + queue + invoke
+
+## Choose this layer when
+
+- requests are JSON-based and may run concurrently
+- concurrency policy should be explicit and reusable
+- protocol adapters should not directly own queueing logic
+
+Move up to `tool_runtime` when a protocol adapter wants normalized tool descriptors and invoke results.
+
+## Related guides
+
+- session adapter: `../json_session_invoke/README.md`
+- protocol-neutral runtime layer: `../tool_runtime/README.md`

include/task_scheduler/README.md

@@ -31,13 +31,14 @@ struct TaskExecutionPlan {
 template<bool EnableThreadSafety = false>
 class BasicRequestClassifier {
 public:
-    using AdapterType = json_session_invoke::BasicJsonSessionInvokeAdapter<EnableThreadSafety>;
-    using ToolSchedulingScope = typename AdapterType::ToolSchedulingScope;
-    using ToolMetadataView = typename AdapterType::ToolMetadataView;
-    using ToolStatefulKind = typename AdapterType::ToolStatefulKind;
-
-    explicit BasicRequestClassifier(const AdapterType& adapter)
-        : adapter_(adapter)
+    using JsonSessionInvokeAdapterType =
+        json_session_invoke::BasicJsonSessionInvokeAdapter<EnableThreadSafety>;
+    using ToolSchedulingScope = typename JsonSessionInvokeAdapterType::ToolSchedulingScope;
+    using ToolMetadataView = typename JsonSessionInvokeAdapterType::ToolMetadataView;
+    using ToolStatefulKind = typename JsonSessionInvokeAdapterType::ToolStatefulKind;
+
+    explicit BasicRequestClassifier(const JsonSessionInvokeAdapterType& json_session_invoke_adapter)
+        : json_session_invoke_adapter_(json_session_invoke_adapter)
     {
     }
 
@@ -63,7 +64,7 @@ class BasicRequestClassifier {
 private:
     TaskExecutionPlan classifyParsedRequest(const std::string& tool_name, const json& args) const
     {
-        const auto metadata = adapter_.findToolMetadata(tool_name);
+        const auto metadata = json_session_invoke_adapter_.findToolMetadata(tool_name);
         if (!metadata.has_value())
         {
             throw JsonInvokeError("function_not_found", "function not found: " + tool_name);
@@ -234,7 +235,7 @@ class BasicRequestClassifier {
         return SchedulingKey{object_id};
     }
 
-    const AdapterType& adapter_;
+    const JsonSessionInvokeAdapterType& json_session_invoke_adapter_;
 };
 
 using RequestClassifierThreadSafe = BasicRequestClassifier<true>;