protogrid-sdk 0.2.0__tar.gz

protogrid_sdk-0.2.0/.gitignore

@@ -0,0 +1,7 @@
+node_modules/
+dist/
+.venv/
+__pycache__/
+*.tsbuildinfo
+pnpm-lock.yaml
+.mcp-tokens.json

protogrid_sdk-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 protogrid contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

protogrid_sdk-0.2.0/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.5
+Name: protogrid-sdk
+Version: 0.2.0
+Summary: Client for the protogrid MCP registry: find servers by intent, get a connection block, connect with no human in the loop.
+Project-URL: Homepage, https://protogrid.dev
+Project-URL: Documentation, https://docs.protogrid.dev/sdk/python/
+Project-URL: Repository, https://github.com/protogrid-dev/sdk
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.20; extra == 'mcp'
+Provides-Extra: pydantic-ai
+Requires-Dist: pydantic-ai>=1.0; extra == 'pydantic-ai'
+Description-Content-Type: text/markdown
+
+# protogrid (Python)
+
+Client for the protogrid registry: find MCP servers by intent, get a machine-readable connection
+block, and connect with no human in the loop wherever the server allows it.
+
+```python
+import os
+from protogrid import ProtogridClient, find_connectable, open_session
+
+registry = ProtogridClient()  # public registry; ProtogridClient("http://localhost:8080") for a local stack
+found = find_connectable(registry, "send an email", secrets=os.environ)
+async with open_session(found.connection, os.environ) as session:   # mcp.ClientSession, initialized
+    tools = await session.list_tools()
+```
+
+- `ProtogridClient` / `AsyncProtogridClient`: `search`, `get_server`, `list_tools`, `list_all_tools`, `get_connection`.
+- No key needed. A free key from https://protogrid.dev/account raises the limits (60 requests per minute, 5,000 per day); the client reads `PROTOGRID_API_KEY`, or pass `ProtogridClient(api_key=...)`.
+- Connection blocks carry `${NAME}` placeholders; `substitute_secrets` fills them from your own store. The registry never sees secret values.
+- `connection_class`: **R0** remote, no auth · **R1** remote, static secret you hold · **R2** remote OAuth (one consent) · **L0** local package (`allow_local=True`) · `unknown`.
+- R2: `open_session(conn, oauth=OAuthOptions(store, consent))` runs the one-time consent (`loopback_consent` or `manual_consent`) through the official SDK's OAuth provider and keeps tokens in your `TokenStore`; later runs need no human.
+- PydanticAI: `to_pydantic_ai(conn, secrets)` returns an `MCPToolset`. `to_fastmcp_transport` and `to_mcp_servers` are pure formatters.
+- Install: `pip install protogrid-sdk` (imported as `protogrid`). Extras: `protogrid-sdk[mcp]` for `open_session`, `protogrid-sdk[pydantic-ai]` for the toolset.
+
+Examples: `examples/find_and_call.py` (search → connect → call a tool) and `examples/pydantic_ai_agent.py` (agent with a registry-found toolset, no LLM key needed).

protogrid_sdk-0.2.0/README.md

@@ -0,0 +1,24 @@
+# protogrid (Python)
+
+Client for the protogrid registry: find MCP servers by intent, get a machine-readable connection
+block, and connect with no human in the loop wherever the server allows it.
+
+```python
+import os
+from protogrid import ProtogridClient, find_connectable, open_session
+
+registry = ProtogridClient()  # public registry; ProtogridClient("http://localhost:8080") for a local stack
+found = find_connectable(registry, "send an email", secrets=os.environ)
+async with open_session(found.connection, os.environ) as session:   # mcp.ClientSession, initialized
+    tools = await session.list_tools()
+```
+
+- `ProtogridClient` / `AsyncProtogridClient`: `search`, `get_server`, `list_tools`, `list_all_tools`, `get_connection`.
+- No key needed. A free key from https://protogrid.dev/account raises the limits (60 requests per minute, 5,000 per day); the client reads `PROTOGRID_API_KEY`, or pass `ProtogridClient(api_key=...)`.
+- Connection blocks carry `${NAME}` placeholders; `substitute_secrets` fills them from your own store. The registry never sees secret values.
+- `connection_class`: **R0** remote, no auth · **R1** remote, static secret you hold · **R2** remote OAuth (one consent) · **L0** local package (`allow_local=True`) · `unknown`.
+- R2: `open_session(conn, oauth=OAuthOptions(store, consent))` runs the one-time consent (`loopback_consent` or `manual_consent`) through the official SDK's OAuth provider and keeps tokens in your `TokenStore`; later runs need no human.
+- PydanticAI: `to_pydantic_ai(conn, secrets)` returns an `MCPToolset`. `to_fastmcp_transport` and `to_mcp_servers` are pure formatters.
+- Install: `pip install protogrid-sdk` (imported as `protogrid`). Extras: `protogrid-sdk[mcp]` for `open_session`, `protogrid-sdk[pydantic-ai]` for the toolset.
+
+Examples: `examples/find_and_call.py` (search → connect → call a tool) and `examples/pydantic_ai_agent.py` (agent with a registry-found toolset, no LLM key needed).

protogrid_sdk-0.2.0/examples/find_and_call.py

@@ -0,0 +1,66 @@
+"""End to end, no human: find a server for an intent, connect, call a tool you did not know existed.
+
+    uv run python examples/find_and_call.py "get the current weather for a city" Madrid
+
+Uses the public registry; set REGISTRY_URL=http://localhost:8080 for a local stack.
+Secrets for R1 servers come from the environment: any ${NAME} placeholder is read from os.environ[NAME].
+"""
+from __future__ import annotations
+
+import asyncio
+import os
+import sys
+
+from protogrid import ProtogridClient, find_connectable, open_session
+
+
+def args_for(schema: dict, string_value: str) -> dict | None:
+    out: dict = {}
+    props = schema.get("properties") or {}
+    for r in schema.get("required") or []:
+        p = props.get(r) or {}
+        if "default" in p:
+            out[r] = p["default"]
+        elif p.get("enum"):
+            out[r] = p["enum"][0]
+        elif p.get("type") == "string":
+            out[r] = string_value
+        elif p.get("type") in ("number", "integer"):
+            out[r] = 1
+        elif p.get("type") == "boolean":
+            out[r] = True
+        else:
+            return None
+    return out
+
+
+async def main() -> int:
+    intent = sys.argv[1] if len(sys.argv) > 1 else "get the current weather for a city"
+    string_value = sys.argv[2] if len(sys.argv) > 2 else intent
+    registry = ProtogridClient(**({"base_url": os.environ["REGISTRY_URL"]} if os.environ.get("REGISTRY_URL") else {}))
+    found = find_connectable(registry, intent, secrets=os.environ)
+    if not found:
+        print(f'nothing autonomous found for "{intent}"')
+        return 1
+    r = found.result
+    print(f"→ {r['name']} ({r['connection_class']}, trust {r['trust_score']}); matched: {', '.join(t['name'] for t in r['matched_tools']) or 'server text'}")
+    async with open_session(found.connection, os.environ) as session:
+        tools = (await session.list_tools()).tools
+        print(f"connected; {len(tools)} tools: {', '.join(t.name for t in tools[:8])}{', …' if len(tools) > 8 else ''}")
+        matched = [t for m in r["matched_tools"] for t in tools if t.name == m["name"]]
+        for t in [*matched, *tools]:
+            a = args_for(getattr(t, "input_schema", None) or getattr(t, "inputSchema", None) or {}, string_value)
+            if a is None:
+                continue
+            print(f"calling {t.name} with {a}")
+            out = await session.call_tool(t.name, a)
+            text = "\n".join(getattr(c, "text", "") for c in out.content)
+            print("tool error:" if getattr(out, "is_error", getattr(out, "isError", False)) else "result:", text[:600])
+            break
+        else:
+            print("no tool callable without more information; stopping here")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(asyncio.run(main()))

protogrid_sdk-0.2.0/examples/pydantic_ai_agent.py

@@ -0,0 +1,43 @@
+"""PydanticAI flagship: a registry-found MCP server becomes a toolset of an agent.
+
+    uv run python examples/pydantic_ai_agent.py "get the current weather for a city"
+
+Uses the public registry; set REGISTRY_URL=http://localhost:8080 for a local stack.
+Uses PydanticAI's TestModel so it runs without an LLM key; swap the model for a real one to let the
+model choose and call the tools. R1 secrets come from the environment.
+"""
+from __future__ import annotations
+
+import asyncio
+import os
+import sys
+
+from pydantic_ai import Agent
+from pydantic_ai.messages import ToolCallPart
+from pydantic_ai.models.test import TestModel
+
+from protogrid import ProtogridClient, find_connectable, to_pydantic_ai
+
+
+async def main() -> int:
+    intent = sys.argv[1] if len(sys.argv) > 1 else "get the current weather for a city"
+    registry = ProtogridClient(**({"base_url": os.environ["REGISTRY_URL"]} if os.environ.get("REGISTRY_URL") else {}))
+    found = find_connectable(registry, intent, secrets=os.environ)
+    if not found:
+        print(f'nothing autonomous found for "{intent}"')
+        return 1
+    print(f"→ {found.result['name']} ({found.result['connection_class']}, trust {found.result['trust_score']})")
+    toolset = to_pydantic_ai(found.connection, os.environ)
+    # TestModel calls every available tool once with schema-derived arguments, so the run shows
+    # the agent using tools it learned about from the registry, with no LLM key.
+    agent = Agent(TestModel(), toolsets=[toolset])
+    async with agent:
+        result = await agent.run(intent)
+    calls = [p for m in result.all_messages() for p in m.parts if isinstance(p, ToolCallPart)]
+    print(f"agent called {len(calls)} registry-found tools: {', '.join(c.tool_name for c in calls)}")
+    print("run finished:", str(result.output)[:160])
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(asyncio.run(main()))

protogrid_sdk-0.2.0/pyproject.toml

@@ -0,0 +1,34 @@
+[project]
+name = "protogrid-sdk"
+version = "0.2.0"
+description = "Client for the protogrid MCP registry: find servers by intent, get a connection block, connect with no human in the loop."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+dependencies = ["httpx>=0.27"]
+
+[project.optional-dependencies]
+mcp = ["mcp>=1.20"]
+pydantic-ai = ["pydantic-ai>=1.0"]
+
+[dependency-groups]
+dev = ["pytest>=8", "pytest-asyncio>=0.24", "mcp>=1.20", "pydantic-ai>=1.0", "uvicorn>=0.30", "starlette>=0.40"]
+
+[project.urls]
+Homepage = "https://protogrid.dev"
+Documentation = "https://docs.protogrid.dev/sdk/python/"
+Repository = "https://github.com/protogrid-dev/sdk"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/protogrid"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.uv]
+package = true

protogrid_sdk-0.2.0/src/protogrid/__init__.py

@@ -0,0 +1,17 @@
+"""protogrid: find MCP servers by intent, get a connection block, connect with no human in the loop."""
+from .client import DEFAULT_BASE_URL, AsyncProtogridClient, ProtogridClient, ProtogridError
+from .connect import Connectable, OAuthOptions, afind_connectable, find_connectable, open_session, resolve_entry, secrets_satisfied
+from .formatters import to_fastmcp_transport, to_mcp_servers, to_pydantic_ai
+from .oauth import ConsentHandler, FileTokenStore, MemoryTokenStore, TokenStore, has_tokens, loopback_consent, manual_consent, oauth_provider
+from .secrets import MissingSecretsError, placeholders_in, substitute_secrets
+from .types import META_NS, ConnectionClass, ConnectionResponse, ConnectionTarget, Descriptor, ListToolsResponse, SearchResponse, SearchResult, TrustFlag
+
+__all__ = [
+    "DEFAULT_BASE_URL", "AsyncProtogridClient", "ProtogridClient", "ProtogridError",
+    "Connectable", "OAuthOptions", "afind_connectable", "find_connectable", "open_session", "resolve_entry", "secrets_satisfied",
+    "to_fastmcp_transport", "to_mcp_servers", "to_pydantic_ai",
+    "ConsentHandler", "FileTokenStore", "MemoryTokenStore", "TokenStore", "has_tokens", "loopback_consent", "manual_consent", "oauth_provider",
+    "MissingSecretsError", "placeholders_in", "substitute_secrets",
+    "META_NS", "ConnectionClass", "ConnectionResponse", "ConnectionTarget", "Descriptor", "ListToolsResponse", "SearchResponse", "SearchResult", "TrustFlag",
+]
+__version__ = "0.2.0"

protogrid_sdk-0.2.0/src/protogrid/client.py

@@ -0,0 +1,176 @@
+"""Sync and async clients for the registry REST API (one method per operation)."""
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any
+
+import os
+
+import httpx
+
+from .types import ConnectionResponse, ConnectionTarget, Descriptor, ListToolsResponse, SearchResponse, ToolEntry
+
+
+#: The public registry. Pass ``base_url="http://localhost:8080"`` for a self-hosted or local stack.
+DEFAULT_BASE_URL = "https://api.protogrid.dev"
+
+
+class ProtogridError(Exception):
+    def __init__(self, status: int, body: dict[str, Any] | None, retry_after: float | None = None):
+        self.status = status
+        self.body = body or {}
+        self.retry_after = retry_after
+        super().__init__(self.body.get("message") or self.body.get("error") or f"HTTP {status}")
+
+    @property
+    def code(self) -> str:
+        return str(self.body.get("error") or f"http_{self.status}")
+
+
+def _search_params(q: str, limit: int | None, class_: Sequence[str] | None, transport: str | None, category: str | None, min_trust: int | None, flags: Sequence[str] | None, exclude_flags: Sequence[str] | None) -> dict[str, str]:
+    p: dict[str, str] = {"q": q}
+    if limit is not None:
+        p["limit"] = str(limit)
+    if class_:
+        p["class"] = ",".join(class_)
+    if transport:
+        p["transport"] = transport
+    if category:
+        p["category"] = category
+    if min_trust is not None:
+        p["min_trust"] = str(min_trust)
+    if flags:
+        p["flags"] = ",".join(flags)
+    if exclude_flags:
+        p["exclude_flags"] = ",".join(exclude_flags)
+    return p
+
+
+def _raise_for(res: httpx.Response) -> None:
+    if res.is_success:
+        return
+    try:
+        body = res.json()
+    except ValueError:
+        body = {"error": f"http_{res.status_code}", "message": res.text[:200]}
+    ra = res.headers.get("retry-after")
+    raise ProtogridError(res.status_code, body, float(ra) if ra else None)
+
+
+class _Base:
+    def __init__(self, base_url: str = DEFAULT_BASE_URL, *, api_key: str | None = None, timeout: float = 15.0, user_agent: str | None = None):
+        self.base_url = base_url.rstrip("/")
+        # Defaults to PROTOGRID_API_KEY; pass api_key="" to send none. Keys: https://protogrid.dev/account
+        if api_key is None:
+            api_key = os.environ.get("PROTOGRID_API_KEY")
+        headers = {"accept": "application/json"}
+        if api_key:
+            headers["authorization"] = f"Bearer {api_key}"
+        if user_agent:
+            headers["user-agent"] = user_agent
+        self._headers = headers
+        self._timeout = timeout
+
+    @staticmethod
+    def _server_path(name: str, suffix: str = "") -> str:
+        from urllib.parse import quote
+
+        return f"/v1/servers/{quote(name, safe='')}{suffix}"
+
+
+class ProtogridClient(_Base):
+    """Synchronous client."""
+
+    def __init__(self, base_url: str = DEFAULT_BASE_URL, *, api_key: str | None = None, timeout: float = 15.0, user_agent: str | None = None, transport: httpx.BaseTransport | None = None):
+        super().__init__(base_url, api_key=api_key, timeout=timeout, user_agent=user_agent)
+        self._http = httpx.Client(base_url=self.base_url, headers=self._headers, timeout=timeout, transport=transport)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> ProtogridClient:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def _get(self, path: str, params: dict[str, str] | None = None) -> Any:
+        res = self._http.get(path, params=params)
+        _raise_for(res)
+        return res.json()
+
+    def search(self, q: str, *, limit: int | None = None, class_: Sequence[str] | None = None, transport: str | None = None, category: str | None = None, min_trust: int | None = None, flags: Sequence[str] | None = None, exclude_flags: Sequence[str] | None = None) -> SearchResponse:
+        return self._get("/v1/search", _search_params(q, limit, class_, transport, category, min_trust, flags, exclude_flags))
+
+    def get_server(self, name: str, *, schemas: bool = False) -> Descriptor:
+        return self._get(self._server_path(name), {"schemas": "true"} if schemas else None)
+
+    def list_tools(self, name: str, *, limit: int | None = None, cursor: str | None = None) -> ListToolsResponse:
+        p: dict[str, str] = {}
+        if limit is not None:
+            p["limit"] = str(limit)
+        if cursor:
+            p["cursor"] = cursor
+        return self._get(self._server_path(name, "/tools"), p or None)
+
+    def list_all_tools(self, name: str) -> list[ToolEntry]:
+        out: list[ToolEntry] = []
+        cursor: str | None = None
+        while True:
+            page = self.list_tools(name, limit=100, cursor=cursor)
+            out.extend(page["tools"])
+            cursor = page.get("next_cursor")
+            if not cursor:
+                return out
+
+    def get_connection(self, name: str, target: ConnectionTarget = "mcpServers") -> ConnectionResponse:
+        return self._get(self._server_path(name, "/connection"), {"target": target})
+
+
+class AsyncProtogridClient(_Base):
+    """Asynchronous client (same methods, awaitable)."""
+
+    def __init__(self, base_url: str = DEFAULT_BASE_URL, *, api_key: str | None = None, timeout: float = 15.0, user_agent: str | None = None, transport: httpx.AsyncBaseTransport | None = None):
+        super().__init__(base_url, api_key=api_key, timeout=timeout, user_agent=user_agent)
+        self._http = httpx.AsyncClient(base_url=self.base_url, headers=self._headers, timeout=timeout, transport=transport)
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncProtogridClient:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()
+
+    async def _get(self, path: str, params: dict[str, str] | None = None) -> Any:
+        res = await self._http.get(path, params=params)
+        _raise_for(res)
+        return res.json()
+
+    async def search(self, q: str, *, limit: int | None = None, class_: Sequence[str] | None = None, transport: str | None = None, category: str | None = None, min_trust: int | None = None, flags: Sequence[str] | None = None, exclude_flags: Sequence[str] | None = None) -> SearchResponse:
+        return await self._get("/v1/search", _search_params(q, limit, class_, transport, category, min_trust, flags, exclude_flags))
+
+    async def get_server(self, name: str, *, schemas: bool = False) -> Descriptor:
+        return await self._get(self._server_path(name), {"schemas": "true"} if schemas else None)
+
+    async def list_tools(self, name: str, *, limit: int | None = None, cursor: str | None = None) -> ListToolsResponse:
+        p: dict[str, str] = {}
+        if limit is not None:
+            p["limit"] = str(limit)
+        if cursor:
+            p["cursor"] = cursor
+        return await self._get(self._server_path(name, "/tools"), p or None)
+
+    async def list_all_tools(self, name: str) -> list[ToolEntry]:
+        out: list[ToolEntry] = []
+        cursor: str | None = None
+        while True:
+            page = await self.list_tools(name, limit=100, cursor=cursor)
+            out.extend(page["tools"])
+            cursor = page.get("next_cursor")
+            if not cursor:
+                return out
+
+    async def get_connection(self, name: str, target: ConnectionTarget = "mcpServers") -> ConnectionResponse:
+        return await self._get(self._server_path(name, "/connection"), {"target": target})

protogrid_sdk-0.2.0/src/protogrid/connect.py

@@ -0,0 +1,146 @@
+"""From a connection response to a live MCP session (official ``mcp`` package, optional)."""
+from __future__ import annotations
+
+import os
+from collections.abc import AsyncIterator, Mapping, Sequence
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+from typing import Any
+
+from .client import AsyncProtogridClient, ProtogridClient, ProtogridError
+from .oauth import ConsentHandler, TokenStore, has_tokens, oauth_provider
+from .secrets import placeholders_in, substitute_secrets
+from .types import ConnectionResponse, McpServersEntry, SearchResult
+
+Secrets = Mapping[str, str | None]
+
+
+def resolve_entry(conn: ConnectionResponse, secrets: Secrets | None = None, *, partial: bool = False) -> tuple[str, McpServersEntry]:
+    """The single ``mcpServers`` entry of a connection response, with secrets substituted."""
+    key = conn["key"]
+    servers = conn["connection"]["mcpServers"]
+    entry = servers.get(key) or next(iter(servers.values()), None)
+    if entry is None:
+        raise ValueError(f"connection for {conn['server']} has no mcpServers entry")
+    return key, substitute_secrets(entry, secrets or {}, partial=partial)
+
+
+def secrets_satisfied(conn: ConnectionResponse, secrets: Secrets | None = None) -> bool:
+    """True when every placeholder the connection needs has a value in ``secrets``."""
+    s = secrets or {}
+    return all(s.get(n) is not None for n in placeholders_in(conn["connection"]))
+
+
+@dataclass
+class OAuthOptions:
+    store: TokenStore
+    consent: ConsentHandler
+    client_name: str = "protogrid-sdk agent"
+    scope: str | None = None
+    client_metadata_url: str | None = None
+
+
+@dataclass
+class Connectable:
+    result: SearchResult
+    connection: ConnectionResponse
+
+
+def _classes(class_: Sequence[str] | None, allow_local: bool, token_store: TokenStore | None) -> list[str]:
+    if class_:
+        return list(class_)
+    return ["R0", "R1", *(["R2"] if token_store else []), *(["L0"] if allow_local else [])]
+
+
+def _accept(result: SearchResult, conn: ConnectionResponse, secrets: Secrets | None, allow_local: bool, token_store: TokenStore | None) -> bool:
+    if conn.get("kind") == "bundle":
+        return False
+    r2_ok = result["connection_class"] == "R2" and token_store is not None and has_tokens(token_store, result["name"])
+    if not result["autonomous"] and not r2_ok and not (allow_local and result["connection_class"] == "L0"):
+        return False
+    return secrets_satisfied(conn, secrets)
+
+
+def find_connectable(client: ProtogridClient, q: str, *, secrets: Secrets | None = None, allow_local: bool = False, token_store: TokenStore | None = None, limit: int = 10, class_: Sequence[str] | None = None, **search: Any) -> Connectable | None:
+    """First search hit an agent can connect to now: R0, R1 with secrets present, R2 with stored tokens."""
+    res = client.search(q, limit=limit, class_=_classes(class_, allow_local, token_store), **search)
+    for result in res["results"]:
+        if not result["autonomous"] and result["connection_class"] not in ("R2", "L0"):
+            continue
+        try:
+            conn = client.get_connection(result["name"])
+        except ProtogridError:
+            continue
+        if _accept(result, conn, secrets, allow_local, token_store):
+            return Connectable(result, conn)
+    return None
+
+
+async def afind_connectable(client: AsyncProtogridClient, q: str, *, secrets: Secrets | None = None, allow_local: bool = False, token_store: TokenStore | None = None, limit: int = 10, class_: Sequence[str] | None = None, **search: Any) -> Connectable | None:
+    res = await client.search(q, limit=limit, class_=_classes(class_, allow_local, token_store), **search)
+    for result in res["results"]:
+        if not result["autonomous"] and result["connection_class"] not in ("R2", "L0"):
+            continue
+        try:
+            conn = await client.get_connection(result["name"])
+        except ProtogridError:
+            continue
+        if _accept(result, conn, secrets, allow_local, token_store):
+            return Connectable(result, conn)
+    return None
+
+
+@asynccontextmanager
+async def open_session(conn: ConnectionResponse, secrets: Secrets | None = None, *, oauth: OAuthOptions | None = None, client_name: str = "protogrid-sdk", **session_kwargs: Any) -> AsyncIterator[Any]:
+    """Async context manager yielding an initialized ``mcp.ClientSession`` for the preferred remote or package.
+
+    Streamable HTTP, SSE and stdio are supported. For R2 servers pass ``oauth``; the one-time
+    consent runs inside the first request, later runs use the stored tokens.
+    """
+    from mcp import ClientSession
+    from mcp.types import Implementation
+
+    if conn.get("kind") == "bundle":
+        raise ValueError(f"{conn['server']} is only available as a bundle; no transport can be built")
+    use_oauth = oauth is not None and conn.get("kind") == "remote" and conn.get("auth_type") in ("oauth2", "unknown")
+    _, entry = resolve_entry(conn, secrets, partial=use_oauth)
+    from . import __version__  # at call time: the package __init__ imports this module
+
+    info = Implementation(name=client_name, version=__version__)
+
+    if "url" in entry:
+        headers = dict(entry.get("headers") or {})
+        auth = None
+        if use_oauth:
+            assert oauth is not None
+            # The provider sets Authorization itself; a declared `${TOKEN}` placeholder must not block it.
+            for k in [k for k, v in headers.items() if k.lower() == "authorization" and placeholders_in(v)]:
+                del headers[k]
+            auth = oauth_provider(conn["server"], entry["url"], store=oauth.store, consent=oauth.consent, client_name=oauth.client_name, scope=oauth.scope, client_metadata_url=oauth.client_metadata_url)
+        if entry.get("type") == "sse":
+            from mcp.client.sse import sse_client
+
+            async with sse_client(entry["url"], headers=headers, auth=auth) as (read, write):
+                async with ClientSession(read, write, client_info=info, **session_kwargs) as session:
+                    await session.initialize()
+                    yield session
+            return
+        from mcp.client.streamable_http import create_mcp_http_client, streamable_http_client
+
+        http = create_mcp_http_client(headers=headers, auth=auth)
+        async with http:
+            async with streamable_http_client(entry["url"], http_client=http) as (read, write):
+                async with ClientSession(read, write, client_info=info, **session_kwargs) as session:
+                    await session.initialize()
+                    yield session
+        return
+
+    from mcp.client.stdio import StdioServerParameters, stdio_client
+
+    env = {k: v for k, v in os.environ.items()}
+    env.update(entry.get("env") or {})
+    params = StdioServerParameters(command=entry["command"], args=list(entry.get("args") or []), env=env)
+    async with stdio_client(params) as (read, write):
+        async with ClientSession(read, write, client_info=info, **session_kwargs) as session:
+            await session.initialize()
+            yield session

protogrid_sdk-0.2.0/src/protogrid/formatters.py

@@ -0,0 +1,42 @@
+"""Pure formatters connection → framework input (design rule: a formatter is a pure function,
+no framework imported by the core). ``to_pydantic_ai`` imports PydanticAI lazily."""
+from __future__ import annotations
+
+from typing import Any
+
+from .connect import Secrets, resolve_entry
+from .types import ConnectionResponse
+
+
+def to_mcp_servers(conn: ConnectionResponse, secrets: Secrets | None = None) -> dict[str, Any]:
+    """Generic ``{"mcpServers": {key: entry}}`` block with secrets substituted."""
+    key, entry = resolve_entry(conn, secrets)
+    return {"mcpServers": {key: entry}}
+
+
+def to_fastmcp_transport(conn: ConnectionResponse, secrets: Secrets | None = None) -> dict[str, Any]:
+    """Constructor arguments for a FastMCP client transport (what PydanticAI's ``MCPToolset`` uses).
+
+    Returns ``{"kind": "streamable-http" | "sse", "url", "headers"}`` or ``{"kind": "stdio", "command", "args", "env"}``.
+    """
+    _, entry = resolve_entry(conn, secrets)
+    if "url" in entry:
+        return {"kind": "sse" if entry.get("type") == "sse" else "streamable-http", "url": entry["url"], "headers": dict(entry.get("headers") or {})}
+    return {"kind": "stdio", "command": entry["command"], "args": list(entry.get("args") or []), "env": dict(entry.get("env") or {})}
+
+
+def to_pydantic_ai(conn: ConnectionResponse, secrets: Secrets | None = None, *, auth: Any = None, **toolset_kwargs: Any) -> Any:
+    """A PydanticAI ``MCPToolset`` for the preferred remote or package (requires ``pydantic-ai``).
+
+    ``auth`` may be an ``httpx.Auth`` (e.g. :func:`protogrid.oauth.oauth_provider`) for R2 servers.
+    """
+    from pydantic_ai.mcp import MCPToolset, SSETransport, StdioTransport, StreamableHttpTransport
+
+    t = to_fastmcp_transport(conn, secrets)
+    if t["kind"] == "stdio":
+        transport: Any = StdioTransport(t["command"], t["args"], env=t["env"] or None)
+    elif t["kind"] == "sse":
+        transport = SSETransport(t["url"], headers=t["headers"] or None, auth=auth)
+    else:
+        transport = StreamableHttpTransport(t["url"], headers=t["headers"] or None, auth=auth)
+    return MCPToolset(transport, id=conn["key"], **toolset_kwargs)