Action Metadata Reference · Developers Hub

MyronActionMetadata is the declarative contract for one action. The dispatcher uses it for routing, schema validation, and scope checks. The manifest and MCP server use it for discovery. Documentation should treat this metadata as the source of truth for action shape.

Human Path

Extension authors fill out metadata in each action class:

public function metadata(): MyronActionMetadata
{
    return new MyronActionMetadata(
        uri: '/api/v1/x/my_vendor/status',
        method: 'GET',
        domain: 'x.my_vendor.status',
        resource: 'status',
        verb: 'get',
        inputSchema: ['type' => 'object', 'properties' => []],
        outputSchema: ['type' => 'object', 'properties' => ['ready' => ['type' => 'boolean']]],
        requiredScope: MyronApiScopes::CONTENT_READ,
        summary: 'Return this extension status.',
        sideEffects: [],
        preconditions: ['The extension is enabled and granted content.read.'],
        postconditions: [],
        audienceClass: 3,
        exposeToMcp: true,
    );
}

AI Path

An AI coding agent can author metadata locally. An installed AI client should discover loaded actions from /api/v1/manifest, MCP tools/list, or MCP resources rather than relying on a copied list from documentation.

Scopes

This reference page does not require a runtime scope to read. Individual actions declare their own requiredScope, and runtime callers must hold that scope before the dispatcher invokes the action. MCP tools/list also uses that field to omit tools the caller cannot invoke.

Field Reference

Field	Type	Default	Used by	AI/MCP significance	Safety notes
`uri`	string	required	Registry, dispatcher, manifest, MCP call routing	Direct API path and underlying target for `tools/call`.	Extension URIs must start with `/api/v1/x/{vendor}/`.
`method`	string	required	Registry and dispatcher	Determines direct API verb and MCP dispatch method.	Use `GET` for reads; use `POST`, `PATCH`, or `DELETE` for writes.
`domain`	string	required	Manifest, MCP tool naming, audit	First part of default tool name.	Extension domains must start with `x.{vendor}.`.
`resource`	string	required	Manifest, MCP tool naming	Second part of default tool name.	Use a stable resource noun.
`verb`	string	required	Manifest, MCP tool naming, audit	Third part of default tool name.	Keep it stable; clients may cache discovery.
`inputSchema`	array	required	Dispatcher validation, MCP tool schema	Tells AI clients what arguments are accepted.	Extension schemas must not be empty arrays.
`outputSchema`	array	required	Manifest and compatibility documentation	Helps clients understand result shape.	Extension schemas must not be empty arrays.
`requiredScope`	string or null	required	Auth, dispatcher, MCP list filtering	Tells clients which caller scope is needed.	`null` means public action; do not use public scope for private extension data.
`summary`	string	required	Manifest and MCP tool description	Main short context for AI tool choice.	Keep concise and action-specific.
`sideEffects`	list<string>	`[]`	Manifest, docs, audit context	Helps AI decide whether a call mutates state.	Must be honest; do not leave writes undocumented.
`preconditions`	list<string>	`[]`	Manifest and docs	Teaches clients what must be true before calling.	Return declared errors when preconditions fail.
`postconditions`	list<string>	`[]`	Manifest and docs	Teaches clients what should be true after success.	Do not claim effects the action does not guarantee.
`audienceClass`	int	`2`	Manifest and registry review	Indicates intended audience class.	Use established local meaning; do not invent public support.
`adminAliases`	list<string>	`[]`	Registry audit	Maps legacy admin POST verbs to registered actions.	Internal drift guard aid, not an extension routing escape hatch.
`snapshotInclude`	bool	`false`	System snapshot composer	May include read results in live install snapshot.	Only meaningful for GET actions; composer skips non-GET actions.
`snapshotKey`	string or null	`null`	System snapshot composer	JSON path for snapshot placement.	Required only when `snapshotInclude:true`.
`exposeToMcp`	bool	`true`	MCP `tools/list`	Controls whether an action appears as an MCP tool.	Hide only for documented policy reasons.
`supportsProgress`	bool	`false`	MCP transport	Indicates long-running progress support.	Do not set true unless progress notifications are implemented.
`liveContentResolution`	array	`[]`	Compatibility documents	Describes content re-render behavior.	Use only when the action participates in that contract.

toArray() emits these fields into the manifest shape. Documentation pages should use the field names as emitted: inputSchema, outputSchema, requiredScope, sideEffects, preconditions, postconditions, snapshotInclude, snapshotKey, exposeToMcp, supportsProgress, and liveContentResolution.

Extension Validation

ActionRegistry::registerExtension() applies extension-specific validation before the action is registered:

Rule	Required shape
Vendor	`^[a-z][a-z0-9_]*$`
URI prefix	`/api/v1/x/{vendor}/`
Domain prefix	`x.{vendor}.`
Input schema	non-empty array
Output schema	non-empty array

These checks protect the extension namespace. They do not replace operator grants or caller scopes.

Manifest and Discovery

The action catalog is live. Clients should discover the current surface through the running install:

direct API manifest for full action metadata,
MCP tools/list for exposed, scope-allowed tools,
MCP resources for snapshot and compatibility documents.

Do not freeze a copied action list in docs. The docs explain contracts and examples; the install reports its actual registered actions.

Artifacts

Primary artifacts for this contract are:

MyronActionMetadata constructor arguments,
MyronActionMetadata::toArray() manifest output,
action classes under app/extensions/{vendor}/actions/,
direct API manifest output,
MCP tools/list tool definitions.

Safety Boundary

Metadata is not a permission bypass. requiredScope does not grant scope; it declares the gate. exposeToMcp:true does not make an action callable unless the action loads and the caller holds the required scope. exposeToMcp:false does not remove the action from the registry or manifest; it only hides the action from MCP tool listing.

Verification

For a new action:

Confirm the action registers without namespace or schema errors.
Read the manifest and confirm metadata fields are present.
Call the direct API with a scoped caller.
Call MCP tools/list and confirm exposure matches exposeToMcp and caller scope.
If snapshotInclude:true, read the system snapshot or compatibility document and confirm placement under snapshotKey.

Failure Modes

Failure	Likely source	Safe fix
Action does not register	Extension namespace or schema validation failed.	Check URI, domain, vendor, and non-empty schemas.
Tool missing from MCP	`exposeToMcp:false`, action not loaded, or caller lacks scope.	Check metadata, load state, and caller scope.
Manifest metadata is misleading	Metadata no longer matches implementation.	Update action metadata with the same change as the implementation.
Snapshot entry absent	`snapshotInclude` false, non-GET method, missing `snapshotKey`, or caller scope filtering.	Use snapshot fields only for suitable read actions.
AI client calls wrong tool name	Client cached an old name or inferred name incorrectly.	Re-read `tools/list` from the running install.