@decocms/bindings 1.0.1-alpha.4 → 1.0.2

package/README.md

@@ -621,14 +621,14 @@ This will generate ESM output in the `dist/` directory with TypeScript declarati
 
 ### Testing
 
-Tests are written with [Vitest](https://vitest.dev/):
+Tests are written with [Bun](https://bun.com/docs/test):
 
 ```bash
 # Run tests once
-bun run test
+bun test
 
 # Watch mode
-bun run test:watch
+bun test --watch
 ```
 
 ## Publishing

package/package.json

@@ -1,29 +1,26 @@
 {
   "name": "@decocms/bindings",
-  "version": "1.0.1-alpha.4",
+  "version": "1.0.2",
   "type": "module",
   "scripts": {
-    "test": "vitest run",
-    "test:watch": "vitest"
+    "check": "tsc --noEmit",
+    "test": "bun test"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.20.2",
+    "@modelcontextprotocol/sdk": "1.20.2",
     "zod": "^3.25.76",
-    "zod-from-json-schema": "^0.0.5",
-    "zod-to-json-schema": "3.25.0"
+    "zod-from-json-schema": "^0.0.5"
   },
   "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": {
-    "vitest": "3.2.4"
+    "./assistant": "./src/well-known/assistant.ts",
+    "./prompt": "./src/well-known/prompt.ts",
+    "./workflow": "./src/well-known/workflow.ts"
   },
   "engines": {
     "node": ">=24.0.0"

package/src/core/binder.ts

@@ -6,47 +6,9 @@
  */
 
 import type { ZodType } from "zod";
-import { zodToJsonSchema } from "zod-to-json-schema";
 import { createMCPFetchStub, MCPClientFetchStub } from "./client/mcp";
+import { ServerClient } from "./client/mcp-client";
 import { MCPConnection } from "./connection";
-import { isSubset } from "./subset";
-
-type JsonSchema = Record<string, unknown>;
-
-/**
- * Checks if a value is a Zod schema by looking for the _def property
- */
-function isZodSchema(value: unknown): value is ZodType<unknown> {
-  return (
-    value !== null &&
-    typeof value === "object" &&
-    "_def" in value &&
-    typeof (value as Record<string, unknown>)._def === "object"
-  );
-}
-
-/**
- * Normalizes a schema to JSON Schema format.
- * Accepts either a Zod schema or a JSON schema and returns a JSON schema.
- *
- * @param schema - A Zod schema or JSON schema
- * @returns The JSON schema representation, or null if input is null/undefined
- */
-export function normalizeToJsonSchema(
-  schema: ZodType<unknown> | JsonSchema | null | undefined,
-): JsonSchema | null {
-  if (schema == null) {
-    return null;
-  }
-
-  if (isZodSchema(schema)) {
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    return zodToJsonSchema(schema as any) as JsonSchema;
-  }
-
-  // Already a JSON schema
-  return schema as JsonSchema;
-}
 
 /**
  * ToolBinder defines a single tool within a binding.
@@ -138,6 +100,18 @@ export const bindingClient = <TDefinition extends readonly ToolBinder[]>(
 ) => {
   return {
     ...createBindingChecker(binder),
+    forClient: (client: ServerClient): MCPClientFetchStub<TDefinition> => {
+      return createMCPFetchStub<TDefinition>({
+        client,
+        streamable: binder.reduce(
+          (acc, tool) => {
+            acc[tool.name] = tool.streamable === true;
+            return acc;
+          },
+          {} as Record<string, boolean>,
+        ),
+      });
+    },
     forConnection: (
       mcpConnection: MCPConnection,
     ): MCPClientFetchStub<TDefinition> => {
@@ -155,7 +129,7 @@ export const bindingClient = <TDefinition extends readonly ToolBinder[]>(
   };
 };
 
-export type MCPBindingClient<T extends ReturnType<typeof bindingClient>> =
+export type MCPBindingClient<T extends ReturnType<typeof bindingClient<any>>> =
   ReturnType<T["forConnection"]>;
 
 /**
@@ -197,42 +171,7 @@ export function createBindingChecker<TDefinition extends readonly ToolBinder[]>(
         if (!matchedTool) {
           return false;
         }
-
-        // === INPUT SCHEMA VALIDATION ===
-        // Tool must accept what binder requires
-        // Check: isSubset(binder, tool) - every value valid under binder is valid under tool
-        const binderInputSchema = normalizeToJsonSchema(binderTool.inputSchema);
-        const toolInputSchema = normalizeToJsonSchema(matchedTool.inputSchema);
-
-        if (binderInputSchema && toolInputSchema) {
-          // Check if binder input is a subset of tool input (tool accepts what binder requires)
-          if (!isSubset(binderInputSchema, toolInputSchema)) {
-            return false;
-          }
-        } else if (binderInputSchema && !toolInputSchema) {
-          // Binder requires input schema but tool doesn't have one
-          return false;
-        }
-
-        // === OUTPUT SCHEMA VALIDATION ===
-        // Tool must provide what binder expects (but can provide more)
-        // Check: isSubset(binder, tool) - tool provides at least what binder expects
-        const binderOutputSchema = normalizeToJsonSchema(
-          binderTool.outputSchema,
-        );
-        const toolOutputSchema = normalizeToJsonSchema(
-          matchedTool.outputSchema,
-        );
-
-        if (binderOutputSchema && toolOutputSchema) {
-          // Check if binder output is a subset of tool output (tool provides what binder expects)
-          if (!isSubset(binderOutputSchema, toolOutputSchema)) {
-            return false;
-          }
-        } else if (binderOutputSchema && !toolOutputSchema) {
-          // Binder expects output schema but tool doesn't have one
-          return false;
-        }
+        // FIXME @mcandeia Zod to JSONSchema converstion is creating inconsistent schemas
       }
       return true;
     },

package/src/core/client/index.ts

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

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

@@ -9,8 +9,10 @@ import {
 import { WebSocketClientTransport } from "@modelcontextprotocol/sdk/client/websocket.js";
 import { RequestOptions } from "@modelcontextprotocol/sdk/shared/protocol.js";
 import {
+  CallToolRequest,
   Implementation,
   ListToolsRequest,
+  ListToolsResult,
   ListToolsResultSchema,
 } from "@modelcontextprotocol/sdk/types.js";
 import { MCPConnection } from "../connection";
@@ -41,10 +43,16 @@ class Client extends BaseClient {
     return result;
   }
 }
-
+type CallToolResponse = Awaited<ReturnType<Client["callTool"]>>;
 export interface ServerClient {
-  client: Client;
-  callStreamableTool: (tool: string, args: unknown) => Promise<Response>;
+  client: {
+    callTool: (params: CallToolRequest["params"]) => Promise<CallToolResponse>;
+    listTools: () => Promise<ListToolsResult>;
+  };
+  callStreamableTool: (
+    tool: string,
+    args: Record<string, unknown>,
+  ) => Promise<Response>;
 }
 export const createServerClient = async (
   mcpServer: { connection: MCPConnection; name?: string },
@@ -83,7 +91,12 @@ export const createServerClient = async (
         headers.set(key, value);
       }
 
-      return fetch(mcpServer.connection.url + `/call-tool/${tool}`, {
+      const url = new URL(mcpServer.connection.url);
+      // Trim trailing slashes from pathname, ensuring it starts with '/'
+      const trimmedPath = url.pathname.replace(/\/+$/, "") || "/";
+      url.pathname = `${trimmedPath}/call-tool/${encodeURIComponent(tool)}`;
+
+      return fetch(url.href, {
         method: "POST",
         redirect: "manual",
         body: JSON.stringify(args),
@@ -93,7 +106,7 @@ export const createServerClient = async (
   };
 };
 
-export const createTransport = (
+const createTransport = (
   connection: MCPConnection,
   signal?: AbortSignal,
   extraHeaders?: Record<string, string>,

package/src/core/client/mcp.ts

@@ -2,15 +2,19 @@
 import { z } from "zod";
 import type { MCPConnection } from "../connection";
 import { createMCPClientProxy } from "./proxy";
-
-export interface FetchOptions extends RequestInit {
-  path?: string;
-  segments?: string[];
-}
+export type { ServerClient } from "./mcp-client";
+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(
   {} as {
+    forClient: <TDefinition extends readonly ToolBinder[]>(
+      client: ServerClient,
+    ) => MCPClientFetchStub<TDefinition>;
     forConnection: <TDefinition extends readonly ToolBinder[]>(
       connection: MCPConnection,
     ) => MCPClientFetchStub<TDefinition>;
@@ -34,14 +38,16 @@ 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";
+import { ServerClient } from "./mcp-client";
 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,
@@ -53,6 +59,16 @@ export type MCPClientStub<TDefinition extends readonly ToolBinder[]> = {
 };
 
 export type MCPClientFetchStub<TDefinition extends readonly ToolBinder[]> = {
+  listTools: () => Promise<
+    {
+      id: string;
+      inputSchema: z.ZodType;
+      outputSchema: z.ZodType;
+      description: string;
+      execute: (params: any) => Promise<any>;
+    }[]
+  >;
+} & {
   [K in TDefinition[number] as K["name"]]: K["streamable"] extends true
     ? K extends ToolBinder<string, infer TInput, any, true>
       ? (params: TInput, init?: RequestInit) => Promise<Response>
@@ -74,10 +90,28 @@ export interface MCPClientRaw {
   >;
 }
 export type JSONSchemaToZodConverter = (jsonSchema: any) => z.ZodTypeAny;
-export interface CreateStubAPIOptions {
+
+export interface CreateStubForClientAPIOptions {
+  client: ServerClient;
+  streamable?: Record<string, boolean>;
+  debugId?: () => string;
+  getErrorByStatusCode?: (
+    statusCode: number,
+    message?: string,
+    traceId?: string,
+    errorObject?: unknown,
+  ) => Error;
+}
+
+export interface CreateStubForConnectionAPIOptions {
   connection: MCPConnection;
   streamable?: Record<string, boolean>;
   debugId?: () => string;
+  createServerClient?: (
+    mcpServer: { connection: MCPConnection; name?: string },
+    signal?: AbortSignal,
+    extraHeaders?: Record<string, string>,
+  ) => ServerClient;
   getErrorByStatusCode?: (
     statusCode: number,
     message?: string,
@@ -85,6 +119,9 @@ export interface CreateStubAPIOptions {
     errorObject?: unknown,
   ) => Error;
 }
+export type CreateStubAPIOptions =
+  | CreateStubForClientAPIOptions
+  | CreateStubForConnectionAPIOptions;
 
 export function createMCPFetchStub<TDefinition extends readonly ToolBinder[]>(
   options: CreateStubAPIOptions,

package/src/core/client/proxy.ts

@@ -11,24 +11,49 @@ const safeParse = (content: string) => {
   }
 };
 
-const toolsMap = new Map<
-  string,
-  Promise<
-    Array<{
-      name: string;
-      inputSchema: any;
-      outputSchema?: any;
-      description: string;
-    }>
-  >
->();
+type Tool = {
+  name: string;
+  inputSchema: any;
+  outputSchema?: any;
+  description: string;
+};
 
+const toolsMap = new Map<string, Promise<Array<Tool>>>();
+
+const mapTool = (
+  tool: Tool,
+  callToolFn: (input: any, toolName?: string) => Promise<any>,
+) => {
+  return {
+    ...tool,
+    id: tool.name,
+    inputSchema: tool.inputSchema
+      ? convertJsonSchemaToZod(tool.inputSchema)
+      : undefined,
+    outputSchema: tool.outputSchema
+      ? convertJsonSchemaToZod(tool.outputSchema)
+      : undefined,
+    execute: (input: any) => {
+      return callToolFn(input.context, tool.name);
+    },
+  };
+};
 /**
  * The base fetcher used to fetch the MCP from API.
  */
 export function createMCPClientProxy<T extends Record<string, unknown>>(
   options: CreateStubAPIOptions,
 ): T {
+  const createClient = (extraHeaders?: Record<string, string>) => {
+    if ("connection" in options) {
+      return createServerClient(
+        { connection: options.connection },
+        undefined,
+        extraHeaders,
+      );
+    }
+    return options.client;
+  };
   return new Proxy<T>({} as T, {
     get(_, name) {
       if (name === "toJSON") {
@@ -37,32 +62,28 @@ export function createMCPClientProxy<T extends Record<string, unknown>>(
       if (typeof name !== "string") {
         throw new Error("Name must be a string");
       }
-      async function callToolFn(args: unknown) {
+      if (name === "listTools") {
+        return asCallableTools;
+      }
+      async function callToolFn(
+        args: Record<string, unknown>,
+        toolName = name,
+      ) {
         const debugId = options?.debugId?.();
         const extraHeaders = debugId
           ? { "x-trace-debug-id": debugId }
           : undefined;
 
-        const { client, callStreamableTool } = await createServerClient(
-          { connection: options.connection },
-          undefined,
-          extraHeaders,
-        );
+        const { client, callStreamableTool } = await createClient(extraHeaders);
 
-        if (options?.streamable?.[String(name)]) {
-          return callStreamableTool(String(name), args);
+        if (options?.streamable?.[String(toolName)]) {
+          return callStreamableTool(String(toolName), args);
         }
 
-        const { structuredContent, isError, content } = await client.callTool(
-          {
-            name: String(name),
-            arguments: args as Record<string, unknown>,
-          },
-          undefined,
-          {
-            timeout: 3000000,
-          },
-        );
+        const { structuredContent, isError, content } = await client.callTool({
+          name: String(toolName),
+          arguments: args as Record<string, unknown>,
+        });
 
         if (isError) {
           const maybeErrorMessage = (content as { text: string }[])?.[0]?.text;
@@ -85,7 +106,7 @@ export function createMCPClientProxy<T extends Record<string, unknown>>(
           }
 
           throw new Error(
-            `Tool ${String(name)} returned an error: ${JSON.stringify(
+            `Tool ${String(toolName)} returned an error: ${JSON.stringify(
               structuredContent ?? content,
             )}`,
           );
@@ -93,10 +114,8 @@ export function createMCPClientProxy<T extends Record<string, unknown>>(
         return structuredContent;
       }
 
-      const listToolsFn = async () => {
-        const { client } = await createServerClient({
-          connection: options.connection,
-        });
+      async function listToolsFn() {
+        const { client } = await createClient();
         const { tools } = await client.listTools();
 
         return tools as {
@@ -105,9 +124,12 @@ export function createMCPClientProxy<T extends Record<string, unknown>>(
           outputSchema?: any;
           description: string;
         }[];
-      };
+      }
 
       async function listToolsOnce() {
+        if (!("connection" in options)) {
+          return listToolsFn();
+        }
         const conn = options.connection;
         const key = JSON.stringify(conn);
 
@@ -124,6 +146,12 @@ export function createMCPClientProxy<T extends Record<string, unknown>>(
           return;
         }
       }
+
+      async function asCallableTools() {
+        const tools = (await listToolsOnce()) ?? [];
+        return tools.map((tool) => mapTool(tool, callToolFn));
+      }
+
       callToolFn.asTool = async () => {
         const tools = (await listToolsOnce()) ?? [];
         const tool = tools.find((t) => t.name === name);
@@ -131,19 +159,7 @@ export function createMCPClientProxy<T extends Record<string, unknown>>(
           throw new Error(`Tool ${name} not found`);
         }
 
-        return {
-          ...tool,
-          id: tool.name,
-          inputSchema: tool.inputSchema
-            ? convertJsonSchemaToZod(tool.inputSchema)
-            : undefined,
-          outputSchema: tool.outputSchema
-            ? convertJsonSchemaToZod(tool.outputSchema)
-            : undefined,
-          execute: (input: any) => {
-            return callToolFn(input.context);
-          },
-        };
+        return mapTool(tool, callToolFn);
       };
       return callToolFn;
     },

package/src/index.ts

@@ -13,3 +13,60 @@ export {
   type ToolBinder,
   type ToolWithSchemas,
 } from "./core/binder";
+
+// Re-export registry binding types
+export {
+  MCPRegistryServerSchema,
+  type RegistryAppCollectionEntity,
+  REGISTRY_APP_BINDING,
+} from "./well-known/registry";
+
+// Re-export event subscriber binding types (for connections that receive events)
+export {
+  CloudEventSchema,
+  type CloudEvent,
+  EventResultSchema,
+  type EventResult,
+  OnEventsInputSchema,
+  type OnEventsInput,
+  OnEventsOutputSchema,
+  type OnEventsOutput,
+  EVENT_SUBSCRIBER_BINDING,
+  EventSubscriberBinding,
+  type EventSubscriberBindingClient,
+} from "./well-known/event-subscriber";
+
+// Re-export event bus binding types (for interacting with an event bus)
+export {
+  EventPublishInputSchema,
+  type EventPublishInput,
+  EventPublishOutputSchema,
+  type EventPublishOutput,
+  EventSubscribeInputSchema,
+  type EventSubscribeInput,
+  EventSubscribeOutputSchema,
+  type EventSubscribeOutput,
+  EventUnsubscribeInputSchema,
+  type EventUnsubscribeInput,
+  EventUnsubscribeOutputSchema,
+  type EventUnsubscribeOutput,
+  EventCancelInputSchema,
+  type EventCancelInput,
+  EventCancelOutputSchema,
+  type EventCancelOutput,
+  EventAckInputSchema,
+  type EventAckInput,
+  EventAckOutputSchema,
+  type EventAckOutput,
+  SubscriptionItemSchema,
+  type SubscriptionItem,
+  SubscriptionDetailSchema,
+  type SubscriptionDetail,
+  EventSyncSubscriptionsInputSchema,
+  type EventSyncSubscriptionsInput,
+  EventSyncSubscriptionsOutputSchema,
+  type EventSyncSubscriptionsOutput,
+  EVENT_BUS_BINDING,
+  EventBusBinding,
+  type EventBusBindingClient,
+} from "./well-known/event-bus";

package/src/well-known/assistant.ts

@@ -0,0 +1,87 @@
+/**
+ * Assistants Well-Known Binding
+ *
+ * Defines the interface for AI assistant providers.
+ * Any MCP that implements this binding can provide configurable AI assistants
+ * with a system prompt and runtime configuration (gateway + model).
+ *
+ * This binding uses collection bindings for full CRUD operations.
+ */
+
+import { z } from "zod";
+import type { Binder } from "../core/binder";
+import {
+  BaseCollectionEntitySchema,
+  createCollectionBindings,
+} from "./collections";
+
+/**
+ * Assistant entity schema for AI assistants
+ * Extends BaseCollectionEntitySchema with assistant-specific fields
+ * Base schema already includes: id, title, created_at, updated_at, created_by, updated_by
+ */
+export const AssistantSchema = BaseCollectionEntitySchema.extend({
+  /**
+   * Assistant avatar.
+   * Can be a regular URL or a data URI.
+   */
+  avatar: z
+    .string()
+    .describe("URL or data URI to the assistant's avatar image"),
+
+  /**
+   * System prompt that defines the assistant's behavior.
+   */
+  system_prompt: z
+    .string()
+    .describe("System prompt that defines the assistant's behavior"),
+
+  /**
+   * Selected gateway for this assistant (single gateway).
+   * This gateway determines which MCP tools are exposed to chat.
+   */
+  gateway_id: z.string().describe("Gateway ID to use for this assistant"),
+
+  /**
+   * Selected model for this assistant (model id + the connection where it lives).
+   * This allows the UI/runtime to call the correct model provider connection.
+   */
+  model: z
+    .object({
+      id: z.string().describe("Model ID"),
+      connectionId: z
+        .string()
+        .describe("Connection ID that provides the model"),
+    })
+    .describe("Selected model reference for this assistant"),
+});
+
+/**
+ * ASSISTANT Collection Binding
+ *
+ * Collection bindings for assistants.
+ * Provides full CRUD operations (LIST, GET, CREATE, UPDATE, DELETE) for AI assistants.
+ */
+export const ASSISTANTS_COLLECTION_BINDING = createCollectionBindings(
+  "assistant",
+  AssistantSchema,
+);
+
+/**
+ * ASSISTANTS Binding
+ *
+ * Defines the interface for AI assistant providers.
+ * Any MCP that implements this binding can provide configurable AI assistants.
+ *
+ * Required tools:
+ * - COLLECTION_ASSISTANT_LIST: List available AI assistants with their configurations
+ * - COLLECTION_ASSISTANT_GET: Get a single assistant by ID (includes system_prompt, gateway_id, model)
+ *
+ * Optional tools:
+ * - COLLECTION_ASSISTANT_CREATE: Create a new assistant
+ * - COLLECTION_ASSISTANT_UPDATE: Update an existing assistant
+ * - COLLECTION_ASSISTANT_DELETE: Delete an assistant
+ */
+export const ASSISTANTS_BINDING = [
+  ...ASSISTANTS_COLLECTION_BINDING,
+] as const satisfies Binder;