mainsequence 9.0.22.dev65__py3-none-any.whl → 9.0.23.dev66__py3-none-any.whl

agent_scaffold/AGENTS.md

@@ -77,7 +77,8 @@ bundle. Platform skills are installed separately under
   `mainsequence.client.metatables`, or calls the retired `mainsequence` table
   and migration commands:
   `.agents/skills/mainsequence/maintenance/metatables_transition/SKILL.md`
-- FastAPI APIs serving the Command Center frontend:
+- FastAPI APIs serving the Command Center frontend, and MCP tools and skills
+  served from a FastAPI release:
   `.agents/skills/mainsequence/application_surfaces/api_surfaces/SKILL.md`
 - Jobs, schedules, images, resources, releases, and Artifacts:
   `.agents/skills/mainsequence/platform_operations/orchestration_and_releases/SKILL.md`

agent_scaffold/skills/application_surfaces/api_surfaces/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mainsequence-command-center-fastapi
-description: Build, contract-test, release, and verify a FastAPI code repository resource serving the Command Center frontend, including applications with public OAuth callback or webhook routes. Use when implementing a Command Center wire contract, declaring exact public ingress, or validating the deployed API.
+description: Build, contract-test, release, and verify a FastAPI code repository resource serving the Command Center frontend, including applications with public OAuth callback or webhook routes. Use when implementing a Command Center wire contract, declaring exact public ingress, serving MCP tools or publishing MCP skills from the app (including setting the folder of skills it publishes), or validating the deployed API.
 ---
 
 # Command Center FastAPI Release Lifecycle
@@ -236,10 +236,11 @@ See also
 
 ### MCP tools
 
-To serve MCP tools from the same application, add the `mcp` extra and call
-`install_mcp(app, mcp.streamable_http_app(), lifespan=mcp.session_manager.run)`
-after `install_request_identity(app)`, with a stateless FastMCP server that
-returns JSON. Tools authorize with `User.get_logged_user()` and
+To serve MCP tools from the same application, add the `mcp` extra (the
+official MCP Python SDK 2.x) and call
+`install_mcp(app, mcp.streamable_http_app(stateless_http=True, json_response=True, transport_security=...), lifespan=mcp.session_manager.run)`
+after `install_request_identity(app)`, with an `MCPServer`; 1.x's `FastMCP`
+is not supported by the extra. Tools authorize with `User.get_logged_user()` and
 `User.get_requester()` exactly like REST handlers; admission to the release
 does not authorize every tool. Each tool decides whether it needs a person: a
 tool that needs one fails with its own error when the getter returns `None`,
@@ -251,6 +252,59 @@ threads it uses through `asyncio.to_thread` or anyio's `to_thread.run_sync`,
 and ends with the call. See
 [Serving MCP](https://mainsequence-sdk.github.io/mainsequence-sdk/knowledge/fastapi/#serving-mcp).
 
+### MCP skills
+
+The MCP server publishes skills to its clients only from the folder set with
+`skills_extension`. Setting it is required: without it, the server exposes no
+skills and declares no Skills extension, whatever the repository holds.
+
+1. Ask the user which folder holds the skills to publish. Its name and place
+   are the user's choice; the SDK neither requires nor suggests one. The
+   examples below use `.agents/skills/mcp_only`. Only that folder is published;
+   the coding agents' other skill folders are not.
+2. In that folder, a folder with a `SKILL.md` is a skill, and a folder without
+   one groups skills; the group's path prefixes the URIs of the skills in it.
+   Each `SKILL.md` has frontmatter with `name`, equal to its folder's name, and
+   `description`. Supporting files sit beside it, in any subfolders:
+
+   ```text
+   .agents/skills/mcp_only/      # the folder set below (an example)
+     billing/                    # a group: no SKILL.md
+       refund-review/
+         SKILL.md                # skill://billing/refund-review/SKILL.md
+         references/policy.md
+       chargebacks/
+         SKILL.md                # skill://billing/chargebacks/SKILL.md
+     daily-close/
+       SKILL.md                  # skill://daily-close/SKILL.md
+   ```
+
+   Skill and group folder names are 1 to 64 characters of `a-z`, `0-9` and
+   single hyphens. A skill inside another skill is refused.
+3. Set the folder when constructing the server. A relative path is
+   repository-relative: it is looked up from the module that calls
+   `skills_extension` upwards, so it works from any module of the repository
+   and any working directory. Point at the folder that holds the skills, never
+   at `.agents/skills` itself:
+
+   ```python
+   from mcp.server.mcpserver import MCPServer
+
+   from mainsequence.server.mcp_skills import skills_extension
+
+   mcp = MCPServer("refunds", extensions=[skills_extension(".agents/skills/mcp_only")])
+   ```
+
+4. Commit the folder and start the app. Every skill in it is published; add or
+   remove a skill folder and redeploy to change the list. An invalid skill
+   fails startup with the file and the rule; quote frontmatter values such as
+   `yes`, dates and `0755`.
+
+Clients list the skills with `skills/list` and read them with `skills/get`
+and `resources/read` on the release's `/mcp`, behind the same authentication
+as tools. Do not register your own `skill://` resources. See
+[Skills](https://mainsequence-sdk.github.io/mainsequence-sdk/knowledge/fastapi/#skills).
+
 ### Public provider callbacks and webhooks
 
 An external OAuth redirect or webhook cannot supply a Main Sequence Bearer token.

agent_scaffold/skills/maintenance/code_repository_maintenance/SKILL.md

@@ -162,18 +162,22 @@ mainsequence code-repository update-sdk --path . --dry-run
 mainsequence code-repository update-sdk --path .
 ```
 
-`update-sdk` updates the lock and local environment. It does not publish the
-working tree or authorize a managed-skill or `AGENTS.md` refresh. Report any
-resulting pin mismatch and run those updates only when the user explicitly
-requests them.
+`update-sdk` updates the lock and local environment, then runs the newly
+installed SDK's skill copier in a fresh process against the same repository.
+It replaces SDK-owned skills, removes retired ones, and updates their sentinel.
+It does not refresh platform skills or `AGENTS.md`, or publish the working tree.
+If copying fails, the command fails but the SDK remains upgraded; report that
+partial result and use the printed refresh command to retry after addressing
+the failure. On success, reload this maintenance skill before continuing.
 
 Do not automatically commit or push an SDK update unless the user also asked
 to publish the CodeRepository changes.
 
 ## Refresh Managed Skills And Instructions
 
-Run either managed-scaffold command only when the user explicitly requests that
-specific update. When both are requested, refresh the SDK-owned skills first,
+Outside the skill refresh included in `update-sdk`, run either managed-scaffold
+command only when the user explicitly requests that specific update. When both
+are requested, refresh the SDK-owned skills first,
 then update the managed Main Sequence block in
 `AGENTS.md`:
 

agent_scaffold/skills/sdk_code_repository_execution/SKILL.md

@@ -49,7 +49,8 @@ Do not let this skill become a domain manual.
 
 - MetaTables, table updates, and domain data discovery: use the installed
   `metatables` package skills and documentation
-- FastAPI APIs serving the Command Center frontend:
+- FastAPI APIs serving the Command Center frontend, and MCP tools and skills
+  served from a FastAPI release:
   `.agents/skills/mainsequence/application_surfaces/api_surfaces/SKILL.md`
 - CodeRepository audits, blocker analysis, and upstream SDK assessment:
   `.agents/skills/mainsequence/maintenance/bug_auditor/SKILL.md`

mainsequence/cli/cli.py

@@ -7633,7 +7633,10 @@ def code_repository_update_sdk(
     dry_run: bool = typer.Option(False, "--dry-run", help="Print steps but do not execute"),
 ):
     """
-    Upgrade the CodeRepository SDK dependency (`mainsequence`) using `uv`.
+    Upgrade the CodeRepository SDK dependency and refresh its SDK-owned skills.
+
+    After installing with `uv`, run the updated SDK's skill copier in a fresh
+    process. Platform skills and AGENTS.md are not changed.
 
     Parameters
     ----------
@@ -7655,10 +7658,20 @@ def code_repository_update_sdk(
     code_repository_dir = _resolve_code_repository_dir(code_repository_id, path)
     ensure_venv(code_repository_dir)
 
+    refresh_args = [
+        "run",
+        "--no-sync",
+        "mainsequence",
+        "code-repository",
+        "update-agent-skills",
+        "--path",
+        str(code_repository_dir),
+    ]
     steps = [
         "resolve uv executable",
         "uv lock --upgrade-package mainsequence",
         "uv sync",
+        f"uv {shlex.join(refresh_args)}",
     ]
     print_table("Update SDK plan", ["Step"], [[s] for s in steps])
 
@@ -7671,34 +7684,18 @@ def code_repository_update_sdk(
         run_uv(uv, ["lock", "--upgrade-package", "mainsequence"], cwd=code_repository_dir)
         run_uv(uv, ["sync"], cwd=code_repository_dir)
 
-    success("SDK update complete.")
-    _warn_if_sdk_skills_stale(code_repository_dir)
-
-
-def _warn_if_sdk_skills_stale(code_repository_dir: pathlib.Path) -> None:
+    # The current process still has the pre-upgrade CLI loaded.
     try:
-        version = _code_repository_installed_package_version(code_repository_dir, "mainsequence")
-        sentinel = code_repository_dir / ".agents" / "skills" / "mainsequence" / "PINNED_FROM.txt"
-        values = (
-            dict(
-                line.split("=", 1)
-                for line in sentinel.read_text(encoding="utf-8").splitlines()
-                if "=" in line
-            )
-            if sentinel.is_file()
-            else {}
-        )
-    except (OSError, ValueError, typer.Exit):
-        warn("Could not check the vendored SDK skill pin. Run update-agent-skills to refresh it.")
-        return
-    pinned = values.get("pinned_version", values.get("sdk_version"))
-    if pinned != version:
-        warn(
-            f"Vendored SDK skills are stale or missing (pinned: {pinned or 'missing'}; installed: {version}). "
-            "No scaffold files were changed. Refresh with "
-            "`uv run --offline mainsequence code-repository update-agent-skills --path .` "
-            "and `uv run --offline mainsequence code-repository update AGENTS.md --path .`."
+        run_uv(uv, refresh_args, cwd=code_repository_dir)
+    except (OSError, RuntimeError) as exc:
+        error(
+            f"SDK upgraded, but SDK skill refresh failed: {exc}\n"
+            "The SDK upgrade has not been rolled back. "
+            f"Retry from {code_repository_dir} with: uv {shlex.join(refresh_args)}"
         )
+        raise typer.Exit(1) from exc
+
+    success("SDK update and SDK skill refresh complete.")
 
 
 @code_repository.command("update")

mainsequence/server/_mcp_skills_upstream/__init__.py

@@ -0,0 +1,60 @@
+"""The official MCP Skills extension, copied until an ``mcp`` release ships it (ADR 0039).
+
+``server.py`` and ``shared.py`` are ``src/mcp/server/skills.py`` and
+``src/mcp/shared/skills.py`` of the official MCP Python SDK,
+https://github.com/modelcontextprotocol/python-sdk, at commit
+``9a754b0aabb873d9707d52dc165b569fb442ec8c`` ("Add `Skills` extension", #3485),
+the server side of the ``io.modelcontextprotocol/skills`` extension. They run on
+the released ``mcp`` 2.3.0.
+
+The only change is one import in ``server.py``, which reads ``shared.py`` from
+this package instead of ``mcp.shared.skills``. Nothing else is edited, fixed or
+extended; take an upstream fix by copying both files again from a later commit.
+``UPSTREAM`` records each file's SHA-256 as upstream published it, and a test
+checks that the copies still match. Delete this package once an ``mcp`` release
+contains the extension.
+
+The copied files are under the license of the MCP Python SDK:
+
+    MIT License
+
+    Copyright (c) 2024 Anthropic, PBC
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in all
+    copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+    SOFTWARE.
+"""
+
+COMMIT = "9a754b0aabb873d9707d52dc165b569fb442ec8c"
+
+# Copied file: (upstream path, SHA-256 of the upstream file).
+UPSTREAM = {
+    "server.py": (
+        "src/mcp/server/skills.py",
+        "4a7e9b1db05d693b07c45a4db4ef85ef54713708a96154841255aa3c8d8a5334",
+    ),
+    "shared.py": (
+        "src/mcp/shared/skills.py",
+        "2669d7f4fa0ba328bdde70589d410f58274f5e8aff9d01e31e9b500d7a45ccfb",
+    ),
+}
+
+# The one line changed in server.py: (upstream, copy).
+CHANGED_IMPORT = (
+    "from mcp.shared.skills import (",
+    "from mainsequence.server._mcp_skills_upstream.shared import (",
+)

mainsequence/server/_mcp_skills_upstream/server.py

@@ -0,0 +1,172 @@
+"""The Skills extension (`io.modelcontextprotocol/skills`, SEP-2640).
+
+SEP-2640 defines a convention for serving Agent Skills over MCP using the
+Resources primitive: a skill is a directory of files, conventionally exposed
+under the `skill://` scheme, and enumerated and fetched through two required
+methods (`skills/list`, `skills/get`) plus one optional one
+(`resources/directory/read`). See
+https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2640.
+
+This module provides the protocol-level plumbing only: request/response
+handling, SEP-2640 conformance validation, and capability advertisement. It
+does not discover, read, or hash skills from a filesystem — a server author
+supplies handlers that answer `skills/list`/`skills/get`/`resources/directory/read`
+however their catalog is stored, and serves the underlying `skill://` file
+content through the server's ordinary resource-registration APIs
+(`MCPServer.add_resource`, or an `@mcp.resource(...)` template).
+
+    async def list_skills(ctx, params):
+        return ListSkillsResult(skills=[...])
+
+    async def get_skill(ctx, params):
+        if params.uri != "skill://git-workflow/SKILL.md":
+            raise MCPError(code=INVALID_PARAMS, message="unknown skill")
+        return GetSkillResult(skill=...)
+
+    mcp = MCPServer("catalog", extensions=[Skills(list_skills=list_skills, get_skill=get_skill)])
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable, Sequence
+from typing import Any
+
+from mcp_types import CacheableResult
+from mcp_types.jsonrpc import INTERNAL_ERROR, INVALID_PARAMS
+from mcp_types.version import MODERN_PROTOCOL_VERSIONS
+from pydantic import ValidationError
+
+from mcp.server.context import HandlerResult, ServerRequestContext
+from mcp.server.extension import Extension, MethodBinding
+from mcp.shared.exceptions import MCPError
+from mainsequence.server._mcp_skills_upstream.shared import (
+    EXTENSION_ID,
+    METHOD_GET,
+    METHOD_LIST,
+    METHOD_READ_DIRECTORY,
+    GetSkillParams,
+    GetSkillResult,
+    ListSkillsParams,
+    ListSkillsResult,
+    ReadDirectoryParams,
+    ReadDirectoryResult,
+    parse_directory_uri,
+    skill_name_from_uri,
+    validate_directory_result,
+)
+
+__all__ = ["Skills"]
+
+ListSkillsHandler = Callable[[ServerRequestContext[Any, Any], ListSkillsParams], Awaitable[ListSkillsResult]]
+GetSkillHandler = Callable[[ServerRequestContext[Any, Any], GetSkillParams], Awaitable[GetSkillResult]]
+ReadDirectoryHandler = Callable[[ServerRequestContext[Any, Any], ReadDirectoryParams], Awaitable[ReadDirectoryResult]]
+
+
+class Skills(Extension):
+    """The Skills extension: serve `skills/list`, `skills/get`, and directory reads.
+
+    `list_skills` and `get_skill` are required; a server MUST answer both per
+    SEP-2640, whether or not a skill appears in the listing. `read_directory`
+    is optional — supplying it advertises the `directoryRead` capability
+    setting and serves `resources/directory/read`; omitting it advertises
+    neither. Handlers run per request, so a catalog that changes over time
+    (or is too large to enumerate) can return a partial or empty listing.
+
+    Handler error contract: raise `MCPError` to return a specific error to the
+    caller (e.g. `INVALID_PARAMS` from `get_skill` for a URI it doesn't serve).
+    A result that isn't SEP-2640 conformant is caught here and reported as
+    `INTERNAL_ERROR` — a server fault, not the caller's bad params.
+    """
+
+    identifier = EXTENSION_ID
+
+    def __init__(
+        self,
+        *,
+        list_skills: ListSkillsHandler,
+        get_skill: GetSkillHandler,
+        read_directory: ReadDirectoryHandler | None = None,
+    ) -> None:
+        self._list_skills = list_skills
+        self._get_skill = get_skill
+        self._read_directory = read_directory
+
+    def settings(self) -> dict[str, Any]:
+        return {"directoryRead": True} if self._read_directory is not None else {}
+
+    def methods(self) -> Sequence[MethodBinding]:
+        bindings = [
+            MethodBinding(METHOD_LIST, ListSkillsParams, self._handle_list),
+            MethodBinding(METHOD_GET, GetSkillParams, self._handle_get),
+        ]
+        if self._read_directory is not None:
+            bindings.append(MethodBinding(METHOD_READ_DIRECTORY, ReadDirectoryParams, self._handle_read_directory))
+        return bindings
+
+    async def _handle_list(self, ctx: ServerRequestContext[Any, Any], params: ListSkillsParams) -> HandlerResult:
+        # `ListSkillsResult`/`Skill` self-validate on construction, so a handler that builds a
+        # non-conformant listing raises `ValidationError` here — a server fault, surfaced as an
+        # Internal error rather than the framework's default Invalid params for a bad body. The
+        # models stay mutable, so re-validate the outbound payload too: a handler that mutates a
+        # skill after building the result can't ship a non-conformant listing past this point.
+        try:
+            result = await self._list_skills(ctx, params)
+            ListSkillsResult.model_validate(result.model_dump())
+        except ValidationError:
+            raise MCPError(code=INTERNAL_ERROR, message="Handler returned an invalid result") from None
+        return _finalize_cacheable(result, ctx.protocol_version)
+
+    async def _handle_get(self, ctx: ServerRequestContext[Any, Any], params: GetSkillParams) -> HandlerResult:
+        _require_skill_md_uri(params.uri)
+        # `Skill` self-validates on construction, and the re-validation guards post-construction
+        # mutation, both as in `_handle_list`.
+        try:
+            result = await self._get_skill(ctx, params)
+            GetSkillResult.model_validate(result.model_dump())
+        except ValidationError:
+            raise MCPError(code=INTERNAL_ERROR, message="Handler returned an invalid result") from None
+        if result.skill.uri != params.uri:
+            raise MCPError(code=INTERNAL_ERROR, message="Handler returned an invalid result")
+        return _finalize_cacheable(result, ctx.protocol_version)
+
+    async def _handle_read_directory(
+        self, ctx: ServerRequestContext[Any, Any], params: ReadDirectoryParams
+    ) -> HandlerResult:
+        assert self._read_directory is not None
+        _require_directory_uri(params.uri)
+        result = await self._read_directory(ctx, params)
+        try:
+            validate_directory_result(params.uri, result)
+        except ValueError:
+            raise MCPError(code=INTERNAL_ERROR, message="Handler returned an invalid result") from None
+        return result
+
+
+def _require_skill_md_uri(uri: str) -> None:
+    try:
+        skill_name_from_uri(uri)
+    except ValueError as exc:
+        raise MCPError(code=INVALID_PARAMS, message=str(exc)) from exc
+
+
+def _require_directory_uri(uri: str) -> None:
+    try:
+        parse_directory_uri(uri)
+    except ValueError as exc:
+        raise MCPError(code=INVALID_PARAMS, message=str(exc)) from exc
+
+
+def _finalize_cacheable(result: CacheableResult, protocol_version: str) -> HandlerResult:
+    """Gate SEP-2549's `ttlMs`/`cacheScope` to protocol version 2026-07-28+.
+
+    `skills/list` and `skills/get` are extension methods, so — unlike a core spec
+    method — the runner's per-version surface sieve never runs on their results;
+    nothing else strips these fields for a legacy connection. `CacheableResult`
+    defaults to `cache_scope="private"`, keeping user-specific entries out of shared caches.
+    """
+    if protocol_version in MODERN_PROTOCOL_VERSIONS:
+        return result
+    dumped = result.model_dump(by_alias=True, mode="json", exclude_none=True)
+    dumped.pop("ttlMs", None)
+    dumped.pop("cacheScope", None)
+    return dumped

mainsequence/server/_mcp_skills_upstream/shared.py

@@ -0,0 +1,297 @@
+"""Wire types and SEP-2640 conformance checks for the Skills extension.
+
+Shared by the server (`mcp.server.skills`) and client (`mcp.client.extensions.skills`)
+surfaces, mirroring how `mcp.shared.extension` hosts the identifier grammar
+both tiers need. See https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2640.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Annotated, Any, Literal
+from urllib.parse import urlsplit
+
+from mcp_types import CacheableResult, PaginatedRequestParams, PaginatedResult, Request, RequestParams, Resource
+from pydantic import AfterValidator, BaseModel, ConfigDict, Field, model_validator
+from pydantic.alias_generators import to_camel
+
+__all__ = [
+    "Frontmatter",
+    "SkillResource",
+    "SkillResources",
+    "Skill",
+    "ListSkillsParams",
+    "ListSkillsResult",
+    "GetSkillParams",
+    "GetSkillResult",
+    "ReadDirectoryParams",
+    "ReadDirectoryResult",
+]
+
+EXTENSION_ID = "io.modelcontextprotocol/skills"
+"""The Skills extension identifier, advertised under `ServerCapabilities.extensions`."""
+
+METHOD_LIST = "skills/list"
+METHOD_GET = "skills/get"
+METHOD_READ_DIRECTORY = "resources/directory/read"
+
+MAX_RESOURCES_PER_SKILL = 512
+"""SEP-2640 per-skill resource-count threshold (`SKILL.md` included).
+
+A SHOULD NOT limit, not a hard cap: the spec requires a host to support skills
+*up to and including* 512 entries and permits it to support larger ones, so a
+`Skill` does not reject an over-count manifest."""
+
+MAX_TOTAL_SIZE = 16 * 1024 * 1024
+"""SEP-2640 per-skill total-byte-size threshold (16 MiB), summed over `resources[].size`.
+
+A SHOULD NOT limit, not a hard cap (see `MAX_RESOURCES_PER_SKILL`); an over-size
+manifest is not rejected."""
+
+_NAME_RE = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
+_DIGEST_RE = re.compile(r"^sha256:[0-9a-f]{64}$")
+
+
+def _check_digest(value: str) -> str:
+    if not _DIGEST_RE.fullmatch(value):
+        raise ValueError(f"invalid SHA-256 digest {value!r}; expected 'sha256:' + 64 lowercase hex characters")
+    return value
+
+
+class _SkillModel(BaseModel):
+    """Base for Skills value types: matches `mcp_types`' internal `MCPModel` config.
+
+    `MCPModel` itself isn't public; every field defined below is already a
+    single word, so this only matters if a future field needs camelCase.
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)
+
+
+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."""
+
+
+Frontmatter = dict[str, Any]
+"""A skill's `SKILL.md` YAML frontmatter, rendered verbatim as JSON."""
+
+SkillResources = list[SkillResource] | Literal["dynamic"]
+"""A skill's complete resource manifest, or the `"dynamic"` marker (SEP-2640 Resources)."""
+
+
+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
+
+    @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):
+    """Result of `resources/directory/read`."""
+
+    resources: list[Resource]
+
+
+class ListSkillsRequest(Request[ListSkillsParams | None, Literal["skills/list"]]):
+    method: Literal["skills/list"] = "skills/list"
+    params: ListSkillsParams | None = None
+
+
+class GetSkillRequest(Request[GetSkillParams, Literal["skills/get"]]):
+    method: Literal["skills/get"] = "skills/get"
+    params: GetSkillParams
+
+
+class ReadDirectoryRequest(Request[ReadDirectoryParams, Literal["resources/directory/read"]]):
+    method: Literal["resources/directory/read"] = "resources/directory/read"
+    params: ReadDirectoryParams
+
+
+def skill_name_from_uri(uri: str) -> str:
+    """Return the skill `name` encoded in a `SKILL.md` resource URI.
+
+    Per SEP-2640 Resource Mapping, the final `<skill-path>` segment equals the
+    skill's `name`; for a bare `skill://<name>/SKILL.md` (no organizational
+    prefix) that segment is the authority.
+
+    Raises:
+        ValueError: If `uri` is not an absolute URI ending in `/SKILL.md`.
+    """
+    parts = urlsplit(uri)
+    if not parts.scheme or parts.query or parts.fragment:
+        raise ValueError(f"skill URI {uri!r} is not a valid absolute resource URI")
+    if not parts.path.endswith("/SKILL.md"):
+        raise ValueError(f"skill URI {uri!r} must end in /SKILL.md")
+    directory = parts.path[: -len("/SKILL.md")].strip("/")
+    if directory:
+        name = directory.rsplit("/", 1)[-1]
+    else:
+        name = parts.hostname or ""
+    if not name:
+        raise ValueError(f"skill URI {uri!r} has no skill name")
+    return name
+
+
+def _validate_resource_uri_in_skill(skill_uri: str, resource_uri: str) -> None:
+    """Raise `ValueError` unless `resource_uri` names a file within `skill_uri`'s directory."""
+    skill_parts = urlsplit(skill_uri)
+    resource_parts = urlsplit(resource_uri)
+    if not resource_parts.scheme or resource_parts.query or resource_parts.fragment:
+        raise ValueError(f"resource URI {resource_uri!r} is invalid")
+    if resource_uri.endswith("/"):
+        raise ValueError(f"resource URI {resource_uri!r} names a directory, not a file")
+    if skill_parts.scheme != resource_parts.scheme or skill_parts.netloc != resource_parts.netloc:
+        raise ValueError(f"resource URI {resource_uri!r} is outside the skill root {skill_uri!r}")
+    root = skill_parts.path[: -len("/SKILL.md")]
+    if resource_parts.path != skill_parts.path and not resource_parts.path.startswith(root + "/"):
+        raise ValueError(f"resource URI {resource_uri!r} is outside the skill root {skill_uri!r}")
+    if any(segment in (".", "..") for segment in resource_parts.path.split("/")):
+        raise ValueError(f"resource URI {resource_uri!r} contains a traversal segment")
+
+
+def parse_directory_uri(uri: str) -> tuple[str, str, str]:
+    """Split a directory resource URI into `(scheme, netloc, path)`.
+
+    Raises:
+        ValueError: If `uri` has a trailing slash, or is otherwise not a valid
+            absolute resource URI.
+    """
+    if uri.endswith("/"):
+        raise ValueError(f"directory URI {uri!r} must not have a trailing slash")
+    parts = urlsplit(uri)
+    if not parts.scheme or parts.query or parts.fragment:
+        raise ValueError(f"directory URI {uri!r} is not a valid absolute resource URI")
+    return parts.scheme, parts.netloc, parts.path
+
+
+def validate_directory_result(uri: str, result: ReadDirectoryResult) -> None:
+    """Validate that each entry in `result.resources` is a unique direct child of `uri`.
+
+    Checks containment and shape only — that every listed resource is a direct
+    child of `uri` with a unique `uri`. It cannot confirm the listing
+    is exhaustive, since it has no independent view of the directory's contents.
+
+    Raises:
+        ValueError: If `uri` is malformed, or any entry is not a direct child,
+            or two entries share a `uri`.
+    """
+    scheme, netloc, parent_path = parse_directory_uri(uri)
+    seen_uris: set[str] = set()
+    prefix = parent_path.rstrip("/") + "/" if parent_path.rstrip("/") else "/"
+    for resource in result.resources:
+        child = urlsplit(resource.uri)
+        if not child.scheme or child.query or child.fragment:
+            raise ValueError(f"directory {uri!r} child has invalid URI {resource.uri!r}")
+        if child.scheme != scheme or child.netloc != netloc:
+            raise ValueError(f"resource {resource.uri!r} is not a child of directory {uri!r}")
+        relative = child.path.removeprefix(prefix)
+        if relative == child.path or not relative or "/" in relative or relative in (".", ".."):
+            raise ValueError(f"resource {resource.uri!r} is not a direct child of directory {uri!r}")
+        if resource.uri in seen_uris:
+            raise ValueError(f"directory {uri!r} contains a duplicate child {resource.uri!r}")
+        seen_uris.add(resource.uri)

mainsequence/server/fastapi.py

@@ -394,7 +394,9 @@ def install_mcp(app, mcp_app, *, lifespan):
     ``mcp_app`` is the server's ASGI application, answering Streamable HTTP at
     ``/mcp`` statelessly with JSON responses. ``lifespan`` is a zero-argument
     callable returning its async context manager. With the official MCP Python
-    SDK, pass ``mcp.streamable_http_app()`` and ``mcp.session_manager.run``.
+    SDK's ``MCPServer``, pass ``mcp.streamable_http_app(stateless_http=True,
+    json_response=True, transport_security=...)`` and ``mcp.session_manager.run``;
+    its skills come from ``mainsequence.server.mcp_skills`` (ADR 0039).
 
     Install request identity first. Tools read the caller with
     ``User.get_logged_user()`` and, on a requester-bound call, the person it

mainsequence/server/mcp_skills.py

@@ -0,0 +1,408 @@
+"""An application's Agent Skills served through the MCP Skills extension (ADR 0039).
+
+``skills_extension(directory)`` reads a directory of Agent Skills once and returns
+the official ``io.modelcontextprotocol/skills`` extension for the application's
+``MCPServer``. The extension answers ``skills/list`` and ``skills/get``, and every
+skill file is an ordinary resource served with the exact bytes its manifest
+digests. Needs the ``mcp`` extra.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import math
+import mimetypes
+import os
+import re
+import sys
+from pathlib import Path
+
+import yaml
+
+try:
+    from mcp.server.extension import ResourceBinding
+    from mcp.server.mcpserver.resources import BinaryResource, TextResource
+    from mcp.shared.exceptions import MCPError
+    from mcp_types.jsonrpc import INVALID_PARAMS
+    from pydantic import ValidationError
+except ImportError as exc:
+    raise ImportError(
+        "Serving skills needs the official MCP Python SDK 2.x: install mainsequence[mcp]."
+    ) from exc
+
+try:
+    from mcp.server.skills import Skills
+    from mcp.shared.skills import GetSkillResult, ListSkillsResult, Skill, SkillResource
+except ImportError:
+    # Until an mcp release contains the extension, its verbatim copy.
+    from ._mcp_skills_upstream.server import Skills
+    from ._mcp_skills_upstream.shared import (
+        GetSkillResult,
+        ListSkillsResult,
+        Skill,
+        SkillResource,
+    )
+
+# Content changes only with a new revision, and digests catch a stale entry.
+_TTL_MS = 300_000
+_MAX_FILES = 512
+_MAX_BYTES = 16 * 1024 * 1024
+_SKILL_MD = "SKILL.md"
+_NAME = re.compile(r"[a-z0-9]+(?:-[a-z0-9]+)*", flags=re.ASCII)
+_NAME_RULE = "1 to 64 characters of a-z, 0-9 and single hyphens, not at either end"
+# Unreserved URI characters only, so a file's URI never needs percent-encoding.
+_SEGMENT = re.compile(r"[A-Za-z0-9._~-]+", flags=re.ASCII)
+# Python's built-in table only, not the host's mime.types files.
+_MIME_TYPES = mimetypes.MimeTypes()
+_MIME_TYPES.add_type("text/markdown", ".md")
+
+
+class _Yaml11Loader(yaml.SafeLoader):
+    """PyYAML's safe loader: YAML 1.1, as hosts using PyYAML read frontmatter."""
+
+
+class _Yaml12Loader(yaml.SafeLoader):
+    """The safe loader with YAML 1.2 core schema scalars, as most other hosts read them."""
+
+
+def _mapping(loader, node):
+    """A mapping without repeated keys, which parsers resolve differently."""
+    seen = set()
+    for key, _ in node.value:
+        if isinstance(key, yaml.ScalarNode):
+            if key.value in seen:
+                raise yaml.constructor.ConstructorError(
+                    None, None, f"found duplicate key {key.value!r}", key.start_mark
+                )
+            seen.add(key.value)
+    return loader.construct_mapping(node, deep=True)
+
+
+def _int_12(loader, node):
+    value = loader.construct_scalar(node)
+    if value.startswith("0o"):
+        return int(value[2:], 8)
+    if value.startswith("0x"):
+        return int(value[2:], 16)
+    return int(value)
+
+
+_Yaml12Loader.yaml_implicit_resolvers = {}
+for _tag, _pattern, _first in (
+    ("null", r"^(?:~|null|Null|NULL|)$", ["~", "n", "N", ""]),
+    ("bool", r"^(?:true|True|TRUE|false|False|FALSE)$", list("tTfF")),
+    ("int", r"^(?:[-+]?[0-9]+|0o[0-7]+|0x[0-9a-fA-F]+)$", list("-+0123456789")),
+    (
+        "float",
+        r"^(?:[-+]?(?:\.[0-9]+|[0-9]+(?:\.[0-9]*)?)(?:[eE][-+]?[0-9]+)?"
+        r"|[-+]?\.(?:inf|Inf|INF)|\.(?:nan|NaN|NAN))$",
+        list("-+.0123456789"),
+    ),
+):
+    _Yaml12Loader.add_implicit_resolver(f"tag:yaml.org,2002:{_tag}", re.compile(_pattern), _first)
+_Yaml12Loader.add_constructor("tag:yaml.org,2002:int", _int_12)
+for _loader in (_Yaml11Loader, _Yaml12Loader):
+    _loader.add_constructor("tag:yaml.org,2002:map", _mapping)
+
+
+def _invalid(path, rule):
+    return ValueError(f"{path}: {rule}.")
+
+
+def _listing(path):
+    """A directory's entries in name order, without hidden ones."""
+    try:
+        with os.scandir(path) as entries:
+            return sorted(
+                (entry for entry in entries if not entry.name.startswith(".")),
+                key=lambda entry: entry.name,
+            )
+    except OSError as exc:
+        raise _invalid(path, f"cannot be read ({exc.strerror})") from None
+
+
+def _files(path, parts=()):
+    """Every regular file under a skill directory: its path parts and path, in name order."""
+    for entry in _listing(path):
+        entry_path = Path(entry.path)
+        if entry.is_symlink():
+            raise _invalid(entry_path, "is a symbolic link; a skill holds only regular files")
+        if not _SEGMENT.fullmatch(entry.name):
+            raise _invalid(entry_path, "a skill path may use only A-Z a-z 0-9 . _ ~ -")
+        if entry.is_dir(follow_symlinks=False):
+            yield from _files(entry_path, (*parts, entry.name))
+        elif entry.is_file(follow_symlinks=False):
+            yield (*parts, entry.name), entry_path
+        else:
+            raise _invalid(entry_path, "is not a regular file or directory")
+
+
+def _json_value(path, value, where):
+    if isinstance(value, dict):
+        for key, item in value.items():
+            if not isinstance(key, str):
+                raise _invalid(path, f"{where} has the key {key!r}, which is not a string")
+            _json_value(path, item, f"{where}.{key}")
+    elif isinstance(value, list):
+        for index, item in enumerate(value):
+            _json_value(path, item, f"{where}[{index}]")
+    elif isinstance(value, float):
+        if not math.isfinite(value):
+            raise _invalid(path, f"{where} is not a finite number")
+    elif value is not None and not isinstance(value, bool | int | str):
+        raise _invalid(path, f"{where} is a {type(value).__name__}, not a JSON value")
+
+
+def _difference(first, second, where):
+    """Where two parses of the same YAML disagree, or None."""
+    if type(first) is not type(second):
+        return where
+    if isinstance(first, dict):
+        if list(first) != list(second):
+            return where
+        pairs = [(first[key], second[key], f"{where}.{key}") for key in first]
+    elif isinstance(first, list):
+        if len(first) != len(second):
+            return where
+        pairs = [
+            (a, b, f"{where}[{index}]")
+            for index, (a, b) in enumerate(zip(first, second, strict=True))
+        ]
+    else:
+        return None if first == second else where
+    for a, b, inner in pairs:
+        found = _difference(a, b, inner)
+        if found:
+            return found
+    return None
+
+
+def _text(path, frontmatter, key, *, longest=None, required=False):
+    if key not in frontmatter:
+        if required:
+            raise _invalid(path, f"the frontmatter has no {key}")
+        return
+    value = frontmatter[key]
+    if not isinstance(value, str) or not value or (longest and len(value) > longest):
+        size = f"1 to {longest} characters" if longest else "a non-empty string"
+        raise _invalid(path, f"{key} must be {size}")
+
+
+def _frontmatter(path, data, name):
+    """The SKILL.md frontmatter as a JSON object that every YAML parser reads alike."""
+    try:
+        lines = data.decode("utf-8").split("\n")
+    except UnicodeDecodeError:
+        raise _invalid(path, "SKILL.md must be UTF-8") from None
+    if lines[0].removesuffix("\r") != "---":
+        raise _invalid(path, "SKILL.md must begin with a '---' line that opens its frontmatter")
+    end = next(
+        (index for index, line in enumerate(lines) if index and line.removesuffix("\r") == "---"),
+        None,
+    )
+    if end is None:
+        raise _invalid(path, "the frontmatter has no closing '---' line")
+    source = "\n".join(lines[1:end])
+    try:
+        as_yaml_11 = yaml.load(source, Loader=_Yaml11Loader)
+        frontmatter = yaml.load(source, Loader=_Yaml12Loader)
+    except yaml.YAMLError as exc:
+        raise _invalid(path, f"the frontmatter is not valid YAML ({exc})") from None
+    if not isinstance(frontmatter, dict):
+        raise _invalid(path, "the frontmatter must be a mapping")
+    _json_value(path, frontmatter, "frontmatter")
+    differs = _difference(as_yaml_11, frontmatter, "frontmatter")
+    if differs:
+        raise _invalid(
+            path,
+            f"{differs} reads differently under YAML 1.1 and YAML 1.2; quote it "
+            "(for example yes, no, on, off, dates and numbers with leading zeros)",
+        )
+    value = frontmatter.get("name")
+    if not (isinstance(value, str) and len(value) <= 64 and _NAME.fullmatch(value)):
+        raise _invalid(path, f"name must be {_NAME_RULE}")
+    if value != name:
+        raise _invalid(path, f"name {value!r} must equal its directory's name {name!r}")
+    _text(path, frontmatter, "description", longest=1024, required=True)
+    _text(path, frontmatter, "compatibility", longest=500)
+    _text(path, frontmatter, "license")
+    _text(path, frontmatter, "allowed-tools")
+    metadata = frontmatter.get("metadata", {})
+    if not isinstance(metadata, dict) or not all(isinstance(v, str) for v in metadata.values()):
+        raise _invalid(path, "metadata must map strings to strings")
+    return frontmatter
+
+
+def _resource(uri, data, *, name, description=None):
+    """A resource serving exactly ``data``: as text when it is UTF-8, else as a blob."""
+    guessed, encoding = _MIME_TYPES.guess_type(uri)
+    guessed = guessed if encoding is None else None
+    try:
+        text = data.decode("utf-8")
+    except UnicodeDecodeError:
+        mime_type = guessed or "application/octet-stream"
+        return BinaryResource(
+            uri=uri, name=name, description=description, mime_type=mime_type, data=data
+        )
+    mime_type = guessed or "text/plain"
+    return TextResource(uri=uri, name=name, description=description, mime_type=mime_type, text=text)
+
+
+def _skill(root, skill_path):
+    """One skill folder, read once: its entry and the resources serving its files."""
+    name = root.name
+    files, total = {}, 0
+    for parts, path in _files(root):
+        if parts[-1] == _SKILL_MD and len(parts) > 1:
+            raise _invalid(
+                path,
+                "a skill inside another skill is not served; "
+                "give it its own folder beside that skill or in a group folder",
+            )
+        try:
+            if len(files) == _MAX_FILES or total + path.stat().st_size > _MAX_BYTES:
+                raise _invalid(root, f"a skill may hold at most {_MAX_FILES} files and 16 MiB")
+            data = path.read_bytes()
+        except OSError as exc:
+            raise _invalid(path, f"cannot be read ({exc.strerror})") from None
+        total += len(data)
+        if total > _MAX_BYTES:
+            raise _invalid(root, f"a skill may hold at most {_MAX_FILES} files and 16 MiB")
+        files["/".join(parts)] = data
+    if _SKILL_MD not in files:
+        raise _invalid(root, "a skill folder must hold a SKILL.md")
+    frontmatter = _frontmatter(root / _SKILL_MD, files[_SKILL_MD], name)
+    order = [_SKILL_MD, *sorted(path for path in files if path != _SKILL_MD)]
+    uris = {path: f"skill://{skill_path}/{path}" for path in order}
+    try:
+        entry = Skill(
+            uri=uris[_SKILL_MD],
+            frontmatter=frontmatter,
+            resources=[
+                SkillResource(
+                    uri=uris[path],
+                    digest="sha256:" + hashlib.sha256(files[path]).hexdigest(),
+                    size=len(files[path]),
+                )
+                for path in order
+            ],
+        )
+    except ValidationError as exc:
+        raise _invalid(root, f"is not a valid Skills extension entry ({exc})") from None
+    resources = [
+        _resource(
+            uris[_SKILL_MD], files[_SKILL_MD], name=name, description=frontmatter["description"]
+        )
+    ]
+    resources += [
+        _resource(uris[path], files[path], name=path.rsplit("/", 1)[-1]) for path in order[1:]
+    ]
+    return entry, resources
+
+
+class _DirectorySkills(Skills):
+    """The official Skills extension, serving one skills directory read at startup."""
+
+    def __init__(self, catalog):
+        super().__init__(list_skills=self._list_skills, get_skill=self._get_skill)
+        self._skills = [entry for entry, _ in catalog]
+        self._by_uri = {entry.uri: entry for entry in self._skills}
+        self._resources = [
+            ResourceBinding(resource) for _, resources in catalog for resource in resources
+        ]
+
+    def resources(self):
+        return self._resources
+
+    async def _list_skills(self, ctx, params):
+        if params.cursor is not None:
+            raise MCPError(code=INVALID_PARAMS, message="Invalid cursor: skills/list has one page.")
+        return ListSkillsResult(skills=self._skills, ttl_ms=_TTL_MS, cache_scope="private")
+
+    async def _get_skill(self, ctx, params):
+        skill = self._by_uri.get(params.uri)
+        if skill is None:
+            raise MCPError(code=INVALID_PARAMS, message=f"No skill is served at {params.uri}")
+        return GetSkillResult(skill=skill, ttl_ms=_TTL_MS, cache_scope="private")
+
+
+def _skills_directory(directory, caller):
+    """``directory`` as an absolute path; a relative one is found above the calling module."""
+    path = Path(directory)
+    if path.is_absolute():
+        return path
+    start = Path(caller).resolve().parent if caller else Path.cwd()
+    for base in (start, *start.parents):
+        if (base / path).is_dir():
+            return base / path
+    raise ValueError(
+        f"No directory {path} was found in {start} or above it: a relative skills directory "
+        "is resolved from the module that calls skills_extension, up to the repository root."
+    )
+
+
+def _holds_skill_md(folder):
+    return any(
+        entry.name == _SKILL_MD and entry.is_file(follow_symlinks=False)
+        for entry in _listing(folder)
+    )
+
+
+def _collect(folder, prefix, catalog):
+    """The skills under ``folder``: a folder with a SKILL.md is a skill, one without groups."""
+    for entry in _listing(folder):
+        path = Path(entry.path)
+        if entry.is_symlink():
+            raise _invalid(path, "is a symbolic link; skills and group folders are directories")
+        if not entry.is_dir(follow_symlinks=False):
+            continue  # A file beside skills, such as a README, belongs to no skill.
+        # The first folder becomes the skill URI's host, so every name keeps the name rule.
+        if not (len(entry.name) <= 64 and _NAME.fullmatch(entry.name)):
+            raise _invalid(path, f"a skill or group folder's name must be {_NAME_RULE}")
+        segments = (*prefix, entry.name)
+        if _holds_skill_md(path):
+            catalog.append(_skill(path, "/".join(segments)))
+            continue
+        found = len(catalog)
+        _collect(path, segments, catalog)
+        if len(catalog) == found:
+            raise _invalid(
+                path,
+                "holds no SKILL.md and no skill: a skill folder needs a SKILL.md, "
+                "a group folder needs skills",
+            )
+
+
+def skills_extension(directory):
+    """The MCP Skills extension serving the Agent Skills in ``directory``.
+
+    Pass it when constructing the application's server,
+    ``MCPServer(name, extensions=[skills_extension(directory)])``. ``directory``
+    is the folder the application chooses for the skills it publishes, with any
+    name and place in the repository: an absolute path, or a path relative to the
+    repository, found from the calling module's directory upwards. Without the
+    extension the server exposes no skills, and nothing outside ``directory`` is
+    published.
+
+    A folder in ``directory`` that holds a ``SKILL.md`` is a skill; a folder
+    without one groups skills, and its path prefixes their URIs:
+    ``billing/refund-review/SKILL.md`` is ``skill://billing/refund-review/SKILL.md``.
+    Hidden names are skipped. Every file is read now: manifests digest the bytes
+    served, and a change on disk takes effect at the next start. A folder that
+    breaks the Agent Skills format or the extension's limits raises
+    ``ValueError`` naming the file and the rule. The server's ``skill://``
+    resources belong to this extension. See ADR 0039.
+    """
+    directory = _skills_directory(directory, sys._getframe(1).f_globals.get("__file__"))
+    if not directory.is_dir():
+        raise _invalid(directory, "the skills folder does not exist")
+    if _holds_skill_md(directory):
+        raise _invalid(directory, "pass the folder that contains the skills, not a skill")
+    catalog = []
+    _collect(directory, (), catalog)
+    if not catalog:
+        raise _invalid(directory, "the skills folder holds no skill")
+    return _DirectorySkills(sorted(catalog, key=lambda skill: skill[0].uri))
+
+
+__all__ = ["skills_extension"]

{mainsequence-9.0.22.dev65.dist-info → mainsequence-9.0.23.dev66.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mainsequence
-Version: 9.0.22.dev65
+Version: 9.0.23.dev66
 Summary: Main Sequence SDK
 Author-email: Main Sequence GmbH <dev@main-sequence.io>
 License-Expression: MIT
@@ -32,7 +32,7 @@ Requires-Dist: structlog
 Requires-Dist: typer
 Requires-Dist: urllib3>=2.7.0
 Provides-Extra: mcp
-Requires-Dist: mcp<2,>=1.28; extra == "mcp"
+Requires-Dist: mcp<3,>=2.3; extra == "mcp"
 Dynamic: license-file
 
 <p align="center">

{mainsequence-9.0.22.dev65.dist-info → mainsequence-9.0.23.dev66.dist-info}/RECORD

@@ -1,13 +1,13 @@
-agent_scaffold/AGENTS.md,sha256=-tK1zUP6j3QAlFXmwFVSNPfbzchZRJSzj26L-RU9Gis,6471
+agent_scaffold/AGENTS.md,sha256=Y_alRuPiX82gfu1ChPCOtBMvF44YiWr4wHxUq3hL43w,6529
 agent_scaffold/skills/a2a_sdk_execution/SKILL.md,sha256=NcwIQ1QgD4Ku0mG2Hb-Izee8p9fm9LTPHa6gDEWTOSQ,13200
-agent_scaffold/skills/application_surfaces/api_surfaces/SKILL.md,sha256=QvYPjIwRQ6lBcHo9OSf61GWv8sDAEOxLUUneOozEi34,21685
+agent_scaffold/skills/application_surfaces/api_surfaces/SKILL.md,sha256=gdoe860TEQyrMIVcN1L3Cf8lBYv3ErMkTNWcNrWjOKo,24427
 agent_scaffold/skills/mainsequence-inference/SKILL.md,sha256=yv8aAHLQ2FBBSWPIFadY7pGNTwtR-yiR_-UzaGRN9-g,12502
 agent_scaffold/skills/maintenance/bug_auditor/SKILL.md,sha256=CCKs7edyZ9RK-WtAgXJXucokJFXZxk8sRUe0_imFtu8,8610
-agent_scaffold/skills/maintenance/code_repository_maintenance/SKILL.md,sha256=pPsZaERlfokSJ6b6vLjpA5U0KuKxbOFzzcxOVW_ikiI,17935
+agent_scaffold/skills/maintenance/code_repository_maintenance/SKILL.md,sha256=vJ7ksmqvgjdQGS3QYGb6oD7HaRi5LNIo1PYKTEV_eyU,18283
 agent_scaffold/skills/maintenance/metatables_transition/SKILL.md,sha256=PisgpytcksJnfZMS6aiPCmahsT3fm8DIwk_cefXA2qU,3759
 agent_scaffold/skills/platform_operations/access_control_and_sharing/SKILL.md,sha256=rB_52v63tR5dptYYviaAHzYmnhLPgWsex2lpZkYDDuk,14765
 agent_scaffold/skills/platform_operations/orchestration_and_releases/SKILL.md,sha256=_84nnJKl_w-JrcbiTIairbFf9ptoQvW5Y1kMxn_XzkU,16871
-agent_scaffold/skills/sdk_code_repository_execution/SKILL.md,sha256=zly7MheB-Sjd0x6l_oPCOTBqkL2E4SSXwTlfSwdIPfQ,10196
+agent_scaffold/skills/sdk_code_repository_execution/SKILL.md,sha256=_CzYF7p0slC8m9oeKgGbWjCjvXW607SCCFC8dClujtE,10254
 mainsequence/__init__.py,sha256=70CbIo7ZG1mzi5uwkqDtVESunBE0RanHjeFg4ptfsA0,385
 mainsequence/__main__.py,sha256=KuAP69uduS2ImrPIgNMzbGBRepZzjqvUONu5vFh4v4A,176
 mainsequence/_request_identity.py,sha256=vsbnQeJ9ycRB2p8oFTUxfPkzDh7-SBQ5Pxzn04pjqVM,4183
@@ -24,7 +24,7 @@ mainsequence/scaffold_skills.py,sha256=k0V6eKC5AwbHr9wB9UGMJNF-8eJ0_1izF4-BU01KH
 mainsequence/cli/__init__.py,sha256=sMWTnomCaISjnureLuXFRqOzkH2Y77uYEivsd-M6_8Y,28
 mainsequence/cli/api.py,sha256=u3vjwJ5w_u4o76ufkePXKIh6dixOHDok_r8Os0iA_04,128865
 mainsequence/cli/browser_auth.py,sha256=Vb5MBOnPC05HLZzVNUDODobJ_p5wEIzH_h8rIlpShlE,9984
-mainsequence/cli/cli.py,sha256=8EM0j2rRvGX-t1ByfkVD8HUUx5QgK1BiurCImZfjqYI,269846
+mainsequence/cli/cli.py,sha256=4t0vf-gi_Ez4MjvAEOAfGYwVuSxb1HECRRyaruQvp6M,269468
 mainsequence/cli/code_repository_status.py,sha256=SHEnU8YSWFowPG6dEdE4Yd8CS1tIcJSE1MXFLfvD3Os,5975
 mainsequence/cli/config.py,sha256=TJYnM11kg5pH2O7AGWFLpNEkC9UEu0g7k2RLjhAHCzo,45724
 mainsequence/cli/docker_utils.py,sha256=eAnp9MI042cHWwKasA5IF2I7INL3A6tV2JX-cSIe7rc,10687
@@ -53,10 +53,14 @@ mainsequence/instrumentation/__init__.py,sha256=J_9XmfjprElvz0u2t9rTyJT0kFdyKpxd
 mainsequence/instrumentation/utils.py,sha256=b-ihjSioAepeLfMpudM2SqCtvnxMqIXileHx3klBCQU,3377
 mainsequence/server/__init__.py,sha256=BHUAhtdWPDRdxX07NYO_6wrBv5mf0GsXflecO52PmUc,73
 mainsequence/server/caller_assertions.py,sha256=7OEgPXxiGv-P98K6-XVKFSiNcYZkEFDmehBc_oJKkFM,12563
-mainsequence/server/fastapi.py,sha256=ZMtazH8ZN2C82uTkBtl0UQdx6F9mlCHD1HurgZQdHbU,18512
-mainsequence-9.0.22.dev65.dist-info/licenses/LICENSE,sha256=b6Ecsk8wjsEby3lbSzdljR6hHiFGHBizt9iWV2p1c_I,1074
-mainsequence-9.0.22.dev65.dist-info/METADATA,sha256=iVI-Dap3Gl5LvTSpmppG5uR9Q8vMKnRauM7J-GURhew,7467
-mainsequence-9.0.22.dev65.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-mainsequence-9.0.22.dev65.dist-info/entry_points.txt,sha256=XGAOq3-mF2lWWpeRJvoaWyMarRcK167mH1g124aGdUs,88
-mainsequence-9.0.22.dev65.dist-info/top_level.txt,sha256=BFeblM_Q9q0cUWBvTxnfWcWQEHtf5XZi9nOS-Gdfwus,28
-mainsequence-9.0.22.dev65.dist-info/RECORD,,
+mainsequence/server/fastapi.py,sha256=jdLWtD5roG7kLzZgdsezhDEXVz3mCnpY6rqc2Qio1U4,18667
+mainsequence/server/mcp_skills.py,sha256=-krRwAHCAMipScgGJ19uVkzznhTop1Nz4C_wRY1GUpw,16690
+mainsequence/server/_mcp_skills_upstream/__init__.py,sha256=px283qBMf3z1nxCfN3WHrH9v8Y8jOb1xoBqZMRZcaD8,2694
+mainsequence/server/_mcp_skills_upstream/server.py,sha256=laHsfpoaYX3LcwQ04-GN7r0_C63fG6CzyXDci2rmbHE,7695
+mainsequence/server/_mcp_skills_upstream/shared.py,sha256=JmnX9PoLoyi93nBYnUEPWCdPXor_nQHjHptQDXpFzPs,11978
+mainsequence-9.0.23.dev66.dist-info/licenses/LICENSE,sha256=b6Ecsk8wjsEby3lbSzdljR6hHiFGHBizt9iWV2p1c_I,1074
+mainsequence-9.0.23.dev66.dist-info/METADATA,sha256=wt6keqLEOGf1mggNThtqGuZ-O6fh7s_6SnT0O-9H51k,7466
+mainsequence-9.0.23.dev66.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+mainsequence-9.0.23.dev66.dist-info/entry_points.txt,sha256=XGAOq3-mF2lWWpeRJvoaWyMarRcK167mH1g124aGdUs,88
+mainsequence-9.0.23.dev66.dist-info/top_level.txt,sha256=BFeblM_Q9q0cUWBvTxnfWcWQEHtf5XZi9nOS-Gdfwus,28
+mainsequence-9.0.23.dev66.dist-info/RECORD,,