reflex-mcphost 0.1.0__py3-none-any.whl

reflex_mcphost/__init__.py

@@ -0,0 +1,296 @@
+"""reflex-mcphost: an open MCP host built with Reflex (public API re-exports, API Spec §3.6).
+
+The public names are resolved lazily (PEP 562) so ``import reflex_mcphost`` stays cheap and
+pulls in neither the MCP SDK nor SQLite until a name is first used.
+"""
+
+from __future__ import annotations
+
+import logging
+from importlib import import_module
+from importlib.metadata import PackageNotFoundError, version
+from typing import TYPE_CHECKING, Any
+
+# Libraries never configure output (REQ-NFR-040): applications attach their own handlers.
+logging.getLogger(__name__).addHandler(logging.NullHandler())
+
+try:
+    __version__: str = version("reflex-mcphost")
+except PackageNotFoundError:  # pragma: no cover - running from a source tree without metadata
+    __version__ = "0.0.0"
+
+_EXPORTS: dict[str, str] = {
+    # facade and configuration (API §4.1-4.3)
+    "Host": "reflex_mcphost.core.host",
+    "HostConfig": "reflex_mcphost.core.config.models",
+    "ServerDefinition": "reflex_mcphost.core.config.models",
+    "StdioTransport": "reflex_mcphost.core.config.models",
+    "HttpTransport": "reflex_mcphost.core.config.models",
+    "OAuthSettings": "reflex_mcphost.core.config.models",
+    "ConfigOrigin": "reflex_mcphost.core.config.models",
+    "SourceKind": "reflex_mcphost.core.config.models",
+    "ShadowedDefinition": "reflex_mcphost.core.config.models",
+    "ConfigProblem": "reflex_mcphost.core.config.models",
+    "ConfigProblemCode": "reflex_mcphost.core.config.models",
+    "RegistryDiff": "reflex_mcphost.core.config.models",
+    "ServerRegistry": "reflex_mcphost.core.registry",
+    # connections (API §4.5)
+    "ConnectionManager": "reflex_mcphost.core.connection.manager",
+    "ServerState": "reflex_mcphost.core.connection.state",
+    "ServerStatus": "reflex_mcphost.core.connection.state",
+    "LogEntry": "reflex_mcphost.core.connection.stderr",
+    # catalog (API §4.6)
+    "Catalog": "reflex_mcphost.core.catalog",
+    "ToolEntry": "reflex_mcphost.core.catalog",
+    "ResourceEntry": "reflex_mcphost.core.catalog",
+    "ResourceTemplateEntry": "reflex_mcphost.core.catalog",
+    "PromptEntry": "reflex_mcphost.core.catalog",
+    "ResourceContents": "reflex_mcphost.core.catalog",
+    "PromptResult": "reflex_mcphost.core.catalog",
+    # identifiers and consumers (API §3.3, §4.4)
+    "Consumer": "reflex_mcphost.core.types",
+    "ConsumerKind": "reflex_mcphost.core.types",
+    "Fqn": "reflex_mcphost.core.types",
+    # human-in-the-loop seam (API §4.10; Phase 2 subset)
+    "Prompter": "reflex_mcphost.core.prompter",
+    "TrustRequest": "reflex_mcphost.core.prompter",
+    # events (API §4.11)
+    "EventBus": "reflex_mcphost.core.events",
+    "HostEvent": "reflex_mcphost.core.events",
+    "ServerStateChanged": "reflex_mcphost.core.events",
+    "RegistryChanged": "reflex_mcphost.core.events",
+    "CatalogChanged": "reflex_mcphost.core.events",
+    "ResourceUpdated": "reflex_mcphost.core.events",
+    "ServerLog": "reflex_mcphost.core.events",
+    "EventsDropped": "reflex_mcphost.core.events",
+    # consent, invoker, audit (API §4.7-§4.9) and their events (§4.11)
+    "AuditLog": "reflex_mcphost.core.audit",
+    "AuditPage": "reflex_mcphost.core.audit",
+    "AuditQuery": "reflex_mcphost.core.audit",
+    "AuditRecord": "reflex_mcphost.core.audit",
+    "ConsentAnswer": "reflex_mcphost.core.consent.models",
+    "ConsentDecision": "reflex_mcphost.core.consent.models",
+    "ConsentOutcome": "reflex_mcphost.core.consent.outcome",
+    "ConsentPolicy": "reflex_mcphost.core.consent.policy",
+    "ConsentRequest": "reflex_mcphost.core.consent.models",
+    "ConsentRequested": "reflex_mcphost.core.events",
+    "ConsentResolved": "reflex_mcphost.core.events",
+    "ConsentRulesChanged": "reflex_mcphost.core.events",
+    "ConsentRule": "reflex_mcphost.core.consent.models",
+    "ConsentTarget": "reflex_mcphost.core.consent.models",
+    "InvocationError": "reflex_mcphost.core.invoker",
+    "InvocationFinished": "reflex_mcphost.core.events",
+    "InvocationHandle": "reflex_mcphost.core.invoker",
+    "InvocationOutcome": "reflex_mcphost.core.outcomes",
+    "InvocationProgress": "reflex_mcphost.core.events",
+    "InvocationResult": "reflex_mcphost.core.invoker",
+    "InvocationStarted": "reflex_mcphost.core.events",
+    "Invoker": "reflex_mcphost.core.invoker",
+    "OperationKind": "reflex_mcphost.core.consent.outcome",
+    "Progress": "reflex_mcphost.core.outcomes",
+    # OAuth flow and sampling seam (API §4.5, §4.14)
+    "AuthorizationFlow": "reflex_mcphost.core.auth.flow",
+    "SamplingProvider": "reflex_mcphost.core.handlers.sampling",
+    # errors (API §3.4)
+    "AuditUnavailableError": "reflex_mcphost.core.audit",
+    "AuditRecordNotFoundError": "reflex_mcphost.core.audit",
+    "ConsentStoreError": "reflex_mcphost.core.consent.store",
+    "UnknownRuleError": "reflex_mcphost.core.consent.store",
+    "MCPHostError": "reflex_mcphost.core.errors",
+    "ConfigError": "reflex_mcphost.core.errors",
+    "UnknownServerError": "reflex_mcphost.core.errors",
+    "UnknownEntryError": "reflex_mcphost.core.errors",
+    "ServerUnavailableError": "reflex_mcphost.core.errors",
+    "CapabilityNotSupportedError": "reflex_mcphost.core.errors",
+    "AuthorizationError": "reflex_mcphost.core.errors",
+    "ServerRequestError": "reflex_mcphost.core.errors",
+    "SecretStoreError": "reflex_mcphost.core.errors",
+    "HostClosedError": "reflex_mcphost.core.errors",
+    "InputRequestError": "reflex_mcphost.core.errors",
+    "UnknownToolError": "reflex_mcphost.core.errors",
+}
+
+__all__ = [
+    "AuditLog",
+    "AuditPage",
+    "AuditQuery",
+    "AuditRecord",
+    "AuditRecordNotFoundError",
+    "AuditUnavailableError",
+    "AuthorizationError",
+    "AuthorizationFlow",
+    "CapabilityNotSupportedError",
+    "Catalog",
+    "CatalogChanged",
+    "ConfigError",
+    "ConfigOrigin",
+    "ConfigProblem",
+    "ConfigProblemCode",
+    "ConnectionManager",
+    "ConsentAnswer",
+    "ConsentDecision",
+    "ConsentOutcome",
+    "ConsentPolicy",
+    "ConsentRequest",
+    "ConsentRequested",
+    "ConsentResolved",
+    "ConsentRule",
+    "ConsentRulesChanged",
+    "ConsentStoreError",
+    "ConsentTarget",
+    "Consumer",
+    "ConsumerKind",
+    "EventBus",
+    "EventsDropped",
+    "Fqn",
+    "Host",
+    "HostClosedError",
+    "HostConfig",
+    "HostEvent",
+    "HttpTransport",
+    "InputRequestError",
+    "InvocationError",
+    "InvocationFinished",
+    "InvocationHandle",
+    "InvocationOutcome",
+    "InvocationProgress",
+    "InvocationResult",
+    "InvocationStarted",
+    "Invoker",
+    "LogEntry",
+    "MCPHostError",
+    "OAuthSettings",
+    "OperationKind",
+    "Progress",
+    "PromptEntry",
+    "PromptResult",
+    "Prompter",
+    "RegistryChanged",
+    "RegistryDiff",
+    "ResourceContents",
+    "ResourceEntry",
+    "ResourceTemplateEntry",
+    "ResourceUpdated",
+    "SamplingProvider",
+    "SecretStoreError",
+    "ServerDefinition",
+    "ServerLog",
+    "ServerRegistry",
+    "ServerRequestError",
+    "ServerState",
+    "ServerStateChanged",
+    "ServerStatus",
+    "ServerUnavailableError",
+    "ShadowedDefinition",
+    "SourceKind",
+    "StdioTransport",
+    "ToolEntry",
+    "TrustRequest",
+    "UnknownEntryError",
+    "UnknownRuleError",
+    "UnknownServerError",
+    "UnknownToolError",
+    "__version__",
+]
+"""Kept literal for static tools; equal to ``_EXPORTS`` plus ``__version__`` (tested)."""
+
+if TYPE_CHECKING:  # pragma: no cover - static re-exports for type checkers and IDEs
+    from reflex_mcphost.core.audit import (
+        AuditLog,
+        AuditPage,
+        AuditQuery,
+        AuditRecord,
+        AuditRecordNotFoundError,
+        AuditUnavailableError,
+    )
+    from reflex_mcphost.core.auth.flow import AuthorizationFlow
+    from reflex_mcphost.core.catalog import (
+        Catalog,
+        PromptEntry,
+        PromptResult,
+        ResourceContents,
+        ResourceEntry,
+        ResourceTemplateEntry,
+        ToolEntry,
+    )
+    from reflex_mcphost.core.config.models import (
+        ConfigOrigin,
+        ConfigProblem,
+        ConfigProblemCode,
+        HostConfig,
+        HttpTransport,
+        OAuthSettings,
+        RegistryDiff,
+        ServerDefinition,
+        ShadowedDefinition,
+        SourceKind,
+        StdioTransport,
+    )
+    from reflex_mcphost.core.connection.manager import ConnectionManager
+    from reflex_mcphost.core.connection.state import ServerState, ServerStatus
+    from reflex_mcphost.core.connection.stderr import LogEntry
+    from reflex_mcphost.core.consent.models import (
+        ConsentAnswer,
+        ConsentDecision,
+        ConsentRequest,
+        ConsentRule,
+        ConsentTarget,
+    )
+    from reflex_mcphost.core.consent.outcome import ConsentOutcome, OperationKind
+    from reflex_mcphost.core.consent.policy import ConsentPolicy
+    from reflex_mcphost.core.consent.store import ConsentStoreError, UnknownRuleError
+    from reflex_mcphost.core.errors import (
+        AuthorizationError,
+        CapabilityNotSupportedError,
+        ConfigError,
+        HostClosedError,
+        InputRequestError,
+        MCPHostError,
+        SecretStoreError,
+        ServerRequestError,
+        ServerUnavailableError,
+        UnknownEntryError,
+        UnknownServerError,
+        UnknownToolError,
+    )
+    from reflex_mcphost.core.events import (
+        CatalogChanged,
+        ConsentRequested,
+        ConsentResolved,
+        ConsentRulesChanged,
+        EventBus,
+        EventsDropped,
+        HostEvent,
+        InvocationFinished,
+        InvocationProgress,
+        InvocationStarted,
+        RegistryChanged,
+        ResourceUpdated,
+        ServerLog,
+        ServerStateChanged,
+    )
+    from reflex_mcphost.core.handlers.sampling import SamplingProvider
+    from reflex_mcphost.core.host import Host
+    from reflex_mcphost.core.invoker import (
+        InvocationError,
+        InvocationHandle,
+        InvocationResult,
+        Invoker,
+    )
+    from reflex_mcphost.core.outcomes import InvocationOutcome, Progress
+    from reflex_mcphost.core.prompter import Prompter, TrustRequest
+    from reflex_mcphost.core.registry import ServerRegistry
+    from reflex_mcphost.core.types import Consumer, ConsumerKind, Fqn
+
+
+def __getattr__(name: str) -> Any:
+    module = _EXPORTS.get(name)
+    if module is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    value = getattr(import_module(module), name)
+    globals()[name] = value  # cache: later lookups skip __getattr__
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted(__all__)

reflex_mcphost/adapters/__init__.py

@@ -0,0 +1 @@
+"""Optional agent-framework adapters, installed as extras (API §4.13)."""

reflex_mcphost/adapters/langgraph.py

@@ -0,0 +1,77 @@
+"""LangChain/LangGraph adapter (extra ``langgraph``; REQ-TLS-007, API §4.13, spike S-6).
+
+``as_langchain_tools(toolset)`` returns one ``HostTool`` per ``Toolset.list()`` entry. The
+tools are a snapshot: call it again after ``catalog.changed`` (API §4.13). ``HostTool`` is a
+direct ``langchain_core.tools.BaseTool`` subclass (Art. 2) — not ``StructuredTool``, which
+drops or overrides arguments named ``config``/``run_manager`` and fails on ``self`` (S-6):
+the parsed argument dict is passed to ``_arun`` as one positional argument and ``_arun``
+declares neither ``config`` nor ``run_manager``, so LangChain injects nothing. The dict
+``args_schema`` is the Server's input schema unchanged; LangChain does not validate it,
+the Host's Invoker does (REQ-INV-002). Every error outcome, and an alias gone since the
+snapshot (``UnknownToolError`` — only that error; any other ``KeyError`` propagates), is
+raised as ``ToolException(text)`` and, with ``handle_tool_error=True``, becomes
+``ToolMessage(status="error")`` — LangGraph's ``ToolNode`` re-raises any other exception and
+fails the graph (REQ-TLS-005). Only ``langchain_core`` is imported; effects go only through
+``Toolset.call`` (Art. 3).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+try:
+    from langchain_core.tools import BaseTool, ToolException
+except ImportError as exc:  # pragma: no cover - exercised in a subprocess (F5-05)
+    raise ImportError(
+        "reflex_mcphost.adapters.langgraph needs the 'langgraph' extra: "
+        "pip install 'reflex-mcphost[langgraph]'"
+    ) from exc
+
+from pydantic import Field
+
+from reflex_mcphost.toolset import Toolset, UnknownToolError
+
+__all__ = ["as_langchain_tools"]
+
+ASYNC_ONLY = "reflex-mcphost tools are async-only; use ainvoke"
+
+
+class HostTool(BaseTool):
+    """One Host tool as a LangChain tool (async-only)."""
+
+    toolset: Toolset = Field(exclude=True)
+    handle_tool_error: Any = True
+
+    def _to_args_and_kwargs(
+        self, tool_input: str | dict[str, Any], tool_call_id: str | None
+    ) -> tuple[tuple[Any, ...], dict[str, Any]]:
+        parsed = self._parse_input(tool_input, tool_call_id)
+        if not isinstance(parsed, dict):  # a str input is rejected by _parse_input already
+            raise ToolException(f"{self.name} takes a JSON object of arguments")
+        return (dict(parsed),), {}
+
+    def _run(self, *args: Any, **kwargs: Any) -> str:
+        raise NotImplementedError(ASYNC_ONLY)
+
+    async def _arun(self, arguments: dict[str, Any]) -> str:
+        try:
+            outcome = await self.toolset.call(self.name, arguments)
+        except UnknownToolError:  # only a vanished alias; any other KeyError propagates
+            raise ToolException(f"Tool is no longer available: {self.name}") from None
+        if outcome.is_error:
+            raise ToolException(outcome.text)
+        return outcome.text
+
+
+def as_langchain_tools(toolset: Toolset) -> list[BaseTool]:
+    """Snapshot ``toolset`` as LangChain tools (e.g. for ``langgraph.prebuilt.ToolNode``)."""
+    return [
+        HostTool(
+            name=spec.name,
+            description=spec.description,
+            args_schema=spec.input_schema,
+            metadata={"fqn": str(spec.fqn)},
+            toolset=toolset,
+        )
+        for spec in toolset.list()
+    ]

reflex_mcphost/adapters/pydantic_ai.py

@@ -0,0 +1,90 @@
+"""PydanticAI adapter (extra ``pydantic-ai``; REQ-TLS-006, API §4.13, spike S-6).
+
+``as_pydantic_ai_toolset(toolset)`` returns a ``HostToolset``, a subclass of PydanticAI's
+own ``AbstractToolset`` (Art. 2). PydanticAI calls ``get_tools`` before every model request
+and the adapter re-reads ``Toolset.list()`` each time, so catalog changes show up within a
+run (REQ-TLS-004). Arguments are accepted as any JSON object: the Host's Invoker validates
+them against the tool's input schema (REQ-INV-002), as PydanticAI's own ``MCPToolset`` leaves
+validation to the server. Every error outcome — and an alias that vanished since the
+listing (``UnknownToolError``) — is raised as ``ToolFailed(text)``, which PydanticAI returns
+to the model as a failed tool result without spending the retry budget (REQ-TLS-005). Any
+other exception, including a plain ``KeyError``, is a bug and propagates. Effects go only
+through ``Toolset.call`` (Art. 3).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+try:
+    import pydantic_core
+    from pydantic_ai import RunContext, ToolFailed
+    from pydantic_ai.tools import ToolDefinition
+    from pydantic_ai.toolsets import AbstractToolset, ToolsetTool
+except ImportError as exc:  # pragma: no cover - exercised in a subprocess (F5-05)
+    raise ImportError(
+        "reflex_mcphost.adapters.pydantic_ai needs the 'pydantic-ai' extra: "
+        "pip install 'reflex-mcphost[pydantic-ai]'"
+    ) from exc
+
+from reflex_mcphost.toolset import Toolset, UnknownToolError
+
+__all__ = ["as_pydantic_ai_toolset"]
+
+_ANY_OBJECT = pydantic_core.SchemaValidator(
+    pydantic_core.core_schema.dict_schema(
+        pydantic_core.core_schema.str_schema(), pydantic_core.core_schema.any_schema()
+    )
+)
+"""Accept any JSON object; the Invoker validates against the tool's input schema."""
+
+
+class HostToolset(AbstractToolset[Any]):
+    """The Host's tools as a PydanticAI toolset (one per ``Toolset``)."""
+
+    def __init__(self, toolset: Toolset) -> None:
+        self._toolset = toolset
+
+    @property
+    def id(self) -> str | None:
+        """No id: durable execution (which needs one) is out of scope (API §4.13)."""
+        return None
+
+    @property
+    def toolset(self) -> Toolset:
+        """The wrapped framework-neutral Toolset."""
+        return self._toolset
+
+    async def get_tools(self, ctx: RunContext[Any]) -> dict[str, ToolsetTool[Any]]:
+        """The current listing, re-read on every run step (REQ-TLS-004)."""
+        return {
+            spec.name: ToolsetTool(
+                toolset=self,
+                tool_def=ToolDefinition(
+                    name=spec.name,
+                    description=spec.description,
+                    parameters_json_schema=spec.input_schema,
+                    metadata={"fqn": str(spec.fqn)},
+                ),
+                max_retries=1,
+                args_validator=_ANY_OBJECT,
+            )
+            for spec in self._toolset.list()
+        }
+
+    async def call_tool(
+        self, name: str, tool_args: dict[str, Any], ctx: RunContext[Any], tool: ToolsetTool[Any]
+    ) -> Any:
+        """Invoke through ``Toolset.call``; error outcomes raise ``ToolFailed(text)``."""
+        try:
+            outcome = await self._toolset.call(name, tool_args)
+        except UnknownToolError:  # only a vanished alias; any other KeyError propagates
+            raise ToolFailed(f"Tool is no longer available: {name}") from None
+        if outcome.is_error:
+            raise ToolFailed(outcome.text)
+        return outcome.text
+
+
+def as_pydantic_ai_toolset(toolset: Toolset) -> AbstractToolset[Any]:
+    """Expose ``toolset`` as a PydanticAI toolset: ``Agent(model, toolsets=[it])``."""
+    return HostToolset(toolset)

reflex_mcphost/app/__init__.py

@@ -0,0 +1 @@
+"""Reference app and CLI (`reflex-mcphost`)."""