mcp-console 0.0.5__py3-none-win_amd64.whl

mcp_console/__init__.py

@@ -0,0 +1,15 @@
+"""Composable Python integrations for the MCP Console stdio server."""
+
+from . import anthropic, chatlas, codex, openai
+from ._client import AsyncMCPConsole, Requirements
+from ._sync import MCPConsole
+
+__all__ = [
+    "AsyncMCPConsole",
+    "MCPConsole",
+    "Requirements",
+    "anthropic",
+    "chatlas",
+    "codex",
+    "openai",
+]

mcp_console/_client.py

@@ -0,0 +1,252 @@
+from collections.abc import Mapping, Sequence
+from contextlib import AsyncExitStack
+from typing import TYPE_CHECKING, Any, Literal, Self, TypedDict
+
+from ._common import Command, result_text, stdio_command
+
+if TYPE_CHECKING:
+    from mcp import Client
+    from mcp.types import CallToolResult, Tool
+
+
+class Requirements(TypedDict, total=False):
+    """Dependency declarations accepted by the clients' `send(requirements=...)`.
+
+    `add` merges packages into the session declaration. `get` inspects it, `set`
+    replaces it (emptying omitted fields), and `reset` restores startup defaults.
+    Changed replacements of a live worker require `control="restart"`, which
+    also discards its variables. Python packages run in Console's worker
+    environment; installing a framework extra prepares the calling application.
+
+    Attributes:
+        action: `get`, `add` (the default), `set`, or `reset`.
+        python_version: Python version constraints, such as `[">=3.11"]`.
+        exclude_newer: Optional cutoff date for dependency resolution.
+        r: R package requirements.
+        python: Python package requirements.
+        duckdb: DuckDB extensions.
+
+    Examples:
+        Install with `pip install 'mcp-console[client]'`. Add NumPy to Console's
+        managed Python environment and use it in the same call:
+
+        ```python
+        from mcp_console import MCPConsole, Requirements
+
+        requirements: Requirements = {"python": ["numpy"]}
+        with MCPConsole() as console:
+            print(
+                console.send(
+                    requirements=requirements,
+                    python="import numpy as np; np.mean([12, 15, 18, 20, 25])",
+                )
+            )
+        ```
+    """
+
+    action: Literal["get", "add", "set", "reset"]
+    python_version: list[str]
+    exclude_newer: str | None
+    r: list[str]
+    python: list[str]
+    duckdb: list[str]
+
+
+class AsyncMCPConsole:
+    """A persistent, callable connection to ``mcp-console serve``.
+
+    Enter and close the connection in the same async task. The application owns
+    its model clients, agents, and tool loops. The context starts the server and
+    discovers its tools; leaving the context closes its connection and process.
+    Variables persist across `send()` calls on this connection. A new connection
+    starts a new session.
+
+    Args:
+        command: Console executable. Defaults to the installed `mcp-console`.
+        args: Server arguments. Defaults to `["serve"]`.
+        server_parameters: MCP stdio settings such as `cwd` and `env`.
+
+    Examples:
+        Install with `pip install 'mcp-console[client]'`. This script defines
+        values in one cell and uses them in a second cell:
+
+        ```python
+        import asyncio
+        from mcp_console import AsyncMCPConsole
+
+
+        async def main():
+            async with AsyncMCPConsole() as console:
+                print(
+                    await console.send(
+                        python="values = [12, 15, 18, 20, 25]; values"
+                    )
+                )
+                print(
+                    await console.send(
+                        python="import statistics; statistics.mean(values)"
+                    )
+                )
+
+
+        asyncio.run(main())
+        ```
+
+        Framework adapters are created inside this context, after discovery.
+        See [Anthropic](anthropic.tool.html), [chatlas](chatlas.tool.html),
+        [Responses](openai.responses_tool.html), or [Agents](openai.agents_tool.html).
+    """
+
+    def __init__(
+        self,
+        *,
+        command: Command | None = None,
+        args: Sequence[Command] | None = None,
+        server_parameters: Mapping[str, Any] | None = None,
+    ) -> None:
+        self._command = command
+        self._args = args
+        self._server_parameters = dict(server_parameters or {})
+        self._stack: AsyncExitStack | None = None
+        self._client: Client | None = None
+        self._send_tool: Tool | None = None
+
+    async def connect(self) -> "Self":
+        """Start MCP Console and initialize its MCP client session."""
+        if self._client is not None:
+            return self
+
+        from mcp import Client, StdioServerParameters
+
+        command, args = stdio_command(self._command, self._args)
+        parameters = self._server_parameters | {"command": command, "args": args}
+        async with AsyncExitStack() as stack:
+            # Automatic discovery can time out while remote startup is pending
+            # and switch lifecycles on the same connection. Initialize once.
+            client = await stack.enter_async_context(
+                Client(StdioServerParameters(**parameters), mode="legacy")
+            )
+            tools = await client.list_tools()
+            send_tool = next(
+                (tool for tool in tools.tools if tool.name == "send"), None
+            )
+            if send_tool is None:
+                raise RuntimeError("MCP Console did not expose its send tool")
+            self._stack = stack.pop_all()
+            self._client = client
+            self._send_tool = send_tool
+        return self
+
+    async def close(self) -> None:
+        """Close the MCP client session and terminate its subprocess."""
+        stack = self._stack
+        self._stack = self._client = self._send_tool = None
+        if stack is not None:
+            await stack.aclose()
+
+    async def __aenter__(self) -> "Self":
+        return await self.connect()
+
+    async def __aexit__(self, exc_type: object, exc: object, traceback: object) -> None:
+        await self.close()
+
+    async def _call_send(self, arguments: Mapping[str, Any]) -> "CallToolResult":
+        if self._client is None:
+            raise RuntimeError(
+                "AsyncMCPConsole is not connected; use `async with AsyncMCPConsole() as console` "
+                "or call `await console.connect()` first"
+            )
+        return await self._client.call_tool("send", dict(arguments))
+
+    async def send(
+        self,
+        *,
+        r: str | None = None,
+        python: str | None = None,
+        sql: str | None = None,
+        control: Literal["interrupt", "restart"] | None = None,
+        requirements: Requirements | None = None,
+        stdin: str | None = None,
+        timeout_ms: int | None = None,
+    ) -> str:
+        """Run or control the persistent R, Python, and SQL console.
+
+        Send at most one of r, python, or sql per call.
+        If output ends in ``[running; poll with an empty send]``, call again
+        without code or stdin until completion before submitting another cell.
+
+        Args:
+            r: One complete R cell.
+            python: One complete Python cell.
+            sql: One complete SQL cell on the selected connection.
+            control: Interrupt the active operation or restart the runtime.
+            requirements: Declaration keyed by r, python, or duckdb, with optional
+                python_version and exclude_newer constraints. action defaults to
+                add; get returns complete inspection JSON; set replaces omitted
+                fields with empty values; reset restores startup defaults.
+                Changed replacements of a live worker require control="restart".
+            stdin: Exact input for an active prompt or debugger.
+            timeout_ms: Maximum wait after dispatch; timeout does not cancel work.
+                Omission or None uses the server default of 60,000 ms.
+
+        Returns:
+            Collected text output and lifecycle notices. Images appear as MIME
+            placeholders. MCP tool errors raise `RuntimeError`.
+
+        Examples:
+            A short observation window may return before the cell finishes.
+            Poll with an empty call, collecting each chunk without rerunning
+            the cell:
+
+            ```python
+            import asyncio
+            from mcp_console import AsyncMCPConsole
+
+
+            async def main():
+                async with AsyncMCPConsole() as console:
+                    output = await console.send(
+                        python="sum(range(1_000_000))",
+                        timeout_ms=0,
+                    )
+                    print(output, end="")
+                    while output.endswith("[running; poll with an empty send]"):
+                        output = await console.send()
+                        print(output, end="")
+
+
+            asyncio.run(main())
+            ```
+        """
+        arguments = {
+            "r": r,
+            "python": python,
+            "sql": sql,
+            "control": control,
+            "requirements": requirements,
+            "stdin": stdin,
+            "timeout_ms": timeout_ms,
+        }
+        return result_text(
+            await self._call_send(
+                {name: value for name, value in arguments.items() if value is not None}
+            )
+        )
+
+    # Ordinary Python shorthand; SDK registration uses the product adapters.
+    __call__ = send
+
+    @property
+    def send_tool(self) -> "Tool":
+        """The connected server's MCP tool definition, used by SDK adapters.
+
+        Available after connecting. Its input schema reflects the server's
+        configured capabilities. Use a framework adapter to register this
+        schema; automatic inference from `send()` annotations loses that detail.
+        Recreate adapters after reconnecting.
+        """
+        if self._send_tool is None:
+            raise RuntimeError(
+                "Connect the console before creating tools; enter its context or call connect()"
+            )
+        return self._send_tool

mcp_console/_common.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import sysconfig
+from collections.abc import Sequence
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from mcp.types import CallToolResult, ContentBlock
+
+Command = str | os.PathLike[str]
+
+
+def stdio_command(
+    command: Command | None, args: Sequence[Command] | None
+) -> tuple[str, list[str]]:
+    if command is None:
+        candidate = Path(sysconfig.get_path("scripts")) / "mcp-console"
+        command = (
+            candidate if os.access(candidate, os.X_OK) else shutil.which("mcp-console")
+        )
+        if command is None:
+            raise FileNotFoundError(
+                "Install mcp-console in this Python environment or pass command= explicitly"
+            )
+    return os.fspath(command), ["serve"] if args is None else [
+        os.fspath(arg) for arg in args
+    ]
+
+
+def content_text(content: ContentBlock) -> str:
+    if content.type == "text":
+        return content.text
+    if content.type == "image":
+        return f"[{content.mime_type} output]"
+    return content.model_dump_json(by_alias=True, exclude_none=True)
+
+
+def result_text(result: CallToolResult) -> str:
+    text = ""
+    for item in result.content:
+        part = content_text(item)
+        if text and part and not text.endswith("\n") and not part.startswith("\n"):
+            text += "\n"
+        text += part
+    if result.is_error:
+        raise RuntimeError(text or "MCP Console returned an error")
+    if (
+        isinstance(result.structured_content, dict)
+        and "requirements" in result.structured_content
+    ):
+        return json.dumps(result.structured_content, indent=2)
+    return text

mcp_console/_launcher.py

@@ -0,0 +1,32 @@
+"""Keep the Windows command bound to its installed native Console bundle."""
+
+from importlib.metadata import distribution
+import subprocess
+import sys
+
+
+def main() -> int:
+    native = next(
+        (
+            path.locate()
+            for path in distribution("mcp-console").files or ()
+            if path.parts[-2:] == ("libexec", "mcp-console.exe")
+        ),
+        None,
+    )
+    if native is None:
+        print("The installed native MCP Console executable is missing", file=sys.stderr)
+        return 1
+    # Private worker invocations carry explicitly inheritable native events
+    # and pipes. Keep those handles intact while forwarding the command.
+    with subprocess.Popen([str(native), *sys.argv[1:]], close_fds=False) as process:
+        while True:
+            try:
+                status = process.wait()
+                # Python's exit status accepts a signed Windows C int, while
+                # native exception/exit statuses retain all 32 bits.
+                return status if status < 2**31 else status - 2**32
+            except KeyboardInterrupt:
+                # Console control events already reach the native process.
+                # Retain ownership until its shutdown has finished.
+                continue

mcp_console/_sync.py

@@ -0,0 +1,290 @@
+import asyncio
+from collections.abc import Mapping, Sequence
+from concurrent.futures import Future
+from contextlib import ExitStack
+from threading import Condition, Event, Lock
+from typing import TYPE_CHECKING, Any, Literal, Self
+
+from ._client import AsyncMCPConsole, Requirements
+from ._common import Command, result_text
+
+_CANCELLATION_ERROR = (
+    "Request cancellation cleanup did not finish; "
+    "close and reconnect before reusing this connection"
+)
+_CANCELLATION_PENDING = (
+    "Request cancellation cleanup is in progress; wait before reusing this connection"
+)
+
+if TYPE_CHECKING:
+    from anyio.from_thread import BlockingPortal
+    from mcp.types import CallToolResult, Tool
+
+
+class _Request:
+    """Own one SDK call from queued admission through confirmed task retirement.
+
+    The host owns the response Future, so cancelling it never waits for the
+    event loop. SDK cancellation runs on the loop; the task's done callback
+    confirms retirement even if cancellation prevents its coroutine starting.
+    """
+
+    def __init__(
+        self,
+        loop: asyncio.AbstractEventLoop,
+        console: AsyncMCPConsole,
+        arguments: Mapping[str, Any],
+        *,
+        admission: Condition,
+    ) -> None:
+        self.future: Future["CallToolResult"] = Future()
+        self.finished = Event()
+        self._loop = loop
+        self._console = console
+        self._arguments = arguments
+        self._admission = admission
+        self._task: asyncio.Task["CallToolResult"] | None = None
+
+    def start(self) -> None:
+        self._loop.call_soon_threadsafe(self._start)
+
+    def _start(self) -> None:
+        with self._admission:
+            if self.future.cancelled():
+                self.finished.set()
+                return
+            self._task = self._loop.create_task(self._run())
+            self._task.add_done_callback(self._finish)
+
+    async def _run(self) -> "CallToolResult":
+        if self.future.cancelled():
+            raise asyncio.CancelledError
+        return await self._console._call_send(self._arguments)
+
+    def _finish(self, task: asyncio.Task["CallToolResult"]) -> None:
+        with self._admission:
+            try:
+                result = task.result()
+            except asyncio.CancelledError:
+                self.future.cancel()
+            except BaseException as error:
+                if not self.future.cancelled():
+                    self.future.set_exception(error)
+            else:
+                if not self.future.cancelled():
+                    self.future.set_result(result)
+            finally:
+                self.finished.set()
+                self._admission.notify_all()
+
+    def cancel(self) -> None:
+        with self._admission:
+            self.future.cancel()
+            if self._task is None:
+                # The queued start must check the same cancelled Future under
+                # admission, so it cannot create a task after this receipt.
+                self.finished.set()
+                return
+        self._loop.call_soon_threadsafe(self._cancel)
+
+    def _cancel(self) -> None:
+        if self._task is not None:
+            self._task.cancel()
+
+    def abort(self) -> None:
+        # Queue the abort behind the task step awakened by the first cancel,
+        # even when both host callbacks waited for a busy loop. Cancelling
+        # twice before that step coalesces instead of escaping SDK shielding.
+        self._loop.call_soon_threadsafe(self._loop.call_soon, self._cancel)
+
+
+class MCPConsole:
+    """A synchronous, persistent connection to ``mcp-console serve``.
+
+    Use as a context manager or explicitly call ``connect()`` and ``close()``.
+    The context starts Console and discovers its tools; leaving it closes the
+    connection and subprocess. Variables persist across calls on this connection.
+    The application owns its model clients, agents, and tool loops.
+
+    Calls block while the official MCP client runs on a background event loop.
+    Catching `KeyboardInterrupt` while waiting cancels that request's wait,
+    leaving an admitted cell running.
+    Poll to collect its output or send `control="interrupt"` to stop execution.
+    Connect and close only when no other call is in progress.
+
+    Args:
+        command: Console executable. Defaults to the installed `mcp-console`.
+        args: Server arguments. Defaults to `["serve"]`.
+        server_parameters: MCP stdio settings such as `cwd` and `env`.
+
+    Examples:
+        Install with `pip install 'mcp-console[client]'`. Define values in one
+        cell and use them in the next:
+
+        ```python
+        from mcp_console import MCPConsole
+
+        with MCPConsole() as console:
+            print(console.send(python="values = [12, 15, 18, 20, 25]; values"))
+            print(
+                console.send(
+                    python="import statistics; statistics.mean(values)"
+                )
+            )
+        ```
+
+        Create framework adapters inside this context, after discovery. See
+        [chatlas](chatlas.tool.html), [Anthropic](anthropic.tool.html),
+        [Responses](openai.responses_tool.html), or [Agents](openai.agents_tool.html).
+    """
+
+    def __init__(
+        self,
+        *,
+        command: Command | None = None,
+        args: Sequence[Command] | None = None,
+        server_parameters: Mapping[str, Any] | None = None,
+    ) -> None:
+        self._async = AsyncMCPConsole(
+            command=command, args=args, server_parameters=server_parameters
+        )
+        self._stack: ExitStack | None = None
+        self._portal: BlockingPortal | None = None
+        self._loop: asyncio.AbstractEventLoop | None = None
+        self._admission = Condition(Lock())
+        self._cancellation: _Request | None = None
+        self._cancellation_failed = False
+
+    def connect(self) -> "Self":
+        """Start MCP Console and initialize its MCP client session."""
+        if self._cancellation_failed:
+            raise RuntimeError(_CANCELLATION_ERROR)
+        if self._cancellation is not None:
+            raise RuntimeError(_CANCELLATION_PENDING)
+        if self._stack is None:
+            from anyio.from_thread import start_blocking_portal
+
+            with ExitStack() as stack:
+                portal = stack.enter_context(start_blocking_portal())
+                # The MCP transport must enter and exit in the same async task.
+                stack.enter_context(portal.wrap_async_context_manager(self._async))
+                self._portal = portal
+                self._loop = portal.call(asyncio.get_running_loop)
+                self._stack = stack.pop_all()
+        return self
+
+    def close(self) -> None:
+        """Close the MCP session, subprocess, and portal thread."""
+        stack = self._stack
+        if stack is not None:
+            if self._cancellation is not None and not self._cancellation.finished.wait(
+                timeout=5
+            ):
+                # Retain ownership rather than joining a request that still
+                # suppresses native cancellation or permitting a replacement.
+                raise RuntimeError(
+                    "Cancelled request did not stop; connection remains invalid"
+                )
+            try:
+                stack.close()
+            finally:
+                # ExitStack consumes all its callbacks even when teardown
+                # raises; the old portal must never look connected afterward.
+                self._stack = self._portal = self._loop = None
+                self._cancellation = None
+                self._cancellation_failed = False
+
+    def __enter__(self) -> "Self":
+        return self.connect()
+
+    def __exit__(self, exc_type: object, exc: object, traceback: object) -> None:
+        self.close()
+
+    def _call_send(self, arguments: Mapping[str, Any]) -> "CallToolResult":
+        request: _Request | None = None
+        try:
+            with self._admission:
+                try:
+                    if self._cancellation_failed:
+                        raise RuntimeError(_CANCELLATION_ERROR)
+                    if self._cancellation is not None:
+                        raise RuntimeError(_CANCELLATION_PENDING)
+                    if self._loop is None:
+                        raise RuntimeError(
+                            "MCPConsole is not connected; use `with MCPConsole() as console` "
+                            "or call `console.connect()` first"
+                        )
+                    request = _Request(
+                        self._loop, self._async, arguments, admission=self._admission
+                    )
+                    request.start()
+                    # Waiting releases admission for ordinary concurrent calls.
+                    # On interruption it reacquires admission before propagating,
+                    # so cancellation is published before another send can pass.
+                    self._admission.wait_for(request.future.done)
+                    return request.future.result()
+                except KeyboardInterrupt:
+                    if request is not None:
+                        self._cancellation = request
+                    raise
+        except KeyboardInterrupt:
+            if request is None:
+                raise
+            completed = False
+            try:
+                request.cancel()
+                completed = request.finished.wait(timeout=5)
+            finally:
+                with self._admission:
+                    if completed:
+                        self._cancellation = None
+                    else:
+                        self._cancellation_failed = True
+                        request.abort()
+            raise
+
+    def send(
+        self,
+        *,
+        r: str | None = None,
+        python: str | None = None,
+        sql: str | None = None,
+        control: Literal["interrupt", "restart"] | None = None,
+        requirements: Requirements | None = None,
+        stdin: str | None = None,
+        timeout_ms: int | None = None,
+    ) -> str:
+        """Run or control a cell on this connection and return its text output.
+
+        The arguments and polling behavior match
+        [AsyncMCPConsole.send()](AsyncMCPConsole.html#send). Send one language
+        per call. If output ends in `[running; poll with an empty send]`, collect
+        the remaining output with `console.send()` before submitting another cell.
+        Images appear as MIME placeholders; MCP tool errors raise `RuntimeError`.
+        """
+        arguments = {
+            "r": r,
+            "python": python,
+            "sql": sql,
+            "control": control,
+            "requirements": requirements,
+            "stdin": stdin,
+            "timeout_ms": timeout_ms,
+        }
+        return result_text(
+            self._call_send(
+                {name: value for name, value in arguments.items() if value is not None}
+            )
+        )
+
+    __call__ = send
+
+    @property
+    def send_tool(self) -> "Tool":
+        """The connected server's MCP tool definition, used by SDK adapters.
+
+        Available after connecting. Its input schema reflects the server's
+        configured capabilities. Use a framework adapter to register this
+        schema; recreate adapters after reconnecting.
+        """
+        return self._async.send_tool