skills

class SkillResource(_SkillModel):
    """One file in a skill's manifest: `{uri, digest, size}`.

    Shape rules are intrinsic: a `digest` that isn't `sha256:` + 64 lowercase
    hex characters, or a negative `size`, is rejected at construction.
    """

    uri: str
    digest: Annotated[str, AfterValidator(_check_digest)]
    """SHA-256 digest of the file's raw bytes, formatted `sha256:{64 hex chars}`."""
    size: Annotated[int, Field(ge=0)]
    """Length in bytes of the file's raw content."""

class Skill(_SkillModel):
    """An entry returned by `skills/list` or `skills/get`.

    SEP-2640 conformance is intrinsic: constructing (or parsing) a `Skill`
    validates the frontmatter `name`/`description`, and — unless `resources` is
    `"dynamic"` — that every entry names a file within the skill's own directory,
    with no duplicates and `SKILL.md` present. The `MAX_RESOURCES_PER_SKILL`
    (512-entry) and `MAX_TOTAL_SIZE` (16-MiB) limits are SHOULD NOT thresholds,
    not MUST NOT, so an over-limit manifest is accepted.
    """

    uri: str
    """Resource URI of the skill's `SKILL.md`."""
    frontmatter: Frontmatter
    resources: SkillResources
    meta: dict[str, Any] | None = Field(alias="_meta", default=None)
    """Opaque `_meta` the server attaches to this entry."""

    @model_validator(mode="after")
    def _check_conformance(self) -> Skill:
        name = skill_name_from_uri(self.uri)
        frontmatter_name = self.frontmatter.get("name")
        if (
            not isinstance(frontmatter_name, str)
            or not _NAME_RE.fullmatch(frontmatter_name)
            or len(frontmatter_name) > 64
        ):
            raise ValueError(f"skill {self.uri!r} frontmatter name must be 1-64 lowercase, digits, or hyphens")
        if frontmatter_name != name:
            raise ValueError(
                f"skill {self.uri!r} frontmatter name {frontmatter_name!r} does not match URI name {name!r}"
            )
        description = self.frontmatter.get("description")
        if not isinstance(description, str) or not (1 <= len(description) <= 1024):
            raise ValueError(f"skill {self.uri!r} frontmatter description must contain 1 to 1024 characters")
        if self.resources == "dynamic":
            return self
        seen: set[str] = set()
        for resource in self.resources:
            _validate_resource_uri_in_skill(self.uri, resource.uri)
            if resource.uri in seen:
                raise ValueError(f"skill {self.uri!r} lists resource {resource.uri!r} more than once")
            seen.add(resource.uri)
        if self.uri not in seen:
            raise ValueError(f"skill {self.uri!r} resources does not include its own SKILL.md")
        return self

class ListSkillsParams(PaginatedRequestParams):
    """Parameters for `skills/list`."""

class ListSkillsResult(PaginatedResult, CacheableResult):
    """Result of `skills/list`.

    Each skill self-validates; on top of that, constructing (or parsing) this
    result rejects two entries that share a `uri`.

    `ttl_ms`/`cache_scope` are SEP-2549 fields inherited from `CacheableResult`;
    unlike a core spec method, nothing sieves them off the wire for a
    pre-2026-07-28 connection automatically (see `mcp.server.skills`), so
    callers constructing this directly for such a connection must omit them.
    """

    skills: list[Skill]

    @model_validator(mode="after")
    def _check_unique_uris(self) -> ListSkillsResult:
        seen: set[str] = set()
        for skill in self.skills:
            if skill.uri in seen:
                raise ValueError(f"skills/list result lists skill {skill.uri!r} more than once")
            seen.add(skill.uri)
        return self

class GetSkillParams(RequestParams):
    """Parameters for `skills/get`."""

    uri: str
    """URI of the skill's `SKILL.md`."""

class GetSkillResult(CacheableResult):
    """Result of `skills/get`.

    Like `ListSkillsResult`, this extends `CacheableResult`: the stable spec page
    makes `GetSkillResult` carry SEP-2549's `ttl_ms`/`cache_scope`, the same
    freshness hint `resources/read` gives. As on `skills/list`, nothing sieves
    these fields off the wire for a pre-2026-07-28 connection automatically (see
    `mcp.server.skills`), so a caller constructing this directly for such a
    connection must omit them.
    """

    skill: Skill

class ReadDirectoryParams(PaginatedRequestParams):
    """Parameters for `resources/directory/read`."""

    uri: str
    """URI of the directory resource whose direct children are listed."""

class ReadDirectoryResult(PaginatedResult, CacheableResult):
    """Result of `resources/directory/read`.

    Like `ListSkillsResult`, this carries SEP-2549's `ttl_ms`/`cache_scope`, which
    `mcp.server.skills` strips for a pre-2026-07-28 connection.
    """

    resources: list[Resource]