ConduitMcp.Component.Schema (ConduitMCP v0.10.1)

Schema DSL for defining parameters in Component modules.

Provides a simple schema do ... end block with field declarations that generate both JSON Schema (for MCP client introspection) and NimbleOptions schemas (for server-side runtime validation).

Example

defmodule MyApp.Echo do
  use ConduitMcp.Component, type: :tool, description: "Echoes text"

  schema do
    field :text, :string, "The text to echo", required: true, max_length: 150
    field :count, :integer, "Repeat count", default: 1, min: 1, max: 10
  end

  @impl true
  def execute(%{text: text, count: count}, _conn) do
    text(String.duplicate(text, count))
  end
end

Supported Types

:string — String values
:integer — Integer values
:number — Numeric values (float)
:boolean — Boolean values
:object — Nested objects (block form with nested field calls; the blockless form declares an open object with no constrained keys)
:array / {:array, item_type} — Arrays. Use the block form with items/1,2 to constrain the item type

Field Options

required: true — Mark as required (default: false)
default: value — Default value
enum: [...] — Allowed values
min: n / max: n — Numeric constraints
min_length: n / max_length: n — String length constraints
validator: fn — Custom validator function
additional_properties: bool — For :object: whether keys the block did not declare are accepted. Defaults to false when the field declares nested fields and true when it does not, and drives "additionalProperties" in the generated JSON Schema so the published schema matches what is enforced.

Nested Objects and Array Items

Nested fields are enforced at runtime to any depth — required, types, and every option above — and undeclared keys are rejected. Array item schemas are published for clients but not enforced server-side; see ConduitMcp.Validation.SchemaConverter for why.

Handlers receive string keys at every depth below the top level.

Summary

Functions

field(name, type, description, opts \\ [], do_block \\ nil)

Defines a field in the component schema.

items(type)

Declares the item type of the enclosing :array field.

items(type, list)

schema(list)

Defines the parameter schema for a component.

Functions

field(name, type, description, opts \\ [], do_block \\ nil)

(macro)

Defines a field in the component schema.

Examples

# Simple field
field :name, :string, "User's name", required: true

# Field with options
field :age, :integer, "User's age", min: 0, max: 150

# Field without description (uses opts keyword)
field :tags, {:array, :string}, "Tag list"

# Nested object field
field :address, :object, "Mailing address", required: true do
  field :street, :string, "Street", required: true
  field :city, :string, "City", required: true
end

# Open object field — any keys accepted
field :metadata, :object, "Arbitrary metadata"

# Array of objects
field :rows, :array, "Rows" do
  items :object do
    field :id, :integer, "Row id", required: true
  end
end

items(type)

(macro)

Declares the item type of the enclosing :array field.

Item schemas are published to clients in the JSON Schema but are not enforced server-side — NimbleOptions cannot attach a nested schema to a list element type. Validate item contents in your execute/2.

Examples

field :tags, :array, "Tags" do
  items :string
end

field :users, :array, "Users" do
  items :object do
    field :name, :string, "Name", required: true
  end
end

items(type, list)

(macro)

schema(list)

(macro)

Defines the parameter schema for a component.

Wraps field declarations and accumulates them into @component_fields.