MCP Toolset Policy¶

def mount_prefix(spec: collections.abc.Mapping[str, typing.Any]) -> str:
    """Return the path prefix the API's routers are mounted under.

    imbi-api mounts every domain router under the path component of
    ``IMBI_API_URL`` (e.g. ``/api``), so the spec describes
    ``/api/users/me`` while an internal client's ``base_url`` is just
    ``http://imbi-api:8000``. Anything that names a path by hand has to
    add the prefix back, and the spec is the only place it appears.

    Returns:
        The prefix (``''`` when the API is mounted at the root),
        derived from the spec path ending in :data:`PROFILE_PATH`.

    Raises:
        ValueError: When the spec does not contain exactly one path
            ending in :data:`PROFILE_PATH`. This fails *closed*:
            assuming the root would unanchor
            :func:`excluded_route_maps`, re-exposing auth and MFA
            operations as tools, and would point
            :class:`PermissionFilterMiddleware` at a profile URL that
            does not exist.

    """
    paths: collections.abc.Iterable[str] = spec.get('paths') or {}
    matches = [path for path in paths if path.endswith(PROFILE_PATH)]
    if len(matches) != 1:
        raise ValueError(
            f'Cannot determine the API mount prefix: expected exactly '
            f'one spec path ending in {PROFILE_PATH}, found '
            f'{len(matches)}'
        )
    return matches[0].removesuffix(PROFILE_PATH)

def excluded_route_maps(
    spec: collections.abc.Mapping[str, typing.Any],
) -> list[RouteMap]:
    """Endpoints that must never become AI tools regardless of tagging.

    Covers authentication, MFA, the status probe, and image thumbnails.
    The patterns are anchored at the spec's mount prefix so they still
    match on a deployment served under one (e.g. ``/api/auth/login``).

    Args:
        spec: The OpenAPI spec the toolset is built from.

    """
    prefix = re.escape(mount_prefix(spec))
    return [
        RouteMap(pattern=rf'^{prefix}/auth/', mcp_type=MCPType.EXCLUDE),
        RouteMap(pattern=rf'^{prefix}/mfa/', mcp_type=MCPType.EXCLUDE),
        RouteMap(pattern=rf'^{prefix}/status/?$', mcp_type=MCPType.EXCLUDE),
        RouteMap(pattern=r'.*/thumbnail/?$', mcp_type=MCPType.EXCLUDE),
    ]

def exclude_non_ai_tools(
    route: HTTPRoute, _mcp_type: MCPType
) -> MCPType | None:
    """Exclude operations imbi-api flagged as off-limits for AI.

    Intended to be passed as ``route_map_fn`` to
    :meth:`fastmcp.FastMCP.from_openapi`.

    Args:
        route: The OpenAPI route fastmcp is classifying.
        _mcp_type: The component type fastmcp would otherwise assign;
            unused, since the flag overrides any classification.

    Returns:
        :attr:`MCPType.EXCLUDE` when the operation carries
        ``x-imbi-ai-tool: false``, else ``None`` to leave the existing
        route-map decision unchanged. The check is identity-against
        ``False`` so an explicit ``x-imbi-ai-tool: true`` (or the absence
        of the extension) keeps the operation.

    """
    if route.extensions.get(AI_TOOL_EXTENSION) is False:
        return MCPType.EXCLUDE
    return None

def copy_permissions_to_meta(
    route: HTTPRoute, component: FastMCPComponent
) -> None:
    """Copy an operation's required permissions onto the component.

    Intended to be passed as ``mcp_component_fn`` to
    :meth:`fastmcp.FastMCP.from_openapi`. The route carries
    :data:`PERMISSION_EXTENSION` from the spec, but the generated
    component only keeps its route privately; recording the value in
    the public ``meta`` dict at build time lets
    :class:`PermissionFilterMiddleware` read it later without reaching
    into fastmcp internals.
    """
    permissions = route.extensions.get(PERMISSION_EXTENSION)
    if not permissions:
        return
    component.meta = (component.meta or {}) | {
        PERMISSION_META_KEY: permissions
    }

def required_permissions(tool: Tool) -> list[str]:
    """Return the permissions an operation-backed tool enforces.

    Reads what :func:`copy_permissions_to_meta` recorded. Tools built
    without that ``mcp_component_fn``, or whose operation has no
    permission dependency, return an empty list.
    """
    meta = getattr(tool, 'meta', None) or {}
    value = meta.get(PERMISSION_META_KEY)
    return value if isinstance(value, list) else []