mainsequence 9.0.15.dev57__py3-none-any.whl → 9.0.16.dev59__py3-none-any.whl

agent_scaffold/skills/application_surfaces/api_surfaces/SKILL.md

@@ -211,6 +211,16 @@ what people are told:
 See also
 [Requester-bound calls](https://mainsequence-sdk.github.io/mainsequence-sdk/knowledge/fastapi/#requester-bound-calls).
 
+### 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
+`User.get_requester()` exactly like REST handlers; admission to the release
+does not authorize every tool. See
+[Serving MCP](https://mainsequence-sdk.github.io/mainsequence-sdk/knowledge/fastapi/#serving-mcp).
+
 ### Public provider callbacks and webhooks
 
 An external OAuth redirect or webhook cannot supply a Main Sequence Bearer token.

mainsequence/client/models_helpers.py

@@ -822,6 +822,34 @@ class ResourceReleaseRuntimeAccess(BasePydanticModel):
     access: dict[str, Any] | None = Field(default=None, repr=False)
 
 
+class ResourceReleaseMcpConnection(BasePydanticModel):
+    """How to connect to the MCP endpoint of a FastAPI release's active revision."""
+
+    url: str = Field(
+        ...,
+        description="Public MCP endpoint: the release URL plus `/mcp`.",
+        examples=["https://prices.example.test/mcp"],
+    )
+    transport: OpenValueSet[Literal["streamable-http"]] = Field(
+        ...,
+        description=(
+            "MCP transport of the endpoint. A value this SDK does not declare is kept "
+            "but is not a transport to connect with."
+        ),
+        examples=["streamable-http"],
+    )
+    resource_metadata_url: str | None = Field(
+        None,
+        description="OAuth protected-resource metadata URL the endpoint's challenge points to.",
+    )
+    organization_environment_uid: str | None = Field(
+        None, description="Public UID of the connection's Organization Environment."
+    )
+    active_revision_uid: str | None = Field(
+        None, description="Public UID of the revision that advertises the endpoint."
+    )
+
+
 class ResourceRelease(
     CurrentCodeRepositoryBranchCollectionMixin,
     EnvironmentLogSearchMixin,
@@ -853,6 +881,7 @@ class ResourceRelease(
         "resource__uid": ["exact", "in"],
         "related_job__uid": ["exact", "in"],
         "release_kind": ["exact", "in"],
+        "mcp_available": ["exact"],
     }
     FILTER_VALUE_NORMALIZERS: ClassVar[dict[str, str]] = {
         "uid": "uid",
@@ -861,6 +890,7 @@ class ResourceRelease(
         "resource__uid": "uid",
         "related_job__uid": "uid",
         "release_kind": "str",
+        "mcp_available": "bool",
     }
 
     @classmethod
@@ -1005,6 +1035,23 @@ class ResourceRelease(
         ),
         examples=["88888888-8888-4888-8888-888888888888"],
     )
+    mcp_enabled: bool = Field(
+        False,
+        title="MCP Enabled",
+        description=(
+            "Desired MCP capability of a FastAPI release, applied by its next successful "
+            "deployment. False when the response does not carry it."
+        ),
+        examples=[True],
+    )
+    mcp_connection: ResourceReleaseMcpConnection | None = Field(
+        None,
+        title="MCP Connection",
+        description=(
+            "MCP endpoint of the active MCP-enabled revision; None when no active revision "
+            "advertises one. An advertised capability, not a health check."
+        ),
+    )
     observability: ObservabilityLinks | None = Field(
         default=None,
         description="Backend-owned runtime observability and related-history capabilities.",

mainsequence/server/fastapi.py

@@ -6,12 +6,18 @@ import asyncio
 import json
 import os
 import re
-from contextlib import contextmanager
+from contextlib import asynccontextmanager, contextmanager
+from urllib.parse import urlsplit
 from uuid import UUID
 
 import requests
 
-from mainsequence._request_identity import _reads_as_caller, _request_scope
+from mainsequence._request_identity import (
+    RequestIdentityError,
+    _get_request_identity,
+    _reads_as_caller,
+    _request_scope,
+)
 from mainsequence.client.models_user import RequestUserIdentity
 
 from .caller_assertions import (
@@ -296,4 +302,154 @@ def reads_as_caller():
         yield
 
 
-__all__ = ["install_request_identity", "reads_as_caller"]
+_MCP_INSTALLATION = "mainsequence_mcp"
+_MCP_PATH = "/mcp"
+_WILDCARD_ORIGIN = re.compile(r"(https?)://\*\.([a-z0-9.-]+)(?::([0-9]{1,5}))?", flags=re.ASCII)
+
+
+def _mcp_allowed_origins():
+    """The release's public origin and its CORS origins, read once at installation."""
+    entries = [os.environ.get("FASTAPI_PUBLIC_BASE_URL", "")]
+    entries += os.environ.get("FASTAPI_CORS_ALLOW_ORIGINS", "").split(",")
+    exact, patterns = set(), []
+    for entry in entries:
+        entry = entry.strip().rstrip("/").lower()
+        wildcard = _WILDCARD_ORIGIN.fullmatch(entry)
+        if wildcard:
+            scheme, host, port = wildcard.groups()
+            pattern = rf"{scheme}://[a-z0-9-]+\.{re.escape(host)}"
+            patterns.append(re.compile(pattern + (rf":{port}" if port else ""), flags=re.ASCII))
+            continue
+        parts = urlsplit(entry)
+        if parts.scheme in {"http", "https"} and parts.netloc and "*" not in parts.netloc:
+            exact.add(f"{parts.scheme}://{parts.netloc}")
+    return frozenset(exact), tuple(patterns)
+
+
+def _mcp_conflicts(routes, *, installed=None):
+    for route in routes:
+        path = getattr(route, "path", None)
+        if route is not installed and isinstance(path, str):
+            if path == _MCP_PATH or path.startswith(_MCP_PATH + "/"):
+                raise RuntimeError(f"Route {path} conflicts with the MCP endpoint at {_MCP_PATH}.")
+
+
+async def _reply(send, status, detail, headers=()):
+    await send(
+        {
+            "type": "http.response.start",
+            "status": status,
+            "headers": [
+                (b"content-type", b"application/json"),
+                (b"cache-control", b"no-store"),
+                *headers,
+            ],
+        }
+    )
+    await send({"type": "http.response.body", "body": json.dumps({"detail": detail}).encode()})
+
+
+class _McpEndpoint:
+    """Admit authenticated POSTs from an allowed Origin to the application's MCP app."""
+
+    def __init__(self, app, *, allowed_origins):
+        self.app = app
+        self.exact_origins, self.origin_patterns = allowed_origins
+
+    def _origin_allowed(self, origin):
+        origin = origin.strip().rstrip("/").lower()
+        return origin in self.exact_origins or any(
+            pattern.fullmatch(origin) for pattern in self.origin_patterns
+        )
+
+    async def __call__(self, scope, receive, send):
+        if scope.get("method") != "POST":
+            # Stateless profile: no standalone GET stream and no session to delete.
+            await _reply(send, 405, "Method Not Allowed.", headers=[(b"allow", b"POST")])
+            return
+        origins = [value for key, value in scope.get("headers", ()) if key.lower() == b"origin"]
+        if len(origins) > 1 or (origins and not self._origin_allowed(origins[0].decode("latin-1"))):
+            await _reply(send, 403, "Origin is not allowed.")
+            return
+        try:
+            _get_request_identity()
+        except RequestIdentityError:
+            await _reply(send, 401, "Authenticated request user could not be resolved.")
+            return
+        # Stateless profile: a session identifier never selects server-side state.
+        scope = dict(scope)
+        scope["headers"] = [
+            (key, value)
+            for key, value in scope.get("headers", ())
+            if key.lower() != b"mcp-session-id"
+        ]
+        await self.app(scope, receive, send)
+
+
+def install_mcp(app, mcp_app, *, lifespan):
+    """Serve an application-owned MCP server at ``/mcp`` inside request identity.
+
+    ``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``.
+
+    Install request identity first. Tools read the caller with
+    ``User.get_logged_user()`` and, on a requester-bound call, the person it
+    works for with ``User.get_requester()``. Only authenticated POSTs reach the
+    server; other methods answer 405 and an ``Origin`` other than the release's
+    own or its CORS origins answers 403. See ADR 0038.
+    """
+    from starlette.routing import Route
+
+    identity = getattr(app.state, _INSTALLATION, None)
+    if not isinstance(identity, dict) or identity.get("installed") is not True:
+        raise RuntimeError(
+            "Install request identity before MCP: call install_request_identity(app)."
+        )
+    if getattr(app.state, _MCP_INSTALLATION, None) is not None:
+        raise RuntimeError("MCP is already installed.")
+    if any(
+        path == _MCP_PATH or path.startswith(_MCP_PATH + "/")
+        for _, path in identity.get("public_ingress", ())
+    ):
+        raise RuntimeError(f"{_MCP_PATH} cannot be public ingress; MCP requests are authenticated.")
+    if not callable(mcp_app) or not callable(lifespan):
+        raise TypeError("install_mcp needs the MCP ASGI app and its lifespan factory.")
+    _mcp_conflicts(app.router.routes)
+
+    route = Route(
+        _MCP_PATH,
+        endpoint=_McpEndpoint(mcp_app, allowed_origins=_mcp_allowed_origins()),
+        include_in_schema=False,
+    )
+    app.router.routes.insert(0, route)
+    application_lifespan = app.router.lifespan_context
+    started = False
+
+    @asynccontextmanager
+    async def composed_lifespan(application):
+        nonlocal started
+        if started:
+            raise RuntimeError("The MCP lifespan runs once per application.")
+        started = True
+        _mcp_conflicts(app.router.routes, installed=route)
+        async with application_lifespan(application) as state:
+            async with lifespan():
+                yield state
+
+    app.router.lifespan_context = composed_lifespan
+    setattr(
+        app.state,
+        _MCP_INSTALLATION,
+        {
+            "installed": True,
+            "path": _MCP_PATH,
+            "transport": "streamable-http",
+            "stateless": True,
+            "request_identity": True,
+        },
+    )
+
+
+__all__ = ["install_mcp", "install_request_identity", "reads_as_caller"]

{mainsequence-9.0.15.dev57.dist-info → mainsequence-9.0.16.dev59.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mainsequence
-Version: 9.0.15.dev57
+Version: 9.0.16.dev59
 Summary: Main Sequence SDK
 Author-email: Main Sequence GmbH <dev@main-sequence.io>
 License-Expression: MIT
@@ -31,6 +31,8 @@ Requires-Dist: requests>=2.33.0
 Requires-Dist: structlog
 Requires-Dist: typer
 Requires-Dist: urllib3>=2.7.0
+Provides-Extra: mcp
+Requires-Dist: mcp<2,>=1.28; extra == "mcp"
 Dynamic: license-file
 
 <p align="center">

{mainsequence-9.0.15.dev57.dist-info → mainsequence-9.0.16.dev59.dist-info}/RECORD

@@ -1,6 +1,6 @@
 agent_scaffold/AGENTS.md,sha256=-tK1zUP6j3QAlFXmwFVSNPfbzchZRJSzj26L-RU9Gis,6471
 agent_scaffold/skills/a2a_sdk_execution/SKILL.md,sha256=NKtcXibE8TxZzKzz1KzJ2cVZ_EeuJJkb660U6wLvZ3s,11809
-agent_scaffold/skills/application_surfaces/api_surfaces/SKILL.md,sha256=HODSJCgm6Wdpd-nBsbMCb4Ls67P7DqK-j_S4GLFdfIk,19087
+agent_scaffold/skills/application_surfaces/api_surfaces/SKILL.md,sha256=1lPnRtm6qVaqOu_lJkk8V7HJ1NjKsp0hb8LB9xwzPOI,19608
 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
@@ -44,7 +44,7 @@ mainsequence/client/exceptions.py,sha256=xx2L4l3OMNsTybbYkiTKK398ahnutEascM0It35
 mainsequence/client/github_issues.py,sha256=pSTUw3UPrmE6wqnpoJctartTaNSq6iu6PQRrd8hip6I,14568
 mainsequence/client/inference.py,sha256=tYKHRxLR6mA5iLmgd3qURwweWc2OPQuw0__tD3LQgSI,7748
 mainsequence/client/models_foundry.py,sha256=JwQdPLDSO4dZI-KC0SUdmN6izmNIKMb9IzZlYXy0Mig,36488
-mainsequence/client/models_helpers.py,sha256=nlbHuQAylTOHAZOq4ltJQp6QvC3NW_kw7tZFosGc5rM,47311
+mainsequence/client/models_helpers.py,sha256=CQRjBjx3DsREJLRk0vqFsC-Dcll5lUP2ofu6e5UMvhk,49051
 mainsequence/client/models_user.py,sha256=tOngVHxkoEeV-kLLK3cmfESN9gzyXrLlZHFNGVv014Q,45241
 mainsequence/client/observability.py,sha256=_WrDKCaNk_TXmKElKCXC1inork6Exxxe8FRY4m1GI9s,16008
 mainsequence/client/utils.py,sha256=C0h0U-fOBZw3UxIwHcBTLf8CDClAOatf_oRgjvqFth4,31637
@@ -53,10 +53,10 @@ 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=Ix94Kvei31lKb861q6LqKzcB5H1mWnuH_wYwpXEKS1E,12351
-mainsequence/server/fastapi.py,sha256=1l5uIx4jqw092NJwXaA57nI6sAt9a_zXzJKgD4I1NRk,12090
-mainsequence-9.0.15.dev57.dist-info/licenses/LICENSE,sha256=b6Ecsk8wjsEby3lbSzdljR6hHiFGHBizt9iWV2p1c_I,1074
-mainsequence-9.0.15.dev57.dist-info/METADATA,sha256=AxjdXTfjT_TVHTrYRdQljivI9c15SpW9jhtZWyKUzgc,7403
-mainsequence-9.0.15.dev57.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-mainsequence-9.0.15.dev57.dist-info/entry_points.txt,sha256=XGAOq3-mF2lWWpeRJvoaWyMarRcK167mH1g124aGdUs,88
-mainsequence-9.0.15.dev57.dist-info/top_level.txt,sha256=BFeblM_Q9q0cUWBvTxnfWcWQEHtf5XZi9nOS-Gdfwus,28
-mainsequence-9.0.15.dev57.dist-info/RECORD,,
+mainsequence/server/fastapi.py,sha256=jB0EpxTqBw6sChtIGdPHGkC4I2MdV1V0uEd34NLvGQs,18267
+mainsequence-9.0.16.dev59.dist-info/licenses/LICENSE,sha256=b6Ecsk8wjsEby3lbSzdljR6hHiFGHBizt9iWV2p1c_I,1074
+mainsequence-9.0.16.dev59.dist-info/METADATA,sha256=k4UZhJV0jqz8epWSzNgtFkvEMOdf2mTJruMTCZNBn78,7467
+mainsequence-9.0.16.dev59.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+mainsequence-9.0.16.dev59.dist-info/entry_points.txt,sha256=XGAOq3-mF2lWWpeRJvoaWyMarRcK167mH1g124aGdUs,88
+mainsequence-9.0.16.dev59.dist-info/top_level.txt,sha256=BFeblM_Q9q0cUWBvTxnfWcWQEHtf5XZi9nOS-Gdfwus,28
+mainsequence-9.0.16.dev59.dist-info/RECORD,,