mcp-pavoot 0.1.0__tar.gz

mcp_pavoot-0.1.0/.env.example

@@ -0,0 +1,21 @@
+# ─── Runtime config (every user of the MCP) ─────────────────────────────────
+
+# The base URL of the Pavoot API. Use the production URL by default; switch
+# to http://localhost:8000 (or wherever yc-pavoot-api is running) for local
+# testing.
+PAVOOT_API_URL=https://yc-api.pavoot.com
+
+# Your personal API key. Mint one with:
+#   POST /users/api-keys  body {"name": "Claude Desktop"}
+# The raw key is shown ONCE on creation — paste it here and never check it in.
+PAVOOT_API_KEY=pvt_live_replace_me
+
+
+# ─── Maintainer-only (only needed if you publish to PyPI) ───────────────────
+# These are NOT required to run the MCP — they're only read by publish.sh
+# and redeploy.sh. Users installing `mcp-pavoot` from PyPI ignore them.
+
+# PyPI API token from https://pypi.org/manage/account/token/
+# Scope: "Entire account" for the first publish, then narrow to project-only.
+# The token starts with `pypi-`. Treat it like a password.
+PYPI_API_TOKEN=pypi-replace_me

mcp_pavoot-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+.env
+__pycache__/
+*.egg-info/
+*.pyc
+.DS_Store
+build/
+dist/

mcp_pavoot-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

mcp_pavoot-0.1.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: mcp-pavoot
+Version: 0.1.0
+Summary: MCP server that exposes the Pavoot event-planning API
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp[cli]>=1.6.0
+Requires-Dist: python-dotenv>=1.0

mcp_pavoot-0.1.0/README.md

@@ -0,0 +1,185 @@
+# mcp-pavoot
+
+A [Model Context Protocol](https://modelcontextprotocol.io) server that
+exposes the Pavoot event-planning API to MCP hosts (Claude Desktop,
+Cursor, etc.). Once connected, an MCP host can do everything you can do
+in the web app: list your events, drive the planning chat, refine the
+proposed attendees, edit invitation drafts, manage RSVPs and check-ins,
+and generate post-event follow-up emails — all scoped to your account
+via a personal API key.
+
+## Setup
+
+### 1. Mint a Pavoot API key
+
+API keys are scoped per-user. Sign in to Pavoot in the browser to get a
+Clerk session token, then call the API directly:
+
+```bash
+# Replace <CLERK_JWT> with a fresh token from the browser's network tab.
+curl -X POST https://yc-api.pavoot.com/users/api-keys \
+  -H "Authorization: Bearer <CLERK_JWT>" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "Claude Desktop"}'
+```
+
+The response includes a `key` field starting with `pvt_live_…`. **Copy it
+now — it's shown exactly once.** Lose it and you'll have to revoke +
+recreate. The server only stores the SHA-256 hash.
+
+To list your active keys later:
+
+```bash
+curl https://yc-api.pavoot.com/users/api-keys \
+  -H "Authorization: Bearer <CLERK_JWT>"
+```
+
+To revoke one:
+
+```bash
+curl -X DELETE https://yc-api.pavoot.com/users/api-keys/<KEY_ID> \
+  -H "Authorization: Bearer <CLERK_JWT>"
+```
+
+### 2. Install the MCP server
+
+```bash
+cd mcp-pavoot
+python3.12 -m venv .venv
+.venv/bin/pip install -e .
+cp .env.example .env   # then paste your real PAVOOT_API_KEY
+```
+
+### 3. Wire it into your MCP host
+
+#### Claude Desktop
+
+Open `~/Library/Application Support/Claude/claude_desktop_config.json`
+and add:
+
+```json
+{
+  "mcpServers": {
+    "pavoot": {
+      "command": "/Users/ana/Documents/event-new-app/mcp-pavoot/.venv/bin/python",
+      "args": ["-m", "mcp_pavoot"],
+      "env": {
+        "PAVOOT_API_URL": "https://yc-api.pavoot.com",
+        "PAVOOT_API_KEY": "pvt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The Pavoot tools should appear under the 🔌 icon.
+
+#### Cursor
+
+Add to `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "pavoot": {
+      "command": "/Users/ana/Documents/event-new-app/mcp-pavoot/.venv/bin/python",
+      "args": ["-m", "mcp_pavoot"],
+      "env": {
+        "PAVOOT_API_URL": "https://yc-api.pavoot.com",
+        "PAVOOT_API_KEY": "pvt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+      }
+    }
+  }
+}
+```
+
+#### Standalone (interactive testing)
+
+```bash
+.venv/bin/mcp dev src/mcp_pavoot/server.py
+```
+
+This opens the MCP Inspector in your browser so you can call each tool
+directly without a host.
+
+### 4. Smoke-test
+
+In your MCP host, try:
+
+> List my Pavoot events.
+
+The host should call `list_my_events`, then `whoami` to confirm the
+account. From there you can:
+
+> For event "AI Founders Mixer", show me the proposed attendees as a markdown table.
+>
+> Generate invitation drafts for everyone, then show me the first three.
+>
+> Change my pre-event chat — tell it to focus more on AI infra founders.
+
+## Tools
+
+| Domain | Tools |
+|---|---|
+| Util | `whoami`, `health_check` |
+| Events | `list_my_events`, `create_event`, `delete_event`, `get_event_state`, `reset_event`, `duplicate_event`, `regenerate_public_token`, `finalize_event`, `get_finalized`, `quick_setup` |
+| Entry flow | `get_entry_flow`, `answer_entry_flow`, `skip_entry_flow` |
+| Target group | `set_target_group_source`, `get_target_group`, `refine_target_group`, `confirm_target_group` |
+| Concept | `get_event_suggestions`, `select_event_suggestion`, `tweak_event` |
+| Date / location / details | `get_date_location_options`, `set_date_location`, `set_event_details`, `set_event_settings` |
+| Attendees | `get_proposed_attendees`, `refine_attendees`, `review_attendee`, `decline_attendee`, `regenerate_attendees`, `confirm_attendees` |
+| Chat | `pre_event_agent`, `pre_event_chat` |
+| Notes | `get_pre_event_notes`, `set_pre_event_notes`, `get_post_event_notes`, `set_post_event_notes` |
+| Notetaker | `list_notetaker_events`, `list_notetaker_attendees`, `list_attendee_notes`, `add_attendee_note`, `update_attendee_note`, `get_all_event_notes` |
+| Live event | `get_event_dashboard`, `list_rsvps`, `add_rsvp`, `approve_rsvp`, `decline_rsvp`, `check_in_attendee`, `reset_rsvp`, `mark_rsvp`, `check_in_by_qr_token`, `close_registration`, `open_registration` |
+| Invite drafts | `get_invite_template`, `set_invite_template`, `generate_invite_drafts`, `list_invite_drafts`, `update_invite_draft`, `regenerate_invite_draft`, `send_invite_draft`, `send_all_invite_drafts` |
+| CRM | `list_companies`, `list_people`, `get_person`, `enrich_people`, `suggest_events`, `get_attendee_suggestions` |
+| Post-event | `get_event_analytics`, `list_followup_drafts`, `generate_followup_emails`, `update_followup_draft`, `list_attendee_followups`, `generate_attendee_followups`, `update_attendee_followup`, `get_event_report_url`, `create_report_share_link`, `list_followup_templates`, `seed_default_templates`, `create_followup_template`, `update_followup_template`, `delete_followup_template` |
+
+Read-heavy tools (`list_my_events`, `list_people`, `list_rsvps`,
+`list_invite_drafts`, etc.) accept a `format` argument:
+
+- `"json"` (default) — full structured payload
+- `"markdown"` — table or key/value list, good for direct chat display
+- `"csv"` — paste-into-spreadsheet
+- `"summary"` — one-line headline ("12 RSVPs — 8 yes, 2 waitlist, 2 pending")
+
+## Security
+
+- The raw API key is stored ONLY in your MCP host config (and optionally in
+  `mcp-pavoot/.env` — gitignored). The server stores only `sha256(key)`.
+- Each request hits an indexed lookup; `last_used_at` is updated atomically.
+- API keys can NOT mint, list, or revoke other API keys — that surface
+  requires a Clerk browser session (`require_clerk_jwt` dependency).
+- Every mutating request is logged in `request_logs` with the resolved
+  `user_id` and a `X-Request-Source: mcp-pavoot` tag so MCP traffic is
+  distinguishable from browser traffic on the same account.
+
+## Architecture
+
+```
+src/mcp_pavoot/
+  __main__.py    # `python -m mcp_pavoot` entry point
+  server.py      # all @mcp.tool() definitions (83 tools)
+  http.py        # shared httpx.AsyncClient, auth header, error translation
+  formatters.py  # json | markdown | csv | summary
+```
+
+Auth on the Pavoot API end:
+
+- `auth/clerk.py::authenticate_clerk_request` detects `Authorization:
+  Bearer pvt_live_…` and routes to a fast DB lookup (one indexed query,
+  no network). Anything else falls through to the Clerk JWT verifier.
+- `auth/clerk.py::require_clerk_jwt` is the same as `get_current_user_id`
+  but rejects API-key auth with 403 — used by `/users/api-keys` endpoints.
+
+## Development
+
+```bash
+.venv/bin/mcp dev src/mcp_pavoot/server.py    # interactive inspector
+.venv/bin/python -c "from mcp_pavoot.server import mcp"   # syntax check
+```
+
+When updating the API, add the corresponding tool to `server.py`, then
+update the table in this README. The path strings in `server.py` should
+exactly match the routes in `yc-pavoot-api/*/router.py`.

mcp_pavoot-0.1.0/publish.sh

@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+# Publish `mcp-pavoot` to PyPI.
+#
+# Reads PYPI_API_TOKEN from .env (or the environment). Uploads the version
+# currently declared in pyproject.toml — does NOT bump it. Use this for
+# your first publish; for subsequent releases use ./redeploy.sh which bumps
+# the patch version first.
+#
+# Safety:
+#   - Refuses to upload if the version already exists on PyPI (PyPI rejects
+#     re-uploads of the same version, but we check first so the failure mode
+#     is a clean error instead of a half-built dist/).
+#   - Wipes dist/ before building so old wheels don't get re-uploaded.
+#   - Uses the project's .venv if it exists; falls back to system python.
+
+set -euo pipefail
+
+cd "$(dirname "$0")"
+
+# ── Load .env (if present) without exporting unrelated vars ─────────────────
+if [[ -f .env ]]; then
+  set -o allexport
+  # shellcheck disable=SC1091
+  source .env
+  set +o allexport
+fi
+
+if [[ -z "${PYPI_API_TOKEN:-}" || "$PYPI_API_TOKEN" == "pypi-replace_me" ]]; then
+  echo "✗ PYPI_API_TOKEN is not set."
+  echo "  1) Create a token at https://pypi.org/manage/account/token/"
+  echo "  2) Paste it into mcp-pavoot/.env as PYPI_API_TOKEN=pypi-..."
+  exit 1
+fi
+
+# ── Pick interpreter (prefer the project venv) ──────────────────────────────
+PY=".venv/bin/python"
+if [[ ! -x "$PY" ]]; then
+  PY="$(command -v python3 || command -v python)"
+fi
+echo "→ Using interpreter: $PY"
+
+# ── Ensure build + twine are installed ──────────────────────────────────────
+"$PY" -m pip install --quiet --upgrade build twine
+
+# ── Read the version we're about to ship ────────────────────────────────────
+VERSION="$(
+  "$PY" -c "
+import re, pathlib
+m = re.search(r'^version\s*=\s*\"([^\"]+)\"', pathlib.Path('pyproject.toml').read_text(), re.M)
+print(m.group(1) if m else '')"
+)"
+if [[ -z "$VERSION" ]]; then
+  echo "✗ Couldn't find a version in pyproject.toml. Aborting."
+  exit 1
+fi
+echo "→ Publishing mcp-pavoot version $VERSION"
+
+# ── Refuse to re-upload an existing version ─────────────────────────────────
+STATUS="$(curl -s -o /dev/null -w '%{http_code}' "https://pypi.org/pypi/mcp-pavoot/$VERSION/json" || echo 000)"
+if [[ "$STATUS" == "200" ]]; then
+  echo "✗ Version $VERSION already exists on PyPI. Bump the version in"
+  echo "  pyproject.toml (or run ./redeploy.sh) and try again."
+  exit 1
+fi
+
+# ── Clean + build ───────────────────────────────────────────────────────────
+echo "→ Cleaning dist/ and rebuilding..."
+rm -rf dist/ build/ ./*.egg-info src/*.egg-info
+"$PY" -m build
+
+# ── Upload ──────────────────────────────────────────────────────────────────
+echo "→ Uploading to PyPI..."
+TWINE_USERNAME="__token__" \
+TWINE_PASSWORD="$PYPI_API_TOKEN" \
+  "$PY" -m twine upload --non-interactive dist/*
+
+echo
+echo "✓ Published mcp-pavoot $VERSION"
+echo "  Browse:  https://pypi.org/project/mcp-pavoot/$VERSION/"
+echo "  Install: uvx mcp-pavoot"

mcp_pavoot-0.1.0/pyproject.toml

@@ -0,0 +1,20 @@
+[project]
+name = "mcp-pavoot"
+version = "0.1.0"
+description = "MCP server that exposes the Pavoot event-planning API"
+requires-python = ">=3.12"
+dependencies = [
+  "mcp[cli]>=1.6.0",
+  "httpx>=0.27",
+  "python-dotenv>=1.0",
+]
+
+[project.scripts]
+mcp-pavoot = "mcp_pavoot.__main__:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mcp_pavoot"]

mcp_pavoot-0.1.0/redeploy.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+# Bump the patch version in pyproject.toml and publish to PyPI.
+#
+# Use this after making changes to mcp-pavoot. It:
+#   1) Bumps the patch version (e.g. 0.1.0 → 0.1.1) in pyproject.toml
+#   2) Calls ./publish.sh, which builds + uploads
+#
+# Override the bump kind with the first arg:
+#   ./redeploy.sh           # patch bump (default)
+#   ./redeploy.sh patch     # 0.1.0 -> 0.1.1
+#   ./redeploy.sh minor     # 0.1.5 -> 0.2.0
+#   ./redeploy.sh major     # 0.9.3 -> 1.0.0
+#   ./redeploy.sh 1.2.3     # set explicit version
+#
+# PyPI rejects re-uploading the same version, so every redeploy MUST bump.
+
+set -euo pipefail
+
+cd "$(dirname "$0")"
+
+BUMP="${1:-patch}"
+
+PY=".venv/bin/python"
+if [[ ! -x "$PY" ]]; then
+  PY="$(command -v python3 || command -v python)"
+fi
+
+# ── Bump pyproject.toml in place ────────────────────────────────────────────
+NEW_VERSION="$(
+  "$PY" - "$BUMP" <<'PY_BUMP'
+import pathlib, re, sys
+
+bump = sys.argv[1]
+path = pathlib.Path("pyproject.toml")
+text = path.read_text()
+m = re.search(r'^(version\s*=\s*")(\d+)\.(\d+)\.(\d+)(")', text, re.M)
+if not m:
+    sys.exit("✗ Couldn't find version = \"x.y.z\" in pyproject.toml")
+
+major, minor, patch = int(m.group(2)), int(m.group(3)), int(m.group(4))
+
+if bump == "patch":
+    patch += 1
+elif bump == "minor":
+    minor += 1
+    patch = 0
+elif bump == "major":
+    major += 1
+    minor = 0
+    patch = 0
+elif re.match(r"^\d+\.\d+\.\d+$", bump):
+    major, minor, patch = (int(x) for x in bump.split("."))
+else:
+    sys.exit(f"✗ Unknown bump kind: {bump!r}. Use patch/minor/major or x.y.z.")
+
+new = f"{major}.{minor}.{patch}"
+new_text = text[:m.start(2)] + new + text[m.end(4):]
+path.write_text(new_text)
+print(new)
+PY_BUMP
+)"
+
+OLD_VERSION="$(git diff -U0 pyproject.toml 2>/dev/null | grep -E '^-version\s*=' | sed -E 's/.*"([^"]+)".*/\1/' | head -1 || true)"
+
+echo "→ Version bumped${OLD_VERSION:+ from $OLD_VERSION} to $NEW_VERSION (in pyproject.toml)"
+echo
+
+# ── Hand off to publish.sh ──────────────────────────────────────────────────
+exec ./publish.sh

mcp_pavoot-0.1.0/run_mcp.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+# Launch the Pavoot MCP server. Invoked by MCP hosts (Claude Desktop, Cursor)
+# via the `command` field in their config — see README.md for the full block.
+set -euo pipefail
+cd "$(dirname "$0")"
+exec .venv/bin/python -m mcp_pavoot

mcp_pavoot-0.1.0/src/mcp_pavoot/__init__.py

@@ -0,0 +1,8 @@
+"""Pavoot MCP server package.
+
+Exposes the Pavoot event-management API as a set of MCP tools so an MCP
+host (Claude Desktop, Cursor, etc.) can plan events end-to-end for a
+single authenticated user.
+"""
+
+__version__ = "0.1.0"

mcp_pavoot-0.1.0/src/mcp_pavoot/__main__.py

@@ -0,0 +1,12 @@
+"""Entry point: `python -m mcp_pavoot` boots the MCP server over stdio."""
+from __future__ import annotations
+
+from mcp_pavoot.server import mcp
+
+
+def main() -> None:
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

mcp_pavoot-0.1.0/src/mcp_pavoot/formatters.py

@@ -0,0 +1,224 @@
+"""Response formatters for the MCP tools.
+
+The API always returns JSON; the MCP wraps read-heavy responses so a tool
+can be asked for `markdown` (good for direct chat display), `csv` (good
+for paste-into-spreadsheet), or `summary` (a one-line "here's what's in
+this" line). The default `json` returns the payload untouched.
+
+We keep this layer thin on purpose: don't try to be too clever about
+which columns to surface; pick a handful of the most useful ones per
+`kind`. If the LLM wants more it can re-call with format='json'.
+"""
+from __future__ import annotations
+
+import csv
+import io
+from typing import Any
+
+Format = str  # "json" | "markdown" | "csv" | "summary"
+
+# Per-kind column hints for tabular formats. Empty list = "show every key".
+_COLUMNS: dict[str, list[str]] = {
+    "events":           ["id", "name", "starts_at", "active_task", "finalized", "status"],
+    "people":           ["id", "name", "title", "company_name", "enrich_status"],
+    "companies":        ["name", "one_liner", "industries", "location", "website"],
+    "attendees":        ["id", "name", "title", "company", "city", "email"],
+    "rsvps":            ["contact_id", "name", "company", "status", "email"],
+    "invite_drafts":    ["id", "recipient_name", "recipient_email", "subject", "status"],
+    "followup_drafts":  ["segment", "subject"],
+    "attendee_followups": ["contact_id", "name", "segment", "subject", "note_count"],
+    "templates":        ["id", "name", "is_default", "rule_definition"],
+    "notes":            ["created_at", "author_name", "method", "important", "content"],
+    "notetaker_attendees": ["id", "display_name", "company", "title", "note_count", "my_note_count", "latest_note_at"],
+    "notetaker_events": ["id", "name", "starts_at", "status", "attendee_count", "invited_count"],
+}
+
+
+def _truncate(s: Any, limit: int = 120) -> str:
+    text = str(s) if s is not None else ""
+    if len(text) <= limit:
+        return text
+    return text[: limit - 1].rstrip() + "…"
+
+
+def _md_escape(s: Any) -> str:
+    return _truncate(s).replace("|", "\\|").replace("\n", " ")
+
+
+def _pick_columns(kind: str, row: dict[str, Any]) -> list[str]:
+    cols = _COLUMNS.get(kind) or []
+    if cols:
+        return [c for c in cols if c in row] + [k for k in row if k not in cols]
+    return list(row.keys())
+
+
+def _markdown_table(rows: list[dict[str, Any]], kind: str) -> str:
+    if not rows:
+        return "_(no rows)_"
+    cols = _pick_columns(kind, rows[0])
+    header = "| " + " | ".join(cols) + " |"
+    sep    = "| " + " | ".join("---" for _ in cols) + " |"
+    body   = "\n".join(
+        "| " + " | ".join(_md_escape(r.get(c, "")) for c in cols) + " |"
+        for r in rows
+    )
+    return "\n".join([header, sep, body])
+
+
+def _markdown_kv(d: dict[str, Any]) -> str:
+    return "\n".join(f"- **{k}**: {_truncate(v)}" for k, v in d.items())
+
+
+def _to_csv(rows: list[dict[str, Any]], kind: str) -> str:
+    if not rows:
+        return ""
+    cols = _pick_columns(kind, rows[0])
+    buf = io.StringIO()
+    writer = csv.writer(buf)
+    writer.writerow(cols)
+    for r in rows:
+        writer.writerow([r.get(c, "") for c in cols])
+    return buf.getvalue()
+
+
+def _summary(data: Any, kind: str) -> str:
+    """Single line that captures the headline for this kind of payload."""
+    if kind == "events" and isinstance(data, list):
+        finalized = sum(1 for e in data if e.get("finalized"))
+        return f"{len(data)} events ({finalized} finalized)."
+    if kind == "people" and isinstance(data, list):
+        enriched = sum(1 for p in data if p.get("enrich_status") == "enriched")
+        return f"{len(data)} people ({enriched} enriched)."
+    if kind == "attendees" and isinstance(data, dict):
+        proposed = data.get("proposed") or []
+        confirmed = data.get("confirmed") or []
+        return f"{len(proposed)} proposed, {len(confirmed)} confirmed."
+    if kind == "rsvps" and isinstance(data, dict):
+        rsvps = data.get("rsvps") or data.get("attendees") or []
+        counts = data.get("counts") or {}
+        if counts:
+            pretty = ", ".join(f"{v} {k}" for k, v in counts.items() if v and k != "total")
+            return f"{len(rsvps)} attendees — {pretty}."
+        return f"{len(rsvps)} attendees."
+    if kind == "dashboard" and isinstance(data, dict):
+        counts = data.get("counts") or {}
+        pretty = ", ".join(f"{v} {k}" for k, v in counts.items() if v)
+        return pretty or "no activity yet."
+    if kind == "invite_drafts" and isinstance(data, dict):
+        counts = data.get("counts") or {}
+        return ", ".join(f"{v} {k}" for k, v in counts.items()) or "no drafts."
+    if kind == "followup_drafts" and isinstance(data, dict):
+        drafts = data.get("drafts") or []
+        return f"{len(drafts)} follow-up drafts."
+    if kind == "attendee_followups" and isinstance(data, dict):
+        drafts = data.get("drafts") or []
+        return f"{len(drafts)} per-attendee drafts."
+    if kind == "notes" and isinstance(data, list):
+        important = sum(1 for n in data if n.get("important"))
+        return f"{len(data)} notes ({important} important)."
+    if kind == "notetaker_attendees" and isinstance(data, list):
+        with_notes = sum(1 for a in data if (a.get("note_count") or 0) > 0)
+        return f"{len(data)} checked in ({with_notes} have notes)."
+    if kind == "notetaker_events" and isinstance(data, list):
+        return f"{len(data)} events."
+    if kind == "event_notes_bundle" and isinstance(data, dict):
+        attendees = data.get("attendees") or []
+        total = data.get("total_notes") or 0
+        with_notes = sum(1 for a in attendees if (a.get("notes") or []))
+        return f"{total} notes across {with_notes}/{len(attendees)} attendees."
+    if kind == "analytics" and isinstance(data, dict):
+        funnel = data.get("funnel") or {}
+        if funnel:
+            return " → ".join(f"{k}:{v}" for k, v in funnel.items())
+    if isinstance(data, list):
+        return f"{len(data)} items."
+    return "(summary unavailable for this payload)"
+
+
+# Common shapes the API returns for lists-inside-a-dict. The formatter
+# unwraps these so users don't have to know the envelope name.
+_LIST_KEYS = ("rsvps", "drafts", "attendees", "people", "events", "keys", "templates")
+
+
+def _extract_rows(data: Any) -> list[dict[str, Any]] | None:
+    if isinstance(data, list):
+        return data
+    if isinstance(data, dict):
+        for k in _LIST_KEYS:
+            v = data.get(k)
+            if isinstance(v, list):
+                return v
+        # Special case: proposed-attendees view has {proposed, confirmed}.
+        if "proposed" in data and isinstance(data["proposed"], list):
+            return data["proposed"]
+    return None
+
+
+def _markdown_event_notes_bundle(data: dict[str, Any]) -> str:
+    """One-section-per-attendee transcript view of every note for an event."""
+    attendees = data.get("attendees") or []
+    if not attendees:
+        return "_(no checked-in attendees)_"
+    parts: list[str] = []
+    for a in attendees:
+        header = a.get("display_name") or a.get("name") or a.get("id") or "Unknown"
+        sub = []
+        if a.get("title"): sub.append(str(a["title"]))
+        if a.get("company"): sub.append(str(a["company"]))
+        suffix = f" — {' @ '.join(sub)}" if sub else ""
+        parts.append(f"### {header}{suffix}")
+        notes = a.get("notes") or []
+        if not notes:
+            parts.append("_(no notes)_")
+            continue
+        for n in notes:
+            ts = n.get("created_at", "")
+            star = "⭐ " if n.get("important") else ""
+            author = n.get("author_name") or ""
+            method = n.get("method") or ""
+            head = f"- **{ts}** {star}_{method}_"
+            if author:
+                head += f" · {author}"
+            parts.append(head)
+            content = _truncate(n.get("content"), 4000)
+            for line in content.splitlines() or [""]:
+                parts.append(f"    {line}")
+        parts.append("")
+    return "\n".join(parts).rstrip()
+
+
+def format_response(data: Any, format: Format, kind: str) -> Any:
+    """Shape a tool response for the model.
+
+    - `json`     → passthrough.
+    - `summary`  → a one-line description.
+    - `markdown` → table for list-shaped payloads, key/value list for dicts.
+    - `csv`      → standard CSV for list-shaped payloads; falls back to JSON
+                   for dicts (we don't try to flatten arbitrary objects).
+    """
+    fmt = (format or "json").lower()
+    if fmt == "json":
+        return data
+    if fmt == "summary":
+        return _summary(data, kind)
+
+    rows = _extract_rows(data)
+
+    if fmt == "markdown":
+        if kind == "event_notes_bundle" and isinstance(data, dict):
+            return _markdown_event_notes_bundle(data)
+        if rows is not None:
+            return _markdown_table(rows, kind)
+        if isinstance(data, dict):
+            return _markdown_kv(data)
+        return _truncate(data, 2000)
+
+    if fmt == "csv":
+        if rows is not None:
+            return _to_csv(rows, kind)
+        # CSV doesn't really fit dicts; punt back to JSON rather than
+        # producing something misleading.
+        return data
+
+    # Unknown format — fail soft and return JSON.
+    return data