tool.hpp

Go to the documentation of this file.

// Copyright (c) 2025 [caomengxuan666]
 
#pragma once
 
 
#include <algorithm>
#include <cctype>
#include <cstdint>
#include <optional>
#include <string>
#include <string_view>
#include <unordered_map>
#include <unordered_set>
#include <utility>
#include <vector>
 
#include "cxxmcp/core/result.hpp"
#include "cxxmcp/protocol/annotations.hpp"
#include "cxxmcp/protocol/resource.hpp"
#include "cxxmcp/protocol/schema.hpp"
#include "cxxmcp/protocol/task.hpp"
#include "cxxmcp/protocol/types.hpp"
#include "cxxmcp/protocol/types_reflect.hpp"
 
namespace mcp::protocol {
 
enum class TaskSupport {
  Forbidden,
  Optional,
  Required,
};
 
struct ToolExecution {
  std::optional<TaskSupport> task_support;
 
  ToolExecution& with_task_support(TaskSupport value) & {
    task_support = value;
    return *this;
  }
 
  ToolExecution&& with_task_support(TaskSupport value) && {
    task_support = value;
    return std::move(*this);
  }
};
 
template <>
struct Reflect<ToolExecution> {
  static constexpr bool defined = true;
  static auto fields() {
    return std::make_tuple(field("taskSupport", &ToolExecution::task_support));
  }
  static std::vector<std::string> known_keys() { return {"taskSupport"}; }
};
CXXMCP_REFLECT_CHECK(ToolExecution, 1);
 
template <>
struct JsonFieldTraits<ToolExecution> {
  static void serialize(Json& json, const char* key,
                        const ToolExecution& value) {
    json[key] = reflect_to_json(value);
  }
  static bool deserialize(const Json& json, const char* key,
                          ToolExecution& target) {
    if (!json.contains(key)) {
      return false;
    }
    auto result = reflect_from_json<ToolExecution>(json.at(key));
    if (!result) {
      return false;
    }
    target = std::move(*result);
    return true;
  }
};
 
struct ContentBlock {
  std::string type = "text";
  std::string text;
  Json data = Json::object();
  std::string mime_type;
  std::optional<ResourceContents> resource;
  std::optional<Resource> resource_link;
  Json annotations = Json::object();
  std::optional<Json> meta;
  Json extensions = Json::object();
 
  static ContentBlock text_content(std::string value) {
    ContentBlock block;
    block.type = "text";
    block.text = std::move(value);
    return block;
  }
 
  static ContentBlock image(std::string base64_data, std::string mime_type) {
    ContentBlock block;
    block.type = "image";
    block.data = std::move(base64_data);
    block.mime_type = std::move(mime_type);
    return block;
  }
 
  static ContentBlock audio(std::string base64_data, std::string mime_type) {
    ContentBlock block;
    block.type = "audio";
    block.data = std::move(base64_data);
    block.mime_type = std::move(mime_type);
    return block;
  }
 
  static ContentBlock embedded_resource(ResourceContents value) {
    ContentBlock block;
    block.type = "resource";
    block.resource = std::move(value);
    return block;
  }
 
  static ContentBlock resource_link_content(Resource value) {
    ContentBlock block;
    block.type = "resource_link";
    block.resource_link = std::move(value);
    return block;
  }
 
  bool is_text() const noexcept { return type == "text"; }
 
  bool is_image() const noexcept { return type == "image"; }
 
  bool is_audio() const noexcept { return type == "audio"; }
 
  bool is_embedded_resource() const noexcept { return type == "resource"; }
 
  bool is_resource_link() const noexcept { return type == "resource_link"; }
 
  std::optional<std::string_view> as_text() const noexcept {
    if (!is_text()) {
      return std::nullopt;
    }
    return std::string_view(text);
  }
 
  std::optional<std::string_view> as_image_data() const {
    if (!is_image() || !data.is_string()) {
      return std::nullopt;
    }
    return std::string_view(data.get_ref<const std::string&>());
  }
 
  std::optional<std::string_view> as_audio_data() const {
    if (!is_audio() || !data.is_string()) {
      return std::nullopt;
    }
    return std::string_view(data.get_ref<const std::string&>());
  }
 
  const ResourceContents* as_embedded_resource() const noexcept {
    if (!is_embedded_resource() || !resource.has_value()) {
      return nullptr;
    }
    return &*resource;
  }
 
  const Resource* as_resource_link() const noexcept {
    if (!is_resource_link() || !resource_link.has_value()) {
      return nullptr;
    }
    return &*resource_link;
  }
};
 
struct ToolDefinition {
  std::string title;
  std::string name;
  std::string description;
  Json input_schema = Json::object();
  Json output_schema = Json::object();
  bool output_schema_present = false;
  bool streaming = false;
  std::vector<Icon> icons;
  std::optional<ToolExecution> execution;
  std::optional<ToolAnnotations> tool_annotations;
  Json annotations = Json::object();
  std::optional<Json> meta;
  Json extensions = Json::object();
 
  TaskSupport task_support() const noexcept {
    if (!execution.has_value() || !execution->task_support.has_value()) {
      return TaskSupport::Forbidden;
    }
    return *execution->task_support;
  }
};
 
class ToolDefinitionBuilder {
 public:
  explicit ToolDefinitionBuilder(std::string name) {
    definition_.name = std::move(name);
  }
 
  ToolDefinitionBuilder& title(std::string value) {
    definition_.title = std::move(value);
    return *this;
  }
 
  ToolDefinitionBuilder& description(std::string value) {
    definition_.description = std::move(value);
    return *this;
  }
 
  ToolDefinitionBuilder& input_schema(Json schema) {
    definition_.input_schema = std::move(schema);
    return *this;
  }
 
  template <class T>
  ToolDefinitionBuilder& input() {
    return input_schema(schema_for<T>());
  }
 
  ToolDefinitionBuilder& output_schema(Json schema) {
    definition_.output_schema = std::move(schema);
    definition_.output_schema_present = true;
    return *this;
  }
 
  template <class T>
  ToolDefinitionBuilder& output() {
    return output_schema(schema_for<T>());
  }
 
  ToolDefinitionBuilder& streaming(bool value = true) {
    definition_.streaming = value;
    return *this;
  }
 
  ToolDefinitionBuilder& icon(Icon value) {
    definition_.icons.push_back(std::move(value));
    return *this;
  }
 
  ToolDefinitionBuilder& task_support(TaskSupport value) {
    if (!definition_.execution.has_value()) {
      definition_.execution = ToolExecution{};
    }
    definition_.execution->task_support = value;
    return *this;
  }
 
  ToolDefinitionBuilder& annotations(Json value) {
    definition_.annotations = std::move(value);
    return *this;
  }
 
  ToolDefinitionBuilder& tool_annotations(ToolAnnotations value) {
    definition_.tool_annotations = std::move(value);
    return *this;
  }
 
  ToolDefinitionBuilder& meta(Json value) {
    definition_.meta = std::move(value);
    return *this;
  }
 
  ToolDefinition build() const& { return definition_; }
 
  ToolDefinition build() && { return std::move(definition_); }
 
 private:
  ToolDefinition definition_;
};
 
inline ToolDefinitionBuilder tool_definition(std::string name) {
  return ToolDefinitionBuilder(std::move(name));
}
 
struct ToolCall {
  std::string name;
  Json arguments = Json::object();
  std::optional<TaskRequestParameters> task;
  std::optional<Json> meta;
  std::optional<std::string> request_state;
  std::optional<Json> input_responses;
  Json extensions = Json::object();
};
 
template <>
struct Reflect<ToolCall> {
  static constexpr bool defined = true;
  static auto fields() {
    return std::make_tuple(
        field("name", &ToolCall::name),
        field("arguments", &ToolCall::arguments),
        field("task", &ToolCall::task), field("_meta", &ToolCall::meta),
        field("requestState", &ToolCall::request_state),
        field("inputResponses", &ToolCall::input_responses),
        extensions_field(&ToolCall::extensions,
                         {"name", "arguments", "task", "_meta", "requestState",
                          "inputResponses"}));
  }
  static std::vector<std::string> known_keys() {
    return {"name",  "arguments",    "task",
            "_meta", "requestState", "inputResponses"};
  }
};
 
struct ToolsListResult {
  std::vector<ToolDefinition> tools;
  std::optional<std::string> next_cursor;
  std::optional<Json> meta;
  Json extensions = Json::object();
  std::optional<std::int64_t> ttl_ms;
  std::optional<std::string> cache_scope;
};
 
struct ToolResult {
  std::vector<ContentBlock> content;
  std::optional<Json> structured_content;
  std::optional<bool> is_error;
  std::optional<Json> meta;
  std::optional<std::string> result_type;
  std::optional<Json> input_requests;
  std::optional<std::string> request_state;
  Json extensions = Json::object();
 
  bool is_error_result() const noexcept { return is_error.value_or(false); }
 
  static ToolResult text(std::string value) {
    ToolResult result;
    result.content.push_back(ContentBlock::text_content(std::move(value)));
    result.is_error = false;
    return result;
  }
 
  static ToolResult error_text(std::string value) {
    ToolResult result = text(std::move(value));
    result.is_error = true;
    return result;
  }
};
 
inline core::Error tool_json_error(std::string message) {
  return core::Error{
      static_cast<int>(ErrorCode::InvalidRequest), std::move(message), {}};
}
 
inline std::string_view task_support_to_string(TaskSupport support) noexcept {
  switch (support) {
    case TaskSupport::Forbidden:
      return "forbidden";
    case TaskSupport::Optional:
      return "optional";
    case TaskSupport::Required:
      return "required";
  }
  return "forbidden";
}
 
inline std::optional<TaskSupport> task_support_from_string(
    std::string_view value) noexcept {
  if (value == "forbidden") {
    return TaskSupport::Forbidden;
  }
  if (value == "optional") {
    return TaskSupport::Optional;
  }
  if (value == "required") {
    return TaskSupport::Required;
  }
  return std::nullopt;
}
 
template <>
struct JsonFieldTraits<TaskSupport> {
  static void serialize(Json& json, const char* key, TaskSupport value) {
    json[key] = std::string(task_support_to_string(value));
  }
  static bool deserialize(const Json& json, const char* key,
                          TaskSupport& target) {
    if (!json.contains(key) || !json.at(key).is_string()) {
      return false;
    }
    auto val =
        task_support_from_string(json.at(key).get_ref<const std::string&>());
    if (!val.has_value()) {
      return false;
    }
    target = *val;
    return true;
  }
};
 
inline bool is_valid_base64(std::string_view value) noexcept {
  if (value.empty()) {
    return true;
  }
  if (value.size() % 4 != 0) {
    return false;
  }
 
  std::size_t padding = 0;
  if (value.back() == '=') {
    ++padding;
    if (value.size() >= 2 && value[value.size() - 2] == '=') {
      ++padding;
    }
  }
 
  for (std::size_t i = 0; i < value.size(); ++i) {
    const unsigned char c = static_cast<unsigned char>(value[i]);
    const bool is_base64_char = (c >= 'A' && c <= 'Z') ||
                                (c >= 'a' && c <= 'z') ||
                                (c >= '0' && c <= '9') || c == '+' || c == '/';
    if (is_base64_char) {
      continue;
    }
    if (c == '=' && i >= value.size() - padding) {
      continue;
    }
    return false;
  }
 
  return true;
}
 
inline Json tool_execution_to_json(const ToolExecution& execution) {
  return reflect_to_json(execution);
}
 
inline core::Result<ToolExecution> tool_execution_from_json(const Json& json) {
  return reflect_from_json<ToolExecution>(json);
}
 
inline Json content_block_to_json(const ContentBlock& block) {
  Json json = Json::object();
  json["type"] = block.type;
  if (block.type == "resource" && block.resource.has_value()) {
    json["resource"] = resource_contents_to_json(*block.resource);
  } else if (block.type == "resource_link" && block.resource_link.has_value()) {
    json = resource_to_json(*block.resource_link);
    json["type"] = block.type;
  } else {
    if (!block.text.empty() || block.type == "text") {
      json["text"] = block.text;
    }
    if (((block.type == "image" || block.type == "audio") &&
         block.data.is_string()) ||
        !block.data.empty()) {
      json["data"] = block.data;
    }
    if (!block.mime_type.empty()) {
      json["mimeType"] = block.mime_type;
    }
  }
  if (!block.annotations.empty()) {
    json["annotations"] = block.annotations;
  }
  if (block.meta.has_value()) {
    json["_meta"] = *block.meta;
  }
  append_json_extensions(json, block.extensions);
  return json;
}
 
inline core::Result<std::string> required_content_string(
    const Json& json, std::string_view member, std::string message) {
  const std::string key(member);
  if (!json.contains(key) || !json.at(key).is_string()) {
    return mcp::core::unexpected(tool_json_error(std::move(message)));
  }
  return json.at(key).get<std::string>();
}
 
inline core::Result<ContentBlock> content_block_from_json(const Json& json) {
  if (!json.is_object()) {
    return mcp::core::unexpected(
        tool_json_error("content block must be an object"));
  }
 
  ContentBlock block;
  if (!json.contains("type") || !json.at("type").is_string()) {
    return mcp::core::unexpected(
        tool_json_error("content block requires a string type"));
  }
  block.type = json.at("type").get<std::string>();
 
  if (block.type == "image" || block.type == "audio") {
    const auto data = required_content_string(
        json, "data", block.type + " content block requires string data");
    if (!data) {
      return mcp::core::unexpected(data.error());
    }
    const auto mime_type = required_content_string(
        json, "mimeType",
        block.type + " content block requires string mimeType");
    if (!mime_type) {
      return mcp::core::unexpected(mime_type.error());
    }
    if (!is_valid_base64(*data)) {
      return mcp::core::unexpected(
          tool_json_error(block.type + " content block data must be base64"));
    }
    block.data = *data;
    block.mime_type = *mime_type;
  } else if (block.type == "resource") {
    if (!json.contains("resource")) {
      return mcp::core::unexpected(
          tool_json_error("resource content block requires resource"));
    }
    const auto resource = resource_contents_from_json(json.at("resource"));
    if (!resource) {
      return mcp::core::unexpected(resource.error());
    }
    block.resource = *resource;
  } else if (block.type == "resource_link") {
    const auto resource = resource_from_json(json);
    if (!resource) {
      return mcp::core::unexpected(resource.error());
    }
    block.resource_link = *resource;
  } else if (block.type == "text") {
    const auto text = required_content_string(
        json, "text", "text content block requires string text");
    if (!text) {
      return mcp::core::unexpected(text.error());
    }
    block.text = *text;
  } else {
    return mcp::core::unexpected(
        tool_json_error("content block type is not supported"));
  }
 
  if (json.contains("annotations")) {
    const auto parsed = annotations_from_json(json.at("annotations"));
    if (!parsed) {
      return mcp::core::unexpected(parsed.error());
    }
    block.annotations = annotations_to_json(*parsed);
  }
  if (json.contains("_meta")) {
    if (!json.at("_meta").is_object()) {
      return mcp::core::unexpected(
          tool_json_error("content block _meta must be an object"));
    }
    block.meta = json.at("_meta");
  }
  block.extensions = collect_json_extensions(
      json,
      {"type", "text", "data", "mimeType", "resource", "uri", "name", "title",
       "description", "mimeType", "size", "icons", "annotations", "_meta"});
 
  return block;
}
 
inline Json tool_definition_to_json(const ToolDefinition& definition) {
  Json json = Json::object();
  if (!definition.title.empty()) {
    json["title"] = definition.title;
  }
  json["name"] = definition.name;
  if (!definition.description.empty()) {
    json["description"] = definition.description;
  }
  json["inputSchema"] = definition.input_schema;
  if (definition.output_schema_present || !definition.output_schema.empty()) {
    json["outputSchema"] = definition.output_schema;
  }
  if (definition.streaming) {
    json["streaming"] = definition.streaming;
  }
  if (!definition.icons.empty()) {
    json["icons"] = Json::array();
    for (const auto& icon : definition.icons) {
      json["icons"].push_back(icon_to_json(icon));
    }
  }
  if (definition.execution.has_value()) {
    json["execution"] = tool_execution_to_json(*definition.execution);
  }
  if (definition.tool_annotations.has_value()) {
    json["annotations"] =
        tool_annotations_to_json(*definition.tool_annotations);
  } else if (!definition.annotations.empty()) {
    json["annotations"] = definition.annotations;
  }
  if (definition.meta.has_value()) {
    json["_meta"] = *definition.meta;
  }
  append_json_extensions(json, definition.extensions);
  return json;
}
 
inline core::Result<ToolDefinition> tool_definition_from_json(
    const Json& json) {
  if (!json.is_object()) {
    return mcp::core::unexpected(
        tool_json_error("tool definition must be an object"));
  }
 
  ToolDefinition definition;
  if (json.contains("title")) {
    if (!json.at("title").is_string()) {
      return mcp::core::unexpected(
          tool_json_error("tool definition title must be a string"));
    }
    definition.title = json.at("title").get<std::string>();
  }
  if (!json.contains("name") || !json.at("name").is_string()) {
    return mcp::core::unexpected(
        tool_json_error("tool definition requires a string name"));
  }
  definition.name = json.at("name").get<std::string>();
 
  if (json.contains("description")) {
    if (!json.at("description").is_string()) {
      return mcp::core::unexpected(
          tool_json_error("tool definition description must be a string"));
    }
    definition.description = json.at("description").get<std::string>();
  }
 
  if (!json.contains("inputSchema") || !json.at("inputSchema").is_object()) {
    return mcp::core::unexpected(
        tool_json_error("tool definition requires object inputSchema"));
  }
  definition.input_schema = json.at("inputSchema");
 
  if (json.contains("outputSchema")) {
    if (!json.at("outputSchema").is_object()) {
      return mcp::core::unexpected(
          tool_json_error("tool definition outputSchema must be an object"));
    }
    definition.output_schema = json.at("outputSchema");
    definition.output_schema_present = true;
  }
 
  if (json.contains("streaming")) {
    if (!json.at("streaming").is_boolean()) {
      return mcp::core::unexpected(
          tool_json_error("tool definition streaming must be a boolean"));
    }
    definition.streaming = json.at("streaming").get<bool>();
  }
 
  if (json.contains("icons")) {
    if (!json.at("icons").is_array()) {
      return mcp::core::unexpected(
          tool_json_error("tool definition icons must be an array"));
    }
    for (const auto& item : json.at("icons")) {
      const auto icon = icon_from_json(item);
      if (!icon.has_value()) {
        return mcp::core::unexpected(
            tool_json_error("tool definition icon is invalid"));
      }
      definition.icons.push_back(*icon);
    }
  }
 
  if (json.contains("execution")) {
    const auto execution = tool_execution_from_json(json.at("execution"));
    if (!execution) {
      return mcp::core::unexpected(execution.error());
    }
    definition.execution = *execution;
  }
 
  if (json.contains("annotations")) {
    if (!json.at("annotations").is_object()) {
      return mcp::core::unexpected(
          tool_json_error("tool definition annotations must be an object"));
    }
    const auto parsed = tool_annotations_from_json(json.at("annotations"));
    if (parsed) {
      definition.tool_annotations = *parsed;
    }
    definition.annotations = json.at("annotations");
  }
 
  if (json.contains("_meta")) {
    if (!json.at("_meta").is_object()) {
      return mcp::core::unexpected(
          tool_json_error("tool definition _meta must be an object"));
    }
    definition.meta = json.at("_meta");
  }
  definition.extensions = collect_json_extensions(
      json, {"title", "name", "description", "inputSchema", "outputSchema",
             "streaming", "icons", "execution", "annotations", "_meta"});
 
  return definition;
}
 
inline Json tools_list_result_to_json(const ToolsListResult& result) {
  Json json = Json::object();
  json["tools"] = Json::array();
  for (const auto& tool : result.tools) {
    json["tools"].push_back(tool_definition_to_json(tool));
  }
  if (result.next_cursor.has_value()) {
    json["nextCursor"] = *result.next_cursor;
  }
  if (result.meta.has_value()) {
    json["_meta"] = *result.meta;
  }
  if (result.ttl_ms.has_value()) {
    json["ttlMs"] = *result.ttl_ms;
  }
  if (result.cache_scope.has_value()) {
    json["cacheScope"] = *result.cache_scope;
  }
  append_json_extensions(json, result.extensions);
  return json;
}
 
inline core::Result<ToolsListResult> tools_list_result_from_json(
    const Json& json) {
  if (!json.is_object()) {
    return mcp::core::unexpected(
        tool_json_error("tools/list result must be an object"));
  }
  if (!json.contains("tools") || !json.at("tools").is_array()) {
    return mcp::core::unexpected(
        tool_json_error("tools/list result requires a tools array"));
  }
 
  ToolsListResult result;
  for (const auto& item : json.at("tools")) {
    const auto tool = tool_definition_from_json(item);
    if (!tool) {
      return mcp::core::unexpected(tool.error());
    }
    result.tools.push_back(*tool);
  }
  if (json.contains("nextCursor")) {
    if (!json.at("nextCursor").is_string()) {
      return mcp::core::unexpected(
          tool_json_error("tools/list nextCursor must be a string"));
    }
    result.next_cursor = json.at("nextCursor").get<std::string>();
  }
  if (json.contains("_meta")) {
    if (!json.at("_meta").is_object()) {
      return mcp::core::unexpected(
          tool_json_error("tools/list result _meta must be an object"));
    }
    result.meta = json.at("_meta");
  }
  result.extensions =
      collect_json_extensions(json, {"tools", "nextCursor", "_meta"});
  return result;
}
 
inline Json tool_call_to_json(const ToolCall& call) {
  Json json = Json::object();
  json["name"] = call.name;
  if (!call.arguments.empty()) {
    json["arguments"] = call.arguments;
  }
  if (call.task.has_value()) {
    json["task"] = task_request_parameters_to_json(*call.task);
  }
  if (call.meta.has_value()) {
    json["_meta"] = *call.meta;
  }
  if (call.request_state.has_value()) {
    json["requestState"] = *call.request_state;
  }
  if (call.input_responses.has_value()) {
    json["inputResponses"] = *call.input_responses;
  }
  append_json_extensions(json, call.extensions);
  return json;
}
 
inline core::Result<ToolCall> tool_call_from_json(const Json& json) {
  if (!json.is_object()) {
    return mcp::core::unexpected(
        tool_json_error("tools/call params must be an object"));
  }
  if (!json.contains("name") || !json.at("name").is_string()) {
    return mcp::core::unexpected(
        tool_json_error("tools/call params require a string name"));
  }
 
  ToolCall call;
  call.name = json.at("name").get<std::string>();
  if (json.contains("arguments")) {
    if (!json.at("arguments").is_object()) {
      return mcp::core::unexpected(
          tool_json_error("tools/call arguments must be an object"));
    }
    call.arguments = json.at("arguments");
  }
  if (json.contains("task")) {
    const auto task = task_request_parameters_from_json(json.at("task"));
    if (!task) {
      return mcp::core::unexpected(task.error());
    }
    call.task = *task;
  }
  if (json.contains("_meta")) {
    if (!json.at("_meta").is_object()) {
      return mcp::core::unexpected(
          tool_json_error("tools/call _meta must be an object"));
    }
    call.meta = json.at("_meta");
  }
  if (json.contains("requestState")) {
    call.request_state = json.at("requestState").get<std::string>();
  }
  if (json.contains("inputResponses")) {
    call.input_responses = json.at("inputResponses");
  }
  call.extensions = collect_json_extensions(
      json,
      {"name", "arguments", "task", "_meta", "requestState", "inputResponses"});
  return call;
}
 
inline Json tool_result_to_json(const ToolResult& result) {
  Json json = Json::object();
  if (result.result_type.has_value()) {
    json["resultType"] = *result.result_type;
  }
  if (!result.content.empty()) {
    json["content"] = Json::array();
    for (const auto& block : result.content) {
      json["content"].push_back(content_block_to_json(block));
    }
  }
  if (result.structured_content.has_value()) {
    json["structuredContent"] = *result.structured_content;
  }
  if (result.is_error.has_value()) {
    json["isError"] = *result.is_error;
  }
  if (result.meta.has_value()) {
    json["_meta"] = *result.meta;
  }
  if (result.input_requests.has_value()) {
    json["inputRequests"] = *result.input_requests;
  }
  if (result.request_state.has_value()) {
    json["requestState"] = *result.request_state;
  }
  append_json_extensions(json, result.extensions);
  return json;
}
 
inline core::Result<ToolResult> tool_result_from_json(const Json& json) {
  if (!json.is_object()) {
    return mcp::core::unexpected(
        tool_json_error("tool result must be an object"));
  }
  if (!json.contains("content") && !json.contains("structuredContent") &&
      !json.contains("isError") && !json.contains("_meta") &&
      !json.contains("resultType") && !json.contains("inputRequests") &&
      !json.contains("requestState")) {
    return mcp::core::unexpected(tool_json_error(
        "tool result requires content, structuredContent, isError, _meta, "
        "resultType, inputRequests, or requestState"));
  }
 
  ToolResult result;
  if (json.contains("resultType")) {
    result.result_type = json.at("resultType").get<std::string>();
  }
  if (json.contains("content")) {
    if (!json.at("content").is_array()) {
      return mcp::core::unexpected(
          tool_json_error("tool result content must be an array"));
    }
    for (const auto& item : json.at("content")) {
      const auto block = content_block_from_json(item);
      if (!block) {
        return mcp::core::unexpected(block.error());
      }
      result.content.push_back(*block);
    }
  }
 
  if (json.contains("structuredContent")) {
    result.structured_content = json.at("structuredContent");
  }
 
  if (json.contains("isError")) {
    if (!json.at("isError").is_boolean()) {
      return mcp::core::unexpected(
          tool_json_error("tool result isError must be a boolean"));
    }
    result.is_error = json.at("isError").get<bool>();
  }
 
  if (json.contains("_meta")) {
    if (!json.at("_meta").is_object()) {
      return mcp::core::unexpected(
          tool_json_error("tool result _meta must be an object"));
    }
    result.meta = json.at("_meta");
  }
  if (json.contains("inputRequests")) {
    result.input_requests = json.at("inputRequests");
  }
  if (json.contains("requestState")) {
    result.request_state = json.at("requestState").get<std::string>();
  }
  result.extensions = collect_json_extensions(
      json, {"content", "structuredContent", "isError", "_meta", "resultType",
             "inputRequests", "requestState"});
 
  return result;
}
 
// ── SEP-2243: x-mcp-header support ──────────────────────────────────────────
 
struct XHeaderEntry {
  std::string header_name;  // x-mcp-header value, e.g. "Region"
  std::string param_name;   // property key, e.g. "region"
  std::string type;         // JSON Schema type: "string", "number", etc.
};
 
inline std::vector<XHeaderEntry> extract_x_mcp_headers(
    const Json& input_schema) {
  std::vector<XHeaderEntry> result;
  if (!input_schema.is_object() || !input_schema.contains("properties") ||
      !input_schema.at("properties").is_object()) {
    return result;
  }
  for (auto& [key, prop] : input_schema.at("properties").items()) {
    if (!prop.is_object() || !prop.contains("x-mcp-header") ||
        !prop.at("x-mcp-header").is_string()) {
      continue;
    }
    std::string type_str;
    if (prop.contains("type") && prop.at("type").is_string()) {
      type_str = prop.at("type").get<std::string>();
    }
    result.push_back({prop.at("x-mcp-header").get<std::string>(),
                      std::string(key), std::move(type_str)});
  }
  return result;
}
 
inline bool validate_tool_x_headers(const std::vector<XHeaderEntry>& entries) {
  std::unordered_set<std::string> seen_lower;
  for (const auto& entry : entries) {
    if (entry.header_name.empty()) return false;
    for (char ch : entry.header_name) {
      const auto c = static_cast<unsigned char>(ch);
      if (c < 0x21 || c > 0x7E || c == ':') return false;
    }
    if (entry.type == "object" || entry.type == "array" ||
        entry.type == "null" || entry.type.empty()) {
      return false;
    }
    std::string lower = entry.header_name;
    std::transform(
        lower.begin(), lower.end(), lower.begin(),
        [](unsigned char c) { return static_cast<char>(std::tolower(c)); });
    if (!seen_lower.insert(lower).second) return false;
  }
  return true;
}
 
inline bool needs_base64_encoding(std::string_view value) {
  for (const char ch : value) {
    const auto c = static_cast<unsigned char>(ch);
    if (c < 0x20 || c > 0x7E) return true;
  }
  if (!value.empty() && (value.front() == ' ' || value.back() == ' ')) {
    return true;
  }
  return false;
}
 
inline std::string base64_encode(std::string_view input) {
  static constexpr char kAlphabet[] =
      "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
  std::string result;
  result.reserve(((input.size() + 2) / 3) * 4);
  const auto* data = reinterpret_cast<const unsigned char*>(input.data());
  std::size_t i = 0;
  while (i + 2 < input.size()) {
    result.push_back(kAlphabet[(data[i] >> 2) & 0x3F]);
    result.push_back(
        kAlphabet[((data[i] & 0x03) << 4) | ((data[i + 1] >> 4) & 0x0F)]);
    result.push_back(
        kAlphabet[((data[i + 1] & 0x0F) << 2) | ((data[i + 2] >> 6) & 0x03)]);
    result.push_back(kAlphabet[data[i + 2] & 0x3F]);
    i += 3;
  }
  if (i + 1 == input.size()) {
    result.push_back(kAlphabet[(data[i] >> 2) & 0x3F]);
    result.push_back(kAlphabet[(data[i] & 0x03) << 4]);
    result.push_back('=');
    result.push_back('=');
  } else if (i + 2 == input.size()) {
    result.push_back(kAlphabet[(data[i] >> 2) & 0x3F]);
    result.push_back(
        kAlphabet[((data[i] & 0x03) << 4) | ((data[i + 1] >> 4) & 0x0F)]);
    result.push_back(kAlphabet[(data[i + 1] & 0x0F) << 2]);
    result.push_back('=');
  }
  return result;
}
 
inline std::string encode_header_value(std::string_view value) {
  if (needs_base64_encoding(value)) {
    return "=?base64?" + base64_encode(value) + "?=";
  }
  return std::string(value);
}
 
inline std::string number_to_header_string(const Json& value) {
  if (value.is_number_integer()) {
    return std::to_string(value.get<std::int64_t>());
  }
  return value.dump();
}
 
inline std::unordered_map<std::string, std::string> build_tool_param_headers(
    const Json& arguments, const std::vector<XHeaderEntry>& entries) {
  std::unordered_map<std::string, std::string> headers;
  for (const auto& entry : entries) {
    if (!arguments.contains(entry.param_name)) continue;
    const auto& value = arguments.at(entry.param_name);
    if (value.is_null()) continue;
    std::string header_key = "Mcp-Param-" + entry.header_name;
    if (value.is_boolean()) {
      headers[header_key] = value.get<bool>() ? "true" : "false";
    } else if (value.is_number()) {
      headers[header_key] = number_to_header_string(value);
    } else if (value.is_string()) {
      headers[header_key] = encode_header_value(value.get<std::string>());
    }
  }
  return headers;
}
 
}  // namespace mcp::protocol