Ectomancer.SchemaBuilder (Ectomancer v1.2.1)

Copy Markdown View Source

Converts Ecto types to MCP-compatible JSON Schema definitions.

This module provides utilities to convert Ecto schema types into JSON Schema format suitable for MCP tool definitions.

Example

schema = Ectomancer.SchemaBuilder.build(MyApp.Accounts.User, [:email, :name, :age])
# Returns: %{
#   "type" => "object",
#   "properties" => %{
#     "email" => %{"type" => "string"},
#     "name" => %{"type" => "string"},
#     "age" => %{"type" => "integer"}
#   },
#   "required" => ["email", "name"]
# }

Type Mappings

Ecto TypeJSON SchemaFormat
:string"type" => "string"-
:integer"type" => "integer"-
:float / :decimal"type" => "number"-
:boolean"type" => "boolean"-
:date"type" => "string""date"
:time"type" => "string""time"
:naive_datetime"type" => "string""date-time"
:utc_datetime"type" => "string""date-time"
Ecto.UUID"type" => "string""uuid"
{:array, inner}"type" => "array"items schema
:map / embeds"type" => "object"-

Summary

Functions

build(schema_module, fields \\ nil, opts \\ [])

Builds a JSON Schema for the given fields of a schema.

build_for_action(schema_module, action, opts \\ [])

Builds a JSON Schema for a specific action (create, update, etc.).

type_to_schema(type)

Converts an Ecto type to a JSON Schema definition.

Functions

build(schema_module, fields \\ nil, opts \\ [])

@spec build(module(), [atom()] | nil, keyword()) :: map()

Builds a JSON Schema for the given fields of a schema.

Parameters

  • schema_module - The Ecto schema module
  • fields - List of field names to include (defaults to all writable fields)
  • opts - Options for schema generation
    • :required - List of required fields (defaults to non-nullable fields)
    • :nullable - Whether to mark all fields as nullable (default: false)

Returns

A JSON Schema map with "type", "properties", and optionally "required" keys.

Examples

iex> Ectomancer.SchemaBuilder.build(MyApp.Accounts.User, [:email, :name])
%{
  "type" => "object",
  "properties" => %{
    "email" => %{"type" => "string"},
    "name" => %{"type" => "string"}
  },
  "required" => ["email"]
}

build_for_action(schema_module, action, opts \\ [])

@spec build_for_action(module(), atom(), keyword()) :: map()

Builds a JSON Schema for a specific action (create, update, etc.).

Different actions may have different required fields or include/exclude certain fields.

Examples

iex> Ectomancer.SchemaBuilder.build_for_action(MyApp.Accounts.User, :create)
# Returns schema with all writable fields, required based on nullability

iex> Ectomancer.SchemaBuilder.build_for_action(MyApp.Accounts.User, :update)
# Returns schema with all writable fields, none required (partial updates)

type_to_schema(type)

@spec type_to_schema(any()) :: map()

Converts an Ecto type to a JSON Schema definition.

Examples

iex> Ectomancer.SchemaBuilder.type_to_schema(:string)
%{"type" => "string"}

iex> Ectomancer.SchemaBuilder.type_to_schema(:date)
%{"type" => "string", "format" => "date"}

iex> Ectomancer.SchemaBuilder.type_to_schema({:array, :string})
%{"type" => "array", "items" => %{"type" => "string"}}