Skip to content

README.md

Latest commit

 

History

History
140 lines (107 loc) · 4.74 KB

README.md

File metadata and controls

140 lines (107 loc) · 4.74 KB
Raw

@decocms/bindings

Defines typed, reusable contracts for capabilities exposed through Model Context Protocol tools.

Attribute Value
Workspace @decocms/bindings (packages/bindings)
Kind TypeScript contract library
Runtime Node.js 24+
Distribution Public npm package

Overview

A binding is a list of MCP tool names paired with Zod input and output schemas. It gives producers and consumers one shared description of a capability without coupling either side to a Studio application.

The package includes the binding primitives, typed client adapters, connection types, and well-known contracts for collections, language models, object storage, MCP configuration, assistants, prompts, AI gateway billing, triggers, brands, and event subscribers.

Responsibilities

  • Define Binder and ToolBinder contracts for required and optional tools.
  • Check whether a tool list contains every required binding member.
  • Produce typed clients for an existing MCP client or an MCP connection.
  • Publish reusable Zod schemas and TypeScript types for well-known contracts.
  • Define collection query, pagination, sorting, and CRUD shapes.

Usage

Install the public package:

bun add @decocms/bindings

Define a binding and check whether an MCP tool list implements it:

import {
  createBindingChecker,
  type Binder,
} from "@decocms/bindings";
import { z } from "zod";

const SEARCH_BINDING = [
  {
    name: "SEARCH" as const,
    inputSchema: z.object({ query: z.string() }),
    outputSchema: z.object({ results: z.array(z.string()) }),
  },
  {
    name: "SEARCH_SUGGEST" as const,
    inputSchema: z.object({ prefix: z.string() }),
    outputSchema: z.object({ suggestions: z.array(z.string()) }),
    opt: true,
  },
] as const satisfies Binder;

const checker = createBindingChecker(SEARCH_BINDING);
const supported = checker.isImplementedBy([{ name: "SEARCH" }]);

Supported package exports:

Import path Surface
@decocms/bindings Binding primitives plus event subscriber, trigger, object-storage, and brand exports
@decocms/bindings/collections Collection schemas, factories, and types
@decocms/bindings/llm Deprecated language-model binding
@decocms/bindings/object-storage Object-storage binding
@decocms/bindings/connection MCP connection descriptor types
@decocms/bindings/client Typed MCP clients and HTTP transport
@decocms/bindings/mcp MCP configuration binding
@decocms/bindings/assistant Assistant collection binding
@decocms/bindings/prompt Prompt schemas and types
@decocms/bindings/ai-gateway AI gateway billing binding
@decocms/bindings/trigger Trigger binding and typed client
@decocms/bindings/brand Brand binding and typed client

Architecture

src/core/binder.ts owns the binding model, compatibility checker, and typed client factory. src/core/client/ adapts either a live MCP client or a connection descriptor into callable, binding-shaped methods.

src/well-known/ contains capability-specific schemas and tool lists. The package export map exposes only the supported entry points listed above; the root barrel intentionally re-exports only the most commonly shared contracts.

Collection bindings generate COLLECTION_<NAME>_LIST and COLLECTION_<NAME>_GET as required tools. Unless readOnly: true is set, they also describe optional create, update, and delete tools. The canonical base entity schema includes identity, title, description, timestamps, and audit fields.

Development

Run commands from the repository root:

bun install
bun run --cwd=packages/bindings check
bun run --cwd=packages/bindings test

Run the focused MCP binding test with:

bun test packages/bindings/test/mcp.test.ts

The package publishes TypeScript source directly and has no separate build script.

Boundaries

This package owns capability contracts, not implementations. Database access, authorization, HTTP route handling, Studio application state, and UI behavior belong elsewhere.

Do not import unpublished files under src/; use a package export. Do not add app aliases or reach into apps/api or apps/web.

createBindingChecker currently verifies required tool-name coverage, including regular-expression names and optional entries. The schemas remain part of the binding contract, but the checker does not currently perform structural schema compatibility validation.

The /llm binding targets an older AI SDK provider abstraction and is deprecated. New model integrations use native provider adapters instead of extending that binding.

Related documentation