mcp-toolsets-runtime 0.1.3__py3-none-any.whl

mcp_agent/elements/McpView.jsx

@@ -0,0 +1,89 @@
+// Renders a toolset's UI view in a sandboxed iframe and implements the *host*
+// end of the MCP Apps `ui/*` JSON-RPC-over-postMessage bridge (the same protocol
+// Claude, ChatGPT, Goose and VS Code speak; the view's end is the standard
+// @modelcontextprotocol/ext-apps SDK — see toolsets/*/ui/src/host.ts).
+//
+//   view "ui/initialize" (request)        -> we reply with host info + context
+//   view "ui/notifications/initialized"   -> we push tool-input then tool-result
+//   view "ui/message" (request)           -> sendUserMessage(), then reply {}
+//   view "ui/notifications/size-changed"  -> ignored (the panel frame is fixed)
+//
+// Props (from web.py): { html: the ui:// resource bundle, data: structuredContent }.
+// The bundle is rendered via srcdoc, so the frame has an opaque origin and needs
+// only allow-scripts — never allow-same-origin.
+import { useEffect, useRef } from "react";
+
+const PROTOCOL_VERSION = "2026-01-26"; // ext-apps LATEST_PROTOCOL_VERSION
+
+export default function McpView() {
+  const ref = useRef(null);
+  const { html, data } = props;
+  // Each turn mounts a fresh element, so data is stable per instance; hold it in
+  // a ref so the mount-once listener always sends the current value.
+  const dataRef = useRef(data);
+  dataRef.current = data;
+
+  useEffect(() => {
+    const iframe = ref.current;
+    if (!iframe) return;
+    const post = (message) => iframe.contentWindow?.postMessage(message, "*");
+
+    function onMessage(event) {
+      if (event.source !== iframe.contentWindow) return;
+      const message = event.data;
+      if (!message || message.jsonrpc !== "2.0") return;
+
+      if (message.method === "ui/initialize") {
+        post({
+          jsonrpc: "2.0",
+          id: message.id,
+          result: {
+            protocolVersion: PROTOCOL_VERSION,
+            hostInfo: { name: "chainlit-mcpview", version: "1.0.0" },
+            hostCapabilities: { message: { text: {} } },
+            hostContext: {},
+          },
+        });
+      } else if (message.method === "ui/notifications/initialized") {
+        // tool-input MUST precede tool-result per the spec; the view only needs
+        // the result, and we don't track the call's arguments here, so send an
+        // empty set to satisfy the ordering.
+        post({
+          jsonrpc: "2.0",
+          method: "ui/notifications/tool-input",
+          params: { arguments: {} },
+        });
+        post({
+          jsonrpc: "2.0",
+          method: "ui/notifications/tool-result",
+          params: { content: [], structuredContent: dataRef.current },
+        });
+      } else if (message.method === "ui/message" && message.id !== undefined) {
+        // content is a ContentBlock[]; join the text blocks into the user turn.
+        const text = (message.params?.content ?? [])
+          .filter((block) => block?.type === "text" && typeof block.text === "string")
+          .map((block) => block.text)
+          .join("");
+        if (text) sendUserMessage(text);
+        post({ jsonrpc: "2.0", id: message.id, result: {} });
+      }
+    }
+
+    window.addEventListener("message", onMessage);
+    return () => window.removeEventListener("message", onMessage);
+  }, []);
+
+  return (
+    <iframe
+      ref={ref}
+      srcDoc={html}
+      sandbox="allow-scripts"
+      style={{
+        width: "100%",
+        height: "100%",
+        border: "1px solid var(--border, #e4e7ec)",
+        borderRadius: 10,
+      }}
+    />
+  );
+}

mcp_agent/main.py

@@ -0,0 +1,376 @@
+"""Chat with every toolset behind an mcp-toolsets index URL.
+
+Point ``mcp-agent`` at an index root (anything serving a ``connections`` map
+shaped for ``MultiServerMCPClient``) or directly at a single MCP endpoint;
+it loads every server's tools and lets a chat model drive them in an
+interactive chat.
+
+The model is provider-agnostic and no provider ships by default: pick one by
+setting ``PROVIDER_MODEL`` to a ``provider:model`` string for LangChain's
+``init_chat_model`` (e.g. ``openai:gpt-4o-mini``,
+``anthropic:claude-3-5-haiku-latest``) and installing that provider's package
+(``uv add langchain-openai``). ``PROVIDER_API_KEY`` (the chosen provider's key)
+and ``PROVIDER_MODEL`` are read from the environment or a ``.env`` file.
+"""
+
+import asyncio
+from collections.abc import Iterator
+from contextlib import contextmanager
+from contextvars import ContextVar
+from importlib import resources
+from pathlib import Path
+from typing import Annotated, Any, cast
+
+import httpx
+import typer
+from langchain.agents import create_agent
+from langchain.chat_models import init_chat_model
+from mcp.client.streamable_http import create_mcp_http_client
+from mcp.shared.exceptions import McpError
+from langchain_core.messages import BaseMessage, HumanMessage
+from langchain_core.tools import BaseTool
+from langchain_mcp_adapters.client import MultiServerMCPClient
+from pydantic import Field, SecretStr, ValidationError
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from rich.console import Console
+from rich.markdown import Markdown
+
+# How to set PROVIDER_MODEL when it is missing; shown in the error message.
+PROVIDER_HELP = (
+    "Set PROVIDER_MODEL (e.g. openai:gpt-4o-mini) and PROVIDER_API_KEY in the "
+    "environment or .env, and install the provider package "
+    "(e.g. uv add langchain-openai)."
+)
+SYSTEM_PROMPT = (
+    "You are a helpful assistant with tools from one or more MCP toolsets. "
+    "Use them whenever they can ground your answer; otherwise answer directly."
+)
+
+app = typer.Typer(no_args_is_help=True, help=__doc__)
+console = Console()
+
+# Chainlit host elements shipped as package data (src/mcp_agent/elements/). The
+# web agent renders tool views via a Chainlit CustomElement Chainlit loads from
+# <app-root>/public/elements/, which defaults to ./public/elements relative to
+# where you launch it.
+HOST_ELEMENTS = ("McpView.jsx",)
+DEFAULT_ELEMENTS_DIR = Path("public/elements")
+
+
+def install_host_elements(target: Path) -> list[Path]:
+    """Copy the packaged Chainlit host element(s) into ``target``.
+
+    Returns the paths written. Deterministic and idempotent: it always writes
+    the version shipped with the installed package, so an upgrade + reinstall
+    refreshes the element with no drift. Meant to be run at build time (see the
+    ``install-elements`` command) rather than as a runtime side effect.
+    """
+    target.mkdir(parents=True, exist_ok=True)
+    source = resources.files("mcp_agent") / "elements"
+    written = []
+    for name in HOST_ELEMENTS:
+        dest = target / name
+        dest.write_text((source / name).read_text(encoding="utf-8"), encoding="utf-8")
+        written.append(dest)
+    return written
+
+
+class AgentSettings(BaseSettings):
+    """Agent configuration, validated from the environment or a .env file.
+
+    The CLI takes the URL and model as arguments; the web UI (``web.py``)
+    reads ``MCP_URL`` and ``PROVIDER_MODEL`` from here instead.
+    ``PROVIDER_MODEL`` and ``PROVIDER_API_KEY`` are required — there is no
+    default provider; ``PROVIDER_API_KEY`` is passed straight to
+    ``init_chat_model``.
+    """
+
+    model_config = SettingsConfigDict(env_file=".env", extra="ignore")
+
+    provider_api_key: SecretStr
+    provider_model: str
+    mcp_url: str = "http://localhost:8000/mcp"
+    chainlit_port: int = Field(default=8080, ge=1, le=65535)
+
+
+def connections_from(url: str, payload: Any) -> dict[str, Any]:
+    """Extract an index payload's connections map, else treat url as one server."""
+    if isinstance(payload, dict) and isinstance(payload.get("connections"), dict):
+        return payload["connections"]
+    return {"server": {"transport": "streamable_http", "url": url}}
+
+
+def credential_headers_from(payload: Any) -> dict[str, list[str]] | None:
+    """Per-toolset credential header names from an index payload.
+
+    ``None`` means the payload was not an index (a direct single-server URL),
+    so no declarations are available.
+    """
+    if not (isinstance(payload, dict) and isinstance(payload.get("toolsets"), list)):
+        return None
+    return {
+        entry["name"]: [
+            header.lower() for header in entry.get("credential_headers", [])
+        ]
+        for entry in payload["toolsets"]
+        if isinstance(entry, dict) and entry.get("name")
+    }
+
+
+# Connection failures an agent should report rather than crash on.
+CONNECT_ERRORS = (httpx.HTTPError, OSError, McpError)
+
+
+def first_leaf(error: BaseException) -> BaseException:
+    """Unwrap (possibly nested) ExceptionGroups to the first real exception."""
+    while isinstance(error, BaseExceptionGroup):
+        error = error.exceptions[0]
+    return error
+
+
+def connect_error_hint(url: str) -> str:
+    """A nudge for the most common misconfiguration: a missing /mcp path."""
+    if url.rstrip("/").endswith("/mcp"):
+        return ""
+    return (
+        " Hint: single-toolset servers serve MCP under /mcp "
+        "(e.g. http://localhost:8000/mcp); only an index is served at the root."
+    )
+
+
+def health_url_for(url: str) -> str | None:
+    """Derive a direct MCP endpoint's sibling /health URL, if there is one."""
+    base = url.rstrip("/")
+    return base.removesuffix("/mcp") + "/health" if base.endswith("/mcp") else None
+
+
+async def single_server_credential_headers(
+    client: httpx.AsyncClient, url: str
+) -> dict[str, list[str]] | None:
+    """Ask a direct MCP endpoint's /health which credential headers it reads.
+
+    Returns ``None`` when there is no health route or it doesn't advertise
+    credentials (e.g. a non-mcp-toolsets server).
+    """
+    health_url = health_url_for(url)
+    if health_url is None:
+        return None
+    try:
+        health = (await client.get(health_url)).json()
+        headers = health.get("credential_headers")
+    except (httpx.HTTPError, ValueError, AttributeError):
+        return None
+    if not isinstance(headers, list):
+        return None
+    return {"server": [str(header).lower() for header in headers]}
+
+
+async def fetch_connections(
+    url: str,
+) -> tuple[dict[str, Any], dict[str, list[str]] | None]:
+    """Resolve a URL to a MultiServerMCPClient config plus credential needs."""
+    async with httpx.AsyncClient(follow_redirects=True, timeout=10.0) as client:
+        try:
+            payload = (await client.get(url)).json()
+        except (httpx.HTTPError, ValueError):
+            payload = None
+        connections = connections_from(url, payload)
+        required = credential_headers_from(payload)
+        if required is None:
+            required = await single_server_credential_headers(client, url)
+    return connections, required
+
+
+_credentials: ContextVar[dict[str, str] | None] = ContextVar(
+    "user_credentials", default=None
+)
+
+
+@contextmanager
+def user_credentials(headers: dict[str, str] | None) -> Iterator[None]:
+    """Provide the calling user's credential headers for the duration.
+
+    This is how an agent passes a user's secrets to the tools without the
+    model ever seeing them: they ride the MCP transport, not the conversation.
+    The agent is built once; wrap each turn (``run_turn``) in this and the
+    tool calls made inside read the values at request time, so one long-lived
+    agent serves many users with different credentials.
+    """
+    token = _credentials.set(headers)
+    try:
+        yield
+    finally:
+        _credentials.reset(token)
+
+
+def credential_client_factory(allowed: list[str] | None) -> Any:
+    """Build an httpx client factory injecting the current user's credentials.
+
+    Only headers named in ``allowed`` (the toolset's advertised declaration)
+    are injected, so unrelated toolsets never receive them; ``None`` means no
+    declaration was discoverable (a server the user pointed at directly) and
+    every provided header is sent.
+    """
+    wanted = None if allowed is None else {header.lower() for header in allowed}
+
+    def factory(
+        headers: dict[str, str] | None = None,
+        timeout: httpx.Timeout | None = None,
+        auth: httpx.Auth | None = None,
+    ) -> httpx.AsyncClient:
+        provided = _credentials.get() or {}
+        send = {
+            header: value
+            for header, value in provided.items()
+            if wanted is None or header.lower() in wanted
+        }
+        return create_mcp_http_client(
+            headers={**(headers or {}), **send}, timeout=timeout, auth=auth
+        )
+
+    return factory
+
+
+def with_credential_support(
+    connections: dict[str, Any], required: dict[str, list[str]] | None
+) -> dict[str, Any]:
+    """Wire each connection to inject per-user credentials at call time."""
+    return {
+        name: {
+            **connection,
+            "httpx_client_factory": credential_client_factory(
+                None if required is None else required.get(name, [])
+            ),
+        }
+        for name, connection in connections.items()
+    }
+
+
+async def build_agent(
+    url: str, model: str, api_key: SecretStr
+) -> tuple[Any, dict[str, Any], list[BaseTool]]:
+    """Discover the servers behind ``url`` and build a tool-calling agent.
+
+    Built once per process/session: per-user credentials are not baked in but
+    read from :func:`user_credentials` on every tool call. ``model`` is a
+    ``provider:model`` string for :func:`init_chat_model` and ``api_key`` is
+    that provider's key, so the agent is provider-agnostic.
+    """
+    connections, required = await fetch_connections(url)
+    tools = await MultiServerMCPClient(
+        with_credential_support(connections, required)
+    ).get_tools()
+    agent = create_agent(
+        init_chat_model(model, api_key=api_key.get_secret_value()),
+        tools,
+        system_prompt=SYSTEM_PROMPT,
+    )
+    return agent, connections, tools
+
+
+async def run_turn(
+    agent: Any, messages: list[BaseMessage], text: str
+) -> tuple[list[BaseMessage], list[BaseMessage]]:
+    """Run one chat turn; return the full history and this turn's new messages."""
+    state = {"messages": [*messages, HumanMessage(text)]}
+    result = await agent.ainvoke(cast(Any, state))
+    history: list[BaseMessage] = result["messages"]
+    return history, history[len(messages) + 1 :]
+
+
+async def chat_loop(url: str, model: str, api_key: SecretStr) -> None:
+    try:
+        agent, connections, tools = await build_agent(url, model, api_key)
+    except* CONNECT_ERRORS as group:
+        console.print(
+            f"[red]Could not reach the MCP server(s) behind {url}: "
+            f"{first_leaf(group)}[/red]"
+        )
+        if hint := connect_error_hint(url):
+            console.print(f"[yellow]{hint.strip()}[/yellow]")
+        raise typer.Exit(1) from None
+
+    console.print(
+        f"Connected to [bold]{len(connections)}[/bold] server(s): "
+        f"{', '.join(connections)}"
+    )
+    console.print(f"[dim]{len(tools)} tools: {', '.join(t.name for t in tools)}[/dim]")
+    console.print("[dim]Type a message, or quit to exit.[/dim]")
+
+    messages: list[BaseMessage] = []
+    while True:
+        try:
+            line = console.input("[bold cyan]you>[/bold cyan] ").strip()
+        except (EOFError, KeyboardInterrupt):
+            break
+        if not line:
+            continue
+        if line in ("quit", "exit"):
+            break
+        try:
+            messages, new_messages = await run_turn(agent, messages, line)
+        except Exception as error:  # noqa: BLE001 - keep the chat alive
+            console.print(f"[red]{error}[/red]")
+            continue
+        for message in new_messages:
+            for call in getattr(message, "tool_calls", None) or []:
+                console.print(f"[dim]→ {call['name']} {call['args']}[/dim]")
+        console.print(Markdown(str(messages[-1].content)))
+
+
+@app.command()
+def chat(
+    url: Annotated[
+        str | None,
+        typer.Argument(
+            help="Index URL serving a connections map, or a single MCP endpoint. "
+            "Defaults to MCP_URL from the environment / .env.",
+        ),
+    ] = None,
+    model: Annotated[
+        str | None,
+        typer.Option(
+            "--model",
+            help="Chat model as provider:model (e.g. openai:gpt-4o-mini). "
+            "Overrides PROVIDER_MODEL from the environment / .env.",
+        ),
+    ] = None,
+) -> None:
+    """Discover the MCP servers behind URL and chat with their tools.
+
+    URL and model are read from the environment / .env (the same place as
+    PROVIDER_API_KEY) when omitted, so the agent can be configured entirely
+    by a .env file; CLI arguments override it.
+    """
+    try:
+        settings = AgentSettings(provider_model=model) if model else AgentSettings()
+    except ValidationError:
+        console.print(f"[red]{PROVIDER_HELP}[/red]")
+        raise typer.Exit(1) from None
+    asyncio.run(
+        chat_loop(
+            url or settings.mcp_url, settings.provider_model, settings.provider_api_key
+        )
+    )
+
+
+@app.command("install-elements")
+def install_elements(
+    target: Annotated[
+        Path,
+        typer.Argument(
+            help="Directory to install the Chainlit host element(s) into, "
+            "typically your app root's public/elements.",
+        ),
+    ] = DEFAULT_ELEMENTS_DIR,
+) -> None:
+    """Copy the packaged Chainlit host element(s) into a chainlit app root.
+
+    The web agent (``mcp-agent-web``) renders tool views via a Chainlit
+    CustomElement named "McpView", which Chainlit loads from
+    ``<app-root>/public/elements/``. Run this at build time — e.g. in your
+    Dockerfile: ``RUN mcp-agent install-elements`` — so the element is present
+    without the package writing to your filesystem at runtime.
+    """
+    for dest in install_host_elements(target):
+        console.print(f"[green]installed[/green] {dest}")