protogrid-sdk 0.2.0__py3-none-any.whl

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/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/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/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)

protogrid/oauth.py

@@ -0,0 +1,191 @@
+"""OAuth for R2 servers (D4: the agent holds the tokens; the registry only exposes metadata).
+
+The official ``mcp`` package runs the whole client flow (protected-resource and
+authorization-server discovery, dynamic registration or Client ID Metadata Documents, PKCE,
+refresh) inside its ``OAuthClientProvider``, an ``httpx.Auth``. This module supplies that
+provider from a pluggable :class:`TokenStore` and the single human step, the one-time consent.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import sys
+import threading
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from pathlib import Path
+from typing import Any, Protocol
+from urllib.parse import parse_qs, urlparse
+
+
+class TokenStore(Protocol):
+    """Minimal key/value store; keys are ``"<server name>:<tokens|client>"``. Bring your own."""
+
+    def get(self, key: str) -> Any | None: ...
+    def set(self, key: str, value: Any) -> None: ...
+    def delete(self, key: str) -> None: ...
+
+
+class MemoryTokenStore:
+    def __init__(self) -> None:
+        self._d: dict[str, Any] = {}
+
+    def get(self, key: str) -> Any | None:
+        return self._d.get(key)
+
+    def set(self, key: str, value: Any) -> None:
+        self._d[key] = value
+
+    def delete(self, key: str) -> None:
+        self._d.pop(key, None)
+
+
+class FileTokenStore:
+    """One JSON file, mode 0600. Fine for a single agent process; not for shared hosts."""
+
+    def __init__(self, path: str | os.PathLike[str]):
+        self.path = Path(path)
+
+    def _read(self) -> dict[str, Any]:
+        try:
+            return json.loads(self.path.read_text())
+        except (OSError, ValueError):
+            return {}
+
+    def _write(self, d: dict[str, Any]) -> None:
+        self.path.write_text(json.dumps(d, indent=2))
+        os.chmod(self.path, 0o600)
+
+    def get(self, key: str) -> Any | None:
+        return self._read().get(key)
+
+    def set(self, key: str, value: Any) -> None:
+        d = self._read()
+        d[key] = value
+        self._write(d)
+
+    def delete(self, key: str) -> None:
+        d = self._read()
+        d.pop(key, None)
+        self._write(d)
+
+
+def has_tokens(store: TokenStore, server_name: str) -> bool:
+    """True when the store already holds tokens for ``server_name`` (no human step needed now)."""
+    return store.get(f"{server_name}:tokens") is not None
+
+
+# ---------- consent ----------
+
+
+@dataclass
+class ConsentHandler:
+    """How the one-time consent happens: show the URL, then hand back the code and state."""
+
+    redirect_url: str
+    on_authorization_url: Callable[[str], Awaitable[None]]
+    wait_for_code: Callable[[], Awaitable[tuple[str, str | None]]]
+    close: Callable[[], None] | None = None
+
+
+def loopback_consent(*, host: str = "127.0.0.1", port: int = 0, path: str = "/callback", on_authorization_url: Callable[[str], Awaitable[None]] | None = None, timeout: float = 300.0, success_html: str = "<!doctype html><title>Authorized</title><p>Authorization received. You can close this tab.</p>") -> ConsentHandler:
+    """Loopback redirect receiver (RFC 8252 §7.3): a tiny local HTTP server on a thread."""
+    result: dict[str, Any] = {}
+    got = threading.Event()
+
+    class Handler(BaseHTTPRequestHandler):
+        def do_GET(self) -> None:  # noqa: N802
+            u = urlparse(self.path)
+            if u.path != path:
+                self.send_response(404)
+                self.end_headers()
+                return
+            q = parse_qs(u.query)
+            self.send_response(200)
+            self.send_header("content-type", "text/html; charset=utf-8")
+            self.end_headers()
+            self.wfile.write(success_html.encode())
+            if "code" in q:
+                result["code"] = q["code"][0]
+                result["state"] = q.get("state", [None])[0]
+            else:
+                result["error"] = f"{q.get('error', ['no code in redirect'])[0]} {q.get('error_description', [''])[0]}".strip()
+            got.set()
+
+        def log_message(self, *a: Any) -> None:
+            pass
+
+    HTTPServer.allow_reuse_address = True
+    server = HTTPServer((host, port), Handler)
+    threading.Thread(target=server.serve_forever, daemon=True).start()
+
+    def close() -> None:
+        server.shutdown()
+        server.server_close()
+    actual_port = server.server_address[1]
+
+    async def default_show(url: str) -> None:
+        print(f"Open this URL to authorize:\n{url}", file=sys.stderr)
+
+    async def wait() -> tuple[str, str | None]:
+        ok = await asyncio.to_thread(got.wait, timeout)
+        if not ok:
+            raise TimeoutError("timed out waiting for the authorization redirect")
+        if "error" in result:
+            raise RuntimeError(f"authorization failed: {result['error']}")
+        return result["code"], result.get("state")
+
+    return ConsentHandler(redirect_url=f"http://{host}:{actual_port}{path}", on_authorization_url=on_authorization_url or default_show, wait_for_code=wait, close=close)
+
+
+def manual_consent(redirect_url: str, on_authorization_url: Callable[[str], Awaitable[None]], wait_for_code: Callable[[], Awaitable[tuple[str, str | None]]]) -> ConsentHandler:
+    """For headless agents: relay the URL and the code through whatever channel exists."""
+    return ConsentHandler(redirect_url=redirect_url, on_authorization_url=on_authorization_url, wait_for_code=wait_for_code)
+
+
+# ---------- provider ----------
+
+
+def oauth_provider(server_name: str, server_url: str, *, store: TokenStore, consent: ConsentHandler, client_name: str = "protogrid-sdk agent", scope: str | None = None, client_metadata_url: str | None = None) -> Any:
+    """``mcp.client.auth.OAuthClientProvider`` (an ``httpx.Auth``) backed by ``store``, scoped to one server.
+
+    Requires the ``mcp`` package. Pass the result as ``auth`` to the transports / ``open_session``.
+    """
+    from mcp.client.auth import OAuthClientProvider, TokenStorage
+    from mcp.shared.auth import AuthorizationCodeResult, OAuthClientInformationFull, OAuthClientMetadata, OAuthToken
+
+    k_tokens, k_client = f"{server_name}:tokens", f"{server_name}:client"
+
+    class _Storage(TokenStorage):
+        async def get_tokens(self) -> OAuthToken | None:
+            d = store.get(k_tokens)
+            return OAuthToken.model_validate(d) if d else None
+
+        async def set_tokens(self, tokens: OAuthToken) -> None:
+            store.set(k_tokens, tokens.model_dump(mode="json", exclude_none=True))
+
+        async def get_client_info(self) -> OAuthClientInformationFull | None:
+            d = store.get(k_client)
+            return OAuthClientInformationFull.model_validate(d) if d else None
+
+        async def set_client_info(self, client_info: OAuthClientInformationFull) -> None:
+            store.set(k_client, client_info.model_dump(mode="json", exclude_none=True))
+
+    async def callback() -> AuthorizationCodeResult:
+        code, state = await consent.wait_for_code()
+        return AuthorizationCodeResult(code=code, state=state)
+
+    metadata = OAuthClientMetadata(
+        client_name=client_name,
+        redirect_uris=[consent.redirect_url],  # type: ignore[list-item]
+        grant_types=["authorization_code", "refresh_token"],
+        response_types=["code"],
+        token_endpoint_auth_method="none",
+        **({"scope": scope} if scope else {}),
+    )
+    kwargs: dict[str, Any] = {}
+    if client_metadata_url:
+        kwargs["client_metadata_url"] = client_metadata_url
+    return OAuthClientProvider(server_url=server_url, client_metadata=metadata, storage=_Storage(), redirect_handler=consent.on_authorization_url, callback_handler=callback, **kwargs)

protogrid/secrets.py

@@ -0,0 +1,64 @@
+"""``${NAME}`` placeholder substitution. The registry never sees secret values; the caller
+supplies them here, at the last moment, from whatever store it already has."""
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from typing import Any, TypeVar
+
+PLACEHOLDER = re.compile(r"\$\{([A-Za-z0-9_.-]+)\}")
+T = TypeVar("T")
+
+
+class MissingSecretsError(KeyError):
+    def __init__(self, missing: list[str]):
+        super().__init__(f"missing secrets: {', '.join(missing)}")
+        self.missing = missing
+
+
+def placeholders_in(value: Any) -> list[str]:
+    """Placeholder names that appear anywhere in ``value`` (strings, lists, dicts)."""
+    out: dict[str, None] = {}
+
+    def visit(v: Any) -> None:
+        if isinstance(v, str):
+            for m in PLACEHOLDER.finditer(v):
+                out.setdefault(m.group(1))
+        elif isinstance(v, list):
+            for x in v:
+                visit(x)
+        elif isinstance(v, dict):
+            for x in v.values():
+                visit(x)
+
+    visit(value)
+    return list(out)
+
+
+def substitute_secrets(value: T, secrets: Mapping[str, str | None], *, partial: bool = False) -> T:
+    """Deep copy of ``value`` with every ``${NAME}`` replaced from ``secrets``.
+
+    Raises :class:`MissingSecretsError` when a placeholder has no value, unless ``partial``.
+    """
+    missing: dict[str, None] = {}
+
+    def repl(m: re.Match[str]) -> str:
+        v = secrets.get(m.group(1))
+        if v is None:
+            missing.setdefault(m.group(1))
+            return m.group(0)
+        return v
+
+    def visit(v: Any) -> Any:
+        if isinstance(v, str):
+            return PLACEHOLDER.sub(repl, v)
+        if isinstance(v, list):
+            return [visit(x) for x in v]
+        if isinstance(v, dict):
+            return {k: visit(x) for k, x in v.items()}
+        return v
+
+    out = visit(value)
+    if missing and not partial:
+        raise MissingSecretsError(list(missing))
+    return out

protogrid/types.py

@@ -0,0 +1,111 @@
+"""Wire types of the protogrid REST API (TypedDicts: zero-copy over the JSON).
+
+Hand-written to match the platform's descriptor contract; the SDK carries no server-specific
+knowledge (design rule: SDKs are server-agnostic).
+"""
+from __future__ import annotations
+
+from typing import Any, Literal, TypedDict
+
+ConnectionClass = Literal["R0", "R1", "R2", "L0", "unknown"]
+AuthType = Literal["none", "api_key", "oauth2", "unknown"]
+ConnectionTarget = Literal["mcpServers", "vscode", "cursor", "claude-code-cli", "codex-toml", "opencode", "gemini", "goose"]
+TrustFlag = Literal["multi-version-spam", "duplicate-repo", "no-repository", "no-connection", "deprecated", "unreachable", "blocked", "deleted"]
+
+#: Reverse-DNS namespace of protogrid.dev under ``_meta``.
+META_NS = "dev.protogrid"
+
+
+class NextAction(TypedDict, total=False):
+    action: str
+    description: str
+    href: str
+    arguments: dict[str, Any]
+
+
+class MatchedTool(TypedDict):
+    name: str
+    description: str
+
+
+class SearchResult(TypedDict):
+    name: str
+    title: str | None
+    description: str
+    connection_class: ConnectionClass
+    autonomous: bool
+    human_steps: list[str]
+    categories: list[str]
+    trust_score: int | None
+    trust_flags: list[str]
+    tool_count: int
+    score: float
+    matched_tools: list[MatchedTool]
+
+
+class SearchResponse(TypedDict):
+    query: str
+    mode: str
+    count: int
+    results: list[SearchResult]
+    next_actions: list[NextAction]
+
+
+class SecretRef(TypedDict):
+    name: str
+    where: str
+
+
+class RemoteEntry(TypedDict, total=False):
+    type: Literal["http", "sse"]
+    url: str
+    headers: dict[str, str]
+
+
+class PackageEntry(TypedDict, total=False):
+    command: str
+    args: list[str]
+    env: dict[str, str]
+
+
+McpServersEntry = RemoteEntry | PackageEntry
+
+
+class ConnectionResponse(TypedDict, total=False):
+    server: str
+    key: str
+    kind: Literal["remote", "package", "bundle"]
+    class_: ConnectionClass  # JSON key is "class"; use conn["class"]
+    autonomous: bool
+    human_steps: list[str]
+    target: ConnectionTarget
+    content_type: str
+    connection: Any
+    secrets: list[SecretRef]
+    auth_type: AuthType
+    oauth: dict[str, Any]
+    placeholders: str
+    next_actions: list[NextAction]
+
+
+class ToolEntry(TypedDict, total=False):
+    name: str
+    title: str | None
+    description: str
+    input_schema: Any
+    output_schema: Any
+    annotations: Any
+    source: str
+    observed_at: str
+
+
+class ListToolsResponse(TypedDict):
+    server: str
+    count: int
+    tools: list[ToolEntry]
+    next_cursor: str | None
+    next_actions: list[NextAction]
+
+
+Descriptor = dict[str, Any]
+"""``{"server": <official server.json>, "_meta": {...}, "next_actions": [...]}``."""

protogrid_sdk-0.2.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,11 @@
+protogrid/__init__.py,sha256=X2LfJmywrXu7PVA5hu54TS4f3J2ryZ5KVs7KPclPJMg,1465
+protogrid/client.py,sha256=u6O3vwvK3zSCvFylyOtpxwaCFQHGmPtQkqrzbx5hS4E,7501
+protogrid/connect.py,sha256=ydBW2kwVendBIqPVQB1GyQ0mgNRoPe9WkDjys-JY4mU,7110
+protogrid/formatters.py,sha256=wHFMZWZbJVWMgFxSNNX1DGulLuP_-f44sIfSv8LTW8c,2160
+protogrid/oauth.py,sha256=XAsP2v0Fx9ro_tVG3mNKcUYaZWZUarinRKtEIfpHv6M,7697
+protogrid/secrets.py,sha256=Ii8fSHK9vYNzU0we4Jso17UXGLuLeUyismEd53OARBs,1976
+protogrid/types.py,sha256=RGZRkd99PpRUgL9eilUbPKJpQ3Y36kfM9CWpEUP9pew,2717
+protogrid_sdk-0.2.0.dist-info/METADATA,sha256=gfuewy3uFWriMW3UODMqV6_buIpoenOifPoWO4ZycYU,2605
+protogrid_sdk-0.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+protogrid_sdk-0.2.0.dist-info/licenses/LICENSE,sha256=gSy1bL-4EmcZaPwVKALrMPKBTJz_sQxqssfgF6Fbhg8,1079
+protogrid_sdk-0.2.0.dist-info/RECORD,,

protogrid_sdk-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

protogrid_sdk-0.2.0.dist-info/licenses/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.