@decocms/bindings 1.0.0 → 1.0.1-alpha-candy.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/bindings",
-  "version": "1.0.0",
+  "version": "1.0.1-alpha-candy.1",
   "type": "module",
   "scripts": {
     "test": "vitest run",
@@ -14,11 +14,11 @@
   },
   "exports": {
     ".": "./src/index.ts",
-    "./models": "./src/well-known/models.ts",
     "./collections": "./src/well-known/collections.ts",
     "./llm": "./src/well-known/language-model.ts",
     "./connection": "./src/core/connection.ts",
     "./client": "./src/core/client/index.ts",
+    "./mcp": "./src/well-known/mcp.ts",
     "./agent": "./src/well-known/agent.ts"
   },
   "devDependencies": {

package/src/core/binder.ts

@@ -16,8 +16,7 @@ type JsonSchema = Record<string, unknown>;
 /**
  * Checks if a value is a Zod schema by looking for the _def property
  */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-function isZodSchema(value: unknown): value is ZodType<any> {
+function isZodSchema(value: unknown): value is ZodType<unknown> {
   return (
     value !== null &&
     typeof value === "object" &&
@@ -33,16 +32,16 @@ function isZodSchema(value: unknown): value is ZodType<any> {
  * @param schema - A Zod schema or JSON schema
  * @returns The JSON schema representation, or null if input is null/undefined
  */
-export function normalizeToJsonSchema(
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  schema: ZodType<any> | JsonSchema | null | undefined,
+function normalizeToJsonSchema(
+  schema: ZodType<unknown> | JsonSchema | null | undefined,
 ): JsonSchema | null {
   if (schema == null) {
     return null;
   }
 
   if (isZodSchema(schema)) {
-    return zodToJsonSchema(schema) as JsonSchema;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return zodToJsonSchema(schema as any) as JsonSchema;
   }
 
   // Already a JSON schema

package/src/core/client/index.ts

@@ -1 +1,9 @@
 export { HTTPClientTransport } from "./http-client-transport";
+export {
+  createMCPFetchStub,
+  isStreamableToolBinder,
+  MCPClient,
+  type CreateStubAPIOptions,
+  type MCPClientFetchStub,
+  type MCPClientStub,
+} from "./mcp";

package/src/core/client/mcp-client.ts

@@ -93,7 +93,7 @@ export const createServerClient = async (
   };
 };
 
-export const createTransport = (
+const createTransport = (
   connection: MCPConnection,
   signal?: AbortSignal,
   extraHeaders?: Record<string, string>,

package/src/core/client/mcp.ts

@@ -3,10 +3,11 @@ import { z } from "zod";
 import type { MCPConnection } from "../connection";
 import { createMCPClientProxy } from "./proxy";
 
-export interface FetchOptions extends RequestInit {
-  path?: string;
-  segments?: string[];
-}
+export const isStreamableToolBinder = (
+  toolBinder: ToolBinder,
+): toolBinder is ToolBinder<string, any, any, true> => {
+  return toolBinder.streamable === true;
+};
 
 // Default fetcher instance with API_SERVER_URL and API_HEADERS
 export const MCPClient = new Proxy(
@@ -34,14 +35,15 @@ export const MCPClient = new Proxy(
   },
 );
 
+export interface FetchOptions extends RequestInit {
+  path?: string;
+  segments?: string[];
+}
+
+// Default fetcher instance with API_SERVER_URL and API_HEADERS
 import type { ToolBinder } from "../binder";
 export type { ToolBinder };
 
-export const isStreamableToolBinder = (
-  toolBinder: ToolBinder,
-): toolBinder is ToolBinder<string, any, any, true> => {
-  return toolBinder.streamable === true;
-};
 export type MCPClientStub<TDefinition extends readonly ToolBinder[]> = {
   [K in TDefinition[number] as K["name"]]: K extends ToolBinder<
     string,

package/src/core/subset.ts

@@ -309,7 +309,7 @@ function isObjectSubset(a: JSONSchema, b: JSONSchema): boolean {
   for (const key of Object.keys(bProps)) {
     if (key in aProps) {
       // Both have the property, check recursively
-      if (!isSubset(aProps[key], bProps[key])) {
+      if (!isSubset(aProps[key]!, bProps[key]!)) {
         return false;
       }
     } else {
@@ -327,7 +327,7 @@ function isObjectSubset(a: JSONSchema, b: JSONSchema): boolean {
         // A is open, check if additionalProperties schema satisfies B's property
         const aAdditional = a.additionalProperties;
         if (aAdditional && typeof aAdditional === "object") {
-          if (!isSubset(aAdditional, bProps[key])) {
+          if (!isSubset(aAdditional, bProps[key]!)) {
             return false;
           }
         }
@@ -351,7 +351,7 @@ function isObjectSubset(a: JSONSchema, b: JSONSchema): boolean {
         typeof b.additionalProperties === "object"
       ) {
         // B has a schema for additional properties, check compatibility
-        if (!isSubset(aProps[key], b.additionalProperties)) {
+        if (!isSubset(aProps[key]!, b.additionalProperties)) {
           return false;
         }
       }

package/src/well-known/collections.ts

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { z, type ZodType } from "zod";
 import type { ToolBinder } from "../core/binder";
 
 /**
@@ -23,6 +23,7 @@ import type { ToolBinder } from "../core/binder";
 export const BaseCollectionEntitySchema = z.object({
   id: z.string().describe("Unique identifier for the entity"),
   title: z.string().describe("Human-readable title for the entity"),
+  description: z.string().nullish().describe("Description of the entity"),
   created_at: z.string().datetime(),
   updated_at: z.string().datetime(),
   created_by: z.string().optional(),
@@ -251,7 +252,7 @@ export interface CollectionBindingOptions {
  * ```
  */
 export function createCollectionBindings<
-  TEntitySchema extends BaseCollectionEntitySchemaType,
+  TEntitySchema extends z.AnyZodObject,
   TName extends string,
 >(
   collectionName: TName,
@@ -261,19 +262,18 @@ export function createCollectionBindings<
   const upperName = collectionName.toUpperCase() as Uppercase<TName>;
   const readOnly = options?.readOnly ?? false;
 
-  const bindings: CollectionBinding<TEntitySchema, Uppercase<TName>>[number][] =
-    [
-      {
-        name: `COLLECTION_${upperName}_LIST` as const,
-        inputSchema: CollectionListInputSchema,
-        outputSchema: createCollectionListOutputSchema(entitySchema),
-      },
-      {
-        name: `COLLECTION_${upperName}_GET` as const,
-        inputSchema: CollectionGetInputSchema,
-        outputSchema: createCollectionGetOutputSchema(entitySchema),
-      },
-    ];
+  const bindings: ToolBinder[] = [
+    {
+      name: `COLLECTION_${upperName}_LIST` as const,
+      inputSchema: CollectionListInputSchema,
+      outputSchema: createCollectionListOutputSchema(entitySchema),
+    },
+    {
+      name: `COLLECTION_${upperName}_GET` as const,
+      inputSchema: CollectionGetInputSchema,
+      outputSchema: createCollectionGetOutputSchema(entitySchema),
+    },
+  ];
 
   // Only include mutation operations if not read-only
   if (!readOnly) {
@@ -299,71 +299,67 @@ export function createCollectionBindings<
     );
   }
 
-  return bindings satisfies readonly ToolBinder[];
+  return bindings as unknown as CollectionBinding<
+    TEntitySchema,
+    Uppercase<TName>
+  >;
 }
 
-export type ReadOnlyCollectionBinding<
-  TEntitySchema extends BaseCollectionEntitySchemaType,
-  TUpperName extends Uppercase<string> = Uppercase<string>,
-> = [
-  {
-    name: `COLLECTION_${TUpperName}_LIST`;
-    inputSchema: typeof CollectionListInputSchema;
-    outputSchema: ReturnType<
-      typeof createCollectionListOutputSchema<TEntitySchema>
-    >;
-  },
-  {
-    name: `COLLECTION_${TUpperName}_GET`;
-    inputSchema: typeof CollectionGetInputSchema;
-    outputSchema: ReturnType<
-      typeof createCollectionGetOutputSchema<TEntitySchema>
-    >;
-  },
-];
+// Helper type for tool definition
+type ToolBinding<
+  Name extends string,
+  Input,
+  Output,
+  Opt extends boolean = false,
+> = {
+  name: Name;
+  inputSchema: ZodType<Input>;
+  outputSchema: ZodType<Output>;
+} & (Opt extends true ? { opt: true } : unknown);
+
 /**
  * Type helper to extract the collection binding type
  */
 export type CollectionBinding<
-  TEntitySchema extends BaseCollectionEntitySchemaType,
+  TEntitySchema extends z.AnyZodObject,
   TUpperName extends Uppercase<string> = Uppercase<string>,
+  TEntity = z.infer<TEntitySchema>,
 > = [
-  ...ReadOnlyCollectionBinding<TEntitySchema, TUpperName>,
-  {
-    name: `COLLECTION_${TUpperName}_CREATE`;
-    inputSchema: ReturnType<
-      typeof createCollectionInsertInputSchema<TEntitySchema>
-    >;
-    outputSchema: ReturnType<
-      typeof createCollectionInsertOutputSchema<TEntitySchema>
-    >;
-    opt: true;
-  },
-  {
-    name: `COLLECTION_${TUpperName}_UPDATE`;
-    inputSchema: ReturnType<
-      typeof createCollectionUpdateInputSchema<TEntitySchema>
-    >;
-    outputSchema: ReturnType<
-      typeof createCollectionUpdateOutputSchema<TEntitySchema>
-    >;
-    opt: true;
-  },
-  {
-    name: `COLLECTION_${TUpperName}_DELETE`;
-    inputSchema: typeof CollectionDeleteInputSchema;
-    outputSchema: ReturnType<
-      typeof createCollectionDeleteOutputSchema<TEntitySchema>
-    >;
-    opt: true;
-  },
+  ToolBinding<
+    `COLLECTION_${TUpperName}_LIST`,
+    CollectionListInput,
+    CollectionListOutput<TEntity>
+  >,
+  ToolBinding<
+    `COLLECTION_${TUpperName}_GET`,
+    CollectionGetInput,
+    CollectionGetOutput<TEntity>
+  >,
+  ToolBinding<
+    `COLLECTION_${TUpperName}_CREATE`,
+    CollectionInsertInput<TEntity>,
+    CollectionInsertOutput<TEntity>,
+    true
+  >,
+  ToolBinding<
+    `COLLECTION_${TUpperName}_UPDATE`,
+    CollectionUpdateInput<TEntity>,
+    CollectionUpdateOutput<TEntity>,
+    true
+  >,
+  ToolBinding<
+    `COLLECTION_${TUpperName}_DELETE`,
+    CollectionDeleteInput,
+    CollectionDeleteOutput<TEntity>,
+    true
+  >,
 ];
 
 /**
  * Type helper to extract tool names from a collection binding
  */
 export type CollectionTools<
-  TEntitySchema extends BaseCollectionEntitySchemaType,
+  TEntitySchema extends z.AnyZodObject,
   TUpperName extends Uppercase<string> = Uppercase<string>,
 > = CollectionBinding<TEntitySchema, TUpperName>[number]["name"];
 
@@ -373,6 +369,21 @@ export type CollectionGetInput = z.infer<typeof CollectionGetInputSchema>;
 export type CollectionDeleteInput = z.infer<typeof CollectionDeleteInputSchema>;
 export type OrderByExpression = z.infer<typeof OrderByExpressionSchema>;
 
+/**
+ * Type helper for insert input with generic item type
+ */
+export type CollectionInsertInput<T> = {
+  data: T;
+};
+
+/**
+ * Type helper for update input with generic item type
+ */
+export type CollectionUpdateInput<T> = {
+  id: string;
+  data: Partial<T>;
+};
+
 /**
  * Type helper for list output with generic item type
  */

package/src/well-known/mcp.ts

@@ -0,0 +1,35 @@
+/**
+ * MCP Well-Known Binding
+ *
+ * Defines the interface for retrieving MCP configuration.
+ */
+
+import { z } from "zod/v3";
+import type { Binder } from "../core/binder";
+
+/**
+ * MCP Configuration Output Schema
+ */
+export const McpConfigurationOutputSchema = z.object({
+  scopes: z.array(z.string()).describe("List of scopes available"),
+  stateSchema: z
+    .record(z.string(), z.unknown())
+    .describe("JSON Schema (draft-07) defining the state structure"),
+});
+
+export type McpConfigurationOutput = z.infer<
+  typeof McpConfigurationOutputSchema
+>;
+
+/**
+ * MCP Binding
+ *
+ * Tool to retrieve the MCP configuration including scopes and state schema.
+ */
+export const MCP_BINDING = [
+  {
+    name: "MCP_CONFIGURATION",
+    inputSchema: z.object({}),
+    outputSchema: McpConfigurationOutputSchema,
+  },
+] as const satisfies Binder;

package/test/mcp.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from "vitest";
+import {
+  MCP_BINDING,
+  McpConfigurationOutputSchema,
+} from "../src/well-known/mcp";
+
+describe("MCP Binding", () => {
+  it("should match the expected structure", () => {
+    expect(MCP_BINDING).toHaveLength(1);
+    const tool = MCP_BINDING[0];
+    expect(tool.name).toBe("MCP_CONFIGURATION");
+    expect(tool.inputSchema).toBeDefined();
+    expect(tool.outputSchema).toBeDefined();
+  });
+
+  it("should validate correct output", () => {
+    const validOutput = {
+      scopes: ["scope1", "scope2"],
+      stateSchema: {
+        type: "object",
+        properties: {
+          foo: { type: "string" },
+        },
+      },
+    };
+
+    const result = McpConfigurationOutputSchema.safeParse(validOutput);
+    expect(result.success).toBe(true);
+  });
+
+  it("should fail on invalid output", () => {
+    const invalidOutput = {
+      scopes: "not-an-array", // Invalid
+      stateSchema: { type: "object" },
+    };
+
+    const result = McpConfigurationOutputSchema.safeParse(invalidOutput);
+    expect(result.success).toBe(false);
+  });
+});