69async def call(
 70    node_: type[Node[_P, _TOutput]] | RTFunction[_P, _TOutput],
 71    *args: _P.args,
 72    **kwargs: _P.kwargs,
 73) -> _TOutput:
 74    """
 75    Call a node from within a node inside the framework. This will return a coroutine that you can interact with
 76    in whatever way using async/await logic.
 77
 78    Usage:
 79    ```python
 80    # for sequential operation
 81    result = await call(NodeA, "hello world", 42)
 82
 83    # for parallel operation
 84    tasks = [call(NodeA, "hello world", i) for i in range(10)]
 85    results = await asyncio.gather(*tasks)
 86    ```
 87
 88    Args:
 89        node: The node type you would like to create. This could be a function decorated with `@function_node`, a function, or a Node instance.
 90        *args: The arguments to pass to the node
 91        **kwargs: The keyword arguments to pass to the node
 92    """
 93    node: type[Node[_P, _TOutput]]
 94
 95    if hasattr(node_, "node_type"):
 96        # local import to prevent circular import issues (note it is a purely type checking import)
 97        from railtracks.built_nodes.function.base import RTFunction
 98
 99        assert isinstance(node_, RTFunction)
100        node = extract_node_from_function(node_)
101    else:
102        node = node_
103
104    # if the context is none then we will need to create a wrapper for the state object to work with.
105    if not is_context_present():
106        # we have to use lazy import here to prevent a circular import issue. This is a must have unfortunately.
107        from railtracks import Session
108
109        with Session():
110            result = await _start(node, args=args, kwargs=kwargs)
111            return result
112
113    # if the context is not active then we know this is the top level request
114    if not is_context_active():
115        result = await _start(node, args=args, kwargs=kwargs)
116        return result
117
118    # if the context is active then we can just run the node
119    result = await _run(node, args=args, kwargs=kwargs)
120    return result

265def astream(
266    node_: type[Node[_P, _TOutput]],
267    *args: _P.args,
268    **kwargs: _P.kwargs,
269) -> Stream[_TOutput]:
270    """
271    Invoke an agent node with streaming enabled and return a `Stream` over its emitted chunks.
272
273    Async-iterate the returned `Stream` for token chunks and read `.result` for the final
274    return value, or `await` it directly when you only want the result. Streaming is
275    frame-local: only the node invoked here streams its LLM responses; nested `rt.call`
276    children run buffered.
277
278    Args:
279        node_: The agent node class to invoke (built with `rt.agent_node(...)`). Only agent
280            nodes are accepted; a `@function_node` / tool node has no token stream to
281            surface, so use `rt.call` for those.
282        *args: The positional arguments to pass to the node.
283        **kwargs: The keyword arguments to pass to the node.
284
285    Returns:
286        Stream[_TOutput]: An async iterator over the chunks, with the final result available
287            via `.result` (or by awaiting the stream).
288
289    Raises:
290        NodeCreationError: If `node_` is not an agent node.
291    """
292    # local import to prevent circular import issues (mirrors rt.call)
293    from railtracks.nodes.nodes import Node
294
295    # rt.astream streams an agent's LLM tokens, so it only accepts agent nodes built with
296    # rt.agent_node(...). Validate the input up front: anything that is not an agent `Node`
297    # subclass (a @function_node / tool node, or a raw value) has no token stream to surface,
298    # so it is rejected here rather than unpacked use rt.call instead.
299    is_agent_node = (
300        isinstance(node_, type) and issubclass(node_, Node) and node_.type() == "Agent"
301    )
302    if not is_agent_node:
303        name = getattr(node_, "__name__", None) or repr(node_)
304        raise NodeCreationError(
305            message=f"rt.astream only supports agent nodes, but {name!r} is not one.",
306            notes=[
307                "Pass an agent built with rt.agent_node(...) to rt.astream(...).",
308                "To run a function/tool node, use rt.call(...) instead.",
309            ],
310        )
311    node = node_
312
313    # Session lifecycle is owned here, not by the Stream handle. When called outside any
314    # session we open one and hold it in this closure; the Stream calls `_close` back once
315    # it finishes (see Stream.on_start / on_close), so the session's open/close logic lives
316    # with astream rather than inside the returned object.
317    owned: list[Session] = []
318
319    def _open() -> None:
320        if not is_context_present():
321            from railtracks import Session  # lazy import to avoid a circular import
322
323            owned.append(Session())
324
325    def _close() -> None:
326        while owned:
327            owned.pop().__exit__(None, None, None)
328
329    return Stream(node, args, kwargs, on_start=_open, on_close=_close)

 8async def broadcast(item: str):
 9    """
10    Broadcasts a one-off **event** to the session bus.
11
12    This triggers the `broadcast_callback` you have provided to the `Session` (or via
13    `rt.set_config`). Each broadcast is a discrete event, independent of any LLM token
14    output an agent produces.
15
16    Args:
17        item (str): The item you want to broadcast.
18    """
19    publisher = get_publisher()
20
21    await publisher.publish(BroadcastEvent(node_id=get_parent_id(), item=item))

19async def call_batch(
20    node: type[Node[..., _TOutput]] | RTFunction[..., _TOutput],
21    *iterables: Iterable[Any],
22    return_exceptions: bool = True,
23):
24    """
25    Complete a node over multiple iterables, allowing for parallel execution.
26
27    Note the results will be returned in the order of the iterables, not the order of completion.
28
29    If one of the nodes returns an exception, the thrown exception will be included as a response.
30
31    Args:
32        node: The node type to create.
33        *iterables: The iterables to map the node over.
34        return_exceptions: If True, exceptions will be returned as part of the results.
35            If False, exceptions will be raised immediately, and you will lose access to the results.
36            Defaults to true.
37
38    Returns:
39        An iterable of results from the node.
40
41    Usage:
42        ```python
43        results = await batch(NodeA, ["hello world"] * 10)
44        for result in results:
45            handle(result)
46        ```
47    """
48    # this is big typing disaster but there is no way around it. Try if if you want to.
49    contracts = [call(node, *args) for args in zip(*iterables)]
50
51    results = await asyncio.gather(*contracts, return_exceptions=return_exceptions)
52    return results

 19class ExecutionInfo:
 20    """
 21    A class that contains the full details of the state of a run at any given point in time.
 22
 23    The class is designed to be used as a snapshot of state that can be used to display the state of the run, or to
 24    create a graphical representation of the system.
 25    """
 26
 27    def __init__(
 28        self,
 29        request_forest: RequestForest,
 30        node_forest: NodeForest,
 31        stamper: StampManager,
 32    ):
 33        self.request_forest = request_forest
 34        self.node_forest = node_forest
 35        self.stamper = stamper
 36
 37    @classmethod
 38    def default(cls) -> ExecutionInfo:
 39        """Creates a new "empty" instance of the ExecutionInfo class with the default values."""
 40        return cls.create_new()
 41
 42    @classmethod
 43    def create_new(
 44        cls,
 45    ) -> ExecutionInfo:
 46        """
 47        Creates a new empty instance of state variables with the provided executor configuration.
 48
 49        """
 50        request_heap = RequestForest()
 51        node_heap = NodeForest()
 52        stamper = StampManager()
 53
 54        return ExecutionInfo(
 55            request_forest=request_heap,
 56            node_forest=node_heap,
 57            stamper=stamper,
 58        )
 59
 60    @property
 61    def answer(self):
 62        """Convenience method to access the answer of the run."""
 63        return self.request_forest.answer
 64
 65    @property
 66    def all_stamps(self) -> List[Stamp]:
 67        """Convenience method to access all the stamps of the run."""
 68        return self.stamper.all_stamps
 69
 70    @property
 71    def name(self):
 72        """
 73        Gets the name of the graph by pulling the name of the insertion request. It will raise a ValueError if the insertion
 74        request is not present or there are multiple insertion requests.
 75        """
 76        insertion_requests = self.insertion_requests
 77
 78        # The name is only defined for the length of 1.
 79        # NOTE: Maybe we should send a warning once to user in other cases.
 80        if len(insertion_requests) != 1:
 81            return None
 82
 83        i_r = insertion_requests[0]
 84
 85        return self.node_forest.get_node_type(i_r.sink_id).name()
 86
 87    @property
 88    def insertion_requests(self):
 89        """A convenience method to access all the insertion requests of the run."""
 90        return self.request_forest.insertion_request
 91
 92    def _get_info(self, ids: List[str] | str | None = None) -> ExecutionInfo:
 93        """
 94        Gets a subset of the current state based on the provided node ids. It will contain all the children of the provided node ids
 95
 96        Note: If no ids are provided, the full state is returned.
 97
 98        Args:
 99            ids (List[str] | str | None): A list of node ids to filter the state by. If None, the full state is returned.
100
101        Returns:
102            ExecutionInfo: A new instance of ExecutionInfo containing only the children of the provided ids.
103
104        """
105        if ids is None:
106            return self
107        else:
108            # firstly lets
109            if isinstance(ids, str):
110                ids = [ids]
111
112            # we need to quickly check to make sure these ids are valid
113            for identifier in ids:
114                if identifier not in self.request_forest:
115                    raise ValueError(
116                        f"Identifier '{identifier}' not found in the current state."
117                    )
118
119            new_node_forest, new_request_forest = create_sub_state_info(
120                self.node_forest.heap(),
121                self.request_forest.heap(),
122                ids,
123            )
124            return ExecutionInfo(
125                node_forest=new_node_forest,
126                request_forest=new_request_forest,
127                stamper=self.stamper,
128            )
129
130    def _to_graph(self) -> Tuple[List[Vertex], List[Edge]]:
131        """
132        Converts the current state into its graph representation.
133
134        Returns:
135            List[Node]: An iterable of nodes in the graph.
136            List[Edge]: An iterable of edges in the graph.
137        """
138        return self.node_forest.to_vertices(), self.request_forest.to_edges()
139
140    def graph_serialization(self) -> dict[str, Any]:
141        """
142                Creates a string (JSON) representation of this info object designed to be used to construct a graph for this
143                info object.
144
145                Some important notes about its structure are outlined below:
146                - The `nodes` key contains a list of all the nodes in the graph, represented as `Vertex` objects.
147                - The `edges` key contains a list of all the edges in the graph, represented as `Edge` objects.
148                - The `stamps` key contains an ease of use list of all the stamps associated with the run, represented as `Stamp` objects.
149
150                - The "nodes" and "requests" key will be outlined with normal graph details like connections and identifiers in addition to a loose details object.
151                - However, both will carry an addition param called "stamp" which is a timestamp style object.
152                - They also will carry a "parent" param which is a recursive structure that allows you to traverse the graph in time.
153
154
155        ```
156        """
157        parent_nodes = [x.identifier for x in self.insertion_requests]
158
159        infos = [self._get_info(parent_node) for parent_node in parent_nodes]
160
161        runs = []
162
163        for info, parent_node_id in zip(infos, parent_nodes):
164            insertion_requests = info.request_forest.insertion_request
165
166            assert len(insertion_requests) == 1
167            parent_request = insertion_requests[0]
168
169            all_parents = parent_request.get_all_parents()
170
171            start_time = all_parents[-1].stamp.time
172
173            assert len([x for x in all_parents if x.status == "Completed"]) <= 1
174            end_time = None
175            for req in all_parents:
176                if req.status in ["Completed", "Failed"]:
177                    end_time = req.stamp.time
178                    break
179
180            entry = {
181                "name": info.name,
182                "run_id": parent_node_id,
183                "nodes": info.node_forest.to_vertices(),
184                "status": parent_request.status,
185                "edges": info.request_forest.to_edges(),
186                "steps": _get_stamps_from_forests(
187                    info.node_forest, info.request_forest
188                ),
189                "start_time": start_time,
190                "end_time": end_time,
191            }
192            runs.append(entry)
193
194        return json.loads(
195            json.dumps(
196                runs,
197                cls=RTJSONEncoder,
198            )
199        )

14class ExecutorConfig:
15    def __init__(
16        self,
17        *,
18        timeout: float | None = None,
19        end_on_error: bool = False,
20        broadcast_callback: (
21            Callable[[str], None] | Callable[[str], Coroutine[None, None, None]] | None
22        ) = None,
23        save_state: bool | None = None,
24        payload_callback: Callable[[dict[str, Any]], None] | None = None,
25    ):
26        """
27        ExecutorConfig is special configuration object designed to allow customization of the executor in the RT system.
28
29        Args:
30            timeout (float | None): The maximum number of seconds to wait for a response to your top level request. Pass None (or omit) to disable the timeout entirely.
31            end_on_error (bool): If true, the executor will stop execution when an exception is encountered.
32            broadcast_callback (Callable or Coroutine): A function or coroutine that receives items published with `rt.broadcast`.
33            save_state (bool | None): Deprecated at the user-facing API layer (see Flow). `RAILTRACKS_DISABLE_EVENTS=True` skips the write regardless. Otherwise, explicit value wins; when unset, defaults to True (save).
34        """
35        self.timeout = timeout
36        self.end_on_error = end_on_error
37        self.subscriber = broadcast_callback
38        # During test runs, disable save_state by default unless
39        # RAILTRACKS_ALLOW_PERSISTENCE is set (see `save_state` property).
40        self._user_save_state = save_state
41
42        self.payload_callback = payload_callback
43
44    # this is done because if we try to lock the save_state in init
45    # later when we want to allow a few tests to actually run persistance, they wont be able to do so
46    @property
47    def save_state(self) -> bool:
48        if os.getenv("RAILTRACKS_TEST_MODE") and not os.getenv(
49            "RAILTRACKS_ALLOW_PERSISTENCE"
50        ):
51            return False
52        if _disable_events():
53            return False
54        return True if self._user_save_state is None else self._user_save_state
55
56    def precedence_overwritten(
57        self,
58        *,
59        timeout: float | None = None,
60        end_on_error: bool | None = None,
61        subscriber: (
62            Callable[[str], None] | Callable[[str], Coroutine[None, None, None]] | None
63        ) = None,
64        save_state: bool | None = None,
65        payload_callback: Callable[[dict[str, Any]], None] | None = None,
66    ):
67        """
68        If any of the parameters are provided (not None), it will create a new update the current instance with the new values and return a deep copied reference to it.
69        """
70        return ExecutorConfig(
71            timeout=timeout,
72            end_on_error=end_on_error
73            if end_on_error is not None
74            else self.end_on_error,
75            broadcast_callback=subscriber
76            if subscriber is not None
77            else self.subscriber,
78            save_state=save_state if save_state is not None else self._user_save_state,
79            payload_callback=payload_callback
80            if payload_callback is not None
81            else self.payload_callback,
82        )
83
84    def __repr__(self):
85        return (
86            f"ExecutorConfig(timeout={self.timeout}, end_on_error={self.end_on_error}, "
87            f"save_state={self._user_save_state}, payload_callback={self.payload_callback})"
88        )

499def set_config(
500    *,
501    timeout: float | None = None,
502    end_on_error: bool | None = None,
503    broadcast_callback: (
504        Callable[[str], None] | Callable[[str], Coroutine[None, None, None]] | None
505    ) = None,
506    save_state: bool | None = None,
507) -> None:
508    """
509    Sets the global configuration for the executor. This will be propagated to all new runners created after this call.
510
511    - If you call this function after the runner has been created, it will not affect the current runner.
512    - This function will only overwrite the values that are provided, leaving the rest unchanged.
513
514    Args:
515        broadcast_callback: A passive listener for one-off events published with `rt.broadcast`.
516    """
517
518    if is_context_active():
519        warnings.warn(
520            "The executor config is being set after the runner has been created, this is not recommended"
521        )
522
523    config = global_executor_config.get()
524
525    new_config = config.precedence_overwritten(
526        timeout=timeout,
527        end_on_error=end_on_error,
528        subscriber=broadcast_callback,
529        save_state=save_state,
530    )
531
532    global_executor_config.set(new_config)

334def function_node(
335    func: Callable[_P, Coroutine[None, None, _TOutput]]
336    | Callable[_P, _TOutput]
337    | List[Callable[_P, Coroutine[None, None, _TOutput]] | Callable[_P, _TOutput]]
338    | None = None,
339    /,
340    *,
341    name: str | None = None,
342    manifest: ToolManifest | None = None,
343    middleware: Iterable[Middleware[_P, _TOutput]] | None = None,
344) -> (
345    CallableAsyncRTFunction[_P, _TOutput]
346    | CallableSyncRTFunction[_P, _TOutput]
347    | List[CallableAsyncRTFunction[_P, _TOutput] | CallableSyncRTFunction[_P, _TOutput]]
348    | Callable[
349        [Callable[_P, Coroutine[None, None, _TOutput]] | Callable[_P, _TOutput]],
350        RTFunction[_P, _TOutput],
351    ]
352    | None
353):
354    """
355    Creates a new Node type from a function that can be used in `rt.call()`.
356
357    By default, it will parse the function's docstring and turn them into tool details and parameters. However, if
358    you provide custom ToolManifest it will override that logic.
359
360    Can be used three ways::
361
362        # 1. direct call
363        node = rt.function_node(my_fn, middleware=[guard])
364
365        # 2. bare decorator
366        @rt.function_node
367        def my_fn(...): ...
368
369        # 3. parametrized decorator (attach middleware / guardrails declaratively)
370        @rt.function_node(middleware=[guard], name="echo")
371        def my_fn(...): ...
372
373    WARNING: If you overriding tool parameters. It is on you to make sure they will work with your function.
374
375    NOTE: If you have already converted this function to a node this function will do nothing
376
377    Args:
378        func (Callable, optional): The function to convert into a Node. Omit it to use the
379            parametrized-decorator form, which returns a decorator that takes the function.
380        name (str, optional): Human-readable name for the node/tool.
381        manifest (ToolManifest, optional): The details you would like to override the tool with.
382        middleware (list[Middleware] | None): Middleware applied around the node boundary.
383    """
384
385    # No function yet -> parametrized-decorator form: bind the options and return
386    # a decorator that finishes the job once the function is supplied.
387    if func is None:
388
389        def _decorator(
390            f: Callable[_P, Coroutine[None, None, _TOutput]] | Callable[_P, _TOutput],
391        ) -> (
392            CallableAsyncRTFunction[_P, _TOutput] | CallableSyncRTFunction[_P, _TOutput]
393        ):
394            return function_node(f, name=name, manifest=manifest, middleware=middleware)
395
396        return _decorator
397
398    # handle the case where a list of functions is provided
399    if isinstance(func, list):
400        return [
401            function_node(f, name=name, manifest=manifest, middleware=middleware)
402            for f in func
403        ]
404    else:
405        return _single_function_node(
406            func, name=name, manifest=manifest, middleware=middleware
407        )

141def agent_node(
142    name: str | None = None,
143    *,
144    tool_nodes: Iterable[Type[Node] | RTFunction] | None = None,
145    output_schema: Type[_TBaseModel] | None = None,
146    llm: ModelSource,
147    system_message: SystemMessage | str | None = None,
148    manifest: ToolManifest | None = None,
149    middleware: Iterable[Middleware[_P, StructuredResponse[_TBaseModel]]]
150    | Iterable[Middleware[_P, StringResponse]]
151    | None = None,
152    model_middleware: Iterable[ModelMiddleware] | None = None,
153    _shape: Callable[_P, object] = _user_input_shape,
154) -> type[Node[_P, StringResponse]] | type[Node[_P, StructuredResponse[_TBaseModel]]]:
155    """
156    Dynamically creates an agent based on the provided parameters.
157
158    Args:
159        name (str | None): The name of the agent. If none the default will be used.
160        tool_nodes (Iterable[Type[Node] | RTFunction] | None): If your agent has access to tools, what does it have access to?
161            Cannot be combined with output_schema -- see below.
162        output_schema (Type[_TBaseModel] | None): If your agent should return a structured output, what is the output_schema?
163            Cannot be combined with tool_nodes: providing both raises NodeCreationError, since the model does not
164            reliably call tools when a structured output_schema is also requested (it may fabricate a plausible
165            tool result instead of actually invoking the tool).
166        llm (ModelBase | Callable[[], ModelBase]): The LLM model to use, or a no-arg
167            factory resolved fresh on every model call (lets the agent pick its model
168            at invocation time, e.g. from config or rt.context).
169        system_message (SystemMessage | str | None): System message for the agent.
170        manifest (ToolManifest | None): If you want to use this as a tool in other agents you can pass in a ToolManifest.
171        middleware (list[Middleware] | None): Middleware applied around the agent's node boundary
172            (user_input -> Response).
173        model_middleware (list[Middleware] | None): Middleware applied around each raw model call
174            (messages/schema/tools -> Response), inside the tool-calling loop.
175        _shape (Callable[_P, object]): Internal use only. Used to infer the ParamSpec for the agent's input shape.
176
177    NOTE: Supplying a parameter `_shape` will break typing and you will be responsible for it. DO NOT USE THIS!!
178    """
179    _check_no_combined_tools_and_schema(tool_nodes, output_schema)
180
181    unpacked_tool_nodes = _unpack_tool_nodes(tool_nodes)
182
183    # See issue (___) this logic should be migrated soon.
184    if manifest is not None:
185        tool_details = manifest.description
186        tool_params = manifest.parameters
187    else:
188        tool_details = None
189        tool_params = None
190
191    return _build_dynamic_agent(
192        unpacked_tool_nodes=unpacked_tool_nodes,
193        output_schema=output_schema,
194        name=name,
195        llm=llm,
196        system_message=system_message,
197        tool_details=tool_details,
198        tool_params=tool_params,
199        middleware=middleware,
200        model_middleware=model_middleware,
201    )

25class MCPStdioParams(StdioServerParameters):
26    """
27    Configuration parameters for STDIO-based MCP server connections.
28
29    Extends the standard StdioServerParameters with a timeout field.
30
31    Attributes:
32        timeout: Maximum time to wait for operations (default: 30 seconds)
33    """
34
35    timeout: timedelta = timedelta(seconds=30)
36
37    def as_stdio_params(self) -> StdioServerParameters:
38        """
39        Convert to standard StdioServerParameters, excluding the timeout field.
40
41        Returns:
42            StdioServerParameters without the timeout attribute
43        """
44        stdio_kwargs = self.dict(exclude={"timeout"})
45        return StdioServerParameters(**stdio_kwargs)

48class MCPHttpParams(BaseModel):
49    """
50    Configuration parameters for HTTP-based MCP server connections.
51
52    Supports both SSE (Server-Sent Events) and streamable HTTP transports.
53    The transport type is automatically determined based on the URL.
54
55    Attributes:
56        url: The MCP server URL (use /sse suffix for SSE transport)
57        headers: Optional HTTP headers for authentication
58        timeout: Connection timeout (default: 30 seconds)
59        sse_read_timeout: SSE read timeout (default: 5 minutes)
60        terminate_on_close: Whether to terminate connection on close (default: True)
61        auth: Optional HTTPX authentication handler
62    """
63
64    model_config = {"arbitrary_types_allowed": True}
65
66    url: str
67    headers: dict[str, Any] | None = None
68    timeout: timedelta = timedelta(seconds=30)
69    sse_read_timeout: timedelta = timedelta(seconds=60 * 5)
70    terminate_on_close: bool = True
71    auth: httpx.Auth | None = None

 8def connect_mcp(
 9    config: MCPStdioParams | MCPHttpParams,
10    client_session: ClientSession | None = None,
11    setup_timeout: float = 30,
12) -> MCPServer:
13    """
14    Connect to an MCP server and return a server instance with available tools.
15
16    This is the primary entry point for using MCP servers in Railtracks.
17    The server will connect in the background, discover available tools,
18    and convert them to Railtracks Node classes.
19
20    The connection remains active until explicitly closed or the context exits.
21
22    Usage Examples:
23        # STDIO connection (local MCP server)
24        config = rt.MCPStdioParams(
25            command="uvx",
26            args=["mcp-server-time"]
27        )
28        server = rt.connect_mcp(config)
29
30        # HTTP connection (remote MCP server)
31        config = rt.MCPHttpParams(
32            url="https://mcp.example.com/sse",
33            headers={"Authorization": "Bearer token"}
34        )
35        server = rt.connect_mcp(config)
36
37        # Context manager (recommended)
38        with rt.connect_mcp(config) as server:
39            tools = server.tools
40            # Use tools...
41        # Automatically closed
42
43        # Access tools
44        for tool in server.tools:
45            print(f"Tool: {tool.name()}")
46            print(f"Description: {tool.tool_info().description}")
47
48    Args:
49        config: Server configuration:
50            - MCPStdioParams: For local servers via stdin/stdout
51            - MCPHttpParams: For remote servers via HTTP/SSE
52        client_session: Optional pre-configured ClientSession for advanced use cases.
53                       If not provided, a new session will be created automatically.
54        setup_timeout: Maximum seconds to wait for connection (default: 30).
55                      Increase for slow servers or complex authentication flows.
56
57    Returns:
58        MCPServer: Connected server instance with:
59            - tools: List of Node classes representing MCP tools
60            - close(): Method to explicitly close the connection
61            - Context manager support for automatic cleanup
62
63    Raises:
64        FileNotFoundError: If STDIO command not found. Verify the command is:
65                          - Installed and in your PATH
66                          - Spelled correctly (check for typos)
67                          - Executable (check permissions on Unix)
68        ConnectionError: If connection to server fails. Check:
69                        - Server URL is correct and accessible
70                        - Network connectivity and firewall settings
71                        - Authentication credentials are valid
72                        - Server is running and accepting connections
73        TimeoutError: If connection exceeds setup_timeout. Try:
74                     - Increasing setup_timeout parameter
75                     - Checking server performance/load
76                     - Verifying server is responding
77        RuntimeError: For other setup failures (e.g., protocol errors, config issues)
78
79    Note:
80        - The connection runs in a background thread for sync/async bridging
81        - Tools are cached after first retrieval for performance
82        - Always close() the server when done or use context manager
83        - Jupyter compatibility patches are applied automatically
84    """
85    # Apply Jupyter compatibility patches if needed
86    apply_patches()
87
88    return MCPServer(
89        config=config, client_session=client_session, setup_timeout=setup_timeout
90    )