@decocms/bindings 0.2.4-beta.4 → 1.0.0-test.1

package/README.md

@@ -36,7 +36,7 @@ Bindings are a core concept for defining and enforcing standardized interfaces t
 A binding is an array of tool definitions, each specifying a name and input/output schemas:
 
 ```typescript
-import { z } from "zod/v3";
+import { z } from "zod";
 import type { Binder } from "@decocms/bindings";
 
 // Define input/output schemas
@@ -242,7 +242,7 @@ All collection entity schemas must extend `BaseCollectionEntitySchema`, which re
 Collection bindings are a well-known binding pattern for SQL table-like structures. Import them from the well-known collections module:
 
 ```typescript
-import { z } from "zod/v3";
+import { z } from "zod";
 import { createCollectionBindings } from "@decocms/bindings/collections";
 import { createBindingChecker } from "@decocms/bindings";
 
@@ -491,7 +491,7 @@ Collection bindings are designed to work with TanStack DB's query-collection. Th
 Here's how you would implement a collection binding in an MCP server:
 
 ```typescript
-import { z } from "zod/v3";
+import { z } from "zod";
 import { createCollectionBindings } from "@decocms/bindings/collections";
 import { impl } from "@decocms/sdk/mcp/bindings/binder";
 

package/package.json

@@ -1,12 +1,10 @@
 {
   "name": "@decocms/bindings",
-  "version": "0.2.4-beta.4",
+  "version": "1.0.0-test.1",
   "type": "module",
   "scripts": {
-    "build": "tsup",
     "test": "vitest run",
-    "test:watch": "vitest",
-    "prepublishOnly": "npm run build"
+    "test:watch": "vitest"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.20.2",
@@ -14,40 +12,16 @@
     "zod-from-json-schema": "^0.0.5",
     "zod-to-json-schema": "3.25.0"
   },
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "files": [
-    "dist/**/*"
-  ],
   "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
-    },
-    "./client": {
-      "types": "./dist/core/client/index.d.ts",
-      "default": "./dist/core/client/index.js"
-    },
-    "./llm": {
-      "types": "./dist/well-known/language-model.d.ts",
-      "default": "./dist/well-known/language-model.js"
-    },
-    "./connection": {
-      "types": "./dist/core/connection.d.ts",
-      "default": "./dist/core/connection.js"
-    },
-    "./collections": {
-      "types": "./dist/well-known/collections.d.ts",
-      "default": "./dist/well-known/collections.js"
-    },
-    "./agent": {
-      "types": "./dist/well-known/agent.d.ts",
-      "default": "./dist/well-known/agent.js"
-    }
+    ".": "./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",
+    "./agent": "./src/well-known/agent.ts"
   },
   "devDependencies": {
-    "tsup": "^8.5.0",
-    "typescript": "^5.9.3",
     "vitest": "3.2.4"
   },
   "engines": {

package/src/core/binder.ts

@@ -0,0 +1,241 @@
+/**
+ * Core Binder Types and Utilities
+ *
+ * This module provides the core types and utilities for the bindings system.
+ * Bindings define standardized interfaces that integrations (MCPs) can implement.
+ */
+
+import type { ZodType } from "zod";
+import { zodToJsonSchema } from "zod-to-json-schema";
+import { createMCPFetchStub, MCPClientFetchStub } from "./client/mcp";
+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
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function isZodSchema(value: unknown): value is ZodType<any> {
+  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(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  schema: ZodType<any> | JsonSchema | null | undefined,
+): JsonSchema | null {
+  if (schema == null) {
+    return null;
+  }
+
+  if (isZodSchema(schema)) {
+    return zodToJsonSchema(schema) as JsonSchema;
+  }
+
+  // Already a JSON schema
+  return schema as JsonSchema;
+}
+
+/**
+ * ToolBinder defines a single tool within a binding.
+ * It specifies the tool name, input/output schemas, and whether it's optional.
+ *
+ * @template TName - The tool name (can be a string or RegExp for pattern matching)
+ * @template TInput - The input type (inferred from inputSchema)
+ * @template TReturn - The return type (inferred from outputSchema)
+ */
+export interface ToolBinder<
+  TName extends string | RegExp = string,
+  // biome-ignore lint/suspicious/noExplicitAny: Generic type parameter
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  TInput = any,
+  TReturn extends object | null | boolean = object,
+  TStreamable extends boolean = boolean,
+> {
+  /** The name of the tool (e.g., "DECO_CHAT_CHANNELS_JOIN") */
+  name: TName;
+
+  /** Zod schema for validating tool input */
+  inputSchema: ZodType<TInput>;
+
+  /** Optional Zod schema for validating tool output */
+  outputSchema?: TStreamable extends true ? never : ZodType<TReturn>;
+
+  /**
+   * Whether this tool is streamable.
+   */
+  streamable?: TStreamable;
+
+  /**
+   * Whether this tool is optional in the binding.
+   * If true, an implementation doesn't need to provide this tool.
+   */
+  opt?: true;
+}
+
+/**
+ * Binder represents a collection of tool definitions that form a binding.
+ * A binding is like a TypeScript interface - it defines what tools must be implemented.
+ *
+ * @template TDefinition - Array of ToolBinder definitions
+ *
+ * @example
+ * ```ts
+ * const MY_BINDING = [{
+ *   name: "MY_TOOL" as const,
+ *   inputSchema: z.object({ id: z.string() }),
+ *   outputSchema: z.object({ success: z.boolean() }),
+ * }] as const satisfies Binder;
+ * ```
+ */
+export type Binder<
+  TDefinition extends readonly ToolBinder[] = readonly ToolBinder[],
+> = TDefinition;
+
+/**
+ * Tool with schemas for validation
+ */
+export interface ToolWithSchemas {
+  name: string;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  inputSchema?: ZodType<any> | Record<string, unknown>;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  outputSchema?: ZodType<any> | Record<string, unknown>;
+}
+
+/**
+ * Binding checker interface
+ */
+export interface BindingChecker {
+  /**
+   * Check if a set of tools implements the binding with full schema validation.
+   *
+   * Validates:
+   * - Tool name matches (exact or regex)
+   * - Input schema: Tool accepts what binder requires (no removals from binder to tool)
+   * - Output schema: Tool provides what binder expects (no removals from tool to binder)
+   *
+   * @param tools - Array of tools with names and schemas
+   * @returns Promise<boolean> - true if all tools implement the binding correctly
+   */
+  isImplementedBy: (tools: ToolWithSchemas[]) => boolean;
+}
+
+export const bindingClient = <TDefinition extends readonly ToolBinder[]>(
+  binder: TDefinition,
+) => {
+  return {
+    ...createBindingChecker(binder),
+    forConnection: (
+      mcpConnection: MCPConnection,
+    ): MCPClientFetchStub<TDefinition> => {
+      return createMCPFetchStub<TDefinition>({
+        connection: mcpConnection,
+        streamable: binder.reduce(
+          (acc, tool) => {
+            acc[tool.name] = tool.streamable === true;
+            return acc;
+          },
+          {} as Record<string, boolean>,
+        ),
+      });
+    },
+  };
+};
+
+export type MCPBindingClient<T extends ReturnType<typeof bindingClient>> =
+  ReturnType<T["forConnection"]>;
+
+/**
+ * Creates a binding checker with full schema validation using structural subset checking.
+ *
+ * This performs strict compatibility checking:
+ * - For input schemas: Validates that the tool can accept what the binder requires (binder ⊆ tool)
+ * - For output schemas: Validates that the tool provides what the binder expects (binder ⊆ tool)
+ *
+ * @param binderTools - The binding definition to check against
+ * @returns A binding checker with an async isImplementedBy method
+ *
+ * @example
+ * ```ts
+ * const checker = createBindingChecker(MY_BINDING);
+ * const isCompatible = await checker.isImplementedBy(availableTools);
+ * ```
+ */
+export function createBindingChecker<TDefinition extends readonly ToolBinder[]>(
+  binderTools: TDefinition,
+): BindingChecker {
+  return {
+    isImplementedBy: (tools: ToolWithSchemas[]): boolean => {
+      for (const binderTool of binderTools) {
+        // Find matching tool by name (exact or regex)
+        const pattern =
+          typeof binderTool.name === "string"
+            ? new RegExp(`^${binderTool.name}$`)
+            : binderTool.name;
+
+        const matchedTool = tools.find((t) => pattern.test(t.name));
+
+        // Skip optional tools that aren't present
+        if (!matchedTool && binderTool.opt) {
+          continue;
+        }
+
+        // Required tool not found
+        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;
+        }
+      }
+      return true;
+    },
+  };
+}

package/src/core/client/README.md

@@ -0,0 +1,3 @@
+# Client Implementation
+
+This folder is basically a duplicated implementation based on runtime/binder.ts client. We should duplicate for now since we are remodeling the way applications invoke mesh.

package/{dist/core/client/http-client-transport.js → src/core/client/http-client-transport.ts}

@@ -1,11 +1,21 @@
+import type { JSONRPCMessage } from "@modelcontextprotocol/sdk/types.js";
 import {
-  StreamableHTTPClientTransport
+  StreamableHTTPClientTransport,
+  type StreamableHTTPClientTransportOptions,
 } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
-class HTTPClientTransport extends StreamableHTTPClientTransport {
-  constructor(url, opts) {
+
+export class HTTPClientTransport extends StreamableHTTPClientTransport {
+  constructor(url: URL, opts?: StreamableHTTPClientTransportOptions) {
     super(url, opts);
   }
-  send(message, options) {
+
+  override send(
+    message: JSONRPCMessage,
+    options?: {
+      resumptionToken?: string;
+      onresumptiontoken?: (token: string) => void;
+    },
+  ): Promise<void> {
     const mockAction = getMockActionFor(message);
     if (mockAction?.type === "emit") {
       this.onmessage?.(mockAction.message);
@@ -17,9 +27,15 @@ class HTTPClientTransport extends StreamableHTTPClientTransport {
     return super.send(message, options);
   }
 }
-function getMockActionFor(message) {
+
+type MockAction =
+  | { type: "emit"; message: JSONRPCMessage }
+  | { type: "suppress" };
+
+function getMockActionFor(message: JSONRPCMessage): MockAction | null {
   const m = message;
   if (!m || typeof m !== "object" || !("method" in m)) return null;
+
   switch (m.method) {
     case "initialize": {
       const protocolVersion = m?.params?.protocolVersion;
@@ -30,12 +46,12 @@ function getMockActionFor(message) {
           result: {
             protocolVersion,
             capabilities: { tools: {} },
-            serverInfo: { name: "deco-chat-server", version: "1.0.0" }
+            serverInfo: { name: "deco-chat-server", version: "1.0.0" },
           },
           jsonrpc: m.jsonrpc ?? "2.0",
           // @ts-expect-error - id is not typed
-          id: m.id
-        }
+          id: m.id,
+        } as JSONRPCMessage,
       };
     }
     case "notifications/roots/list_changed":
@@ -48,7 +64,3 @@ function getMockActionFor(message) {
       return null;
   }
 }
-export {
-  HTTPClientTransport
-};
-//# sourceMappingURL=http-client-transport.js.map

package/src/core/client/index.ts

@@ -0,0 +1 @@
+export { HTTPClientTransport } from "./http-client-transport";

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

@@ -0,0 +1,149 @@
+import {
+  Client as BaseClient,
+  ClientOptions,
+} from "@modelcontextprotocol/sdk/client/index.js";
+import {
+  SSEClientTransport,
+  SSEClientTransportOptions,
+} from "@modelcontextprotocol/sdk/client/sse.js";
+import { WebSocketClientTransport } from "@modelcontextprotocol/sdk/client/websocket.js";
+import { RequestOptions } from "@modelcontextprotocol/sdk/shared/protocol.js";
+import {
+  Implementation,
+  ListToolsRequest,
+  ListToolsResultSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import { MCPConnection } from "../connection";
+import { HTTPClientTransport } from "./http-client-transport";
+
+/**
+ * WARNNING: This is a hack to prevent schema compilation errors.
+ * More info at: https://github.com/modelcontextprotocol/typescript-sdk/issues/923
+ *
+ * Make sure to keep this updated with the right version of the SDK.
+ * https://github.com/modelcontextprotocol/typescript-sdk/blob/bf817939917277a4c59f2e19e7b44b8dd7ff140c/src/client/index.ts#L480
+ */
+class Client extends BaseClient {
+  constructor(_clientInfo: Implementation, options?: ClientOptions) {
+    super(_clientInfo, options);
+  }
+
+  override async listTools(
+    params?: ListToolsRequest["params"],
+    options?: RequestOptions,
+  ) {
+    const result = await this.request(
+      { method: "tools/list", params },
+      ListToolsResultSchema,
+      options,
+    );
+
+    return result;
+  }
+}
+
+export interface ServerClient {
+  client: Client;
+  callStreamableTool: (tool: string, args: unknown) => Promise<Response>;
+}
+export const createServerClient = async (
+  mcpServer: { connection: MCPConnection; name?: string },
+  signal?: AbortSignal,
+  extraHeaders?: Record<string, string>,
+): Promise<ServerClient> => {
+  const transport = createTransport(mcpServer.connection, signal, extraHeaders);
+
+  if (!transport) {
+    throw new Error("Unknown MCP connection type");
+  }
+
+  const client = new Client({
+    name: mcpServer?.name ?? "MCP Client",
+    version: "1.0.0",
+  });
+
+  await client.connect(transport);
+
+  return {
+    client,
+    callStreamableTool: (tool, args) => {
+      if (mcpServer.connection.type !== "HTTP") {
+        throw new Error("HTTP connection required");
+      }
+
+      const headers = new Headers(extraHeaders);
+
+      if (!headers.has("Authorization")) {
+        headers.set("Authorization", `Bearer ${mcpServer.connection.token}`);
+      }
+
+      for (const [key, value] of Object.entries(
+        mcpServer.connection.headers ?? {},
+      )) {
+        headers.set(key, value);
+      }
+
+      return fetch(mcpServer.connection.url + `/call-tool/${tool}`, {
+        method: "POST",
+        redirect: "manual",
+        body: JSON.stringify(args),
+        headers,
+      });
+    },
+  };
+};
+
+export const createTransport = (
+  connection: MCPConnection,
+  signal?: AbortSignal,
+  extraHeaders?: Record<string, string>,
+) => {
+  if (connection.type === "Websocket") {
+    return new WebSocketClientTransport(new URL(connection.url));
+  }
+
+  if (connection.type !== "SSE" && connection.type !== "HTTP") {
+    return null;
+  }
+
+  const authHeaders: Record<string, string> = connection.token
+    ? { authorization: `Bearer ${connection.token}` }
+    : {};
+
+  const headers: Record<string, string> = {
+    ...authHeaders,
+    ...(extraHeaders ?? {}),
+    ...("headers" in connection ? connection.headers || {} : {}),
+  };
+
+  if (connection.type === "SSE") {
+    const config: SSEClientTransportOptions = {
+      requestInit: { headers, signal },
+    };
+
+    if (connection.token) {
+      config.eventSourceInit = {
+        fetch: (req, init) => {
+          return fetch(req, {
+            ...init,
+            headers: {
+              ...headers,
+              Accept: "text/event-stream",
+            },
+            signal,
+          });
+        },
+      };
+    }
+
+    return new SSEClientTransport(new URL(connection.url), config);
+  }
+  return new HTTPClientTransport(new URL(connection.url), {
+    requestInit: {
+      headers,
+      signal,
+      // @ts-ignore - this is a valid option for fetch
+      credentials: "include",
+    },
+  });
+};

package/src/core/client/mcp.ts

@@ -0,0 +1,93 @@
+/* oxlint-disable no-explicit-any */
+import { z } from "zod";
+import type { MCPConnection } from "../connection";
+import { createMCPClientProxy } from "./proxy";
+
+export interface FetchOptions extends RequestInit {
+  path?: string;
+  segments?: string[];
+}
+
+// Default fetcher instance with API_SERVER_URL and API_HEADERS
+export const MCPClient = new Proxy(
+  {} as {
+    forConnection: <TDefinition extends readonly ToolBinder[]>(
+      connection: MCPConnection,
+    ) => MCPClientFetchStub<TDefinition>;
+  },
+  {
+    get(_, name) {
+      if (name === "toJSON") {
+        return null;
+      }
+
+      if (name === "forConnection") {
+        return <TDefinition extends readonly ToolBinder[]>(
+          connection: MCPConnection,
+        ) =>
+          createMCPFetchStub<TDefinition>({
+            connection,
+          });
+      }
+      return global[name as keyof typeof global];
+    },
+  },
+);
+
+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,
+    infer TInput,
+    infer TReturn
+  >
+    ? (params: TInput, init?: RequestInit) => Promise<TReturn>
+    : never;
+};
+
+export type MCPClientFetchStub<TDefinition extends readonly ToolBinder[]> = {
+  [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>
+      : never
+    : K extends ToolBinder<string, infer TInput, infer TReturn, any>
+      ? (params: TInput, init?: RequestInit) => Promise<Awaited<TReturn>>
+      : never;
+};
+
+export interface MCPClientRaw {
+  callTool: (tool: string, args: unknown) => Promise<unknown>;
+  listTools: () => Promise<
+    {
+      name: string;
+      inputSchema: any;
+      outputSchema?: any;
+      description: string;
+    }[]
+  >;
+}
+export type JSONSchemaToZodConverter = (jsonSchema: any) => z.ZodTypeAny;
+export interface CreateStubAPIOptions {
+  connection: MCPConnection;
+  streamable?: Record<string, boolean>;
+  debugId?: () => string;
+  getErrorByStatusCode?: (
+    statusCode: number,
+    message?: string,
+    traceId?: string,
+    errorObject?: unknown,
+  ) => Error;
+}
+
+export function createMCPFetchStub<TDefinition extends readonly ToolBinder[]>(
+  options: CreateStubAPIOptions,
+): MCPClientFetchStub<TDefinition> {
+  return createMCPClientProxy<MCPClientFetchStub<TDefinition>>(options);
+}