@unifiedcommerce/core 0.1.0 → 0.2.0

package/src/interfaces/mcp/server.ts

@@ -1,617 +0,0 @@
-import type { MCPResource, MCPTool } from "../../config/types.js";
-import type { AnalyticsQueryParams } from "../../modules/analytics/service.js";
-import { buildAnalyticsScope } from "../../modules/analytics/types.js";
-import type { Kernel } from "../../runtime/kernel.js";
-import { orderStateMachine } from "../../kernel/state-machine/machine.js";
-import {
-  enrichEntityForAgent,
-  enrichInventoryForAgent,
-  enrichOrderForAgent,
-} from "./context-enrichment.js";
-
-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

@@ -1,68 +0,0 @@
-import { Hono } from "hono";
-import { streamSSE, type SSEStreamingApi } from "hono/streaming";
-import type { MCPTool } from "../../config/types.js";
-import type { Kernel } from "../../runtime/kernel.js";
-import { registerMCPCapabilities } from "./server.js";
-
-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;
-}