hyperforge 1.0.0.post437__tar.gz → 1.0.0.post447__tar.gz

{hyperforge-1.0.0.post437 → hyperforge-1.0.0.post447}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hyperforge
-Version: 1.0.0.post437
+Version: 1.0.0.post447
 Summary: Agentic Framework for Orchestrated Runtime, Governance, and Execution
 Author: AI Data Team
 Author-email: AI Data Team <learning@nuclia.com>
@@ -23,6 +23,7 @@ Requires-Dist: aiodns
 Requires-Dist: anyio>=4.15.1
 Requires-Dist: httpx>=0.28.1,<0.29
 Requires-Dist: httpcore>=1.0.9,<1.1
+Requires-Dist: urllib3>=2.8.0,<3
 Requires-Dist: jinja2
 Requires-Dist: jsonschema
 Requires-Dist: restrictedpython>=8.5
@@ -132,6 +133,30 @@ All settings are provided through environment variables consumed by Pydantic `Ba
 | `LOAD_MODULES` | Comma-separated list of agent package modules to load at startup |
 | `NUCLIA_ZONE` | Nuclia zone (default `arag`) |
 | `NUCLIA_PUBLIC_URL` | Public Nuclia URL template (default `https://{zone}.nuclia.com`) |
+| `MCP_MAX_SERVERS` | Maximum cached MCP managers (default `100`) |
+| `MCP_MAX_SESSIONS_PER_SERVER` | Maximum concurrent connections per MCP manager (default `100`) |
+| `MCP_SESSION_IDLE_TTL_SECONDS` | Idle lifetime of each MCP connection and cached manager (default `1800`) |
+
+### MCP connections
+
+API and standalone applications expose their configured MCP limits through the
+typed `mcp_settings` property, without falling back to session-server settings.
+
+Multiple clients can use the same `/api/v1/agent/{agent_id}/session/{session}/mcp`
+URL, including `session/ephemeral`. Each initialization receives its own
+`Mcp-Session-Id`; subsequent requests and DELETE must include that ID. DELETE
+only terminates the requested connection. Missing IDs on GET or DELETE return 400;
+unknown or expired IDs return 404. Clients should initialize a new connection
+after a 404, not reuse the expired ID.
+
+Managers whose last connection has closed can be evicted immediately when the
+pool is full.
+
+MCP transports remain process-local. Multi-replica deployments must route an
+authenticated user's initialization and subsequent requests to the same API
+replica using a stable, trusted identity header. Hashing only `Mcp-Session-Id`
+does not work because initialization has no session ID. Pod restarts or changes
+to the replica set can still require reinitialization.
 
 ### Standalone A2A
 

{hyperforge-1.0.0.post437 → hyperforge-1.0.0.post447}/README.md

@@ -82,6 +82,30 @@ All settings are provided through environment variables consumed by Pydantic `Ba
 | `LOAD_MODULES` | Comma-separated list of agent package modules to load at startup |
 | `NUCLIA_ZONE` | Nuclia zone (default `arag`) |
 | `NUCLIA_PUBLIC_URL` | Public Nuclia URL template (default `https://{zone}.nuclia.com`) |
+| `MCP_MAX_SERVERS` | Maximum cached MCP managers (default `100`) |
+| `MCP_MAX_SESSIONS_PER_SERVER` | Maximum concurrent connections per MCP manager (default `100`) |
+| `MCP_SESSION_IDLE_TTL_SECONDS` | Idle lifetime of each MCP connection and cached manager (default `1800`) |
+
+### MCP connections
+
+API and standalone applications expose their configured MCP limits through the
+typed `mcp_settings` property, without falling back to session-server settings.
+
+Multiple clients can use the same `/api/v1/agent/{agent_id}/session/{session}/mcp`
+URL, including `session/ephemeral`. Each initialization receives its own
+`Mcp-Session-Id`; subsequent requests and DELETE must include that ID. DELETE
+only terminates the requested connection. Missing IDs on GET or DELETE return 400;
+unknown or expired IDs return 404. Clients should initialize a new connection
+after a 404, not reuse the expired ID.
+
+Managers whose last connection has closed can be evicted immediately when the
+pool is full.
+
+MCP transports remain process-local. Multi-replica deployments must route an
+authenticated user's initialization and subsequent requests to the same API
+replica using a stable, trusted identity header. Hashing only `Mcp-Session-Id`
+does not work because initialization has no session ID. Pod restarts or changes
+to the replica set can still require reinitialization.
 
 ### Standalone A2A
 

{hyperforge-1.0.0.post437 → hyperforge-1.0.0.post447}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "hyperforge"
-version = "1.0.0.post437"
+version = "1.0.0.post447"
 description = "Agentic Framework for Orchestrated Runtime, Governance, and Execution"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -30,6 +30,7 @@ dependencies = [
     "anyio>=4.15.1",
     "httpx>=0.28.1,<0.29",
     "httpcore>=1.0.9,<1.1",
+    "urllib3>=2.8.0,<3",
     "jinja2",
     "jsonschema",
     "RestrictedPython>=8.5",

{hyperforge-1.0.0.post437 → hyperforge-1.0.0.post447}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "hyperforge"
-version = "1.0.0.post437"
+version = "1.0.0.post447"
 authors = [{ name = "AI Data Team", email = "learning@nuclia.com" }]
 description = "Agentic Framework for Orchestrated Runtime, Governance, and Execution"
 readme = "README.md"
@@ -31,6 +31,7 @@ dependencies = [
     "anyio>=4.15.1",
     "httpx>=0.28.1,<0.29",
     "httpcore>=1.0.9,<1.1",
+    "urllib3>=2.8.0,<3",
     "jinja2",
     "jsonschema",
     "RestrictedPython>=8.5",

{hyperforge-1.0.0.post437 → hyperforge-1.0.0.post447}/src/hyperforge/api/app.py

@@ -83,6 +83,10 @@ class HTTPApplication(FastAPI):
             for extra_middleware in self.extra_middlewares:
                 self.add_middleware(extra_middleware)
 
+    @property
+    def mcp_settings(self) -> Settings:
+        return self.settings
+
     async def startup(self) -> None:
         GLOBAL_REGISTRY.clear()
         await setup_telemetry(SERVICE_NAME)

{hyperforge-1.0.0.post437 → hyperforge-1.0.0.post447}/src/hyperforge/api/mcp_server_pool.py

@@ -1,5 +1,4 @@
 import asyncio
-import json
 import time
 from collections.abc import Awaitable, Callable
 from typing import Any
@@ -9,17 +8,25 @@ from fastapi import HTTPException
 from mcp.server.streamable_http import MCP_SESSION_ID_HEADER
 from mcp.server.streamable_http_manager import StreamableHTTPSessionManager
 from starlette.requests import Request
+from starlette.responses import Response
+from starlette.types import Message, Receive, Scope, Send
+
+from hyperforge.api import logger
 
 MCPServerKey = tuple[str, str, str, str, str]
 MCPServerFactory = Callable[[], Awaitable["ManagedMCPServer"]]
 
 
 class ManagedMCPServer:
-    def __init__(self, manager: StreamableHTTPSessionManager):
+    def __init__(self, manager: StreamableHTTPSessionManager, max_sessions: int = 100):
         self.manager = manager
         self.started = asyncio.Event()
         self.task: asyncio.Task[None] | None = None
-        self.session_created = False
+        self.active_sessions = 0
+        self.max_sessions = max_sessions
+        self._session_creation_lock = anyio.Lock()
+        self._session_closed = anyio.Event()
+        self.has_been_leased = False
         self.active_requests = 0
         self.last_used = time.monotonic()
 
@@ -56,6 +63,7 @@ class ManagedMCPServer:
             await asyncio.gather(self.task, return_exceptions=True)
 
     def reserve_request(self) -> None:
+        self.has_been_leased = True
         self.active_requests += 1
         self.last_used = time.monotonic()
 
@@ -65,26 +73,42 @@ class ManagedMCPServer:
         self.active_requests -= 1
         self.last_used = time.monotonic()
 
-    def accept_request(self, request: Request) -> bool:
-        if request.headers.get(MCP_SESSION_ID_HEADER):
-            return True
-        if self.session_created:
-            return False
-        self.session_created = True
-        return True
-
-    def is_reinitialization(self, request: Request, body: bytes) -> bool:
-        if (
-            not self.session_created
-            or request.method != "POST"
-            or request.headers.get(MCP_SESSION_ID_HEADER)
-        ):
-            return False
-        try:
-            message = json.loads(body)
-        except (json.JSONDecodeError, UnicodeDecodeError):
-            return False
-        return isinstance(message, dict) and message.get("method") == "initialize"
+    def release_session(self) -> None:
+        self.active_sessions -= 1
+        self._session_closed.set()
+        self._session_closed = anyio.Event()
+
+    async def handle_request(self, scope: Scope, receive: Receive, send: Send) -> None:
+        request = Request(scope)
+        if request.method == "POST" and not request.headers.get(MCP_SESSION_ID_HEADER):
+            async with self._session_creation_lock:
+                if self.active_sessions >= self.max_sessions:
+                    response = Response(
+                        "MCP session capacity is exhausted", status_code=503
+                    )
+                    await response(scope, receive, send)
+                    return
+                await self.manager.handle_request(scope, receive, send)
+        elif request.method == "DELETE":
+            async with self._session_creation_lock:
+                session_closed = self._session_closed
+                status: int | None = None
+
+                async def observe_send(message: Message) -> None:
+                    nonlocal status
+                    if message["type"] == "http.response.start":
+                        status = message["status"]
+                    await send(message)
+
+                await self.manager.handle_request(scope, receive, observe_send)
+                if status == 200:
+                    await session_closed.wait()
+                    # SDK 1.x retains explicitly terminated transports.
+                    session_id = request.headers["mcp-session-id"]
+                    self.manager._server_instances.pop(session_id, None)
+                    self.manager._session_owners.pop(session_id, None)
+        else:
+            await self.manager.handle_request(scope, receive, send)
 
 
 class MCPRequestLease:
@@ -109,7 +133,7 @@ class MCPServerPool:
         self._idle_ttl_seconds = idle_ttl_seconds
         self._startup_timeout_seconds = startup_timeout_seconds
         self._servers: dict[MCPServerKey, ManagedMCPServer] = {}
-        self._creating: dict[MCPServerKey, asyncio.Task[Any]] = {}
+        self._creating: dict[MCPServerKey, asyncio.Task[ManagedMCPServer]] = {}
         self._retired_tasks: set[asyncio.Task[Any]] = set()
         self._lock = anyio.Lock()
         self._shutting_down = False
@@ -123,10 +147,6 @@ class MCPServerPool:
         body: bytes,
         factory: MCPServerFactory,
     ) -> MCPRequestLease:
-        current_task = asyncio.current_task()
-        if current_task is None:
-            raise RuntimeError("MCP request task is unavailable")
-
         stale_server = None
         async with self._lock:
             self._ensure_running()
@@ -139,28 +159,38 @@ class MCPServerPool:
                 and time.monotonic() - server.last_used >= self._idle_ttl_seconds
             ):
                 stale_server = self._servers.pop(key)
-                stale_server.close()
+                self._retire_server(stale_server)
                 server = None
-            if server is not None and server.is_reinitialization(request, body):
-                if server.active_requests:
-                    raise HTTPException(
-                        status_code=409,
-                        detail="MCP session is still active for this path",
-                    )
-                stale_server = self._servers.pop(key)
-                stale_server.close()
-                server = None
-
             if server is not None:
-                return self._lease(server, request)
-            if key in self._creating:
+                return self._lease(server)
+            if request.headers.get(MCP_SESSION_ID_HEADER):
+                raise HTTPException(status_code=404, detail="MCP session not found")
+            if request.method != "POST":
+                raise HTTPException(status_code=400, detail="Missing Mcp-Session-Id")
+            creating_task = self._creating.get(key)
+            if creating_task is None:
+                self._reserve_capacity()
+                creating_task = asyncio.create_task(
+                    self._create_server(key, factory, stale_server)
+                )
+                self._creating[key] = creating_task
+                creating_task.add_done_callback(self._log_creation_failure)
+
+        created = await asyncio.shield(creating_task)
+        async with self._lock:
+            self._ensure_running()
+            if self._servers.get(key) is not created:
                 raise HTTPException(
-                    status_code=409,
-                    detail="MCP session initialization is already in progress",
+                    status_code=503, detail="MCP server initialization was interrupted"
                 )
-            self._reserve_capacity()
-            self._creating[key] = current_task
+            return self._lease(created)
 
+    async def _create_server(
+        self,
+        key: MCPServerKey,
+        factory: MCPServerFactory,
+        stale_server: ManagedMCPServer | None,
+    ) -> ManagedMCPServer:
         candidate = None
         registered = False
         try:
@@ -172,19 +202,26 @@ class MCPServerPool:
             async with self._lock:
                 self._ensure_running()
                 self._evict_for_capacity()
-                lease = self._lease(candidate, request)
                 self._servers[key] = candidate
                 self._creating.pop(key, None)
                 registered = True
-                return lease
+                return candidate
         except BaseException:
             if candidate is not None and not registered:
                 await candidate.stop()
             async with self._lock:
-                if self._creating.get(key) is current_task:
+                if self._creating.get(key) is asyncio.current_task():
                     self._creating.pop(key, None)
             raise
 
+    @staticmethod
+    def _log_creation_failure(task: asyncio.Task[ManagedMCPServer]) -> None:
+        if not task.cancelled() and (error := task.exception()) is not None:
+            logger.error(
+                "MCP server initialization failed",
+                exc_info=(type(error), error, error.__traceback__),
+            )
+
     async def remove(self, key: MCPServerKey) -> None:
         async with self._lock:
             server = self._servers.pop(key, None)
@@ -257,12 +294,7 @@ class MCPServerPool:
         if self._shutting_down:
             raise HTTPException(status_code=503, detail="MCP service is shutting down")
 
-    def _lease(self, server: ManagedMCPServer, request: Request) -> MCPRequestLease:
-        if not server.accept_request(request):
-            raise HTTPException(
-                status_code=409,
-                detail="MCP session already initialized for this path",
-            )
+    def _lease(self, server: ManagedMCPServer) -> MCPRequestLease:
         server.reserve_request()
         return MCPRequestLease(server)
 
@@ -281,7 +313,7 @@ class MCPServerPool:
             for key, server in self._servers.items()
             if server.active_requests == 0
             and (
-                not server.session_created
+                (server.has_been_leased and server.active_sessions == 0)
                 or now - server.last_used >= self._idle_ttl_seconds
             )
         ]
@@ -292,6 +324,10 @@ class MCPServerPool:
             )
         key, server = min(candidates, key=lambda item: item[1].last_used)
         self._servers.pop(key)
+
+        self._retire_server(server)
+
+    def _retire_server(self, server: ManagedMCPServer) -> None:
         server.close()
         if server.task is not None:
             self._retired_tasks.add(server.task)

{hyperforge-1.0.0.post437 → hyperforge-1.0.0.post447}/src/hyperforge/api/settings.py

@@ -43,5 +43,6 @@ class Settings(BaseSettings):
     mcp_max_request_bytes: int = Field(default=1024 * 1024, ge=1)
     mcp_max_response_bytes: int = Field(default=4 * 1024 * 1024, ge=1)
     mcp_max_servers: int = Field(default=100, ge=1)
+    mcp_max_sessions_per_server: int = Field(default=100, ge=1)
     mcp_session_idle_ttl_seconds: int = Field(default=1800, ge=1)
     mcp_startup_timeout_seconds: int = Field(default=30, ge=1)

{hyperforge-1.0.0.post437 → hyperforge-1.0.0.post447}/src/hyperforge/api/v1/mcp_interaction.py

@@ -1,8 +1,9 @@
 import asyncio
 import json
 import uuid
+from contextlib import asynccontextmanager
 from functools import partial
-from typing import TYPE_CHECKING, Any, Iterable, Sequence
+from typing import TYPE_CHECKING, Any, AsyncIterator, Iterable, Sequence
 
 from fastapi import Header, HTTPException
 from mcp.server.fastmcp.exceptions import ResourceError
@@ -283,12 +284,10 @@ def _get_mcp_auth_config(app: "HTTPApplication", agent_id: str):
 
 
 def _get_first_enabled_mcp_auth_config(app: "HTTPApplication"):
-    agents_cfg = getattr(app, "_agents_cfg", None)
-    if isinstance(agents_cfg, dict):
-        for agent_id in agents_cfg:
-            auth_config = get_enabled_mcp_auth(agents_cfg, agent_id)
-            if auth_config is not None:
-                return auth_config
+    for agent_id in app._agents_cfg:
+        auth_config = get_enabled_mcp_auth(app._agents_cfg, agent_id)
+        if auth_config is not None:
+            return auth_config
     return None
 
 
@@ -300,6 +299,17 @@ async def _create_mcp_server(
     account: str,
     max_request_bytes: int,
 ) -> ManagedMCPServer:
+    runtime_settings = app.mcp_settings
+
+    @asynccontextmanager
+    async def mcp_lifespan(server: MCPServer) -> AsyncIterator[dict[str, Any]]:
+        managed_server.active_sessions += 1
+        try:
+            async with default_lifespan(server) as context:
+                yield context
+        finally:
+            managed_server.release_session()
+
     agent_manager: AgentManager = request.app.agent_manager
     workflows, agent_config, prompts = await asyncio.gather(
         agent_manager.workflows_list(account=account, agent_id=agent_id),
@@ -310,7 +320,7 @@ async def _create_mcp_server(
         name=agent_id,
         version="1.0.0",
         instructions=agent_config.instructions,
-        lifespan=default_lifespan,
+        lifespan=mcp_lifespan,
     )
     mcp_server.list_tools()(partial(list_tools, workflows))
     mcp_server.call_tool()(
@@ -331,9 +341,12 @@ async def _create_mcp_server(
         json_response=True,
         stateless=False,
         security_settings=None,
+        session_idle_timeout=runtime_settings.mcp_session_idle_ttl_seconds,
         max_request_body_size=max_request_bytes,
     )
-    managed_server = ManagedMCPServer(manager)
+    managed_server = ManagedMCPServer(
+        manager, max_sessions=runtime_settings.mcp_max_sessions_per_server
+    )
     await managed_server.start()
     return managed_server
 
@@ -374,9 +387,7 @@ class _MCPTransportResponse(Response):
             return await receive()
 
         if self.request.method == "GET":
-            await self.managed_server.manager.handle_request(
-                scope, patched_receive, send
-            )
+            await self.managed_server.handle_request(scope, patched_receive, send)
             return
 
         response_status = 200
@@ -404,7 +415,7 @@ class _MCPTransportResponse(Response):
                 elif not response_too_large:
                     body_chunks.append(chunk)
 
-        await self.managed_server.manager.handle_request(
+        await self.managed_server.handle_request(
             scope, patched_receive, intercepting_send
         )
         if response_too_large:
@@ -498,20 +509,6 @@ async def mcp_interaction_protected_resource_metadata(
 
 
 @router.delete("/api/v1/agent/{agent_id}/session/{session}/mcp", tags=["MCP"])
-@requires_one([AgentRole.MEMBER])
-async def mcp_handler_delete(
-    request: Request,
-    agent_id: str,
-    session: str,
-    x_stf_user: str = Header(..., include_in_schema=False),
-    x_stf_account: str = Header(..., include_in_schema=False),
-    x_stf_account_type: str = Header(..., include_in_schema=False),
-):
-    app: HTTPApplication = request.app
-    key = (x_stf_account, x_stf_user, x_stf_account_type, agent_id, session)
-    await app.mcp_server_pool.remove(key)
-
-
 @router.get("/api/v1/agent/{agent_id}/session/{session}/mcp", tags=["MCP"])
 @router.post("/api/v1/agent/{agent_id}/session/{session}/mcp", tags=["MCP"])
 @requires_one([AgentRole.MEMBER])
@@ -524,7 +521,11 @@ async def interaction_mcp_handler(
     x_stf_account_type: str = Header(..., include_in_schema=False),
 ):
     app: HTTPApplication = request.app
-    runtime_settings = getattr(app, "_standalone_settings", app.settings)
+    if request.method in {"GET", "DELETE"} and not request.headers.get(
+        "mcp-session-id"
+    ):
+        raise HTTPException(status_code=400, detail="Missing Mcp-Session-Id")
+    runtime_settings = app.mcp_settings
     max_request_bytes = runtime_settings.mcp_max_request_bytes
     max_response_bytes = runtime_settings.mcp_max_response_bytes
     content_length = request.headers.get("content-length")

{hyperforge-1.0.0.post437 → hyperforge-1.0.0.post447}/src/hyperforge/standalone/app.py

@@ -321,6 +321,10 @@ class StandaloneApplication(FastAPI):
     def settings(self) -> ServerSettings:
         return self._server_settings
 
+    @property
+    def mcp_settings(self) -> StandaloneSettings:
+        return self._standalone_settings
+
     # ------------------------------------------------------------------
     # Lifecycle
     # ------------------------------------------------------------------

{hyperforge-1.0.0.post437 → hyperforge-1.0.0.post447}/src/hyperforge/standalone/settings.py

@@ -192,6 +192,7 @@ class StandaloneSettings(BaseSettings):
     mcp_max_request_bytes: int = Field(default=1024 * 1024, ge=1)
     mcp_max_response_bytes: int = Field(default=4 * 1024 * 1024, ge=1)
     mcp_max_servers: int = Field(default=100, ge=1)
+    mcp_max_sessions_per_server: int = Field(default=100, ge=1)
     mcp_session_idle_ttl_seconds: int = Field(default=1800, ge=1)
     mcp_startup_timeout_seconds: int = Field(default=30, ge=1)