@reventlessdev/reventless-core 3.0.0-alpha.134

package/src/components/Api/MCP_SchemaGenerator.res

@@ -0,0 +1,185 @@
+// MCP schema generator.
+// Derives MCP tool and resource definitions from sury schemas
+// using the shared SuryToJsonSchema utility.
+
+open ReventlessInfra.Api
+
+let extractVariantNames = Reventless.DcbTag.extractVariantNames
+
+// ─── MCP definition types ─────────────────────────────────────────────────
+
+type mcpToolDefinition = {
+  name: string,
+  description: string,
+  inputSchema: JSON.t,
+}
+
+type mcpResourceDefinition = {
+  uriTemplate: string,
+  name: string,
+  description: string,
+  mimeType: string,
+}
+
+// ─── Tool generation ──────────────────────────────────────────────────────
+
+let buildDescriptionSuffix = (
+  ~base: string,
+  ~entry: ReventlessInfra.Api.mutationSchemaEntry,
+): string => {
+  let viewsSuffix = switch entry.linkedViews {
+  | Some(views) if views->Array.length > 0 =>
+    ` Affects views: ${views->Array.join(", ")}.`
+  | _ => ""
+  }
+  let consistencySuffix = switch entry.consistencyRead {
+  | Some(view) => ` Reads: ${view} for consistency.`
+  | None => ""
+  }
+  base ++ viewsSuffix ++ consistencySuffix
+}
+
+/** Generate MCP tool definitions from mutation entries.
+    Each command variant becomes a separate tool. */
+let generateTools = (
+  ~pluginName: string,
+  ~mutationEntries: array<mutationSchemaEntry>,
+): array<mcpToolDefinition> => {
+  let tools: array<mcpToolDefinition> = []
+
+  mutationEntries->Array.forEach(entry => {
+    let schema = entry.commandSchema
+    let entryDescription = entry.description->Option.getOr("")
+
+    switch schema {
+    | Union({anyOf}) =>
+      // Aggregate commands: each variant is a separate tool.
+      // Inject an "id" property (aggregate instance ID) since aggregate
+      // commands target a specific instance.
+      anyOf->Array.forEachWithIndex((variantSchema, i) => {
+        let fieldName = entry.fieldNames->Array.get(i)->Option.getOr("")
+        if fieldName->String.length > 0 {
+          let inputSchema = SuryToJsonSchema.deriveObjectSchema(variantSchema)
+          // Add "id" to the JSON Schema properties and required list
+          let withId = switch inputSchema->JSON.Decode.object {
+          | Some(obj) =>
+            let props = switch obj->Dict.get("properties") {
+            | Some(p) =>
+              switch p->JSON.Decode.object {
+              | Some(propsDict) =>
+                // Build new dict with "id" first so it appears first in the schema
+                let ordered = Dict.fromArray([
+                  ("id", SuryToJsonSchema.jsonObject([("type", SuryToJsonSchema.str("string"))])),
+                ])
+                propsDict->Dict.toArray->Array.forEach(((k, v)) => ordered->Dict.set(k, v))
+                JSON.Encode.object(ordered)
+              | None => p
+              }
+            | None => JSON.Encode.null
+            }
+            obj->Dict.set("properties", props)
+            // Add "id" to required array
+            switch obj->Dict.get("required") {
+            | Some(req) =>
+              switch req->JSON.Decode.array {
+              | Some(arr) =>
+                arr->Array.unshift(JSON.Encode.string("id"))
+                obj->Dict.set("required", JSON.Encode.array(arr))
+              | None => ()
+              }
+            | None =>
+              obj->Dict.set("required", JSON.Encode.array([JSON.Encode.string("id")]))
+            }
+            JSON.Encode.object(obj)
+          | None => inputSchema
+          }
+          let base =
+            entryDescription->String.length > 0
+              ? entryDescription
+              : `Execute ${fieldName} on ${pluginName}`
+          let desc = buildDescriptionSuffix(~base, ~entry)
+          tools->Array.push({name: fieldName, description: desc, inputSchema: withId})
+        }
+      })
+    | Object(_) =>
+      // Single command (e.g. DCB StateChangeSlice)
+      let fieldName = entry.fieldNames->Array.get(0)->Option.getOr("")
+      if fieldName->String.length > 0 {
+        let inputSchema = SuryToJsonSchema.deriveObjectSchema(schema)
+        let base =
+          entryDescription->String.length > 0
+            ? entryDescription
+            : `Execute ${fieldName} on ${pluginName}`
+        let desc = buildDescriptionSuffix(~base, ~entry)
+        tools->Array.push({name: fieldName, description: desc, inputSchema})
+      }
+    | _ => ()
+    }
+  })
+
+  tools
+}
+
+// ─── Resource generation ──────────────────────────────────────────────────
+
+/** Generate MCP resource definitions from query entries.
+    Each query entry becomes one or two resources (single + list). */
+let generateResources = (
+  ~pluginName: string,
+  ~queryEntries: array<querySchemaEntry>,
+): array<mcpResourceDefinition> => {
+  let resources: array<mcpResourceDefinition> = []
+
+  queryEntries->Array.forEach(entry => {
+    let entryDescription = entry.description->Option.getOr("")
+
+    // Single-item resource with ID parameter
+    let singleDesc =
+      entryDescription->String.length > 0
+        ? entryDescription
+        : `Read a single ${entry.returnTypeName} by ID`
+    resources->Array.push({
+      uriTemplate: `${pluginName}/${entry.singleFieldName}/{id}`,
+      name: entry.returnTypeName,
+      description: singleDesc,
+      mimeType: "application/json",
+    })
+
+    // List resource
+    let listFieldName = entry.listFieldName
+    let listDesc = `List all ${listFieldName}`
+    resources->Array.push({
+      uriTemplate: `${pluginName}/${listFieldName}`,
+      name: listFieldName,
+      description: listDesc,
+      mimeType: "application/json",
+    })
+  })
+
+  resources
+}
+
+// ─── Event history resource generation ───────────────────────────────────
+
+/** Generate MCP resource definitions from event log entries.
+    Each entry becomes a single-entity event history resource. */
+let generateEventHistoryResources = (
+  ~pluginName: string,
+  ~eventLogEntries: array<ReventlessInfra.Api.eventLogSchemaEntry>,
+): array<mcpResourceDefinition> => {
+  let resources: array<mcpResourceDefinition> = []
+
+  eventLogEntries->Array.forEach(entry => {
+    let eventTypes = extractVariantNames(entry.eventSchema)
+    let typeList = eventTypes->Array.join(", ")
+
+    resources->Array.push({
+      uriTemplate: `${pluginName}/${entry.displayName}_events/{entityId}`,
+      name: `${entry.displayName}_events`,
+      description: `Event history for ${entry.displayName}. Event types: ${typeList}`,
+      mimeType: "application/json",
+    })
+  })
+
+  resources
+}

package/src/components/Api/MCP_SchemaGenerator.res.mjs

@@ -0,0 +1,146 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Stdlib_JSON from "@rescript/runtime/lib/es6/Stdlib_JSON.js";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as DcbTag$Reventless from "@reventlessdev/reventless-spec/src/components/DcbTag.res.mjs";
+import * as SuryToJsonSchema$ReventlessCore from "./SuryToJsonSchema.res.mjs";
+
+function buildDescriptionSuffix(base, entry) {
+  let views = entry.linkedViews;
+  let viewsSuffix = views !== undefined && views.length !== 0 ? ` Affects views: ` + views.join(", ") + `.` : "";
+  let view = entry.consistencyRead;
+  let consistencySuffix = view !== undefined ? ` Reads: ` + view + ` for consistency.` : "";
+  return base + viewsSuffix + consistencySuffix;
+}
+
+function generateTools(pluginName, mutationEntries) {
+  let tools = [];
+  mutationEntries.forEach(entry => {
+    let schema = entry.commandSchema;
+    let entryDescription = Stdlib_Option.getOr(entry.description, "");
+    switch (schema.type) {
+      case "object" :
+        let fieldName = Stdlib_Option.getOr(entry.fieldNames[0], "");
+        if (fieldName.length <= 0) {
+          return;
+        }
+        let inputSchema = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(schema);
+        let base = entryDescription.length > 0 ? entryDescription : `Execute ` + fieldName + ` on ` + pluginName;
+        let desc = buildDescriptionSuffix(base, entry);
+        tools.push({
+          name: fieldName,
+          description: desc,
+          inputSchema: inputSchema
+        });
+        return;
+      case "union" :
+        schema.anyOf.forEach((variantSchema, i) => {
+          let fieldName = Stdlib_Option.getOr(entry.fieldNames[i], "");
+          if (fieldName.length <= 0) {
+            return;
+          }
+          let inputSchema = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(variantSchema);
+          let obj = Stdlib_JSON.Decode.object(inputSchema);
+          let withId;
+          if (obj !== undefined) {
+            let p = obj["properties"];
+            let props;
+            if (p !== undefined) {
+              let propsDict = Stdlib_JSON.Decode.object(p);
+              if (propsDict !== undefined) {
+                let ordered = Object.fromEntries([[
+                    "id",
+                    SuryToJsonSchema$ReventlessCore.jsonObject([[
+                        "type",
+                        SuryToJsonSchema$ReventlessCore.str("string")
+                      ]])
+                  ]]);
+                Object.entries(propsDict).forEach(param => {
+                  ordered[param[0]] = param[1];
+                });
+                props = ordered;
+              } else {
+                props = p;
+              }
+            } else {
+              props = null;
+            }
+            obj["properties"] = props;
+            let req = obj["required"];
+            if (req !== undefined) {
+              let arr = Stdlib_JSON.Decode.array(req);
+              if (arr !== undefined) {
+                arr.unshift("id");
+                obj["required"] = arr;
+              }
+            } else {
+              obj["required"] = ["id"];
+            }
+            withId = obj;
+          } else {
+            withId = inputSchema;
+          }
+          let base = entryDescription.length > 0 ? entryDescription : `Execute ` + fieldName + ` on ` + pluginName;
+          let desc = buildDescriptionSuffix(base, entry);
+          tools.push({
+            name: fieldName,
+            description: desc,
+            inputSchema: withId
+          });
+        });
+        return;
+      default:
+        return;
+    }
+  });
+  return tools;
+}
+
+function generateResources(pluginName, queryEntries) {
+  let resources = [];
+  queryEntries.forEach(entry => {
+    let entryDescription = Stdlib_Option.getOr(entry.description, "");
+    let singleDesc = entryDescription.length > 0 ? entryDescription : `Read a single ` + entry.returnTypeName + ` by ID`;
+    resources.push({
+      uriTemplate: pluginName + `/` + entry.singleFieldName + `/{id}`,
+      name: entry.returnTypeName,
+      description: singleDesc,
+      mimeType: "application/json"
+    });
+    let listFieldName = entry.listFieldName;
+    let listDesc = `List all ` + listFieldName;
+    resources.push({
+      uriTemplate: pluginName + `/` + listFieldName,
+      name: listFieldName,
+      description: listDesc,
+      mimeType: "application/json"
+    });
+  });
+  return resources;
+}
+
+function generateEventHistoryResources(pluginName, eventLogEntries) {
+  let resources = [];
+  eventLogEntries.forEach(entry => {
+    let eventTypes = DcbTag$Reventless.extractVariantNames(entry.eventSchema);
+    let typeList = eventTypes.join(", ");
+    resources.push({
+      uriTemplate: pluginName + `/` + entry.displayName + `_events/{entityId}`,
+      name: entry.displayName + `_events`,
+      description: `Event history for ` + entry.displayName + `. Event types: ` + typeList,
+      mimeType: "application/json"
+    });
+  });
+  return resources;
+}
+
+let extractVariantNames = DcbTag$Reventless.extractVariantNames;
+
+export {
+  extractVariantNames,
+  buildDescriptionSuffix,
+  generateTools,
+  generateResources,
+  generateEventHistoryResources,
+}
+/* DcbTag-Reventless Not a pure module */

package/src/components/Api/SchemaType.res

@@ -0,0 +1,126 @@
+type rec schemaType =
+  | ScalarString
+  | ScalarNumber
+  | ScalarBoolean
+  | ScalarBigInt
+  | EntityId
+  | Nullable(schemaType)
+  | ArrayOf(schemaType)
+  | ObjectRef(string, dict<schemaType>)
+  | Enum(string, array<string>)
+  | Unknown
+
+let isTagged = Reventless.DcbTag.isTagged
+
+let isIdFieldName = (name: string): bool => {
+  let lower = String.toLowerCase(name)
+  let len = String.length(lower)
+  len > 2 && String.endsWith(lower, "id")
+}
+
+let isIdsFieldName = (name: string): bool => {
+  let lower = String.toLowerCase(name)
+  let len = String.length(lower)
+  len > 3 && String.endsWith(lower, "ids")
+}
+
+let rec fromSury = (~parentName: string, ~fieldName: string, schema: S.t<unknown>): schemaType => {
+  if isTagged(schema) || Reventless.Reference.getTarget(schema)->Option.isSome {
+    EntityId
+  } else {
+    switch schema {
+    | String({const: ?Some(_)}) => ScalarString
+    | String(_) => isIdFieldName(fieldName) ? EntityId : ScalarString
+    | Number(_) => ScalarNumber
+    | Boolean(_) => ScalarBoolean
+    | BigInt(_) => ScalarBigInt
+    | Array({items, additionalItems}) =>
+      let itemType = switch items->Array.get(0) {
+      | Some({schema: itemSchema}) =>
+        fromSury(
+          ~parentName,
+          ~fieldName,
+          itemSchema->(Obj.magic: S.t<unknown> => S.t<unknown>),
+        )
+      | None =>
+        // sury stores the item schema in additionalItems (not items) for S.array().
+        // additionalItems is @unboxed: Strip="strip", Strict="strict", Schema(t) = the schema object.
+        switch additionalItems {
+        | Schema(s) => fromSury(~parentName, ~fieldName, s)
+        | _ => ScalarString
+        }
+      }
+      let itemType = (isIdsFieldName(fieldName) || isIdFieldName(fieldName)) && itemType == ScalarString
+        ? EntityId
+        : itemType
+      ArrayOf(itemType)
+    | Object({properties}) =>
+      let nestedName =
+        parentName ++
+        fieldName->String.charAt(0)->String.toUpperCase ++
+        fieldName->String.slice(~start=1, ~end=fieldName->String.length)
+      let fields = Dict.make()
+      properties
+      ->Dict.toArray
+      ->Array.forEach(((propName, propSchema)) => {
+        if propName !== "TAG" {
+          fields->Dict.set(propName, fromSury(~parentName=nestedName, ~fieldName=propName, propSchema))
+        }
+      })
+      if fields->Dict.keysToArray->Array.length == 0 {
+        Unknown
+      } else {
+        ObjectRef(nestedName, fields)
+      }
+    | Union({anyOf}) =>
+      let nonNullVariants = anyOf->Array.filter(v =>
+        switch v {
+        | Null(_) | Undefined(_) => false
+        | _ => true
+        }
+      )
+      if nonNullVariants->Array.length == 1 {
+        Nullable(
+          fromSury(
+            ~parentName,
+            ~fieldName,
+            nonNullVariants->Array.getUnsafe(0),
+          ),
+        )
+      } else {
+        let constValues = nonNullVariants->Array.filterMap(v =>
+          switch v {
+          | String({const: ?Some(c)}) => Some(c)
+          | _ => None
+          }
+        )
+        if constValues->Array.length == nonNullVariants->Array.length && constValues->Array.length > 0 {
+          let enumName =
+            parentName ++
+            fieldName->String.charAt(0)->String.toUpperCase ++
+            fieldName->String.slice(~start=1, ~end=fieldName->String.length)
+          Enum(enumName, constValues)
+        } else {
+          Unknown
+        }
+      }
+    | Null(_) => Nullable(ScalarString)
+    | _ => Unknown
+    }
+  }
+}
+
+let fromSuryObject = (~typeName: string, schema: S.t<unknown>): option<dict<schemaType>> =>
+  switch schema {
+  | Object({properties}) =>
+    let fields = Dict.make()
+    properties
+    ->Dict.toArray
+    ->Array.forEach(((propName, propSchema)) => {
+      if propName !== "TAG" {
+        fields->Dict.set(propName, fromSury(~parentName=typeName, ~fieldName=propName, propSchema))
+      }
+    })
+    Some(fields)
+  | _ => None
+  }

package/src/components/Api/SchemaType.res.mjs

@@ -0,0 +1,143 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as DcbTag$Reventless from "@reventlessdev/reventless-spec/src/components/DcbTag.res.mjs";
+import * as Reference$Reventless from "@reventlessdev/reventless-spec/src/components/Reference.res.mjs";
+
+function isIdFieldName(name) {
+  let lower = name.toLowerCase();
+  let len = lower.length;
+  if (len > 2) {
+    return lower.endsWith("id");
+  } else {
+    return false;
+  }
+}
+
+function isIdsFieldName(name) {
+  let lower = name.toLowerCase();
+  let len = lower.length;
+  if (len > 3) {
+    return lower.endsWith("ids");
+  } else {
+    return false;
+  }
+}
+
+function fromSury(parentName, fieldName, schema) {
+  if (DcbTag$Reventless.isTagged(schema) || Stdlib_Option.isSome(Reference$Reventless.getTarget(schema))) {
+    return "EntityId";
+  }
+  switch (schema.type) {
+    case "string" :
+      if (schema.const !== undefined || !isIdFieldName(fieldName)) {
+        return "ScalarString";
+      } else {
+        return "EntityId";
+      }
+    case "number" :
+      return "ScalarNumber";
+    case "bigint" :
+      return "ScalarBigInt";
+    case "boolean" :
+      return "ScalarBoolean";
+    case "null" :
+      return {
+        TAG: "Nullable",
+        _0: "ScalarString"
+      };
+    case "array" :
+      let additionalItems = schema.additionalItems;
+      let match = schema.items[0];
+      let itemType = match !== undefined ? fromSury(parentName, fieldName, match.schema) : (
+          additionalItems === "strip" || additionalItems === "strict" ? "ScalarString" : fromSury(parentName, fieldName, additionalItems)
+        );
+      let itemType$1 = (isIdsFieldName(fieldName) || isIdFieldName(fieldName)) && itemType === "ScalarString" ? "EntityId" : itemType;
+      return {
+        TAG: "ArrayOf",
+        _0: itemType$1
+      };
+    case "object" :
+      let nestedName = parentName + fieldName.charAt(0).toUpperCase() + fieldName.slice(1, fieldName.length);
+      let fields = {};
+      Object.entries(schema.properties).forEach(param => {
+        let propName = param[0];
+        if (propName !== "TAG") {
+          fields[propName] = fromSury(nestedName, propName, param[1]);
+          return;
+        }
+      });
+      if (Object.keys(fields).length === 0) {
+        return "Unknown";
+      } else {
+        return {
+          TAG: "ObjectRef",
+          _0: nestedName,
+          _1: fields
+        };
+      }
+    case "union" :
+      let nonNullVariants = schema.anyOf.filter(v => {
+        switch (v.type) {
+          case "null" :
+          case "undefined" :
+            return false;
+          default:
+            return true;
+        }
+      });
+      if (nonNullVariants.length === 1) {
+        return {
+          TAG: "Nullable",
+          _0: fromSury(parentName, fieldName, nonNullVariants[0])
+        };
+      }
+      let constValues = Stdlib_Array.filterMap(nonNullVariants, v => {
+        if (v.type !== "string") {
+          return;
+        }
+        let c = v.const;
+        if (c !== undefined) {
+          return c;
+        }
+      });
+      if (constValues.length !== nonNullVariants.length || constValues.length === 0) {
+        return "Unknown";
+      }
+      let enumName = parentName + fieldName.charAt(0).toUpperCase() + fieldName.slice(1, fieldName.length);
+      return {
+        TAG: "Enum",
+        _0: enumName,
+        _1: constValues
+      };
+    default:
+      return "Unknown";
+  }
+}
+
+function fromSuryObject(typeName, schema) {
+  if (schema.type !== "object") {
+    return;
+  }
+  let fields = {};
+  Object.entries(schema.properties).forEach(param => {
+    let propName = param[0];
+    if (propName !== "TAG") {
+      fields[propName] = fromSury(typeName, propName, param[1]);
+      return;
+    }
+  });
+  return fields;
+}
+
+let isTagged = DcbTag$Reventless.isTagged;
+
+export {
+  isTagged,
+  isIdFieldName,
+  isIdsFieldName,
+  fromSury,
+  fromSuryObject,
+}
+/* DcbTag-Reventless Not a pure module */