@unifiedcommerce/core 0.0.1

package/src/interfaces/mcp/server.ts

@@ -0,0 +1,617 @@
+import type { MCPResource, MCPTool } from "../../config/types";
+import type { AnalyticsQueryParams } from "../../modules/analytics/service";
+import { buildAnalyticsScope } from "../../modules/analytics/types";
+import type { Kernel } from "../../runtime/kernel";
+import { orderStateMachine } from "../../kernel/state-machine/machine";
+import {
+  enrichEntityForAgent,
+  enrichInventoryForAgent,
+  enrichOrderForAgent,
+} from "./context-enrichment";
+
+function textContent(value: unknown) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
+  };
+}
+
+function asObject(params: unknown): Record<string, unknown> {
+  if (!params || typeof params !== "object" || Array.isArray(params)) return {};
+  return params as Record<string, unknown>;
+}
+
+function readString(
+  params: Record<string, unknown>,
+  key: string,
+): string | undefined {
+  const value = params[key];
+  return typeof value === "string" ? value : undefined;
+}
+
+function readNumber(
+  params: Record<string, unknown>,
+  key: string,
+): number | undefined {
+  const value = params[key];
+  return typeof value === "number" && Number.isFinite(value)
+    ? value
+    : undefined;
+}
+
+function readStringArray(
+  params: Record<string, unknown>,
+  key: string,
+): string[] {
+  const value = params[key];
+  if (!Array.isArray(value)) return [];
+  return value.filter((item): item is string => typeof item === "string");
+}
+
+function validationError(message: string): {
+  error: { code: string; message: string };
+} {
+  return {
+    error: {
+      code: "VALIDATION_FAILED",
+      message,
+    },
+  };
+}
+
+export function registerMCPCapabilities(kernel: Kernel): {
+  tools: MCPTool[];
+  resources: MCPResource[];
+} {
+  return {
+    tools: [
+      {
+        name: "catalog_search",
+        description:
+          "Search the catalog. Filter by type, status, category, brand, price range, free-text. Returns paginated results with pricing and availability.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            query: { type: "string" },
+            type: { type: "string" },
+            status: { type: "string" },
+            categorySlug: { type: "string" },
+            brandSlug: { type: "string" },
+            page: { type: "number", default: 1 },
+            limit: { type: "number", default: 20 },
+          },
+        },
+        handler: async (params: unknown) => {
+          const input = asObject(params);
+          const query = (readString(input, "query") ?? "").trim().toLowerCase();
+          const page = readNumber(input, "page") ?? 1;
+          const limit = readNumber(input, "limit") ?? 20;
+          const type = readString(input, "type");
+          const status = readString(input, "status");
+          const categorySlug = readString(input, "categorySlug");
+          const brandSlug = readString(input, "brandSlug");
+          if (query.length > 0) {
+            const searchResult = await kernel.services.search.query({
+              query,
+              page,
+              limit,
+              filters: {
+                ...(type ? { type } : {}),
+                ...(status ? { status } : {}),
+                ...(categorySlug ? { category: categorySlug } : {}),
+                ...(brandSlug ? { brand: brandSlug } : {}),
+              },
+            });
+
+            if (!searchResult.ok) return { error: searchResult.error };
+
+            const enrichedItems = await Promise.all(
+              searchResult.value.hits.map(async (hit) => {
+                const entityResult = await kernel.services.catalog.getById(
+                  hit.id,
+                );
+                if (entityResult.ok) {
+                  return enrichEntityForAgent(entityResult.value, kernel);
+                }
+                return hit.document;
+              }),
+            );
+
+            return textContent({
+              items: await Promise.all(enrichedItems),
+              pagination: {
+                page: searchResult.value.page,
+                limit: searchResult.value.limit,
+                total: searchResult.value.total,
+                totalPages: Math.max(
+                  1,
+                  Math.ceil(
+                    searchResult.value.total / searchResult.value.limit,
+                  ),
+                ),
+              },
+              facets: searchResult.value.facets,
+            });
+          }
+
+          const result = await kernel.services.catalog.list({
+            filter: {
+              ...(type ? { type } : {}),
+              ...(status ? { status } : {}),
+              ...(categorySlug ? { category: categorySlug } : {}),
+              ...(brandSlug ? { brand: brandSlug } : {}),
+            },
+            pagination: {
+              page,
+              limit,
+            },
+          });
+          if (!result.ok) return { error: result.error };
+
+          return textContent({
+            ...result.value,
+            items: await Promise.all(
+              result.value.items.map((item) =>
+                enrichEntityForAgent(item, kernel),
+              ),
+            ),
+          });
+        },
+      },
+      {
+        name: "catalog_create_entity",
+        description:
+          "Create a new catalog entity. Requires type, slug, title. Created in draft status.",
+        inputSchema: {
+          type: "object",
+          required: ["type", "slug", "title"],
+          properties: {
+            type: { type: "string" },
+            slug: { type: "string" },
+            title: { type: "string" },
+            description: { type: "string" },
+            metadata: { type: "object" },
+          },
+        },
+        handler: async (params: unknown) => {
+          const input = asObject(params);
+          const type = readString(input, "type");
+          const slug = readString(input, "slug");
+          const title = readString(input, "title");
+          const description = readString(input, "description");
+          if (!type || !slug || !title) {
+            return validationError("type, slug, and title are required.");
+          }
+          const result = await kernel.services.catalog.create(
+            {
+              type,
+              slug,
+              attributes: {
+                locale: "en",
+                title,
+                ...(description !== undefined ? { description } : {}),
+              },
+              ...(input.metadata &&
+              typeof input.metadata === "object" &&
+              !Array.isArray(input.metadata)
+                ? { metadata: input.metadata as Record<string, unknown> }
+                : {}),
+            },
+            kernel.getMCPActor(),
+          );
+
+          if (!result.ok) return { error: result.error };
+          return textContent(await enrichEntityForAgent(result.value, kernel));
+        },
+      },
+      {
+        name: "inventory_check",
+        description: "Check stock levels for one or more entities/variants.",
+        inputSchema: {
+          type: "object",
+          required: ["entityIds"],
+          properties: {
+            entityIds: {
+              type: "array",
+              items: { type: "string" },
+            },
+          },
+        },
+        handler: async (params: unknown) => {
+          const input = asObject(params);
+          const entityIds = readStringArray(input, "entityIds");
+          if (entityIds.length === 0) {
+            return validationError("entityIds is required.");
+          }
+          const result =
+            await kernel.services.inventory.checkMultiple(entityIds);
+          if (!result.ok) return { error: result.error };
+
+          const enriched = await Promise.all(
+            Object.entries(result.value).map(async ([entityId, available]) => {
+              const levelsResult =
+                await kernel.services.inventory.getLevelsByEntityId(entityId);
+              const levels = levelsResult.ok ? levelsResult.value : [];
+              const reorderThreshold = levels[0]?.reorderThreshold;
+              const reorderQuantity = levels[0]?.reorderQuantity;
+
+              return enrichInventoryForAgent({
+                entityId,
+                available,
+                ...(reorderThreshold !== undefined ? { reorderThreshold } : {}),
+                ...(reorderQuantity !== undefined ? { reorderQuantity } : {}),
+              });
+            }),
+          );
+
+          return textContent(enriched);
+        },
+      },
+      {
+        name: "inventory_adjust",
+        description:
+          "Adjust inventory. Positive adds stock, negative removes. Requires reason.",
+        inputSchema: {
+          type: "object",
+          required: ["entityId", "adjustment", "reason"],
+          properties: {
+            entityId: { type: "string" },
+            variantId: { type: "string" },
+            adjustment: { type: "number" },
+            reason: { type: "string" },
+          },
+        },
+        handler: async (params: unknown) => {
+          const input = asObject(params);
+          const entityId = readString(input, "entityId");
+          const adjustment = readNumber(input, "adjustment");
+          const reason = readString(input, "reason");
+          const variantId = readString(input, "variantId");
+          if (!entityId || adjustment === undefined || !reason) {
+            return validationError(
+              "entityId, adjustment, and reason are required.",
+            );
+          }
+
+          const result = await kernel.services.inventory.adjust(
+            {
+              entityId,
+              adjustment,
+              reason,
+              ...(variantId !== undefined ? { variantId } : {}),
+            },
+            kernel.getMCPActor(),
+          );
+          if (!result.ok) return { error: result.error };
+
+          const availableResult = await kernel.services.inventory.getAvailable(
+            entityId,
+            variantId,
+          );
+
+          return textContent(
+            enrichInventoryForAgent({
+              entityId,
+              available: availableResult.ok ? availableResult.value : 0,
+              ...(result.value.reorderThreshold !== undefined
+                ? { reorderThreshold: result.value.reorderThreshold }
+                : {}),
+              ...(result.value.reorderQuantity !== undefined
+                ? { reorderQuantity: result.value.reorderQuantity }
+                : {}),
+            }),
+          );
+        },
+      },
+      {
+        name: "cart_create",
+        description:
+          "Create a new shopping cart. Returns cart ID for subsequent operations.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            customerId: { type: "string" },
+            currency: { type: "string", default: "USD" },
+          },
+        },
+        handler: async (params: unknown) => {
+          const input = asObject(params);
+          const customerId = readString(input, "customerId");
+          const currency = readString(input, "currency");
+          const result = await kernel.services.cart.create(
+            {
+              ...(customerId !== undefined ? { customerId } : {}),
+              ...(currency !== undefined ? { currency } : {}),
+            },
+            kernel.getMCPActor(),
+          );
+          if (!result.ok) return { error: result.error };
+          return textContent(result.value);
+        },
+      },
+      {
+        name: "cart_add_item",
+        description:
+          "Add item to cart. If entity has variants and no variantId provided, fails with available variants.",
+        inputSchema: {
+          type: "object",
+          required: ["cartId", "entityId"],
+          properties: {
+            cartId: { type: "string" },
+            entityId: { type: "string" },
+            variantId: { type: "string" },
+            quantity: { type: "number", default: 1 },
+          },
+        },
+        handler: async (params: unknown) => {
+          const input = asObject(params);
+          const cartId = readString(input, "cartId");
+          const entityId = readString(input, "entityId");
+          const variantId = readString(input, "variantId");
+          const quantity = readNumber(input, "quantity");
+          if (!cartId || !entityId) {
+            return validationError("cartId and entityId are required.");
+          }
+          const result = await kernel.services.cart.addItem(
+            {
+              cartId,
+              entityId,
+              ...(variantId !== undefined ? { variantId } : {}),
+              quantity: quantity ?? 1,
+            },
+            kernel.getMCPActor(),
+          );
+          if (!result.ok) return { error: result.error };
+          return textContent(result.value);
+        },
+      },
+      {
+        name: "order_get",
+        description:
+          "Get order details by ID or order number. Includes line items, payment, fulfillment, and AI context.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            orderId: { type: "string" },
+            orderNumber: { type: "string" },
+          },
+        },
+        handler: async (params: unknown) => {
+          const input = asObject(params);
+          const orderId = readString(input, "orderId");
+          const orderNumber = readString(input, "orderNumber");
+          if (!orderId && !orderNumber) {
+            return validationError(
+              "Either orderId or orderNumber is required.",
+            );
+          }
+
+          const result = orderId
+            ? await kernel.services.orders.getById(
+                orderId,
+                kernel.getMCPActor(),
+              )
+            : await kernel.services.orders.getByNumber(
+                orderNumber ?? "",
+                kernel.getMCPActor(),
+              );
+
+          if (!result.ok) return { error: result.error };
+          const enriched = enrichOrderForAgent(
+            result.value,
+            kernel.getMCPActor().permissions,
+          );
+          return textContent(enriched);
+        },
+      },
+      {
+        name: "order_list",
+        description: "List orders with pagination and optional status filter.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            page: { type: "number", default: 1 },
+            limit: { type: "number", default: 20 },
+            status: { type: "string" },
+          },
+        },
+        handler: async (params: unknown) => {
+          const input = asObject(params);
+          const page = readNumber(input, "page");
+          const limit = readNumber(input, "limit");
+          const status = readString(input, "status");
+          const result = await kernel.services.orders.list(
+            {
+              ...(page !== undefined ? { page } : {}),
+              ...(limit !== undefined ? { limit } : {}),
+              ...(status !== undefined ? { status } : {}),
+            },
+            kernel.getMCPActor(),
+          );
+
+          if (!result.ok) return { error: result.error };
+          return textContent({
+            ...result.value,
+            items: result.value.items.map((order) =>
+              enrichOrderForAgent(order, kernel.getMCPActor().permissions),
+            ),
+          });
+        },
+      },
+      {
+        name: "analytics_query",
+        description:
+          "Query analytics using semantic measures, dimensions, time dimensions, and filters.",
+        inputSchema: {
+          type: "object",
+          required: ["measures"],
+          properties: {
+            measures: {
+              type: "array",
+              items: { type: "string" },
+            },
+            dimensions: {
+              type: "array",
+              items: { type: "string" },
+            },
+            timeDimensions: {
+              type: "array",
+              items: {
+                type: "object",
+                properties: {
+                  dimension: { type: "string" },
+                  granularity: {
+                    type: "string",
+                    enum: ["day", "week", "month", "year"],
+                  },
+                  dateRange: {
+                    oneOf: [
+                      { type: "string" },
+                      {
+                        type: "array",
+                        items: { type: "string" },
+                        minItems: 2,
+                        maxItems: 2,
+                      },
+                    ],
+                  },
+                },
+                required: ["dimension"],
+              },
+            },
+            filters: {
+              type: "array",
+              items: {
+                type: "object",
+                properties: {
+                  member: { type: "string" },
+                  operator: {
+                    type: "string",
+                    enum: [
+                      "equals",
+                      "notEquals",
+                      "contains",
+                      "in",
+                      "notIn",
+                      "gt",
+                      "gte",
+                      "lt",
+                      "lte",
+                      "beforeDate",
+                      "afterDate",
+                      "inDateRange",
+                    ],
+                  },
+                  values: {
+                    type: "array",
+                    items: { type: "string" },
+                  },
+                },
+                required: ["member", "operator"],
+              },
+            },
+            order: {
+              type: "object",
+              additionalProperties: {
+                type: "string",
+                enum: ["asc", "desc"],
+              },
+            },
+            limit: { type: "number", default: 100 },
+          },
+        },
+        handler: async (params: unknown) => {
+          const input = asObject(params);
+          const measures = readStringArray(input, "measures");
+          const limit = readNumber(input, "limit");
+          if (measures.length === 0) {
+            return validationError("measures is required.");
+          }
+
+          const queryParams: AnalyticsQueryParams = {
+            measures,
+            ...(Array.isArray(input.dimensions)
+              ? {
+                  dimensions: input.dimensions.filter(
+                    (item): item is string => typeof item === "string",
+                  ),
+                }
+              : {}),
+            ...(Array.isArray(input.timeDimensions)
+              ? {
+                  timeDimensions: input.timeDimensions as NonNullable<
+                    AnalyticsQueryParams["timeDimensions"]
+                  >,
+                }
+              : {}),
+            ...(Array.isArray(input.filters)
+              ? {
+                  filters: input.filters as NonNullable<
+                    AnalyticsQueryParams["filters"]
+                  >,
+                }
+              : {}),
+            ...(input.order &&
+            typeof input.order === "object" &&
+            !Array.isArray(input.order)
+              ? {
+                  order: input.order as NonNullable<
+                    AnalyticsQueryParams["order"]
+                  >,
+                }
+              : {}),
+            ...(limit !== undefined ? { limit } : {}),
+          };
+
+          // Scope is always derived from the actor — never manually constructed.
+          const analyticsScope = buildAnalyticsScope(kernel.getMCPActor());
+
+          const result = await kernel.services.analytics.query(queryParams, analyticsScope);
+          if (!result.ok) return { error: result.error };
+          return textContent(result.value);
+        },
+      },
+      {
+        name: "analytics_meta",
+        description:
+          "List available analytics measures, dimensions, segments, and models.",
+        inputSchema: {
+          type: "object",
+        },
+        handler: async () => {
+          const metaScope = buildAnalyticsScope(kernel.getMCPActor());
+          const result = await kernel.services.analytics.getMeta();
+          if (!result.ok) return { error: result.error };
+          return textContent(result.value);
+        },
+      },
+    ],
+    resources: [
+      {
+        uri: "commerce://schema/entity-types",
+        name: "Entity Type Schema",
+        description:
+          "Complete schema of all entity types, fields, variants, fulfillment strategies.",
+        mimeType: "application/json",
+        handler: async () => ({
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(kernel.config.entities ?? {}, null, 2),
+            },
+          ],
+        }),
+      },
+      {
+        uri: "commerce://schema/order-states",
+        name: "Order State Machine",
+        description: "All order states and valid transitions.",
+        mimeType: "application/json",
+        handler: async () => ({
+          content: [
+            { type: "text", text: JSON.stringify(orderStateMachine, null, 2) },
+          ],
+        }),
+      },
+    ],
+  };
+}

package/src/interfaces/mcp/transport.ts

@@ -0,0 +1,68 @@
+import { Hono } from "hono";
+import { streamSSE, type SSEStreamingApi } from "hono/streaming";
+import type { MCPTool } from "../../config/types";
+import type { Kernel } from "../../runtime/kernel";
+import { registerMCPCapabilities } from "./server";
+
+async function handleMCPSession(
+  stream: SSEStreamingApi,
+  capabilities: ReturnType<typeof registerMCPCapabilities>,
+): Promise<void> {
+  await stream.writeSSE({
+    event: "ready",
+    data: JSON.stringify({
+      tools: capabilities.tools.map((tool) => ({ name: tool.name, description: tool.description })),
+      resources: capabilities.resources.map((resource) => ({ uri: resource.uri, name: resource.name })),
+    }),
+  });
+}
+
+export function createMCPHandler(kernel: Kernel, customTools?: (kernel: Kernel) => MCPTool[]) {
+  const router = new Hono();
+  const capabilities = registerMCPCapabilities(kernel);
+
+  if (customTools) {
+    capabilities.tools.push(...customTools(kernel));
+  }
+
+  if (kernel.mcpTools.length > 0) {
+    capabilities.tools.push(...kernel.mcpTools);
+  }
+
+  if (kernel.mcpResources.length > 0) {
+    capabilities.resources.push(...kernel.mcpResources);
+  }
+
+  router.get("/sse", async (c) =>
+    streamSSE(c, async (stream) => {
+      await handleMCPSession(stream, capabilities);
+    }),
+  );
+
+  router.post("/tools/:toolName", async (c) => {
+    const tool = capabilities.tools.find((item) => item.name === c.req.param("toolName"));
+    if (!tool) return c.json({ error: "Tool not found" }, 404);
+
+    return c.json(await tool.handler(await c.req.json<unknown>()));
+  });
+
+  router.get("/resources", async (c) => {
+    return c.json({
+      data: capabilities.resources.map((resource) => ({
+        uri: resource.uri,
+        name: resource.name,
+        description: resource.description,
+        mimeType: resource.mimeType,
+      })),
+    });
+  });
+
+  router.get("/resources/:resourceId", async (c) => {
+    const uri = decodeURIComponent(c.req.param("resourceId"));
+    const resource = capabilities.resources.find((item) => item.uri === uri);
+    if (!resource) return c.json({ error: "Resource not found" }, 404);
+    return c.json(await resource.handler());
+  });
+
+  return router;
+}