@decocms/runtime 1.0.0-alpha.37 → 1.0.0-alpha.38

package/config-schema.json

@@ -447,6 +447,10 @@
         "name": {
           "type": "string"
         },
+        "array": {
+          "type": "boolean",
+          "const": true
+        },
         "type": {
           "type": "string",
           "const": "mcp"
@@ -469,6 +473,10 @@
         "name": {
           "type": "string"
         },
+        "array": {
+          "type": "boolean",
+          "const": true
+        },
         "type": {
           "type": "string",
           "const": "mcp"
@@ -479,7 +487,6 @@
         }
       },
       "required": [
-        "app_name",
         "name",
         "type"
       ],
@@ -491,6 +498,10 @@
         "name": {
           "type": "string"
         },
+        "array": {
+          "type": "boolean",
+          "const": true
+        },
         "type": {
           "type": "string",
           "const": "contract"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/runtime",
-  "version": "1.0.0-alpha.37",
+  "version": "1.0.0-alpha.38",
   "type": "module",
   "scripts": {
     "check": "tsc --noEmit"

package/src/bindings/binder.ts

@@ -88,7 +88,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"]>;
 
 export const ChannelBinding = bindingClient(CHANNEL_BINDING);

package/src/bindings.ts

@@ -1,18 +1,96 @@
+import { CollectionBinding } from "packages/bindings/src/well-known/collections.ts";
 import type { MCPConnection } from "./connection.ts";
-import type { DefaultEnv, RequestContext } from "./index.ts";
-import { MCPClient } from "./mcp.ts";
-import type {
-  BindingBase,
-  ContractBinding,
-  MCPAppBinding,
-  MCPBinding,
-} from "./wrangler.ts";
+import type { RequestContext } from "./index.ts";
+import { type MCPClientFetchStub, MCPClient, type ToolBinder } from "./mcp.ts";
+import { z } from "zod";
 
 type ClientContext = Omit<
   RequestContext,
   "ensureAuthenticated" | "state" | "fetchIntegrationMetadata"
 >;
 
+export interface Binding<TType extends string = string> {
+  __type: TType;
+  value: string;
+}
+
+/**
+ * A registry mapping binding type strings (e.g. "@deco/database") to their ToolBinder definitions.
+ * Used by ResolvedBindings to resolve binding types to their corresponding MCP client types.
+ *
+ * @example
+ * ```ts
+ * type MyBindings = {
+ *   "@deco/database": typeof DATABASE_BINDING;
+ *   "@deco/storage": typeof STORAGE_BINDING;
+ * };
+ * ```
+ */
+export type BindingRegistry = Record<string, readonly ToolBinder[]>;
+
+/**
+ * Function that returns Zod Schema
+ */
+export const BindingOf = <TRegistry extends BindingRegistry>(
+  name: keyof TRegistry | "*",
+) => {
+  return z.object({
+    __type: z.literal(name).default(name as any),
+    value: z.string(),
+  });
+};
+
+/**
+ * Recursively transforms a type T by replacing all Binding instances with their
+ * corresponding MCPClientFetchStub based on the __type field.
+ *
+ * @template T - The source type to transform
+ * @template TBindings - A registry mapping binding __type strings to ToolBinder definitions
+ *
+ * @example
+ * ```ts
+ * interface State {
+ *   db: Binding<"@deco/database">;
+ *   items: Array<Binding<"@deco/storage">>;
+ *   config: { nested: Binding<"@deco/config"> };
+ * }
+ *
+ * type Resolved = ResolvedBindings<State, {
+ *   "@deco/database": typeof DATABASE_BINDING;
+ *   "@deco/storage": typeof STORAGE_BINDING;
+ * }>;
+ * // Result:
+ * // {
+ * //   db: MCPClientFetchStub<typeof DATABASE_BINDING>;
+ * //   items: Array<MCPClientFetchStub<typeof STORAGE_BINDING>>;
+ * //   config: { nested: unknown }; // "@deco/config" not in registry
+ * // }
+ * ```
+ */
+export type ResolvedBindings<
+  T,
+  TBindings extends BindingRegistry,
+> = T extends Binding<infer TType>
+  ? TType extends keyof TBindings
+    ? MCPClientFetchStub<TBindings[TType]> & { __type: TType; value: string }
+    : MCPClientFetchStub<[]> & { __type: string; value: string }
+  : T extends Array<infer U>
+    ? Array<ResolvedBindings<U, TBindings>>
+    : T extends object
+      ? { [K in keyof T]: ResolvedBindings<T[K], TBindings> }
+      : T;
+
+export const isBinding = (v: unknown): v is Binding => {
+  return (
+    typeof v === "object" &&
+    v !== null &&
+    "__type" in v &&
+    typeof v.__type === "string" &&
+    "value" in v &&
+    typeof v.value === "string"
+  );
+};
+
 export const proxyConnectionForId = (
   connectionId: string,
   ctx: Omit<ClientContext, "token"> & {
@@ -36,65 +114,72 @@ export const proxyConnectionForId = (
     headers,
   };
 };
+
 const mcpClientForConnectionId = (
   connectionId: string,
   ctx: ClientContext,
   appName?: string,
 ) => {
   const mcpConnection = proxyConnectionForId(connectionId, ctx, appName);
-
-  // TODO(@igorbrasileiro): Switch this proxy to be a proxy that call MCP Client.toolCall from @modelcontextprotocol
-  return MCPClient.forConnection(mcpConnection);
+  return new Proxy(MCPClient.forConnection(mcpConnection), {
+    get(target, name) {
+      if (name === "value") {
+        return connectionId;
+      }
+      if (name === "__type") {
+        return appName;
+      }
+      return target[name as keyof typeof target];
+    },
+  });
 };
 
-function mcpClientFromState(
-  binding: BindingBase | MCPAppBinding,
-  env: DefaultEnv,
-) {
-  const ctx = env.MESH_REQUEST_CONTEXT;
-  const bindingFromState = ctx?.state?.[binding.name];
-  const connectionId =
-    bindingFromState &&
-    typeof bindingFromState === "object" &&
-    "value" in bindingFromState
-      ? bindingFromState.value
-      : undefined;
-  if (typeof connectionId !== "string" && "app_name" in binding) {
-    // in case of a binding to an app name, we need to use the new apps/mcp endpoint which will proxy the request to the app but without any token
-    return undefined;
+const traverseAndReplace = (obj: unknown, ctx: ClientContext): unknown => {
+  // Handle null/undefined
+  if (obj === null || obj === undefined) {
+    return obj;
   }
-  return mcpClientForConnectionId(connectionId, ctx);
-}
 
-export const createContractBinding = (
-  binding: ContractBinding,
-  env: DefaultEnv,
-) => {
-  return mcpClientFromState(binding, env);
-};
-
-export const createIntegrationBinding = (
-  binding: MCPBinding,
-  env: DefaultEnv,
-) => {
-  const connectionId =
-    "connection_id" in binding ? binding.connection_id : undefined;
-  if (!connectionId) {
-    return mcpClientFromState(binding, env);
+  // Handle arrays
+  if (Array.isArray(obj)) {
+    return obj.map((item) => traverseAndReplace(item, ctx));
   }
-  if (!env.MESH_RUNTIME_TOKEN) {
-    throw new Error("MESH_RUNTIME_TOKEN is required");
-  }
-  if (!env.MESH_URL) {
-    throw new Error("MESH_URL is required");
+
+  // Handle objects
+  if (typeof obj === "object") {
+    // Check if this is a binding
+    if (isBinding(obj)) {
+      return mcpClientForConnectionId(obj.value, ctx, obj.__type);
+    }
+
+    // Traverse object properties
+    const result: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(obj)) {
+      result[key] = traverseAndReplace(value, ctx);
+    }
+    return result;
   }
-  // bindings pointed to an specific integration id are binded using the app deployment workspace
-  return mcpClientForConnectionId(
-    connectionId,
-    {
-      token: env.MESH_RUNTIME_TOKEN,
-      meshUrl: env.MESH_URL,
-    },
-    env.MESH_APP_NAME,
-  );
+
+  // Return primitives as-is
+  return obj;
 };
+
+export const initializeBindings = <
+  T,
+  TBindings extends BindingRegistry = BindingRegistry,
+>(
+  ctx: RequestContext,
+): void => {
+  // resolves the state in-place
+  traverseAndReplace(ctx.state, ctx) as ResolvedBindings<T, TBindings>;
+};
+
+interface DefaultRegistry extends BindingRegistry {
+  "@deco/mesh": CollectionBinding<{ hello: string }, "MESH">;
+}
+
+export interface XPTO {
+  MESH: Binding<"@deco/meh">;
+}
+
+export type XPTOResolved = ResolvedBindings<XPTO, DefaultRegistry>;

package/src/events.ts

@@ -4,6 +4,7 @@ import type {
   OnEventsOutput,
 } from "@decocms/bindings";
 import z from "zod";
+import { isBinding } from "./bindings.ts";
 
 // ============================================================================
 // Types
@@ -14,11 +15,6 @@ export interface EventSubscription {
   publisher: string;
 }
 
-interface Binding {
-  __type: string;
-  value: string;
-}
-
 /**
  * Per-event handler - handles events of a specific type
  * Returns result for each event individually
@@ -118,17 +114,6 @@ export type BindingKeysOf<T> = {
 // Type Guards
 // ============================================================================
 
-const isBinding = (v: unknown): v is Binding => {
-  return (
-    typeof v === "object" &&
-    v !== null &&
-    "__type" in v &&
-    typeof v.__type === "string" &&
-    "value" in v &&
-    typeof v.value === "string"
-  );
-};
-
 /**
  * Check if handlers is a global batch handler (has handler + events at top level)
  */

package/src/index.ts

@@ -1,7 +1,11 @@
 /* oxlint-disable no-explicit-any */
 import { decodeJwt } from "jose";
 import type { z } from "zod";
-import { createContractBinding, createIntegrationBinding } from "./bindings.ts";
+import {
+  BindingRegistry,
+  initializeBindings,
+  ResolvedBindings,
+} from "./bindings.ts";
 import { type CORSOptions, handlePreflight, withCORS } from "./cors.ts";
 import { createOAuthHandlers } from "./oauth.ts";
 import { State } from "./state.ts";
@@ -10,8 +14,8 @@ import {
   type CreateMCPServerOptions,
   MCPServer,
 } from "./tools.ts";
-import type { Binding, ContractBinding, MCPBinding } from "./wrangler.ts";
-export { proxyConnectionForId } from "./bindings.ts";
+import type { Binding } from "./wrangler.ts";
+export { proxyConnectionForId, BindingOf } from "./bindings.ts";
 export { type CORSOptions, type CORSOrigin } from "./cors.ts";
 export {
   createMCPFetchStub,
@@ -19,9 +23,13 @@ export {
   type ToolBinder,
 } from "./mcp.ts";
 
-export interface DefaultEnv<TSchema extends z.ZodTypeAny = any> {
-  MESH_REQUEST_CONTEXT: RequestContext<TSchema>;
-  MESH_BINDINGS: string;
+export type { BindingRegistry } from "./bindings.ts";
+
+export interface DefaultEnv<
+  TSchema extends z.ZodTypeAny = any,
+  TBindings extends BindingRegistry = BindingRegistry,
+> {
+  MESH_REQUEST_CONTEXT: RequestContext<TSchema, TBindings>;
   MESH_APP_DEPLOYMENT_ID: string;
   IS_LOCAL: boolean;
   MESH_URL?: string;
@@ -51,8 +59,10 @@ export const MCPBindings = {
 export interface UserDefaultExport<
   TUserEnv = Record<string, unknown>,
   TSchema extends z.ZodTypeAny = never,
-  TEnv = TUserEnv & DefaultEnv<TSchema>,
-> extends CreateMCPServerOptions<TEnv, TSchema> {
+  TBindings extends BindingRegistry = BindingRegistry,
+  TEnv extends TUserEnv & DefaultEnv<TSchema, TBindings> = TUserEnv &
+    DefaultEnv<TSchema, TBindings>,
+> extends CreateMCPServerOptions<TEnv, TSchema, TBindings> {
   fetch?: (req: Request, env: TEnv, ctx: any) => Promise<Response> | Response;
   /**
    * CORS configuration options.
@@ -61,12 +71,6 @@ export interface UserDefaultExport<
   cors?: CORSOptions | false;
 }
 
-// 1. Map binding type to its interface
-interface BindingTypeMap {
-  mcp: MCPBinding;
-  contract: ContractBinding;
-}
-
 export interface User {
   id: string;
   email: string;
@@ -79,8 +83,11 @@ export interface User {
   };
 }
 
-export interface RequestContext<TSchema extends z.ZodTypeAny = any> {
-  state: z.infer<TSchema>;
+export interface RequestContext<
+  TSchema extends z.ZodTypeAny = any,
+  TBindings extends BindingRegistry = BindingRegistry,
+> {
+  state: ResolvedBindings<z.infer<TSchema>, TBindings>;
   token: string;
   meshUrl: string;
   authorization?: string | null;
@@ -91,20 +98,6 @@ export interface RequestContext<TSchema extends z.ZodTypeAny = any> {
   connectionId?: string;
 }
 
-// 2. Map binding type to its creator function
-type CreatorByType = {
-  [K in keyof BindingTypeMap]: (
-    value: BindingTypeMap[K],
-    env: DefaultEnv,
-  ) => unknown;
-};
-
-// 3. Strongly type creatorByType
-const creatorByType: CreatorByType = {
-  mcp: createIntegrationBinding,
-  contract: createContractBinding,
-};
-
 const withDefaultBindings = ({
   env,
   server,
@@ -159,7 +152,6 @@ export const withBindings = <TEnv>({
   server,
   tokenOrContext,
   url,
-  bindings: inlineBindings,
   authToken,
 }: {
   env: TEnv;
@@ -169,7 +161,6 @@ export const withBindings = <TEnv>({
   // authToken is the authorization header
   authToken?: string | null;
   url?: string;
-  bindings?: Binding[];
 }): TEnv => {
   const env = _env as DefaultEnv<any>;
   const authorization = authToken ? authToken.split(" ")[1] : undefined;
@@ -223,11 +214,7 @@ export const withBindings = <TEnv>({
   }
 
   env.MESH_REQUEST_CONTEXT = context;
-  const bindings = inlineBindings ?? MCPBindings.parse(env.MESH_BINDINGS);
-
-  for (const binding of bindings) {
-    env[binding.name] = creatorByType[binding.type](binding as any, env);
-  }
+  initializeBindings(context);
 
   withDefaultBindings({
     env,
@@ -252,19 +239,21 @@ const DEFAULT_CORS_OPTIONS = {
   allowHeaders: ["Content-Type", "Authorization", "mcp-protocol-version"],
 };
 
-export const withRuntime = <TEnv, TSchema extends z.ZodTypeAny = never>(
-  userFns: UserDefaultExport<TEnv, TSchema>,
+export const withRuntime = <
+  TUserEnv,
+  TSchema extends z.ZodTypeAny = never,
+  TBindings extends BindingRegistry = BindingRegistry,
+  TEnv extends TUserEnv & DefaultEnv<TSchema, TBindings> = TUserEnv &
+    DefaultEnv<TSchema, TBindings>,
+>(
+  userFns: UserDefaultExport<TUserEnv, TSchema, TBindings>,
 ) => {
-  const server = createMCPServer<TEnv, TSchema>(userFns);
+  const server = createMCPServer<TUserEnv, TSchema, TBindings>(userFns);
   const corsOptions = userFns.cors ?? DEFAULT_CORS_OPTIONS;
   const oauth = userFns.oauth;
   const oauthHandlers = oauth ? createOAuthHandlers(oauth) : null;
 
-  const fetcher = async (
-    req: Request,
-    env: TEnv & DefaultEnv<TSchema>,
-    ctx: any,
-  ) => {
+  const fetcher = async (req: Request, env: TEnv, ctx: any) => {
     const url = new URL(req.url);
 
     // OAuth routes (when configured)
@@ -359,7 +348,7 @@ export const withRuntime = <TEnv, TSchema extends z.ZodTypeAny = never>(
   };
 
   return {
-    fetch: async (req: Request, env: TEnv & DefaultEnv<TSchema>, ctx?: any) => {
+    fetch: async (req: Request, env: TEnv, ctx?: any) => {
       if (new URL(req.url).pathname === "/_healthcheck") {
         return new Response("OK", { status: 200 });
       }
@@ -373,7 +362,6 @@ export const withRuntime = <TEnv, TSchema extends z.ZodTypeAny = never>(
         authToken: req.headers.get("authorization") ?? null,
         env: { ...process.env, ...env },
         server,
-        bindings: userFns.bindings,
         tokenOrContext: req.headers.get("x-mesh-token") ?? undefined,
         url: req.url,
       });

package/src/tools.ts

@@ -9,10 +9,10 @@ import {
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { zodToJsonSchema } from "zod-to-json-schema";
+import { BindingRegistry } from "./bindings.ts";
 import { Event, type EventHandlers } from "./events.ts";
 import type { DefaultEnv } from "./index.ts";
 import { State } from "./state.ts";
-import { Binding } from "./wrangler.ts";
 
 // Re-export EventHandlers type for external use
 export type { EventHandlers } from "./events.ts";
@@ -154,8 +154,8 @@ export function isStreamableTool(
   return tool && "streamable" in tool && tool.streamable === true;
 }
 
-export interface OnChangeCallback<TSchema extends z.ZodTypeAny = never> {
-  state: z.infer<TSchema>;
+export interface OnChangeCallback<TState> {
+  state: TState;
   scopes: string[];
 }
 
@@ -232,35 +232,34 @@ type PickByType<T, Value> = {
 export interface CreateMCPServerOptions<
   Env = unknown,
   TSchema extends z.ZodTypeAny = never,
+  TBindings extends BindingRegistry = BindingRegistry,
+  TEnv extends Env & DefaultEnv<TSchema, TBindings> = Env &
+    DefaultEnv<TSchema, TBindings>,
+  State extends
+    TEnv["MESH_REQUEST_CONTEXT"]["state"] = TEnv["MESH_REQUEST_CONTEXT"]["state"],
 > {
-  before?: (env: Env & DefaultEnv<TSchema>) => Promise<void> | void;
+  before?: (env: TEnv) => Promise<void> | void;
   oauth?: OAuthConfig;
   events?: {
-    bus?: keyof PickByType<Env & DefaultEnv<TSchema>, EventBusBindingClient>;
-    handlers?: EventHandlers<Env & DefaultEnv<TSchema>, TSchema>;
+    bus?: keyof PickByType<TEnv, EventBusBindingClient>;
+    handlers?: EventHandlers<TEnv, TSchema>;
   };
   configuration?: {
-    onChange?: (
-      env: Env & DefaultEnv<TSchema>,
-      cb: OnChangeCallback<TSchema>,
-    ) => Promise<void>;
+    onChange?: (env: TEnv, cb: OnChangeCallback<State>) => Promise<void>;
     state?: TSchema;
     scopes?: string[];
   };
-  bindings?: Binding[];
   tools?:
     | Array<
         (
-          env: Env & DefaultEnv<TSchema>,
+          env: TEnv,
         ) =>
           | Promise<CreatedTool>
           | CreatedTool
           | CreatedTool[]
           | Promise<CreatedTool[]>
       >
-    | ((
-        env: Env & DefaultEnv<TSchema>,
-      ) => CreatedTool[] | Promise<CreatedTool[]>);
+    | ((env: TEnv) => CreatedTool[] | Promise<CreatedTool[]>);
 }
 
 export type Fetch<TEnv = unknown> = (
@@ -361,9 +360,9 @@ const toolsFor = <TSchema extends z.ZodTypeAny = never>({
         return Promise.resolve({
           stateSchema: jsonSchema,
           scopes: [
-            ...(scopes ?? []),
+            ...((scopes as string[]) ?? []),
             ...Event.scopes(events?.handlers ?? {}),
-            ...(busProp ? [`${busProp}::EVENT_SYNC_SUBSCRIPTIONS`] : []),
+            ...(events ? [`${busProp}::EVENT_SYNC_SUBSCRIPTIONS`] : []),
           ],
         });
       },
@@ -376,18 +375,25 @@ type CallTool = (opts: {
   toolCallInput: unknown;
 }) => Promise<unknown>;
 
-export type MCPServer<TEnv = unknown, TSchema extends z.ZodTypeAny = never> = {
-  fetch: Fetch<TEnv & DefaultEnv<TSchema>>;
+export type MCPServer<
+  TEnv = unknown,
+  TSchema extends z.ZodTypeAny = never,
+  TBindings extends BindingRegistry = BindingRegistry,
+> = {
+  fetch: Fetch<TEnv & DefaultEnv<TSchema, TBindings>>;
   callTool: CallTool;
 };
 
 export const createMCPServer = <
-  TEnv = unknown,
+  Env = unknown,
   TSchema extends z.ZodTypeAny = never,
+  TBindings extends BindingRegistry = BindingRegistry,
+  TEnv extends Env & DefaultEnv<TSchema, TBindings> = Env &
+    DefaultEnv<TSchema, TBindings>,
 >(
-  options: CreateMCPServerOptions<TEnv, TSchema>,
-): MCPServer<TEnv, TSchema> => {
-  const createServer = async (bindings: TEnv & DefaultEnv<TSchema>) => {
+  options: CreateMCPServerOptions<TEnv, TSchema, TBindings>,
+): MCPServer<TEnv, TSchema, TBindings> => {
+  const createServer = async (bindings: TEnv) => {
     await options.before?.(bindings);
 
     const server = new McpServer(
@@ -398,7 +404,7 @@ export const createMCPServer = <
     const toolsFn =
       typeof options.tools === "function"
         ? options.tools
-        : async (bindings: TEnv & DefaultEnv<TSchema>) => {
+        : async (bindings: TEnv) => {
             if (typeof options.tools === "function") {
               return await options.tools(bindings);
             }
@@ -462,7 +468,7 @@ export const createMCPServer = <
     return { server, tools };
   };
 
-  const fetch = async (req: Request, env: TEnv & DefaultEnv<TSchema>) => {
+  const fetch = async (req: Request, env: TEnv) => {
     const { server } = await createServer(env);
     const transport = new HttpServerTransport();
 

package/src/wrangler.ts

@@ -1,5 +1,6 @@
 export interface BindingBase {
   name: string;
+  array?: true;
 }
 
 export interface MCPConnectionBinding extends BindingBase {
@@ -15,7 +16,7 @@ export interface MCPAppBinding extends BindingBase {
   /**
    * The name of the integration to bind.
    */
-  app_name: string;
+  app_name?: string;
 }
 export interface ContractClause {
   id: string;