@decocms/bindings 0.1.0

package/src/well-known/collections.ts

@@ -0,0 +1,403 @@
+import { z } from "zod";
+import type { ToolBinder } from "../core/binder";
+
+/**
+ * Collection Bindings
+ *
+ * This module provides standardized tool bindings for Collections, representing
+ * SQL table-like structures with CRUD + Search operations compatible with TanStack DB.
+ *
+ * Key Features:
+ * - Generic collection bindings that work with any entity type
+ * - Standardized tool naming: `DECO_COLLECTION_{COLLECTION}_*`
+ * - Compatible with TanStack DB query-collection
+ * - Full TypeScript support with proper type constraints
+ * - Support for filtering, sorting, and pagination
+ * - Collection URI format: rsc://{connectionid}/{collection_name}/{item_id}
+ */
+
+/**
+ * Collection URI format validation
+ * Format: rsc://{connectionid}/{collection_name}/{item_id}
+ */
+export const CollectionUriSchema = z
+  .string()
+  .regex(
+    /^rsc:\/\/[^/]+\/[^/]+\/.+$/,
+    "Invalid collection URI format. Expected format: rsc://{connectionid}/{collection_name}/{item_id}",
+  );
+
+/**
+ * Utility function to validate a collection URI format
+ *
+ * @param uri - The URI to validate
+ * @returns True if the URI is valid, false otherwise
+ */
+export function validateCollectionUri(uri: string): boolean {
+  return CollectionUriSchema.safeParse(uri).success;
+}
+
+/**
+ * Utility function to parse a collection URI into its components
+ *
+ * @param uri - The URI to parse
+ * @returns Object containing the parsed components or null if invalid
+ */
+export function parseCollectionUri(uri: string): {
+  connectionId: string;
+  collectionName: string;
+  itemId: string;
+} | null {
+  const result = CollectionUriSchema.safeParse(uri);
+  if (!result.success) {
+    return null;
+  }
+
+  const match = result.data.match(/^rsc:\/\/([^/]+)\/([^/]+)\/(.+)$/);
+  if (!match) {
+    return null;
+  }
+
+  return {
+    connectionId: decodeURIComponent(match[1]),
+    collectionName: decodeURIComponent(match[2]),
+    itemId: decodeURIComponent(match[3]),
+  };
+}
+
+/**
+ * Utility function to construct a collection URI from components
+ *
+ * @param connectionId - The connection identifier
+ * @param collectionName - The collection name
+ * @param itemId - The item identifier
+ * @returns The constructed collection URI
+ */
+export function constructCollectionUri(
+  connectionId: string,
+  collectionName: string,
+  itemId: string,
+): string {
+  return `rsc://${encodeURIComponent(connectionId)}/${
+    encodeURIComponent(collectionName)
+  }/${encodeURIComponent(itemId)}`;
+}
+
+/**
+ * Base schema for collection entities
+ * All collection entities must have a uri field and audit trail fields
+ */
+export const BaseCollectionEntitySchema = z.object({
+  uri: z.string(),
+  created_at: z.string().datetime(),
+  updated_at: z.string().datetime(),
+  created_by: z.string().optional(),
+  updated_by: z.string().optional(),
+});
+
+/**
+ * Type helper for BaseCollectionEntitySchema
+ */
+export type BaseCollectionEntitySchemaType = typeof BaseCollectionEntitySchema;
+
+/**
+ * Where expression type for filtering
+ * Supports TanStack DB predicate push-down patterns
+ */
+export type WhereExpression =
+  | {
+    field: string[];
+    operator: "eq" | "gt" | "gte" | "lt" | "lte" | "in" | "like" | "contains";
+    value: unknown;
+  }
+  | {
+    operator: "and" | "or" | "not";
+    conditions: WhereExpression[];
+  };
+
+/**
+ * Where expression schema for filtering
+ * Supports TanStack DB predicate push-down patterns
+ */
+export const WhereExpressionSchema = z.lazy(() =>
+  z.union([
+    // Simple comparison
+    z.object({
+      field: z.array(z.string()),
+      operator: z.enum([
+        "eq",
+        "gt",
+        "gte",
+        "lt",
+        "lte",
+        "in",
+        "like",
+        "contains",
+      ]),
+      value: z.unknown(),
+    }),
+    // Logical operators
+    z.object({
+      operator: z.enum(["and", "or", "not"]),
+      conditions: z.array(WhereExpressionSchema),
+    }),
+  ])
+) as z.ZodType<WhereExpression>;
+
+/**
+ * Order by expression for sorting
+ */
+export const OrderByExpressionSchema = z.object({
+  field: z.array(z.string()),
+  direction: z.enum(["asc", "desc"]),
+  nulls: z.enum(["first", "last"]).optional(),
+});
+
+/**
+ * List/Query input schema for collections
+ * Compatible with TanStack DB LoadSubsetOptions
+ */
+export const CollectionListInputSchema = z.object({
+  where: WhereExpressionSchema.optional().describe("Filter expression"),
+  orderBy: z
+    .array(OrderByExpressionSchema)
+    .optional()
+    .describe("Sort expressions"),
+  limit: z
+    .number()
+    .int()
+    .min(1)
+    .max(1000)
+    .optional()
+    .describe("Maximum number of items to return"),
+  offset: z
+    .number()
+    .int()
+    .min(0)
+    .optional()
+    .describe("Number of items to skip"),
+});
+
+/**
+ * Factory function to create list output schema for a specific collection type
+ */
+export function createCollectionListOutputSchema<T extends z.ZodTypeAny>(
+  entitySchema: T,
+) {
+  return z.object({
+    items: z.array(entitySchema).describe("Array of collection items"),
+    totalCount: z
+      .number()
+      .int()
+      .min(0)
+      .optional()
+      .describe("Total number of matching items (if available)"),
+    hasMore: z
+      .boolean()
+      .optional()
+      .describe("Whether there are more items available"),
+  });
+}
+
+/**
+ * Get by URI input schema
+ */
+export const CollectionGetInputSchema = z.object({
+  uri: CollectionUriSchema.describe("URI of the entity to retrieve"),
+});
+
+/**
+ * Factory function to create get output schema
+ */
+export function createCollectionGetOutputSchema<T extends z.ZodTypeAny>(
+  entitySchema: T,
+) {
+  return z.object({
+    item: entitySchema
+      .nullable()
+      .describe("The retrieved item, or null if not found"),
+  });
+}
+
+/**
+ * Factory function to create insert input schema
+ */
+export function createCollectionInsertInputSchema<T extends z.ZodTypeAny>(
+  entitySchema: T,
+) {
+  // Remove uri field since it's auto-generated from connectionId/collectionName/itemId
+  return z.object({
+    data: entitySchema.describe("Data for the new entity (without uri)"),
+  });
+}
+
+/**
+ * Factory function to create insert output schema
+ */
+export function createCollectionInsertOutputSchema<T extends z.ZodTypeAny>(
+  entitySchema: T,
+) {
+  return z.object({
+    item: entitySchema.describe("The created entity with generated URI"),
+  });
+}
+
+/**
+ * Factory function to create update input schema
+ */
+export function createCollectionUpdateInputSchema<T extends z.ZodTypeAny>(
+  entitySchema: T,
+) {
+  return z.object({
+    uri: CollectionUriSchema.describe("URI of the entity to update"),
+    data: (entitySchema as unknown as z.AnyZodObject)
+      .partial()
+      .describe("Partial entity data to update"),
+  });
+}
+
+/**
+ * Factory function to create update output schema
+ */
+export function createCollectionUpdateOutputSchema<T extends z.ZodTypeAny>(
+  entitySchema: T,
+) {
+  return z.object({
+    item: entitySchema.describe("The updated entity"),
+  });
+}
+
+/**
+ * Delete input schema
+ */
+export const CollectionDeleteInputSchema = z.object({
+  uri: CollectionUriSchema.describe("URI of the entity to delete"),
+});
+
+/**
+ * Delete output schema
+ */
+export const CollectionDeleteOutputSchema = z.object({
+  success: z.boolean().describe("Whether the deletion was successful"),
+  uri: CollectionUriSchema.describe("URI of the deleted entity"),
+});
+
+/**
+ * Options for creating collection bindings
+ */
+export interface CollectionBindingOptions {
+  /**
+   * If true, only LIST and GET operations will be included (read-only collection)
+   * @default false
+   */
+  readOnly?: boolean;
+}
+
+/**
+ * Creates generic collection bindings for a specific entity type
+ *
+ * This function generates standardized tool bindings that work with any collection/table
+ * by accepting a custom entity schema and collection name. The bindings provide:
+ * - DECO_COLLECTION_{NAME}_LIST - Query/search entities with filtering and sorting (required)
+ * - DECO_COLLECTION_{NAME}_GET - Get a single entity by URI (required)
+ * - DECO_COLLECTION_{NAME}_INSERT - Create a new entity (optional, excluded if readOnly=true)
+ * - DECO_COLLECTION_{NAME}_UPDATE - Update an existing entity (optional, excluded if readOnly=true)
+ * - DECO_COLLECTION_{NAME}_DELETE - Delete an entity (optional, excluded if readOnly=true)
+ *
+ * @param collectionName - The name of the collection/table (e.g., "users", "products", "orders")
+ * @param entitySchema - The Zod schema for the entity type (must extend BaseCollectionEntitySchema)
+ * @param options - Optional configuration for the collection bindings
+ * @returns Array of tool bindings for Collection CRUD + Query operations
+ *
+ * @example
+ * ```typescript
+ * const UserSchema = z.object({
+ *   uri: z.string(),
+ *   created_at: z.string().datetime(),
+ *   updated_at: z.string().datetime(),
+ *   created_by: z.string().optional(),
+ *   updated_by: z.string().optional(),
+ *   name: z.string(),
+ *   email: z.string().email(),
+ * });
+ *
+ * // Full CRUD collection
+ * const USER_COLLECTION_BINDING = createCollectionBindings("users", UserSchema);
+ *
+ * // Read-only collection (only LIST and GET)
+ * const READONLY_COLLECTION_BINDING = createCollectionBindings("products", ProductSchema, { readOnly: true });
+ * ```
+ */
+export function createCollectionBindings<
+  TEntitySchema extends BaseCollectionEntitySchemaType,
+>(
+  collectionName: string,
+  entitySchema: TEntitySchema,
+  options?: CollectionBindingOptions,
+) {
+  const upperName = collectionName.toUpperCase();
+  const readOnly = options?.readOnly ?? false;
+
+  const bindings: ToolBinder[] = [
+    {
+      name: `DECO_COLLECTION_${upperName}_LIST` as const,
+      inputSchema: CollectionListInputSchema,
+      outputSchema: createCollectionListOutputSchema(entitySchema),
+    },
+    {
+      name: `DECO_COLLECTION_${upperName}_GET` as const,
+      inputSchema: CollectionGetInputSchema,
+      outputSchema: createCollectionGetOutputSchema(entitySchema),
+    },
+  ];
+
+  // Only include mutation operations if not read-only
+  if (!readOnly) {
+    bindings.push(
+      {
+        name: `DECO_COLLECTION_${upperName}_INSERT` as const,
+        inputSchema: createCollectionInsertInputSchema(entitySchema),
+        outputSchema: createCollectionInsertOutputSchema(entitySchema),
+        opt: true,
+      },
+      {
+        name: `DECO_COLLECTION_${upperName}_UPDATE` as const,
+        inputSchema: createCollectionUpdateInputSchema(entitySchema),
+        outputSchema: createCollectionUpdateOutputSchema(entitySchema),
+        opt: true,
+      },
+      {
+        name: `DECO_COLLECTION_${upperName}_DELETE` as const,
+        inputSchema: CollectionDeleteInputSchema,
+        outputSchema: CollectionDeleteOutputSchema,
+        opt: true,
+      },
+    );
+  }
+
+  return bindings satisfies readonly ToolBinder[];
+}
+
+/**
+ * Type helper to extract the collection binding type
+ */
+export type CollectionBinding<
+  TEntitySchema extends BaseCollectionEntitySchemaType,
+> = ReturnType<typeof createCollectionBindings<TEntitySchema>>;
+
+/**
+ * Type helper to extract tool names from a collection binding
+ */
+export type CollectionTools<
+  TEntitySchema extends BaseCollectionEntitySchemaType,
+> = CollectionBinding<TEntitySchema>[number]["name"];
+
+// Export types for TypeScript usage
+export type CollectionUri = z.infer<typeof CollectionUriSchema>;
+export type CollectionListInput = z.infer<typeof CollectionListInputSchema>;
+export type CollectionGetInput = z.infer<typeof CollectionGetInputSchema>;
+export type CollectionDeleteInput = z.infer<typeof CollectionDeleteInputSchema>;
+export type CollectionDeleteOutput = z.infer<
+  typeof CollectionDeleteOutputSchema
+>;
+export type OrderByExpression = z.infer<typeof OrderByExpressionSchema>;

package/src/well-known/models.ts

@@ -0,0 +1,69 @@
+/**
+ * Models Well-Known Binding
+ *
+ * Defines the interface for AI model providers.
+ * Any MCP that implements this binding can provide AI models and streaming endpoints.
+ *
+ * This binding uses collection bindings for LIST and GET operations (read-only),
+ * and adds a GET_STREAM_ENDPOINT tool for streaming functionality.
+ */
+
+import { z } from "zod";
+import type { Binder } from "../core/binder";
+import {
+  BaseCollectionEntitySchema,
+  createCollectionBindings,
+} from "./collections";
+
+/**
+ * Model entity schema for AI models
+ * Extends BaseCollectionEntitySchema with model-specific fields
+ */
+const ModelSchema = BaseCollectionEntitySchema.extend({
+  // Model-specific fields
+  id: z.string(),
+  model: z.string(),
+  name: z.string(),
+  logo: z.string().nullable(),
+  capabilities: z.array(z.string()),
+  contextWindow: z.number().nullable(),
+  inputCost: z.number().nullable(),
+  outputCost: z.number().nullable(),
+  outputLimit: z.number().nullable(),
+  description: z.string().nullable(),
+});
+
+/**
+ * MODELS Collection Binding
+ *
+ * Collection bindings for models (read-only).
+ * Provides LIST and GET operations for AI models.
+ */
+export const MODELS_COLLECTION_BINDING = createCollectionBindings(
+  "models",
+  ModelSchema,
+  { readOnly: true },
+);
+
+/**
+ * MODELS Binding
+ *
+ * Defines the interface for AI model providers.
+ * Any MCP that implements this binding can provide AI models and streaming endpoints.
+ *
+ * Required tools:
+ * - DECO_COLLECTION_MODELS_LIST: List available AI models with their capabilities
+ * - DECO_COLLECTION_MODELS_GET: Get a single model by URI
+ * - GET_STREAM_ENDPOINT: Get the streaming endpoint URL for chat completions
+ */
+export const MODELS_BINDING = [
+  ...MODELS_COLLECTION_BINDING,
+  {
+    name: "GET_STREAM_ENDPOINT" as const,
+    inputSchema: z.object({}).passthrough(),
+    outputSchema: z.object({
+      url: z.string().url(),
+    }).partial(),
+  },
+] as const satisfies Binder;
+