@lemonmade/ucp-schema 0.0.0-preview-20260123174501

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# @lemonmade/ucp-schema
+
+## 0.0.0-preview-20260123174501
+
+### Patch Changes
+
+- Add MCP entrypoint
+
+## 0.1.1
+
+### Patch Changes
+
+- [`78291cc`](https://github.com/lemonmade/nursery/commit/78291cc317b2c3499ab09b543dea1aede2fd9495) Thanks [@lemonmade](https://github.com/lemonmade)! - Add MCP entrypoint

package/README.md

@@ -0,0 +1,25 @@
+# `@lemonmade/ucp-schema`
+
+Tools for composing Universal Commerce Protocol (UCP) schemas.
+
+## Basic usage
+
+```ts
+import {UcpSchemaComposer} from '@lemonmade/ucp-schema';
+
+const composer = await UcpSchemaComposer.fromProfile({
+  ucp: {
+    capabilities: [
+      // ... more capabilities ...
+    ],
+  },
+});
+
+const checkoutFile = composer.get(
+  'https://ucp.dev/schemas/shopping/checkout.json',
+);
+const checkoutReadSchema = checkoutFile.composedSchema();
+const checkoutCreateSchema = checkoutFile.composedSchema({operation: 'create'});
+
+// ... use the JSON schemas to validate and transform UCP requests
+```

package/build/esm/compose.mjs

@@ -0,0 +1,375 @@
+/**
+ * Composes operation-aware JSON schemas for UCP objects, based on the capabilities
+ * referenced in a UCP profile.
+ *
+ * @example
+ * ```ts
+ * const composer = await UcpSchemaComposer.fromProfile({
+ *   ucp: {
+ *     capabilities: [
+ *       {
+ *         name: 'dev.ucp.shopping.checkout',
+ *         version: '2026-01-11',
+ *         spec: 'https://ucp.dev/specification/checkout',
+ *         schema: 'https://ucp.dev/schemas/shopping/checkout.json',
+ *       },
+ *       // ... more capabilities ...
+ *     ],
+ *   },
+ * });
+ *
+ * const checkoutFile = composer.get('https://ucp.dev/schemas/shopping/checkout.json');
+ * const checkoutReadSchema = checkoutFile.composedSchema();
+ * const checkoutCreateSchema = checkoutFile.composedSchema({ operation: 'create' });
+ * ```
+ */
+class UcpSchemaComposer {
+  /**
+   * Create a composed schema from a UCP profile. This function will look
+   * at the capabilities and payment handlers in the profile, fetch the
+   * JSON schemas (and any JSON schemas referenced within), and return an
+   * object that allows you to get a composed schema for a specific file
+   * and UCP operation.
+   */
+  static async fromProfile({
+    ucp: {
+      capabilities
+    }
+  }, {
+    fetch: fetchSchema = createDefaultSchemaFetcher()
+  } = {}) {
+    const resolvedCapabilities = await Promise.all(capabilities.map(async capability => {
+      let json;
+      const schemaUrl = new URL(capability.schema);
+      const reverseDnsForUrl = schemaUrl.hostname.split('.').reverse().join('.');
+      if (!capability.name.startsWith(reverseDnsForUrl)) {
+        throw new Error(`Invalid schema name: ${capability.name} does not match URL ${capability.schema}`);
+      }
+      try {
+        // TODO: also need to fetch more JSON schemas that may be referenced by the fields in this one
+        json = await fetchSchema(capability.schema);
+      } catch (error) {
+        throw new Error(`Schema not found for URL: ${capability.schema}`);
+      }
+      return {
+        capability,
+        schema: json
+      };
+    }));
+    return new UcpSchemaComposer({
+      capabilities: resolvedCapabilities
+    });
+  }
+  #profile;
+  #profileNameToUrlMap = new Map();
+  #profileUrlToCapabilityMap = new Map();
+  #schemaMapByOperation = new Map();
+  constructor(profile) {
+    this.#profile = profile;
+    for (const {
+      capability
+    } of profile.capabilities) {
+      this.#profileNameToUrlMap.set(capability.name, capability.schema);
+      this.#profileUrlToCapabilityMap.set(capability.schema, capability);
+    }
+  }
+
+  /**
+   * Get a schema file composer for the specified schema URL.
+   *
+   * @param schema - The schema URL or capability name
+   * @returns A UcpSchemaComposerFile instance, or undefined if not found
+   */
+  get(schema) {
+    const url = this.#profileNameToUrlMap.get(schema) ?? schema;
+    const capability = this.#profileUrlToCapabilityMap.get(url);
+
+    // TODO: we should allow any schema URL, not just the ones that were directly referenced
+    // in the profile. Right now, we do not traverse the graph of other JSON schemas that may be referenced
+    // by the fields in the profile capabilities.
+    if (capability == null) return undefined;
+    return new UcpSchemaComposerFile(url, {
+      capability,
+      composer: this
+    });
+  }
+
+  /**
+   * Get all schema entries for a specific operation.
+   *
+   * @param options - Options for getting entries
+   * @param options.operation - The operation context
+   * @returns An iterator of schema URL and composed schema pairs
+   */
+  entries({
+    operation = 'read'
+  } = {}) {
+    return this.#schemaMapForOperation(operation).entries();
+  }
+
+  /**
+   * Internal method to get the composed schema directly.
+   * Used by UcpSchemaComposerFile.
+   */
+  composedSchema(schema, {
+    operation = 'read'
+  } = {}) {
+    return this.#schemaMapForOperation(operation).get(schema);
+  }
+  #schemaMapForOperation(operation) {
+    let schemaMap = this.#schemaMapByOperation.get(operation);
+    if (schemaMap == null) {
+      schemaMap = createSchemaMap(this.#profile, {
+        operation
+      });
+    }
+    return schemaMap;
+  }
+}
+
+/**
+ * Represents a schema file that can be composed with different operation contexts.
+ */
+class UcpSchemaComposerFile {
+  #url;
+  #composer;
+  constructor(url, {
+    composer,
+    capability
+  }) {
+    this.#url = url;
+    this.#composer = composer;
+    this.capability = capability;
+  }
+
+  /**
+   * Get the composed schema for a specific operation.
+   */
+  composedSchema(options) {
+    const schema = this.#composer.composedSchema(this.#url, options);
+    if (schema == null) {
+      throw new ReferenceError(`Schema not found for URL: ${this.#url}`);
+    }
+    return schema;
+  }
+}
+
+// Helpers
+
+/**
+ * Compose schemas by resolving extensions
+ */
+function createSchemaMap({
+  capabilities
+}, {
+  operation
+}) {
+  const schemaMap = new Map();
+  const schemaNameToUrlMap = new Map();
+  for (const {
+    capability,
+    schema
+  } of capabilities) {
+    schemaNameToUrlMap.set(capability.name, capability.schema);
+    const clonedSchema = structuredClone(schema);
+    processSchemaUcpMetadata(clonedSchema, operation);
+    schemaMap.set(capability.schema, clonedSchema);
+    if (capability.extends == null) continue;
+    const defs = clonedSchema.$defs;
+    const extendedSchemas = Array.isArray(capability.extends) ? capability.extends : [capability.extends];
+    for (const extendedSchemaName of extendedSchemas) {
+      const extensionDef = defs?.[extendedSchemaName];
+      if (extensionDef?.allOf == null) continue;
+      const extendedSchemaUrl = schemaNameToUrlMap.get(extendedSchemaName);
+      const extendedSchema = extendedSchemaUrl ? schemaMap.get(extendedSchemaUrl) : undefined;
+      if (extendedSchema == null) continue;
+
+      // Make the base type ready for extension
+      if (extendedSchema.allOf?.[0]?.$ref !== `#/$defs/${extendedSchemaName}`) {
+        const newDef = {
+          type: 'object',
+          title: `${extendedSchema.title ?? extendedSchemaName} (base)`,
+          ...(extendedSchema.properties ? {
+            properties: extendedSchema.properties
+          } : {}),
+          ...(extendedSchema.required ? {
+            required: extendedSchema.required
+          } : {}),
+          ...(extendedSchema.items ? {
+            items: extendedSchema.items
+          } : {}),
+          ...(extendedSchema.allOf ? {
+            allOf: extendedSchema.allOf
+          } : {}),
+          ...(extendedSchema.oneOf ? {
+            oneOf: extendedSchema.oneOf
+          } : {})
+        };
+        extendedSchema.$defs ??= {};
+        extendedSchema.$defs[extendedSchemaName] = newDef;
+        extendedSchema.allOf = [{
+          type: 'object',
+          $ref: `#/$defs/${extendedSchemaName}`
+        }];
+        delete extendedSchema.properties;
+        delete extendedSchema.required;
+        delete extendedSchema.items;
+        delete extendedSchema.oneOf;
+      }
+      const clonedDefs = structuredClone(defs);
+
+      // Rewrite the extension def to remove a reference to the base type, we will manually
+      // create an `allOf` type for it that includes all schema additions.
+      const filtereExtensionDefAllOf = extensionDef.allOf.filter(({
+        $ref
+      }) => $ref == null || new URL($ref, capability.schema).href !== extendedSchemaUrl);
+      if (filtereExtensionDefAllOf.length > 1) {
+        clonedDefs[extendedSchemaName] = {
+          type: 'object',
+          allOf: filtereExtensionDefAllOf
+        };
+      } else {
+        const {
+          allOf,
+          ...rest
+        } = extensionDef;
+        clonedDefs[extendedSchemaName] = {
+          type: 'object',
+          ...rest,
+          ...filtereExtensionDefAllOf[0]
+        };
+      }
+
+      // TODO: turn this into a smarter def pruning algorithm
+      for (const otherExtendedSchemaName of extendedSchemas) {
+        if (otherExtendedSchemaName === extendedSchemaName) continue;
+        delete clonedDefs[otherExtendedSchemaName];
+      }
+      Object.assign(extendedSchema.$defs, namespaceExtensionDefs(clonedDefs, capability));
+      extendedSchema.allOf.push({
+        type: 'object',
+        $ref: `#/$defs/${namespaceIdentifier(extendedSchemaName, capability)}`
+      });
+    }
+  }
+  return {
+    get(schema) {
+      if (schemaNameToUrlMap.has(schema)) {
+        return schemaMap.get(schemaNameToUrlMap.get(schema));
+      }
+      return schemaMap.get(schema);
+    },
+    entries() {
+      return schemaMap.entries();
+    }
+  };
+}
+function processSchemaUcpMetadata(schema, operation) {
+  let requiredNeedsUpdate = false;
+  const updatedRequired = new Set(schema.required);
+  if (schema.properties != null) {
+    for (const [key, value] of Object.entries(schema.properties)) {
+      processSchemaUcpMetadata(value, operation);
+      if (value.ucp_request == null) continue;
+      const ucpRequest = typeof value.ucp_request === 'string' ? value.ucp_request : value.ucp_request[operation];
+      delete value.ucp_request;
+      if (operation === 'read') continue;
+      switch (ucpRequest) {
+        case 'omit':
+          delete schema.properties[key];
+          if (updatedRequired.has(key)) {
+            requiredNeedsUpdate = true;
+            updatedRequired.delete(key);
+          }
+          break;
+        case 'required':
+          if (!updatedRequired.has(key)) {
+            requiredNeedsUpdate = true;
+            updatedRequired.add(key);
+          }
+          break;
+        case 'optional':
+          if (updatedRequired.has(key)) {
+            requiredNeedsUpdate = true;
+            updatedRequired.delete(key);
+          }
+          break;
+      }
+    }
+  }
+  if (requiredNeedsUpdate) {
+    schema.required = Array.from(updatedRequired);
+  }
+  if (schema.items != null) {
+    if (Array.isArray(schema.items)) {
+      for (const item of schema.items) {
+        processSchemaUcpMetadata(item, operation);
+      }
+    } else {
+      processSchemaUcpMetadata(schema.items, operation);
+    }
+  }
+  if (schema.allOf != null) {
+    for (const allOfSchema of schema.allOf) {
+      processSchemaUcpMetadata(allOfSchema, operation);
+    }
+  }
+  if (schema.oneOf != null) {
+    for (const oneOfSchema of schema.oneOf) {
+      processSchemaUcpMetadata(oneOfSchema, operation);
+    }
+  }
+  if (schema.$defs != null) {
+    for (const value of Object.values(schema.$defs)) {
+      processSchemaUcpMetadata(value, operation);
+    }
+  }
+  return schema;
+}
+function namespaceIdentifier(identifier, capability) {
+  return `${capability.name}~${identifier}`;
+}
+function namespaceExtensionDefs(defs, capability) {
+  const newDefs = {};
+  for (const [key, value] of Object.entries(defs)) {
+    newDefs[namespaceIdentifier(key, capability)] = updateRefsWithNamespace(value, capability);
+  }
+  return newDefs;
+}
+function updateRefsWithNamespace(obj, capability) {
+  if (obj === null || typeof obj !== 'object') {
+    return obj;
+  }
+  if (Array.isArray(obj)) {
+    return obj.map(item => updateRefsWithNamespace(item, capability));
+  }
+  const cloned = obj;
+  for (const [key, value] of Object.entries(obj)) {
+    if (key === '$ref' && typeof value === 'string') {
+      // Update internal references like #/$defs/fulfillment_method
+      const match = value.match(/^#\/\$defs\/(.+)$/);
+      if (match?.[1]) {
+        cloned[key] = `#/$defs/${namespaceIdentifier(match[1], capability)}`;
+      } else {
+        cloned[key] = value;
+      }
+    } else {
+      cloned[key] = updateRefsWithNamespace(value, capability);
+    }
+  }
+  return cloned;
+}
+function createDefaultSchemaFetcher() {
+  const cache = new Map();
+  return url => {
+    const cached = cache.get(url);
+    if (cached) {
+      return cached;
+    }
+    const promise = fetch(url).then(response => response.json());
+    cache.set(url, promise);
+    return promise;
+  };
+}
+
+export { UcpSchemaComposer, UcpSchemaComposerFile };

package/build/esm/index.mjs

@@ -0,0 +1 @@
+export { UcpSchemaComposer } from './compose.mjs';

package/build/esm/mcp.mjs

@@ -0,0 +1,69 @@
+import { z } from 'zod';
+
+/**
+ * Converts a JSON schema object into a record, where each key is its own
+ * independent Zod type, matching all the resolved properties in the source
+ * JSON schema. This is needed for the `outputSchema` property of the MCP
+ * package, which expects a record of types, somewhat at odds with the
+ * MCP UCP specification which defines the result type of most operations as
+ * a whole, resolved `Checkout` object.
+ *
+ * @example
+ * ```ts
+ * const composer = await UcpSchemaComposer.fromProfile(profile);
+ * const checkout = composer.get('https://ucp.dev/schemas/shopping/checkout.json');
+ * const outputSchema = jsonSchemaToOutputSchema(checkout.composedSchema());
+ *
+ * mcpServer.registerTool('get_checkout', {outputSchema}, getCheckout);
+ * ```
+ */
+function jsonSchemaToOutputSchema(baseSchema) {
+  const {
+    properties,
+    required
+  } = flattenJsonSchema(baseSchema);
+  const requiredProperties = new Set(required);
+  const outputSchema = {};
+  for (const [propertyName, propertySchema] of Object.entries(properties)) {
+    // We need to create a stub type that can fully resolve, so we need to include all the defs
+    // in the schema.
+    const zodType = z.fromJSONSchema({
+      $schema: 'https://json-schema.org/draft/2020-12/schema',
+      ...propertySchema,
+      $defs: baseSchema.$defs
+    }, {
+      defaultTarget: 'openapi-3.0'
+    });
+    outputSchema[propertyName] = requiredProperties.has(propertyName) ? zodType : zodType.optional();
+  }
+  return outputSchema;
+}
+function flattenJsonSchema(baseSchema) {
+  const properties = {};
+  const required = new Set();
+  const mergedSchemas = [baseSchema, ...(baseSchema.allOf ?? []).flatMap(schema => {
+    if (schema.properties) {
+      return schema;
+    }
+    if (schema.$ref?.startsWith('#/$defs/')) {
+      return baseSchema.$defs?.[schema.$ref.slice('#/$defs/'.length)] ?? [];
+    }
+    return [];
+  })];
+  for (const schema of mergedSchemas) {
+    if (schema.properties) {
+      Object.assign(properties, schema.properties);
+    }
+    if (schema.required) {
+      for (const requiredPropertyName of schema.required) {
+        required.add(requiredPropertyName);
+      }
+    }
+  }
+  return {
+    properties,
+    required: Array.from(required)
+  };
+}
+
+export { jsonSchemaToOutputSchema };