aeat.entrypoints.mcp._surface module

Decide which tools the console advertises by default.

Dumping the whole ~273-verb tree into tools/list crowds out the user’s question and degrades tool selection (ADR mcp-progressive-discovery P1, amending the refoundation ADR’s R2 delivery posture). The console therefore advertises an orientation core by default - the always-on floor, grounding, and meta-discovery tools plus the small manifest-derived orientation slice (the overview obligation-derivation family and the capability contract verb, the surfaces the operator rules mandate reading first). The full per-verb universe stays reachable through the search + execute meta pair and through runtime toolset activation; it is not advertised up front.

The AEAT_MCP_SURFACE environment toggle preserves the flat surface for an operator who wants it (full) and for the core-vs-full A/B measurement; the shipped default is core. This module is SDK-independent and pure - it classifies descriptors by command key - so the policy is unit-tested directly without the stdio transport.

SURFACE_ENV_VAR

The environment variable selecting the advertised tool surface.

class SurfaceMode(*values)[source]

Bases: StrEnum

The advertised-tool-surface policy.

CORE (the shipped default) advertises only the orientation slice up front; FULL advertises every persona-scoped per-verb tool, the pre-ADR flat surface, kept for opt-out and for the core-vs-full measurement.

CORE
FULL
resolve_surface_mode(raw)[source]

Resolve the AEAT_MCP_SURFACE value to a SurfaceMode.

An unset or blank value is the shipped core default. A set value must name a mode exactly (case-insensitively); an unrecognised value raises with the accepted set named, so a misconfiguration fails loudly rather than silently reverting to a surface the operator did not choose.

Parameters:

raw (str | None) – The raw environment value, or None when unset.

Return type:

SurfaceMode

Returns:

The selected SurfaceMode.

Raises:

ValueError – When raw is a non-empty string naming no known mode.

is_orientation_command(command_key)[source]

Whether command_key belongs to the always-advertised orientation slice.

Return type:

bool

Parameters:

command_key (str)

advertised_descriptors(descriptors, *, mode)[source]

Narrow the per-verb descriptors to those advertised under mode.

FULL returns descriptors unchanged - the flat surface. CORE returns only the orientation slice; the rest of the universe stays reachable through the meta pair and toolset activation but is not listed up front. The caller has already narrowed descriptors to the active persona’s scope, so the orientation core is itself persona-filtered.

Return type:

tuple[McpToolDescriptor, ...]

Returns:

The subset of descriptors to advertise in tools/list.

Parameters: