Manifest Schemas

The SAM manifests of this platform, as the MCPServer’s public get_manifest_schema tool reads them.

Each resource kind’s JSON Schema and example manifest are committed in smarter.apps.api.v1.contract.sam, beside the api contract, as sam/<Kind>.schema.json and sam/<Kind>.example.json. They are the platform’s own, so they describe exactly the manifests that this platform accepts.

A schema is too large, up to about 50 KB, and too nested, with $ref and anyOf, for an LLM to read well. manifest_fields() flattens it into one ManifestField per field, with its dotted path, e.g. spec.config.value, its type, whether it is required, its default and its description. The read-only status is left out: it is never written in a manifest.

validate_manifest_text() parses a manifest that the LLM wrote, and validates it with smarter.apps.api.v1.cli.validation.validate_manifest(), the validation of the cli’s validate command, for the validate_manifest tool. The text comes from anonymous clients, so it is parsed without YAML aliases, whose expansion could make a small document enormous, and it is validated without the checks that make requests, e.g. that an image url responds.

Note

Experimental. The MCPServer was designed and coded by Claude Code (Anthropic’s Claude Opus 5.5), with Lawrence McDaniel as co-author. It is experimental, and will be documented.

class smarter.apps.mcpserver.services.manifests.ManifestField(**data)[source]

Bases: BaseModel

One field of a manifest, flattened from its kind’s JSON Schema.

manifest_fields() returns one per field, parents before their children, and the get_manifest_schema tool shows each one as a line of Markdown. The model is frozen.

default: JsonValue | None: The field’s default, or None if it has none.

description: str: What the field means, from the schema, without the prefix that field_description() removes.

model_config = {'extra': 'forbid', 'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

path: str

The field’s dotted path, e.g. spec.config.value.

A list’s items end with [], and a map’s values with .<key>.

required: bool: Whether a manifest must have the field, when it has the field’s parent.

type: str: The field’s type, in a few words, e.g. string, list of string, or one of: a, b.

smarter.apps.mcpserver.services.manifests.find_kind(name, directory='/Users/mcdaniel/Desktop/gh/smarter-sh/smarter/smarter/smarter/apps/api/v1/contract/sam')[source]

Return the kind that a name means, ignoring case.

Parameters:

name (str) – e.g. llmclient or LLMClient.
directory (str) – The folder of the schemas.

Return type:

str | None

Returns:

The kind, e.g. LLMClient, or None if no kind has that name.

smarter.apps.mcpserver.services.manifests.manifest_example(kind, directory='/Users/mcdaniel/Desktop/gh/smarter-sh/smarter/smarter/smarter/apps/api/v1/contract/sam')[source]

Return a kind’s example manifest.

Parameters:

kind (str) – The kind, e.g. Secret.
directory (str) – The folder of the examples.

Return type:

dict[str, Any]

Returns:

The manifest.

Raises:

FileNotFoundError – If the kind has no example.

smarter.apps.mcpserver.services.manifests.manifest_fields(schema)[source]

Return every field of a manifest, from its kind’s JSON Schema, without the read-only status.

Parameters:: schema (dict[str, Any]) – The kind’s JSON Schema.
Return type:: list[ManifestField]
Returns:: The fields, parents before their children, in the schema’s order.

Example usage:

fields = manifest_fields(manifest_schema("Secret"))
fields[-1].path  # 'spec.config.value'

smarter.apps.mcpserver.services.manifests.manifest_kinds(directory='/Users/mcdaniel/Desktop/gh/smarter-sh/smarter/smarter/smarter/apps/api/v1/contract/sam')[source]

Return the kinds that have a committed JSON Schema.

Side effect: a listing of directory.

Parameters:: directory (str) – The folder of the schemas.
Return type:: list[str]
Returns:: The kinds, sorted, e.g. ["Account", "ApiConnection", ...].

smarter.apps.mcpserver.services.manifests.manifest_schema(kind, directory='/Users/mcdaniel/Desktop/gh/smarter-sh/smarter/smarter/smarter/apps/api/v1/contract/sam')[source]

Return a kind’s JSON Schema.

Parameters:

kind (str) – The kind, e.g. Secret.
directory (str) – The folder of the schemas.

Return type:

dict[str, Any]

Returns:

The schema.

Raises:

FileNotFoundError – If the kind has no schema.

smarter.apps.mcpserver.services.manifests.parse_manifest(text)[source]

Parse a manifest, in YAML or JSON, which YAML includes.

Parameters:: text (str) – The manifest.
Return type:: TypeAliasType
Returns:: The parsed manifest.
Raises:: SmarterMCPServerServiceError – If it is too long, or is not YAML, or has aliases.

smarter.apps.mcpserver.services.manifests.validate_manifest_text(text)[source]

Validate a manifest that the LLM wrote, against the Pydantic model of its kind, without saving it.

The checks that make requests, e.g. that an image url responds, are skipped.

Parameters:: text (str) – The manifest, in YAML or JSON.
Return type:: CliApiValidation
Returns:: Whether it is valid, and its errors.
Raises:: SmarterMCPServerServiceError – If it is too long, or is not YAML.