OzMcp.Config.Template.DSL (OzMcp v0.9.0)

Copy Markdown View Source

Compile-time macros of a resource template module (use OzMcp.Config.Template).

use OzMcp.Config.Template imports the root macro template/2 only. The nested macros are not imported: they work only inside their template block. A nested macro at the root of the module gives a compile error (undefined function uri_template/1).

The macros generate list/0 of the template behaviour. The module must define read/4. A module with the DSL cannot define list/0. The compiled matcher of each template matches the requested uri in the order of the module and gives {template, uri_params}.

The macros

MacroBlockValueWire field
template "name"rootnon-empty stringname
uri_templatetemplatenon-empty string, unique in the module, a valid URI template of RFC 6570uriTemplate
titletemplatenon-empty stringtitle
descriptiontemplatenon-empty stringdescription
mime_typetemplate, iconnon-empty stringmimeType
required_scopestemplatelist of scope tokensnone (a 403 and a filtered resources/templates/list)
annotationstemplateblockannotations
audienceannotationslist of "user" and "assistant"annotations.audience
priorityannotationsnumber from 0 to 1annotations.priority
last_modifiedannotationsISO 8601 date and time with an offset, for example 2025-01-12T15:00:58Zannotations.lastModified
icontemplate (repeatable)blockone entry of icons
srciconhttps: URL, http: URL of a loopback host, or data: URIicons[].src
sizesiconlist of "any" and "WxH" stringsicons[].sizes
themeicon"light" or "dark"icons[].theme
meta key, valuetemplatekey: string or atom, value: a JSON term_meta.<key>

A wrong value, a macro outside its block, or a property declared two times raises at compile time. The template block requires a uri_template. With warn?: true (the default), a template with no title or no description gives a compiler warning.

The DSL checks each uri_template at compile time with OzMcp.Utils.TemplateUri. The template must be a valid URI template of RFC 6570, levels 1 to 3 ({var}, {+var}, {#var}, {.var}, {/var}, {;var}, {?var}, {&var} and the lists {a,b}). A bad template raises with the fault and its position and a level 4 modifier ({a*}, {a:3}) raises too. Two templates of one module whose uri_template strings differ only in the names of their variables (the same shape, for example file:///{a} and file:///{b}) raise too: the first one would hide the second one. The compiled matcher of each template is built at compile time: no parse and no cache at request time.

The guide Templates shows an example of the DSL.

Summary

Functions

annotations(list)

(macro)

audience(value)

(macro)

description(value)

(macro)

icon(list)

(macro)

last_modified(value)

(macro)

meta(key, value)

(macro)

mime_type(value)

(macro)

priority(value)

(macro)

required_scopes(value)

(macro)

sizes(value)

(macro)

src(value)

(macro)

template(entity_name, list)

(macro)

theme(value)

(macro)

title(value)

(macro)

uri_template(value)

(macro)