@decocms/bindings 1.0.1-alpha.3 → 1.0.1

package/src/well-known/language-model.ts

@@ -17,17 +17,229 @@ import {
   createCollectionBindings,
 } from "./collections";
 
+/**
+ * JSON Value Schema
+ * Represents any valid JSON value: null, string, number, boolean, object, or array
+ */
+const JSONValueSchema: z.ZodType<unknown> = z.lazy(() =>
+  z.union([
+    z.null(),
+    z.string(),
+    z.number(),
+    z.boolean(),
+    z.record(z.string(), JSONValueSchema),
+    z.array(JSONValueSchema),
+  ]),
+);
+
+/**
+ * Provider Options Schema
+ * Additional provider-specific options passed through to the provider
+ */
+const ProviderOptionsSchema = z
+  .record(z.string(), z.record(z.string(), JSONValueSchema))
+  .optional()
+  .describe(
+    "Additional provider-specific options. Outer record keyed by provider name, inner by option key",
+  );
+
+/**
+ * Text Part Schema
+ * Text content part of a prompt
+ */
+const TextPartSchema = z.object({
+  type: z.literal("text"),
+  text: z.string().describe("The text content"),
+  providerOptions: ProviderOptionsSchema,
+});
+
+/**
+ * Data Content Schema
+ * File data can be Uint8Array (as base64 string), base64 encoded string, or URL string
+ */
+const DataContentSchema = z
+  .union([z.string(), z.instanceof(Uint8Array)])
+  .describe("File data as base64 encoded string, URL string, or Uint8Array");
+
+/**
+ * File Part Schema
+ * File content part of a prompt
+ */
+const FilePartSchema = z.object({
+  type: z.literal("file"),
+  filename: z.string().optional().describe("Optional filename of the file"),
+  data: DataContentSchema,
+  mediaType: z
+    .string()
+    .describe("IANA media type of the file (e.g., image/png, audio/mp3)"),
+  providerOptions: ProviderOptionsSchema,
+});
+
+/**
+ * Reasoning Part Schema
+ * Reasoning content part of a prompt
+ */
+const ReasoningPartSchema = z.object({
+  type: z.literal("reasoning"),
+  text: z.string().describe("The reasoning text"),
+  providerOptions: ProviderOptionsSchema,
+});
+
+/**
+ * Tool Call Part Schema
+ * Tool call content part of a prompt (usually generated by the AI model)
+ */
+const ToolCallPartSchema = z.object({
+  type: z.literal("tool-call"),
+  toolCallId: z
+    .string()
+    .describe("ID of the tool call, used to match with tool result"),
+  toolName: z.string().describe("Name of the tool being called"),
+  input: z
+    .unknown()
+    .describe(
+      "Arguments of the tool call (JSON-serializable object matching tool input schema)",
+    ),
+  providerExecuted: z
+    .boolean()
+    .optional()
+    .describe("Whether the tool call will be executed by the provider"),
+  providerOptions: ProviderOptionsSchema,
+});
+
+/**
+ * Tool Result Output Schema
+ * The output of a tool result
+ */
+const ToolResultOutputSchema = z.union([
+  z.object({
+    type: z.literal("text"),
+    value: z.string(),
+  }),
+  z.object({
+    type: z.literal("json"),
+    value: JSONValueSchema,
+  }),
+  z.object({
+    type: z.literal("error-text"),
+    value: z.string(),
+  }),
+  z.object({
+    type: z.literal("error-json"),
+    value: JSONValueSchema,
+  }),
+  z.object({
+    type: z.literal("content"),
+    value: z.array(
+      z.union([
+        z.object({
+          type: z.literal("text"),
+          text: z.string().describe("Text content"),
+        }),
+        z.object({
+          type: z.literal("media"),
+          data: z.string().describe("Base-64 encoded media data"),
+          mediaType: z.string().describe("IANA media type"),
+        }),
+      ]),
+    ),
+  }),
+]);
+
+/**
+ * Tool Result Part Schema
+ * Tool result content part of a prompt
+ */
+const ToolResultPartSchema = z.object({
+  type: z.literal("tool-result"),
+  toolCallId: z
+    .string()
+    .describe("ID of the tool call that this result is associated with"),
+  toolName: z.string().describe("Name of the tool that generated this result"),
+  output: ToolResultOutputSchema.describe("Result of the tool call"),
+  providerOptions: ProviderOptionsSchema,
+});
+
+/**
+ * System Message Schema
+ */
+const SystemMessageSchema = z.object({
+  role: z.literal("system"),
+  content: z.string().describe("System message content"),
+  providerOptions: ProviderOptionsSchema,
+});
+
+/**
+ * User Message Schema
+ */
+const UserMessageSchema = z.object({
+  role: z.literal("user"),
+  content: z
+    .array(z.union([TextPartSchema, FilePartSchema]))
+    .describe("User message content parts (text or file)"),
+  providerOptions: ProviderOptionsSchema,
+});
+
+/**
+ * Assistant Message Schema
+ */
+const AssistantMessageSchema = z.object({
+  role: z.literal("assistant"),
+  content: z
+    .array(
+      z.union([
+        TextPartSchema,
+        FilePartSchema,
+        ReasoningPartSchema,
+        ToolCallPartSchema,
+        ToolResultPartSchema,
+      ]),
+    )
+    .describe(
+      "Assistant message content parts (text, file, reasoning, tool-call, or tool-result)",
+    ),
+  providerOptions: ProviderOptionsSchema,
+});
+
+/**
+ * Tool Message Schema
+ */
+const ToolMessageSchema = z.object({
+  role: z.literal("tool"),
+  content: z
+    .array(ToolResultPartSchema)
+    .describe("Tool message content (tool results)"),
+  providerOptions: ProviderOptionsSchema,
+});
+
+/**
+ * Language Model Message Schema
+ * A message in a language model prompt
+ */
+export const LanguageModelMessageSchema = z.union([
+  SystemMessageSchema,
+  UserMessageSchema,
+  AssistantMessageSchema,
+  ToolMessageSchema,
+]);
+
+/**
+ * Language Model Prompt Schema
+ * A prompt is a list of messages based on LanguageModelV2Prompt from @ai-sdk/provider
+ */
+export const LanguageModelPromptSchema = z
+  .array(LanguageModelMessageSchema)
+  .describe("A list of messages forming the prompt");
+
 /**
  * Language Model Call Options Schema
  * Based on LanguageModelV2CallOptions from @ai-sdk/provider
  */
 export const LanguageModelCallOptionsSchema = z.object({
   // Core parameters
-  prompt: z
-    .any()
-    .describe(
-      "A language mode prompt is a standardized prompt type (messages, system, etc.)",
-    ),
+  prompt: LanguageModelPromptSchema.describe(
+    "A language model prompt is a standardized prompt type (array of messages with roles: system, user, assistant, tool)",
+  ),
 
   // Generation parameters
   maxOutputTokens: z

package/src/well-known/mcp.ts

@@ -0,0 +1,36 @@
+/**
+ * MCP Well-Known Binding
+ *
+ * Defines the interface for retrieving MCP configuration.
+ */
+
+import { z } from "zod";
+import type { Binder } from "../core/binder";
+export type { ServerClient } from "../core/client/mcp-client";
+
+/**
+ * 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/src/well-known/prompt.ts

@@ -0,0 +1,110 @@
+/**
+ * Prompts Well-Known Binding
+ *
+ * Defines the interface for prompt providers.
+ * Any MCP that implements this binding can expose prompts as a collection.
+ *
+ * This binding uses collection bindings for full CRUD operations.
+ */
+
+import { z } from "zod";
+import type { Binder } from "../core/binder";
+import {
+  BaseCollectionEntitySchema,
+  createCollectionBindings,
+} from "./collections";
+
+/**
+ * Schema for prompt arguments that can be passed when getting a prompt
+ */
+export const PromptArgumentSchema = z.object({
+  name: z.string().describe("Argument name"),
+  description: z.string().optional().describe("Argument description"),
+  required: z.boolean().optional().describe("Whether argument is required"),
+});
+export type PromptArgument = z.infer<typeof PromptArgumentSchema>;
+
+/**
+ * Schema for prompt icons for display in user interfaces
+ */
+export const PromptIconSchema = z.object({
+  src: z.string().url().describe("Icon URL"),
+  mimeType: z.string().optional().describe("Icon MIME type"),
+  sizes: z.array(z.string()).optional().describe("Icon sizes"),
+});
+export type PromptIcon = z.infer<typeof PromptIconSchema>;
+
+/**
+ * Schema for content within a prompt message
+ */
+export const PromptMessageContentSchema = z.object({
+  type: z.enum(["text", "image", "audio", "resource"]).describe("Content type"),
+  text: z.string().optional().describe("Text content"),
+  data: z.string().optional().describe("Base64-encoded data for image/audio"),
+  mimeType: z
+    .string()
+    .optional()
+    .describe("MIME type for image/audio/resource"),
+  resource: z
+    .object({
+      uri: z.string().describe("Resource URI"),
+      mimeType: z.string().optional().describe("Resource MIME type"),
+      text: z.string().optional().describe("Resource text content"),
+      blob: z.string().optional().describe("Base64-encoded resource blob"),
+    })
+    .optional()
+    .describe("Embedded resource"),
+});
+export type PromptMessageContent = z.infer<typeof PromptMessageContentSchema>;
+
+/**
+ * Schema for a message in a prompt
+ */
+export const PromptMessageSchema = z.object({
+  role: z.enum(["user", "assistant"]).describe("Message role"),
+  content: PromptMessageContentSchema.describe("Message content"),
+});
+export type PromptMessage = z.infer<typeof PromptMessageSchema>;
+
+/**
+ * Full prompt entity schema extending base collection fields
+ */
+export const PromptSchema = BaseCollectionEntitySchema.extend({
+  arguments: z
+    .array(PromptArgumentSchema)
+    .optional()
+    .describe("Arguments that can be passed when getting this prompt"),
+  icons: z
+    .array(PromptIconSchema)
+    .optional()
+    .describe("Icons for display in user interfaces"),
+  messages: z.array(PromptMessageSchema).describe("Prompt messages template"),
+});
+export type Prompt = z.infer<typeof PromptSchema>;
+
+/**
+ * PROMPT Collection Binding
+ *
+ * Collection bindings for prompts.
+ * Provides full CRUD operations (LIST, GET, CREATE, UPDATE, DELETE) for prompts.
+ */
+export const PROMPTS_COLLECTION_BINDING = createCollectionBindings(
+  "prompt",
+  PromptSchema,
+);
+
+/**
+ * PROMPTS Binding
+ *
+ * Required tools:
+ * - COLLECTION_PROMPT_LIST
+ * - COLLECTION_PROMPT_GET
+ *
+ * Optional tools:
+ * - COLLECTION_PROMPT_CREATE
+ * - COLLECTION_PROMPT_UPDATE
+ * - COLLECTION_PROMPT_DELETE
+ */
+export const PROMPTS_BINDING = [
+  ...PROMPTS_COLLECTION_BINDING,
+] as const satisfies Binder;

package/src/well-known/registry.ts

@@ -0,0 +1,128 @@
+/**
+ * Registry App Well-Known Binding
+ *
+ * Defines the interface for accessing public registry apps.
+ * Any MCP that implements this binding can provide a list of available apps
+ * with their configurations and tools.
+ *
+ * This binding includes:
+ * - Collection bindings for LIST and GET operations (read-only)
+ * - Only exposes public apps (unlisted: false)
+ * - Removes sensitive fields (connection details, workspace info)
+ */
+
+import { z } from "zod";
+import {
+  BaseCollectionEntitySchema,
+  createCollectionBindings,
+} from "./collections";
+
+/**
+ * Tool definition schema from registry
+ */
+const RegistryToolSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  description: z.string().optional(),
+  inputSchema: z.record(z.unknown()),
+  outputSchema: z.record(z.unknown()).optional(),
+});
+
+/**
+ * MCP Registry Server schema extending Collection Entity base
+ * Combines BaseCollectionEntitySchema with MCP Registry Spec format
+ * https://spec.modelcontextprotocol.io/specification/2025-03-26/registry/
+ */
+export const MCPRegistryServerSchema = BaseCollectionEntitySchema.extend({
+  // MCP Registry Spec structure
+  _meta: z
+    .object({
+      "io.decocms": z
+        .object({
+          id: z.string(),
+          verified: z.boolean(),
+          scopeName: z.string(),
+          appName: z.string(),
+          friendlyName: z.string().nullable().optional(),
+          metadata: z.record(z.unknown()).nullable().optional(),
+          publishedAt: z.string().datetime().optional(),
+          updatedAt: z.string().datetime().optional(),
+          tools: z
+            .array(RegistryToolSchema)
+            .nullable()
+            .optional()
+            .describe("Available tools exposed by this app"),
+        })
+        .optional(),
+    })
+    .optional(),
+  server: z.object({
+    $schema: z.string().optional(),
+    _meta: z.record(z.unknown()).optional(),
+    name: z.string().describe("The server name (scope/app)"),
+    title: z.string().optional().describe("User-friendly title"),
+    description: z.string().optional().describe("Server description"),
+    icons: z
+      .array(
+        z.object({
+          src: z.string(),
+          mimeType: z.string().optional(),
+          sizes: z.array(z.string()).optional(),
+          theme: z.enum(["light", "dark"]).optional(),
+        }),
+      )
+      .optional(),
+    remotes: z
+      .array(
+        z.object({
+          type: z.enum(["http", "stdio", "sse"]),
+          url: z.string().optional(),
+          headers: z.array(z.unknown()).optional(),
+        }),
+      )
+      .optional(),
+    packages: z.array(z.unknown()).optional(),
+    repository: z
+      .object({
+        url: z.string(),
+        source: z.string().optional(),
+        subfolder: z.string().optional(),
+      })
+      .optional(),
+    version: z.string().optional(),
+    websiteUrl: z.string().optional(),
+  }),
+});
+
+export type RegistryAppCollectionEntity = z.infer<
+  typeof MCPRegistryServerSchema
+>;
+
+/**
+ * Registry App Collection Binding (read-only)
+ *
+ * Collection bindings for registry apps (read-only).
+ * Provides LIST and GET operations for public apps.
+ * Only includes public apps (unlisted: false).
+ *
+ * Returns servers in MCP Registry Spec format with:
+ * - _meta: DecoCMS-specific metadata (id, verified, tools, etc.)
+ * - server: MCP Registry Spec compliant server definition
+ */
+const REGISTRY_APP_COLLECTION_BINDING = createCollectionBindings(
+  "registry_app",
+  MCPRegistryServerSchema,
+  { readOnly: true },
+);
+
+/**
+ * Registry App Binding
+ *
+ * Defines the interface for accessing public registry apps.
+ * Any MCP that implements this binding can provide a searchable list of apps.
+ *
+ * Required tools:
+ * - COLLECTION_REGISTRY_APP_LIST: List available apps with filtering and pagination
+ * - COLLECTION_REGISTRY_APP_GET: Get a single app by ID
+ */
+export const REGISTRY_APP_BINDING = REGISTRY_APP_COLLECTION_BINDING;