@decocms/bindings 0.1.0 → 0.1.1

package/README.md

@@ -216,12 +216,12 @@ const workflowBinding = createResourceBinding("workflow");
 
 ## Collection Bindings
 
-Collection bindings provide standardized CRUD + Search operations for SQL table-like collections, compatible with TanStack DB query-collection. They are designed for database tables where each entity has a unique URI and audit trail fields.
+Collection bindings provide standardized CRUD + Search operations for SQL table-like collections, compatible with TanStack DB query-collection. They are designed for database tables where each entity has a unique ID and human-readable title.
 
 ### Key Features
 
 - **SQL Table-like Structure**: Represents database tables with standardized operations
-- **URI-based Identification**: Uses collection URIs in format `rsc://{connectionid}/{collection_name}/{item_id}`
+- **Simple Identification**: Uses human-readable `id` and `title` fields
 - **Audit Trail**: All entities must include `created_at`, `updated_at`, `created_by`, and `updated_by` fields
 - **TanStack DB Compatible**: Works seamlessly with TanStack DB's query-collection LoadSubsetOptions
 - **Type-Safe**: Full TypeScript support with Zod validation
@@ -230,7 +230,8 @@ Collection bindings provide standardized CRUD + Search operations for SQL table-
 
 All collection entity schemas must extend `BaseCollectionEntitySchema`, which requires:
 
-- `uri`: Collection URI in format `rsc://{connectionid}/{collection_name}/{item_id}`
+- `id`: Unique identifier for the entity (string)
+- `title`: Human-readable title for the entity (string)
 - `created_at`: Creation timestamp (datetime string)
 - `updated_at`: Last update timestamp (datetime string)
 - `created_by`: User who created the entity (optional string)
@@ -247,13 +248,13 @@ import { createBindingChecker } from "@decocms/bindings";
 
 // Define your entity schema extending the base schema
 const TodoSchema = z.object({
-  uri: z.string(), // Collection URI: rsc://{connectionid}/todos/{item_id}
+  id: z.string(), // Unique identifier
+  title: z.string(), // Human-readable title (from base schema)
   created_at: z.string().datetime(),
   updated_at: z.string().datetime(),
   created_by: z.string().optional(),
   updated_by: z.string().optional(),
   // Your custom fields
-  title: z.string(),
   completed: z.boolean(),
   userId: z.number(),
 });
@@ -294,26 +295,26 @@ The `createCollectionBindings` function generates tool bindings based on the `re
    - Output: `items[]`, `totalCount?`, `hasMore?`
 
 2. **GET** - `DECO_COLLECTION_{NAME}_GET`
-   - Get a single entity by URI
-   - Input: `uri`
+   - Get a single entity by ID
+   - Input: `id` (string)
    - Output: `item | null`
 
 **Optional operations (excluded if `readOnly: true`):**
 
 3. **INSERT** - `DECO_COLLECTION_{NAME}_INSERT`
    - Create a new entity
-   - Input: `data` (without uri, which is auto-generated)
-   - Output: `item` (with generated URI)
+   - Input: `data` (id may be auto-generated by the server)
+   - Output: `item` (with generated id)
 
 4. **UPDATE** - `DECO_COLLECTION_{NAME}_UPDATE`
    - Update an existing entity
-   - Input: `uri`, `data` (partial)
+   - Input: `id` (string), `data` (partial)
    - Output: `item`
 
 5. **DELETE** - `DECO_COLLECTION_{NAME}_DELETE`
    - Delete an entity
-   - Input: `uri`
-   - Output: `success`, `uri`
+   - Input: `id` (string)
+   - Output: `success` (boolean), `id` (string)
 
 ### Read-Only Collections
 
@@ -332,7 +333,7 @@ This is useful for collections that are managed externally or should not be modi
 
 ## Models Bindings
 
-Models bindings provide a well-known interface for AI model providers. They use collection bindings under the hood for LIST and GET operations, and add a streaming endpoint tool.
+Models bindings provide a well-known interface for AI model providers. They use collection bindings under the hood for LIST and GET operations, with streaming endpoint information included directly in each model entity.
 
 ### Using Models Bindings
 
@@ -347,7 +348,6 @@ const modelsChecker = createBindingChecker(MODELS_BINDING);
 const availableTools = [
   { name: "DECO_COLLECTION_MODELS_LIST" },
   { name: "DECO_COLLECTION_MODELS_GET" },
-  { name: "GET_STREAM_ENDPOINT" },
 ];
 
 const isImplemented = await modelsChecker.isImplementedBy(availableTools);
@@ -359,21 +359,16 @@ console.log(isImplemented); // true if all required tools are present
 The `MODELS_BINDING` includes:
 
 1. **DECO_COLLECTION_MODELS_LIST** (required)
-   - List available AI models with their capabilities
+   - List available AI models with their capabilities and streaming endpoints
    - Uses collection binding LIST operation
    - Input: `where?`, `orderBy?`, `limit?`, `offset?`
-   - Output: `items[]` (array of model entities)
+   - Output: `items[]` (array of model entities with endpoint info)
 
 2. **DECO_COLLECTION_MODELS_GET** (required)
-   - Get a single model by URI
+   - Get a single model by ID
    - Uses collection binding GET operation
-   - Input: `uri`
-   - Output: `item | null`
-
-3. **GET_STREAM_ENDPOINT** (required)
-   - Get the streaming endpoint URL for chat completions
-   - Input: `{}` (empty object, passthrough)
-   - Output: `{ url?: string }` (optional URL)
+   - Input: `id` (string)
+   - Output: `item | null` (model entity with endpoint info)
 
 ### Model Entity Schema
 
@@ -381,21 +376,29 @@ Models follow the collection entity schema with additional model-specific fields
 
 ```typescript
 {
-  uri: string;                    // Collection URI
-  created_at: string;            // Creation timestamp
-  updated_at: string;             // Last update timestamp
-  created_by?: string;           // User who created
-  updated_by?: string;           // User who last updated
-  id: string;                    // Model ID
-  model: string;                 // Model identifier
-  name: string;                  // Display name
-  logo: string | null;           // Logo URL
-  capabilities: string[];         // Array of capabilities
-  contextWindow: number | null;   // Context window size
-  inputCost: number | null;      // Input cost per token
-  outputCost: number | null;     // Output cost per token
-  outputLimit: number | null;    // Output limit
-  description: string | null;    // Model description
+  id: string;                      // Unique identifier (from base schema)
+  title: string;                   // Display name (from base schema)
+  created_at: string;              // Creation timestamp
+  updated_at: string;              // Last update timestamp
+  created_by?: string;             // User who created
+  updated_by?: string;             // User who last updated
+  logo: string | null;             // Logo URL
+  description: string | null;      // Model description
+  capabilities: string[];          // Array of capabilities
+  limits: {                        // Model limits
+    contextWindow: number;         // Maximum context window size
+    maxOutputTokens: number;       // Maximum output tokens
+  } | null;
+  costs: {                         // Model costs
+    input: number;                 // Cost per input token
+    output: number;                // Cost per output token
+  } | null;
+  endpoint: {                      // Streaming endpoint information
+    url: string;                   // Endpoint URL
+    method: string;                // HTTP method (default: "POST")
+    contentType: string;           // Content type (default: "application/json")
+    stream: boolean;               // Supports streaming (default: true)
+  } | null;
 }
 ```
 
@@ -405,7 +408,6 @@ Here's how you would implement the models binding in an MCP server:
 
 ```typescript
 import { MODELS_BINDING } from "@decocms/bindings/well-known/models";
-import { parseCollectionUri } from "@decocms/bindings/well-known/collections";
 import { impl } from "@decocms/sdk/mcp/bindings/binder";
 
 const modelTools = impl(MODELS_BINDING, [
@@ -420,26 +422,19 @@ const modelTools = impl(MODELS_BINDING, [
         skip: offset,
       });
       
+      // Include endpoint info in each model
       return { items, hasMore: items.length === limit };
     },
   },
   {
-    description: "Get a model by URI",
-    handler: async ({ uri }) => {
-      const parsed = parseCollectionUri(uri);
+    description: "Get a model by ID",
+    handler: async ({ id }) => {
       const item = await db.models.findUnique({
-        where: { id: parsed.itemId },
+        where: { id },
       });
       return { item };
     },
   },
-  {
-    description: "Get streaming endpoint",
-    handler: async () => {
-      // Return your streaming endpoint URL
-      return { url: "https://api.example.com/v1/chat/completions" };
-    },
-  },
 ]);
 ```
 
@@ -487,30 +482,6 @@ The `orderBy` parameter supports multi-field sorting:
 ]
 ```
 
-### Collection URI Helpers
-
-The package provides utility functions for working with collection URIs:
-
-```typescript
-import {
-  validateCollectionUri,
-  parseCollectionUri,
-  constructCollectionUri,
-} from "@decocms/bindings/well-known/collections";
-
-// Validate a URI
-const isValid = validateCollectionUri("rsc://conn-123/users/user-456");
-// true
-
-// Parse a URI into components
-const parsed = parseCollectionUri("rsc://conn-123/users/user-456");
-// { connectionId: "conn-123", collectionName: "users", itemId: "user-456" }
-
-// Construct a URI from components
-const uri = constructCollectionUri("conn-123", "users", "user-456");
-// "rsc://conn-123/users/user-456"
-```
-
 ### TanStack DB Integration
 
 Collection bindings are designed to work with TanStack DB's query-collection. The `where` and `orderBy` expressions are compatible with TanStack DB's `LoadSubsetOptions`, allowing for efficient predicate push-down to your backend.
@@ -522,16 +493,15 @@ Here's how you would implement a collection binding in an MCP server:
 ```typescript
 import { z } from "zod";
 import { createCollectionBindings } from "@decocms/bindings/well-known/collections";
-import { parseCollectionUri, constructCollectionUri } from "@decocms/bindings/well-known/collections";
 import { impl } from "@decocms/sdk/mcp/bindings/binder";
 
 const TodoSchema = z.object({
-  uri: z.string(),
+  id: z.string(),
+  title: z.string(), // From base schema
   created_at: z.string().datetime(),
   updated_at: z.string().datetime(),
   created_by: z.string().optional(),
   updated_by: z.string().optional(),
-  title: z.string(),
   completed: z.boolean(),
   userId: z.number(),
 });
@@ -555,11 +525,10 @@ const todoTools = impl(TODO_COLLECTION_BINDING, [
     },
   },
   {
-    description: "Get a todo by URI",
-    handler: async ({ uri }) => {
-      const parsed = parseCollectionUri(uri);
+    description: "Get a todo by ID",
+    handler: async ({ id }) => {
       const item = await db.todos.findUnique({
-        where: { id: parsed.itemId },
+        where: { id },
       });
       return { item };
     },
@@ -567,21 +536,20 @@ const todoTools = impl(TODO_COLLECTION_BINDING, [
   {
     description: "Create a new todo",
     handler: async ({ data }) => {
-      const item = await db.todos.create({ data });
-      const uri = constructCollectionUri(
-        connectionId,
-        "todos",
-        item.id
-      );
-      return { item: { ...item, uri } };
+      const item = await db.todos.create({ 
+        data: {
+          ...data,
+          id: data.id || generateId(), // Use provided ID or generate one
+        }
+      });
+      return { item };
     },
   },
   {
     description: "Update a todo",
-    handler: async ({ uri, data }) => {
-      const parsed = parseCollectionUri(uri);
+    handler: async ({ id, data }) => {
       const item = await db.todos.update({
-        where: { id: parsed.itemId },
+        where: { id },
         data,
       });
       return { item };
@@ -589,10 +557,9 @@ const todoTools = impl(TODO_COLLECTION_BINDING, [
   },
   {
     description: "Delete a todo",
-    handler: async ({ uri }) => {
-      const parsed = parseCollectionUri(uri);
-      await db.todos.delete({ where: { id: parsed.itemId } });
-      return { success: true, uri };
+    handler: async ({ id }) => {
+      await db.todos.delete({ where: { id } });
+      return { success: true, id };
     },
   },
 ]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/bindings",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "scripts": {
     "build": "tsup",

package/src/well-known/collections.ts

@@ -13,82 +13,16 @@ import type { ToolBinder } from "../core/binder";
  * - 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}
+ * - Simple id and title fields for human-readable identification
  */
 
-/**
- * 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
+ * All collection entities must have an id, title, and audit trail fields
  */
 export const BaseCollectionEntitySchema = z.object({
-  uri: z.string(),
+  id: z.string().describe("Unique identifier for the entity"),
+  title: z.string().describe("Human-readable title for the entity"),
   created_at: z.string().datetime(),
   updated_at: z.string().datetime(),
   created_by: z.string().optional(),
@@ -200,10 +134,10 @@ export function createCollectionListOutputSchema<T extends z.ZodTypeAny>(
 }
 
 /**
- * Get by URI input schema
+ * Get by ID input schema
  */
 export const CollectionGetInputSchema = z.object({
-  uri: CollectionUriSchema.describe("URI of the entity to retrieve"),
+  id: z.string().describe("ID of the entity to retrieve"),
 });
 
 /**
@@ -225,9 +159,9 @@ export function createCollectionGetOutputSchema<T extends z.ZodTypeAny>(
 export function createCollectionInsertInputSchema<T extends z.ZodTypeAny>(
   entitySchema: T,
 ) {
-  // Remove uri field since it's auto-generated from connectionId/collectionName/itemId
+  // Remove id field since it may be auto-generated by the server
   return z.object({
-    data: entitySchema.describe("Data for the new entity (without uri)"),
+    data: entitySchema.describe("Data for the new entity (id may be auto-generated)"),
   });
 }
 
@@ -238,7 +172,7 @@ export function createCollectionInsertOutputSchema<T extends z.ZodTypeAny>(
   entitySchema: T,
 ) {
   return z.object({
-    item: entitySchema.describe("The created entity with generated URI"),
+    item: entitySchema.describe("The created entity with generated id"),
   });
 }
 
@@ -249,7 +183,7 @@ export function createCollectionUpdateInputSchema<T extends z.ZodTypeAny>(
   entitySchema: T,
 ) {
   return z.object({
-    uri: CollectionUriSchema.describe("URI of the entity to update"),
+    id: z.string().describe("ID of the entity to update"),
     data: (entitySchema as unknown as z.AnyZodObject)
       .partial()
       .describe("Partial entity data to update"),
@@ -271,7 +205,7 @@ export function createCollectionUpdateOutputSchema<T extends z.ZodTypeAny>(
  * Delete input schema
  */
 export const CollectionDeleteInputSchema = z.object({
-  uri: CollectionUriSchema.describe("URI of the entity to delete"),
+  id: z.string().describe("ID of the entity to delete"),
 });
 
 /**
@@ -279,7 +213,7 @@ export const CollectionDeleteInputSchema = z.object({
  */
 export const CollectionDeleteOutputSchema = z.object({
   success: z.boolean().describe("Whether the deletion was successful"),
-  uri: CollectionUriSchema.describe("URI of the deleted entity"),
+  id: z.string().describe("ID of the deleted entity"),
 });
 
 /**
@@ -299,7 +233,7 @@ export interface CollectionBindingOptions {
  * 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}_GET - Get a single entity by ID (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)
@@ -312,12 +246,12 @@ export interface CollectionBindingOptions {
  * @example
  * ```typescript
  * const UserSchema = z.object({
- *   uri: z.string(),
+ *   id: z.string(),
+ *   title: 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(),
  * });
  *
@@ -393,7 +327,6 @@ export type CollectionTools<
 > = 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>;

package/src/well-known/models.ts

@@ -4,8 +4,8 @@
  * 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.
+ * This binding uses collection bindings for LIST and GET operations (read-only).
+ * Streaming endpoint information is included directly in the model entity schema.
  */
 
 import { z } from "zod";
@@ -18,19 +18,28 @@ import {
 /**
  * Model entity schema for AI models
  * Extends BaseCollectionEntitySchema with model-specific fields
+ * Base schema already includes: id, title, created_at, updated_at, created_by, updated_by
  */
 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(),
+  capabilities: z.array(z.string()),
+  limits: z.object({
+    contextWindow: z.number(),
+    maxOutputTokens: z.number(),
+  }).nullable(),
+  costs: z.object({
+    input: z.number(),
+    output: z.number(),
+  }).nullable(),
+  // Streaming endpoint information
+  endpoint: z.object({
+    url: z.string().url(),
+    method: z.string().default("POST"),
+    contentType: z.string().default("application/json"),
+    stream: z.boolean().default(true),
+  }).nullable(),
 });
 
 /**
@@ -53,17 +62,8 @@ export const MODELS_COLLECTION_BINDING = createCollectionBindings(
  *
  * 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
+ * - DECO_COLLECTION_MODELS_GET: Get a single model by ID (includes streaming endpoint info)
  */
 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;
-