partiful-api-mcp 1.0.2__py3-none-any.whl

partiful_api_mcp/partiful/tools/invite_guests.py

@@ -0,0 +1,107 @@
+"""Invite guests."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from partiful_api_mcp.core.errors import ErrorCode, ToolError
+from partiful_api_mcp.core.tools import tool
+from partiful_api_mcp.partiful.client import call
+from partiful_api_mcp.partiful.events import EVENT_ID, counts, event_info, hosted
+
+if TYPE_CHECKING:
+    from partiful_api_mcp.core.context import ToolContext
+
+# Partiful's limits per event (help.partiful.com, 21.10.2026).
+_MAX_INVITES = 1000
+_MAX_EMAILS = 500
+
+INPUT_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "event_id": EVENT_ID,
+        "user_ids": {
+            "type": "array",
+            "items": {"type": "string"},
+            "maxItems": _MAX_INVITES,
+            "description": "user_id values from list_past_guests.",
+        },
+        "emails": {
+            "type": "array",
+            "maxItems": _MAX_EMAILS,
+            "items": {
+                "type": "object",
+                "properties": {
+                    "email": {"type": "string", "format": "email"},
+                    "name": {"type": "string", "minLength": 1, "description": "Shown on the invite."},
+                },
+                "required": ["email", "name"],
+                "additionalProperties": False,
+            },
+            "description": "People to invite by email, with the name the invite greets.",
+        },
+        "message": {"type": "string", "maxLength": 480, "description": "Personal note sent with the invites."},
+    },
+    "required": ["event_id"],
+    "additionalProperties": False,
+}
+
+EXAMPLE_RESPONSE: dict[str, Any] = {
+    "event_id": "bK7dR3nMp5Gc9TzXy1Qf",
+    "invited": 2,
+    "by_email": 1,
+    "invited_total": 31,
+}
+
+
+async def check_invite(ctx: ToolContext, args: dict[str, Any]) -> None:
+    """Before approval: nobody to invite or someone else's event fails now."""
+    if not args.get("user_ids") and not args.get("emails"):
+        raise ToolError("Give user_ids or emails.", ErrorCode.INVALID_INPUT)
+    event = await hosted(ctx, args["event_id"])
+    if event.get("status") == "CANCELED":
+        raise ToolError("This event is canceled.", ErrorCode.INVALID_INPUT)
+
+
+@tool(
+    name="invite_guests",
+    title="Invite guests",
+    access="write",
+    confirm=True,
+    description="Invite past guests and mutuals through Partiful, or anyone by email.",
+    details=(
+        "Sends invites as the host's Invite screen does, so they reach real people: Partiful users from "
+        "list_past_guests get Partiful's invite, people in emails get an email with the event link and your "
+        "note. There is no way to invite a phone number: Partiful takes phone contacts only in its app. "
+        "Email invitees still sign in with a phone number to RSVP. Partiful allows 1,000 invites per event, "
+        "500 of them by email. A canceled event is refused. invited_total is the event's Invited count after "
+        "the call. Hosts only. By default you confirm each call; you can switch that off for this tool."
+    ),
+    input_schema=INPUT_SCHEMA,
+    route="POST /events/{event_id}/guests/invite",
+    example_response=EXAMPLE_RESPONSE,
+    check=check_invite,
+)
+async def invite_guests(ctx: ToolContext, args: dict[str, Any]) -> Any:
+    await check_invite(ctx, args)
+    users = list(dict.fromkeys(args.get("user_ids") or []))
+    emails = [{"guestName": e["name"].strip(), "emailAddress": e["email"].strip()} for e in args.get("emails") or []]
+    await call(
+        ctx,
+        "addInvitedGuestsAsHost",
+        {
+            "eventId": args["event_id"],
+            "userIdsToInvite": users,
+            "invitationMessage": (args.get("message") or "").strip(),
+            "otherMutualsCount": 0,
+            "phoneContactsToInvite": [],
+            "emailsToInvite": emails,
+        },
+    )
+    after = await event_info(ctx, args["event_id"])
+    return {
+        "event_id": args["event_id"],
+        "invited": len(users) + len(emails),
+        "by_email": len(emails),
+        "invited_total": counts(after)["invited"],
+    }

partiful_api_mcp/partiful/tools/list_events.py

@@ -0,0 +1,81 @@
+"""List events."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from partiful_api_mcp.core.helpers import limit, page_cursor
+from partiful_api_mcp.core.tools import tool
+from partiful_api_mcp.partiful.client import call, id_token
+from partiful_api_mcp.partiful.events import summary
+
+if TYPE_CHECKING:
+    from partiful_api_mcp.core.context import ToolContext
+
+INPUT_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "when": {
+            "type": "string",
+            "enum": ["upcoming", "past", "all"],
+            "description": "upcoming, past or all. Default: upcoming.",
+        },
+        "limit": {"type": "integer", "description": "1 to 50. Default: 20."},
+        "cursor": {"type": "string", "description": "next_cursor from the previous call."},
+    },
+    "required": [],
+    "additionalProperties": False,
+}
+
+EXAMPLE_RESPONSE: dict[str, Any] = {
+    "events": [
+        {
+            "event_id": "hK3vQ9xLm2Pa7RtYc4Wd",
+            "title": "Rooftop dinner",
+            "start_at": "2026-11-14T19:00:00-05:00",
+            "end_at": "2026-11-14T23:00:00-05:00",
+            "timezone": "America/New_York",
+            "location": "21 Mercer St, New York",
+            "status": "active",
+            "guests": {"going": 28, "maybe": 9, "cant_go": 4, "invited": 31, "waitlist": 0, "pending": 0},
+            "url": "https://partiful.com/e/hK3vQ9xLm2Pa7RtYc4Wd",
+        }
+    ],
+    "next_cursor": None,
+}
+
+
+@tool(
+    name="list_events",
+    title="List events",
+    access="read",
+    confirm=False,
+    description="Events you host, with date, status and guest counts.",
+    details=(
+        "Returns the events this account hosts or cohosts, as the Hosting tab of the home page lists them: "
+        "start and end in the event's time zone, active or canceled, and guests per RSVP status. Events you "
+        "were only invited to are left out. Upcoming come soonest first, past most recent first. Use event_id "
+        "in the other tools."
+    ),
+    input_schema=INPUT_SCHEMA,
+    route="GET /events",
+    example_response=EXAMPLE_RESPONSE,
+)
+async def list_events(ctx: ToolContext, args: dict[str, Any]) -> Any:
+    uid, _ = await id_token(ctx)
+    when = args.get("when") or "upcoming"
+    items: list[dict[str, Any]] = []
+    if when in ("upcoming", "all"):
+        data = await call(ctx, "getMyUpcomingEventsForHomePage")
+        items += sorted((data or {}).get("upcomingEvents") or [], key=lambda e: str(e.get("startDate") or ""))
+    if when in ("past", "all"):
+        data = await call(ctx, "getMyPastEventsForHomePage")
+        past = (data or {}).get("pastEvents") or []
+        items += sorted(past, key=lambda e: str(e.get("startDate") or ""), reverse=True)
+    mine = [item for item in items if uid in (item.get("ownerIds") or [])]
+    page, size = page_cursor(args.get("cursor")), limit(args, 20, 50)
+    chunk = mine[(page - 1) * size : page * size]
+    return {
+        "events": [summary(item) for item in chunk],
+        "next_cursor": str(page + 1) if page * size < len(mine) else None,
+    }

partiful_api_mcp/partiful/tools/list_guests.py

@@ -0,0 +1,81 @@
+"""List guests."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from partiful_api_mcp.core.helpers import limit, page_cursor
+from partiful_api_mcp.core.tools import tool
+from partiful_api_mcp.partiful.events import EVENT_ID, STATUS_NAMES, hosted
+from partiful_api_mcp.partiful.guests import all_guests, guest
+
+if TYPE_CHECKING:
+    from partiful_api_mcp.core.context import ToolContext
+
+INPUT_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "event_id": EVENT_ID,
+        "status": {
+            "type": "string",
+            "enum": ["all", *STATUS_NAMES],
+            "description": "all, going, maybe, cant_go, invited, waitlist or pending. Default: all.",
+        },
+        "checked_in": {"type": "boolean", "description": "Only guests who are checked in (true) or not (false)."},
+        "limit": {"type": "integer", "description": "1 to 200. Default: 100."},
+        "cursor": {"type": "string", "description": "next_cursor from the previous call."},
+    },
+    "required": ["event_id"],
+    "additionalProperties": False,
+}
+
+EXAMPLE_RESPONSE: dict[str, Any] = {
+    "guests": [
+        {
+            "guest_id": "zQ4mR8tLw2Ya6NcPe3Kb",
+            "name": "Maya Chen",
+            "status": "going",
+            "count": 2,
+            "plus_ones": ["Leo Park"],
+            "checked_in": False,
+            "rsvp_at": "2026-11-02T18:21:18-05:00",
+            "message": "Can't wait!",
+            "user_id": "Hn7bV2xQ9kLm4TrW8sYc3Pd5Fg61",
+            "answers": [{"question": "Dietary restrictions", "answer": "Vegetarian"}],
+        }
+    ],
+    "total": 1,
+    "next_cursor": None,
+}
+
+
+@tool(
+    name="list_guests",
+    title="List guests",
+    access="read",
+    confirm=False,
+    description="Guests of an event with RSVP status, check-in and Guest Questionnaire answers.",
+    details=(
+        "Returns the guest list the host sees, oldest RSVP first: name, RSVP status, party size with plus-one "
+        "names, check-in, RSVP note and questionnaire answers. Hosts only. going includes guests approved on a "
+        "Guest Approval event. guest_id goes to approve_guests and check_in_guests; total counts the guests "
+        "that match the filters."
+    ),
+    input_schema=INPUT_SCHEMA,
+    route="GET /events/{event_id}/guests",
+    example_response=EXAMPLE_RESPONSE,
+)
+async def list_guests(ctx: ToolContext, args: dict[str, Any]) -> Any:
+    event = await hosted(ctx, args["event_id"])
+    rows = [guest(doc, event) for doc in await all_guests(ctx, args["event_id"])]
+    wanted = args.get("status") or "all"
+    if wanted != "all":
+        rows = [row for row in rows if row["status"] == wanted]
+    if "checked_in" in args:
+        rows = [row for row in rows if row["checked_in"] is args["checked_in"]]
+    page, size = page_cursor(args.get("cursor")), limit(args, 100, 200)
+    return {
+        "guests": rows[(page - 1) * size : page * size],
+        "total": len(rows),
+        "next_cursor": str(page + 1) if page * size < len(rows) else None,
+    }

partiful_api_mcp/partiful/tools/list_past_guests.py

@@ -0,0 +1,115 @@
+"""List past guests."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from partiful_api_mcp.core.helpers import limit, page_cursor
+from partiful_api_mcp.core.tools import tool
+from partiful_api_mcp.partiful.client import call, id_token
+
+if TYPE_CHECKING:
+    from partiful_api_mcp.core.context import ToolContext
+
+# getContacts pages as the web app asks for them; past this many pages the rest is left out.
+_PAGE = 1000
+_MAX_PAGES = 5
+
+INPUT_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "not_on_event_id": {
+            "type": "string",
+            "description": "Leave out people already on this event (event_id), as its Invite list does.",
+        },
+        "query": {"type": "string", "description": "Only names containing this text."},
+        "limit": {"type": "integer", "description": "1 to 200. Default: 50."},
+        "cursor": {"type": "string", "description": "next_cursor from the previous call."},
+    },
+    "required": [],
+    "additionalProperties": False,
+}
+
+EXAMPLE_RESPONSE: dict[str, Any] = {
+    "people": [
+        {
+            "user_id": "Hn7bV2xQ9kLm4TrW8sYc3Pd5Fg61",
+            "name": "Maya Chen",
+            "past_guest": True,
+            "shared_events": 3,
+            "last_shared_event": {"event_id": "hK3vQ9xLm2Pa7RtYc4Wd", "title": "Rooftop dinner"},
+        }
+    ],
+    "total": 1,
+    "next_cursor": None,
+}
+
+
+@tool(
+    name="list_past_guests",
+    title="List past guests",
+    access="read",
+    confirm=False,
+    description="People you can invite: your past guests and mutuals.",
+    details=(
+        "Returns the people Partiful offers on an event's Invite screen: past guests of your events and "
+        "mutuals from events you went to, with how many events you shared. Give not_on_event_id to leave "
+        "out people already on that event; there is no filter by one past event. query matches part of the "
+        "name. user_id goes to invite_guests. A new account has nobody yet, and shared_events or "
+        "last_shared_event stay 0 or null when Partiful leaves them out."
+    ),
+    input_schema=INPUT_SCHEMA,
+    route="GET /past-guests",
+    example_response=EXAMPLE_RESPONSE,
+)
+async def list_past_guests(ctx: ToolContext, args: dict[str, Any]) -> Any:
+    uid, _ = await id_token(ctx)
+    contacts: list[Any] = []
+    if event_id := args.get("not_on_event_id"):
+        data = await call(ctx, "getContactsFilteredByEvent", {"eventId": event_id})
+        contacts = _items(data)
+    else:
+        cursor: str | None = None
+        for _ in range(_MAX_PAGES):
+            paging: dict[str, Any] = {"maxResults": _PAGE, **({"cursor": cursor} if cursor else {})}
+            result = await call(ctx, "getContacts", {}, paging, whole=True)
+            contacts += _items(result.get("data"))
+            cursor = (result.get("paging") or {}).get("nextCursor")
+            if not cursor:
+                break
+    people = [p for p in (_person(item) for item in contacts) if p and p["user_id"] != uid]
+    if text := (args.get("query") or "").strip().lower():
+        people = [p for p in people if text in (p["name"] or "").lower()]
+    page, size = page_cursor(args.get("cursor")), limit(args, 50, 200)
+    return {
+        "people": people[(page - 1) * size : page * size],
+        "total": len(people),
+        "next_cursor": str(page + 1) if page * size < len(people) else None,
+    }
+
+
+def _items(data: Any) -> list[Any]:
+    """getContacts answers a list, getContactsFilteredByEvent `{contacts: [...]}`."""
+    if isinstance(data, dict):
+        data = data.get("contacts") or data.get("users") or []
+    return data if isinstance(data, list) else []
+
+
+def _person(item: Any) -> dict[str, Any] | None:
+    """One contact, shaped like getContactsFilteredByEvent's; getContacts was only seen empty, so all is optional."""
+    if not isinstance(item, dict):
+        return None
+    nested = item.get("user")
+    user: dict[str, Any] = nested if isinstance(nested, dict) else {}
+    user_id = item.get("id") or item.get("userId") or user.get("id")
+    if not user_id:
+        return None
+    event = item.get("sharedEvent")
+    shared: dict[str, Any] | None = event if isinstance(event, dict) else None
+    return {
+        "user_id": user_id,
+        "name": item.get("name") or user.get("name"),
+        "past_guest": bool(item.get("isPastGuest")),
+        "shared_events": int(item.get("sharedEventCount") or 0),
+        "last_shared_event": {"event_id": shared.get("id"), "title": shared.get("title")} if shared else None,
+    }

partiful_api_mcp/partiful/tools/send_text_blast.py

@@ -0,0 +1,100 @@
+"""Send Text Blast."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from partiful_api_mcp.core.errors import ErrorCode, ToolError
+from partiful_api_mcp.core.tools import tool
+from partiful_api_mcp.partiful.client import call
+from partiful_api_mcp.partiful.events import EVENT_ID, STATUSES, hosted
+from partiful_api_mcp.partiful.guests import all_guests
+
+if TYPE_CHECKING:
+    from partiful_api_mcp.core.context import ToolContext
+
+# Who a blast can go to, as the Send Text Blast modal groups guests.
+_GROUPS = ["going", "maybe", "cant_go", "invited", "waitlist", "pending"]
+# Text length the modal allows by SMS; email only allows more, but SMS is always on here.
+_MAX_TEXT = 480
+
+INPUT_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "event_id": EVENT_ID,
+        "message": {"type": "string", "minLength": 1, "maxLength": _MAX_TEXT, "description": "Message text."},
+        "statuses": {
+            "type": "array",
+            "items": {"type": "string", "enum": _GROUPS},
+            "minItems": 1,
+            "description": "Who receives it: going, maybe, cant_go, invited, waitlist, pending.",
+        },
+        "show_on_event_page": {
+            "type": "boolean",
+            "description": "Also show the blast in the event's activity feed. Default: true.",
+        },
+    },
+    "required": ["event_id", "message", "statuses"],
+    "additionalProperties": False,
+}
+
+EXAMPLE_RESPONSE: dict[str, Any] = {
+    "event_id": "hK3vQ9xLm2Pa7RtYc4Wd",
+    "recipients": 37,
+    "by_status": {"going": 28, "maybe": 9},
+    "sent": True,
+}
+
+
+async def _recipients(ctx: ToolContext, args: dict[str, Any]) -> dict[str, int]:
+    await hosted(ctx, args["event_id"])
+    docs = await all_guests(ctx, args["event_id"])
+    by_status = {name: sum(1 for doc in docs if doc.get("status") in STATUSES[name]) for name in args["statuses"]}
+    if not sum(by_status.values()):
+        raise ToolError("No guest has the chosen statuses, so the blast would reach nobody.", ErrorCode.INVALID_INPUT)
+    return by_status
+
+
+async def check_blast(ctx: ToolContext, args: dict[str, Any]) -> None:
+    """Before approval: a blast to nobody or on someone else's event fails now."""
+    await _recipients(ctx, args)
+
+
+@tool(
+    name="send_text_blast",
+    title="Send Text Blast",
+    access="write",
+    confirm=True,
+    description="Text a message to guests by RSVP status. Partiful allows up to 10 Text Blasts per event.",
+    details=(
+        "Sends a Text Blast as the host's Send Text Blast does: by text and email to every guest with the "
+        "chosen RSVP statuses, push for guests with the app, and shown in the event's feed unless "
+        "show_on_event_page is false. Real people get it at once and it cannot be taken back. Up to 480 "
+        "characters. recipients and by_status count the guests with those statuses at the moment of sending; "
+        "a choice that reaches nobody is refused before you confirm. Partiful allows 10 blasts per event and "
+        "refuses a blast to Invited when that group holds more than 100 guests. The answer does not say how "
+        "many blasts are left. Hosts only. By default you confirm each call; you can switch that off for this "
+        "tool."
+    ),
+    input_schema=INPUT_SCHEMA,
+    route="POST /events/{event_id}/text-blasts",
+    example_response=EXAMPLE_RESPONSE,
+    check=check_blast,
+)
+async def send_text_blast(ctx: ToolContext, args: dict[str, Any]) -> Any:
+    by_status = await _recipients(ctx, args)
+    to = [value for name in args["statuses"] for value in STATUSES[name]]
+    await call(
+        ctx,
+        "createTextBlast",
+        {
+            "eventId": args["event_id"],
+            "message": {
+                "text": args["message"].strip(),
+                "to": to,
+                "showOnEventPage": args.get("show_on_event_page", True),
+                "notificationChannels": ["Sms", "Email"],
+            },
+        },
+    )
+    return {"event_id": args["event_id"], "recipients": sum(by_status.values()), "by_status": by_status, "sent": True}

partiful_api_mcp/partiful/tools/update_event.py

@@ -0,0 +1,50 @@
+"""Update event."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from partiful_api_mcp.core.errors import ErrorCode, ToolError
+from partiful_api_mcp.core.tools import tool
+from partiful_api_mcp.partiful.editing import FIELDS, apply
+from partiful_api_mcp.partiful.events import EVENT_ID, detail, event_info, hosted
+from partiful_api_mcp.partiful.tools.get_event import EXAMPLE_RESPONSE as EVENT
+
+if TYPE_CHECKING:
+    from partiful_api_mcp.core.context import ToolContext
+
+INPUT_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {"event_id": EVENT_ID, **FIELDS},
+    "required": ["event_id"],
+    "additionalProperties": False,
+}
+
+EXAMPLE_RESPONSE: dict[str, Any] = {"updated": ["location"], **EVENT, "location": "88 Bleecker St, New York"}
+
+
+@tool(
+    name="update_event",
+    title="Update event",
+    access="write",
+    confirm=False,
+    description="Change the details or settings of an event you host.",
+    details=(
+        "Changes only the fields you give, as the event's Edit page and settings panel do: title, times, time "
+        "zone, location, description, RSVP deadline, guest limit, Guest Approval and the Guest Questionnaire. "
+        "Fields left out keep their value; a call with no field is refused. Turning Guest Approval on removes "
+        "the guest limit and the waitlist, and the first guest limit turns the waitlist on. New questions "
+        "replace the questionnaire for guests who RSVP from then on. Returns the event after the change, with "
+        "updated listing the fields you gave. Hosts only."
+    ),
+    input_schema=INPUT_SCHEMA,
+    route="PATCH /events/{event_id}",
+    example_response=EXAMPLE_RESPONSE,
+)
+async def update_event(ctx: ToolContext, args: dict[str, Any]) -> Any:
+    changes = {key: value for key, value in args.items() if key != "event_id"}
+    if not changes:
+        raise ToolError("Give at least one field to change.", ErrorCode.INVALID_INPUT)
+    old = await hosted(ctx, args["event_id"])
+    updated = await apply(ctx, args["event_id"], old, changes)
+    return {"updated": updated, **detail(await event_info(ctx, args["event_id"]))}

partiful_api_mcp/runner.py

@@ -0,0 +1,117 @@
+"""All tools of the app in one registry, and the one way to call them: validate, run, map errors.
+
+The REST API, the MCP server, the CLI and `partiful_api_mcp.call()` all go through `Runner.run`.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import importlib
+import pkgutil
+from typing import Any
+
+import jsonschema
+
+from partiful_api_mcp import app
+from partiful_api_mcp import session as sessions
+from partiful_api_mcp.core.context import ToolContext
+from partiful_api_mcp.core.errors import AuthExpiredError, ErrorCode, ToolError
+from partiful_api_mcp.core.tools import ToolSpec
+from partiful_api_mcp.partiful import tools as tools_package
+
+_TOOLS: dict[str, ToolSpec] | None = None
+# One message for a signed-out session, whatever the tool raised.
+_SIGNED_OUT = f"{app.NAME} signed this session out. Sign in to {app.NAME} in Chrome, then run: {app.CLI} connect"
+
+
+def all_tools() -> dict[str, ToolSpec]:
+    """Every tool in the app's tools/ package, by name, in file order."""
+    global _TOOLS
+    if _TOOLS is None:
+        found: dict[str, ToolSpec] = {}
+        for module_info in sorted(pkgutil.iter_modules(tools_package.__path__), key=lambda m: m.name):
+            module = importlib.import_module(f"{tools_package.__name__}.{module_info.name}")
+            for value in vars(module).values():
+                if isinstance(value, ToolSpec) and value.route:
+                    found[value.name] = value
+        _TOOLS = found
+    return _TOOLS
+
+
+def tools(read_only: bool = False) -> list[ToolSpec]:
+    return [spec for spec in all_tools().values() if not read_only or spec.access == "read"]
+
+
+def description(spec: ToolSpec) -> str:
+    """What an agent reads: the one-liner, then the details."""
+    return f"{spec.description}\n\n{spec.details}" if spec.details else spec.description
+
+
+class Runner:
+    """One session for the life of the process; reconnects to Chrome once when the app signs it out."""
+
+    def __init__(self, read_only: bool = False) -> None:
+        self.read_only = read_only
+        self._ctx: ToolContext | None = None
+        self._lock = asyncio.Lock()
+
+    def _context(self) -> ToolContext:
+        if self._ctx is None:
+            session = sessions.load()
+            if not session.signed_in:
+                raise ToolError(
+                    f"No {app.NAME} session yet. Sign in to {app.NAME} in Chrome, then run: {app.CLI} connect",
+                    ErrorCode.AUTH_REQUIRED,
+                )
+            self._ctx = ToolContext(session=session)
+        return self._ctx
+
+    async def run(self, name: str, args: dict[str, Any] | None = None) -> Any:
+        spec = all_tools().get(name)
+        if spec is None:
+            raise ToolError(f"No tool '{name}'. List them with: {app.CLI} tools", ErrorCode.UNKNOWN_TOOL)
+        if self.read_only and spec.access != "read":
+            raise ToolError(f"{name} changes {app.NAME} and this server runs read-only.", ErrorCode.SCOPE_DENIED)
+        args = {k: v for k, v in (args or {}).items() if v is not None}
+        try:
+            jsonschema.validate(args, spec.input_schema)
+        except jsonschema.ValidationError as exc:
+            where = ".".join(str(p) for p in exc.absolute_path)
+            raise ToolError(f"{where + ': ' if where else ''}{exc.message}", ErrorCode.INVALID_INPUT) from None
+        ctx = self._context()
+        try:
+            return await asyncio.wait_for(spec.handler(ctx, args), timeout=spec.timeout_s or 120)
+        except TimeoutError:
+            raise ToolError(f"{app.NAME} took too long to answer.", ErrorCode.TIMEOUT) from None
+        except ToolError as exc:
+            if exc.code is not ErrorCode.AUTH_EXPIRED:
+                raise
+            if not await self._reconnect():
+                raise AuthExpiredError(_SIGNED_OUT) from exc
+            # The app signed the old session out: read it again from Chrome and try once more.
+            try:
+                return await spec.handler(self._context(), args)
+            except AuthExpiredError as again:
+                raise AuthExpiredError(_SIGNED_OUT) from again
+
+    async def _reconnect(self) -> bool:
+        async with self._lock:
+            old = self._context()
+            try:
+                fresh = await asyncio.to_thread(sessions.refresh, old.session)
+            except ToolError:
+                return False
+            same = fresh is not None and (fresh.cookies, fresh.local_storage) == (
+                old.session.cookies,
+                old.session.local_storage,
+            )
+            if fresh is None or same:
+                return False
+            await old.close()
+            self._ctx = ToolContext(session=fresh)
+            return True
+
+    async def close(self) -> None:
+        if self._ctx is not None:
+            await self._ctx.close()
+            self._ctx = None