mainsequence 9.0.22__tar.gz → 9.0.23.dev66__tar.gz

{mainsequence-9.0.22 → mainsequence-9.0.23.dev66}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mainsequence
-Version: 9.0.22
+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 → mainsequence-9.0.23.dev66}/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`

{mainsequence-9.0.22 → mainsequence-9.0.23.dev66}/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.

{mainsequence-9.0.22 → mainsequence-9.0.23.dev66}/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`:
 

{mainsequence-9.0.22 → mainsequence-9.0.23.dev66}/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-9.0.22 → mainsequence-9.0.23.dev66}/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-9.0.23.dev66/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-9.0.23.dev66/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