@unifiedcommerce/core 0.0.1

package/dist/interfaces/mcp/context-enrichment.js

@@ -0,0 +1,119 @@
+import { orderStateMachine } from "../../kernel/state-machine/machine";
+function getAvailableTransitions(status) {
+    const transitions = orderStateMachine.transitions[status];
+    return transitions ? [...transitions] : [];
+}
+async function inventorySummary(kernel, entityId) {
+    const result = await kernel.services.inventory.checkMultiple([entityId]);
+    const available = result.ok ? (result.value[entityId] ?? 0) : 0;
+    // For low stock detection, we need a simple heuristic since we don't have
+    // direct access to all level details from service API. Use available <= 0.
+    const lowStock = available <= 0;
+    return {
+        onHand: available, // approximation when detailed levels not available
+        reserved: 0,
+        available,
+        lowStock,
+        reorderSuggestionUnits: 0,
+    };
+}
+export function enrichOrderForAgent(order, permissions) {
+    return {
+        ...order,
+        _context: {
+            availableTransitions: getAvailableTransitions(order.status),
+            permittedActions: permissions.filter((permission) => ["orders:update", "orders:read", "orders:cancel"].includes(permission)),
+            summary: `Order ${order.orderNumber}: ${order.lineItems.reduce((sum, lineItem) => sum + lineItem.quantity, 0)} item(s) totaling ${order.grandTotal} ${order.currency}. Status: ${order.status}.`,
+            relatedQueries: [
+                {
+                    tool: "inventory_check",
+                    params: {
+                        entityIds: order.lineItems.map((lineItem) => lineItem.entityId),
+                    },
+                },
+                {
+                    tool: "analytics_query",
+                    params: {
+                        measures: ["Orders.revenue"],
+                        dimensions: ["Orders.status"],
+                        filters: [
+                            { member: "Orders.id", operator: "equals", values: [order.id] },
+                        ],
+                    },
+                },
+            ],
+        },
+    };
+}
+/**
+ * Enriches an entity with contextual information for AI agents.
+ * Accepts both SellableEntityRecord and Drizzle-inferred types.
+ * Now async — uses kernel services instead of RuntimeState.
+ */
+export async function enrichEntityForAgent(entity, kernel) {
+    const inventory = await inventorySummary(kernel, entity.id);
+    // Get entity details with variants to count them
+    const entityResult = await kernel.services.catalog.getById(entity.id, {
+        includeVariants: true,
+    });
+    const variantCount = entityResult.ok && entityResult.value.variants
+        ? entityResult.value.variants.length
+        : 0;
+    return {
+        ...entity,
+        _context: {
+            summary: `${entity.slug} has ${variantCount} variant(s), ${inventory.available} available units.`,
+            stockStatus: inventory.lowStock
+                ? "low"
+                : inventory.available > 0
+                    ? "in_stock"
+                    : "out_of_stock",
+            variantCount,
+            relatedQueries: [
+                {
+                    tool: "inventory_check",
+                    params: { entityIds: [entity.id] },
+                },
+                {
+                    tool: "analytics_query",
+                    params: {
+                        measures: ["OrderLineItems.itemsSold"],
+                        dimensions: ["OrderLineItems.title"],
+                        filters: [
+                            {
+                                member: "OrderLineItems.title",
+                                operator: "equals",
+                                values: [entity.slug],
+                            },
+                        ],
+                    },
+                },
+            ],
+        },
+    };
+}
+export function enrichInventoryForAgent(item) {
+    const lowStock = item.reorderThreshold != null
+        ? item.available <= item.reorderThreshold
+        : item.available <= 0;
+    return {
+        ...item,
+        _context: {
+            lowStockWarning: lowStock,
+            reorderSuggestion: lowStock && item.reorderQuantity != null
+                ? {
+                    suggestedUnits: item.reorderQuantity,
+                }
+                : null,
+            summary: lowStock
+                ? `Entity ${item.entityId} is low on stock (${item.available} available).`
+                : `Entity ${item.entityId} has healthy stock (${item.available} available).`,
+            relatedQueries: [
+                {
+                    tool: "catalog_search",
+                    params: { query: item.entityId },
+                },
+            ],
+        },
+    };
+}

package/dist/interfaces/mcp/server.d.ts

@@ -0,0 +1,7 @@
+import type { MCPResource, MCPTool } from "../../config/types";
+import type { Kernel } from "../../runtime/kernel";
+export declare function registerMCPCapabilities(kernel: Kernel): {
+    tools: MCPTool[];
+    resources: MCPResource[];
+};
+//# sourceMappingURL=server.d.ts.map

package/dist/interfaces/mcp/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../src/interfaces/mcp/server.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAG/D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAyDnD,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG;IACvD,KAAK,EAAE,OAAO,EAAE,CAAC;IACjB,SAAS,EAAE,WAAW,EAAE,CAAC;CAC1B,CAyiBA"}

package/dist/interfaces/mcp/server.js

@@ -0,0 +1,515 @@
+import { buildAnalyticsScope } from "../../modules/analytics/types";
+import { orderStateMachine } from "../../kernel/state-machine/machine";
+import { enrichEntityForAgent, enrichInventoryForAgent, enrichOrderForAgent, } from "./context-enrichment";
+function textContent(value) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
+    };
+}
+function asObject(params) {
+    if (!params || typeof params !== "object" || Array.isArray(params))
+        return {};
+    return params;
+}
+function readString(params, key) {
+    const value = params[key];
+    return typeof value === "string" ? value : undefined;
+}
+function readNumber(params, key) {
+    const value = params[key];
+    return typeof value === "number" && Number.isFinite(value)
+        ? value
+        : undefined;
+}
+function readStringArray(params, key) {
+    const value = params[key];
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((item) => typeof item === "string");
+}
+function validationError(message) {
+    return {
+        error: {
+            code: "VALIDATION_FAILED",
+            message,
+        },
+    };
+}
+export function registerMCPCapabilities(kernel) {
+    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) => {
+                    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) => {
+                    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 }
+                            : {}),
+                    }, 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) => {
+                    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) => {
+                    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) => {
+                    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) => {
+                    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) => {
+                    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) => {
+                    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) => {
+                    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 = {
+                        measures,
+                        ...(Array.isArray(input.dimensions)
+                            ? {
+                                dimensions: input.dimensions.filter((item) => typeof item === "string"),
+                            }
+                            : {}),
+                        ...(Array.isArray(input.timeDimensions)
+                            ? {
+                                timeDimensions: input.timeDimensions,
+                            }
+                            : {}),
+                        ...(Array.isArray(input.filters)
+                            ? {
+                                filters: input.filters,
+                            }
+                            : {}),
+                        ...(input.order &&
+                            typeof input.order === "object" &&
+                            !Array.isArray(input.order)
+                            ? {
+                                order: input.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/dist/interfaces/mcp/transport.d.ts

@@ -0,0 +1,5 @@
+import { Hono } from "hono";
+import type { MCPTool } from "../../config/types";
+import type { Kernel } from "../../runtime/kernel";
+export declare function createMCPHandler(kernel: Kernel, customTools?: (kernel: Kernel) => MCPTool[]): Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;
+//# sourceMappingURL=transport.d.ts.map

package/dist/interfaces/mcp/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../../src/interfaces/mcp/transport.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAE5B,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAgBnD,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,EAAE,8EAgD3F"}