parentsquare-mcp 0.1.0__tar.gz

parentsquare_mcp-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.pyc
+*.pyo
+.venv/
+*.egg-info/
+dist/
+build/
+.eggs/
+.idea/
+
+# Local Claude Code settings (contains project-specific permissions with personal IDs)
+.claude/settings.local.json

parentsquare_mcp-0.1.0/CLAUDE.md

@@ -0,0 +1,89 @@
+# ParentSquare MCP Server
+
+## Architecture
+
+MCP server that scrapes ParentSquare's web UI. Runs as stdio transport. While there's no documented public API, ParentSquare has an internal JSON:API at `/api/v2/` that some tools use (e.g. directory).
+
+```
+server.py          — MCP tool definitions, inline image/PDF fetching
+client.py          — HTTP client with auto-relogin on session expiry
+auth.py            — Cookie persistence (~/.parentsquare_cookies.json), 1Password credential loading, MFA flow
+config.py          — URL templates and constants (no personal data — auto-discovered at runtime)
+models.py          — Dataclasses for all parsed entities
+download.py        — File download with conflict handling
+parsers/           — One module per page type (feeds, calendar, media, messages, etc.)
+export_cookies.py  — CLI helper to bootstrap cookies from browser DevTools
+```
+
+## Key Patterns
+
+### Authentication
+- Cookies are lazy-loaded from `~/.parentsquare_cookies.json` on startup (no network call)
+- On session expiry (detected by redirect to `/signin`), credentials are fetched from 1Password CLI (`op item get Parentsquare` — item must be named "Parentsquare" with fields labeled `username` and `password`)
+- MFA state persists to disk (`.parentsquare_mfa_state.json`) so it survives server restarts
+- The server supports MCP elicitation for inline MFA code entry
+- **User-Agent must include "Chrome"** — ParentSquare returns 403 `browser_unsupported` otherwise. The server sets this in `app_lifespan`.
+- The `ps_s` session cookie is **httpOnly** — it can't be read via `document.cookie`, which is why `export_cookies` requires the Network tab in DevTools
+- `ps_s` rotates on every request. `PSClient` calls `_save_cookies_if_changed()` after each successful request to persist the latest value.
+- GraphQL requests (used by `list_groups`) require a CSRF token extracted from a page's `<meta name="csrf-token">` tag. MFA submit also requires a CSRF token from the MFA page.
+
+### JSON:API (`/api/v2/`)
+ParentSquare has an internal JSON:API (not publicly documented). Discovered by inspecting JS bundle XHR calls:
+- **`/api/v2/schools/{id}`** — school info (name, phone, address, timezone). Used by `get_directory`.
+- **`/api/v2/schools/{id}/directory`** — staff directory (JSON:API format with `included` array containing staff records). Used by `get_directory`.
+- **`/api/v2/schools/{id}/users/{user_id}`** — individual staff details (email, photo, virtual phone, office hours). Used by `get_staff_member`.
+- **`/api/v2/users/{id}/virtual_phone_search`** — POST with `{"staff_ids": [...]}` to batch-fetch virtual phone numbers. Used by `get_directory`.
+- **`/api/v2/sections/{id}/staff`** and **`/api/v2/sections/{id}/students`** — per-section (class) directory lookups.
+- Use `client.get_json()` for GET and `client.post_json()` for POST (handles CSRF tokens automatically).
+- Many pages that appear empty in HTML are actually shell pages that load data via this API. If an HTML parser returns no data, check the JS bundle for `/api/v2/` XHR calls.
+
+### HTML Parsing
+- All parsing uses BeautifulSoup with `html.parser`
+- Two distinct image patterns exist in the DOM:
+  - `img.feed-image-thumbnail` — gallery/attached images (outside description div)
+  - `<img>` inside `.description` div — inline embedded images
+- S3/CloudFront download links carry original filenames in `response-content-disposition` query params
+- URL deduplication via `_url_path_key()` prevents returning the same image as both thumbnail and full-size
+
+### Response Formats
+- **Structured JSON** (`-> dict`): `list_schools`, `get_calendar_events`, `get_directory`, `get_student_dashboard` — return dicts that FastMCP serializes as JSON. Better for data-lookup where Claude filters/extracts fields.
+- **Mixed list** (`-> list`): `get_post`, `get_staff_member` — return a list of text + MCP `Image` objects for inline media.
+- **Markdown text** (`-> str`): all other tools — formatted markdown for content-rich responses.
+
+### Inline Content
+- `get_post`: images downloaded as MCP `Image` objects (5 MB per image, 10 MB total cap), PDFs text-extracted via pymupdf
+- `get_staff_member`: profile photo returned as inline `Image`
+- This lets Claude "see" attached calendars, flyers, staff photos etc. without extra tool calls
+
+## Known Gotchas
+
+### Schools Without ICS Calendars
+Some schools don't use the ICS calendar feature. Instead, monthly calendars are posted as **image attachments** in feed posts (e.g. weekly update posts). When `get_calendar_events` returns empty, Claude should:
+1. Browse feeds looking for posts with calendar-like attachment names or body text mentioning "calendar"
+2. Open those posts to view the inline calendar images
+3. Read the calendar image content to answer date questions
+
+### Feed Text: Expanded vs Truncated
+ParentSquare renders both a truncated and expanded (full) version of each post's text in the feed HTML. The expanded version is hidden via `display: none` CSS. The feed parser prefers the expanded version, giving Claude full post text without extra HTTP requests. This is critical — key phrases like "review the attached calendar" or "February Break" are often past the truncation boundary.
+
+## Development
+
+```bash
+uv run parentsquare-mcp              # Run the MCP server
+uv run parentsquare-export-cookies   # Bootstrap cookies from browser
+```
+
+### Adding a New Parser
+1. Create `parsers/<name>.py` with a `parse_*` function that takes `BeautifulSoup` and returns dataclass(es)
+2. Add dataclass(es) to `models.py`
+3. Add the tool in `server.py` using the `@mcp.tool` decorator
+4. Wire through `_with_mfa_retry` for auth handling
+5. Add the URL template to `config.py` if needed
+
+### Account Discovery
+Schools, students, and user ID are auto-discovered at runtime from ParentSquare pages (`gon.*` script variables, sidebar student links, and the school switcher AJAX endpoint). School names are fetched via `/api/v2/schools/{id}`. No config file needed.
+
+## Open Improvement Areas
+
+- **Feed search**: No keyword search/filter on `get_feeds` — Claude must paginate and scan titles/summaries manually. A search tool or keyword parameter would help.
+- **CloudFront URL expiry**: S3/CloudFront signed URLs expire. Cached attachment URLs from older sessions may 403.

parentsquare_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexander Mohr
+
+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.

parentsquare_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: parentsquare-mcp
+Version: 0.1.0
+Summary: MCP server for ParentSquare school communication platform
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: beautifulsoup4>=4.13.0
+Requires-Dist: icalendar>=6.0.0
+Requires-Dist: mcp>=1.26.0
+Requires-Dist: requests>=2.32.0
+Provides-Extra: pdf
+Requires-Dist: pymupdf>=1.27.0; extra == 'pdf'

parentsquare_mcp-0.1.0/README.md

@@ -0,0 +1,100 @@
+# ParentSquare MCP Server
+
+An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that gives Claude access to [ParentSquare](https://www.parentsquare.com), a school-parent communication platform. Since ParentSquare has no public API, this server scrapes the web interface using saved session cookies.
+
+## Features
+
+### Feed & Posts
+- **`get_feeds`** — Browse paginated school feed with titles, authors, summaries, and attachment names
+- **`get_post`** — Full post details with body text, comments, poll results, signup items, and **inline image/PDF content** (Claude can "see" attached calendars, flyers, etc.)
+- **`get_group_feed`** — Posts from a specific group
+
+### Calendar
+- **`get_calendar_events`** — Events from ICS calendar as structured JSON (title, start/end, location, description)
+- Falls back to guiding Claude to search feed posts for image/PDF calendars when ICS is empty
+
+### Communication
+- **`list_conversations`** / **`get_conversation`** — Read message threads
+- **`get_directory`** — Staff directory as structured JSON (name, role, phone, user_id)
+- **`get_staff_member`** — Full staff details with email, office hours, and **inline profile photo**
+
+### Media & Files
+- **`list_photos`** — Photo gallery with URLs
+- **`list_files`** — Document files
+- **`download_file`** — Download any attachment to local disk
+
+### Participate
+- **`list_signups`** — Sign-up and RSVP posts with progress tracking (e.g. "53/103 Items")
+- **`list_notices`** — Alerts and secure documents
+- **`list_polls`** — Polls with vote counts and winning options
+- **`list_forms`** — Permission slips and signable forms
+- **`list_payments`** — Payment items with prices and summary stats
+- **`list_volunteer_hours`** — Logged volunteer hours with totals
+
+### Groups & Discovery
+- **`list_schools`** — Schools and students as structured JSON
+- **`list_school_features`** — Available sections per school (parsed from sidebar)
+- **`list_groups`** — Groups with member counts, descriptions, and membership status
+- **`list_links`** — Quick-access links (Google Drive, external sites)
+
+### Student
+- **`get_student_dashboard`** — School, grade, classes, and teachers as structured JSON
+
+### Authentication
+- **`submit_mfa_code`** — Complete MFA verification with a 6-digit code
+- Supports MCP elicitation for inline MFA prompts
+- Session cookies persisted to `~/.parentsquare_cookies.json`
+- Credentials loaded from 1Password CLI on session expiry
+
+## Setup
+
+### Prerequisites
+- [1Password CLI](https://developer.1password.com/docs/cli/) (`op`) with a "Parentsquare" item containing `username` and `password` fields
+
+### Install in Claude Code
+
+```bash
+claude mcp add --transport stdio parentsquare -- uvx --from git+https://github.com/thehesiod/psquare-mcp parentsquare-mcp
+```
+
+To enable PDF text extraction for post attachments (optional, AGPL-3.0 licensed):
+
+```bash
+claude mcp add --transport stdio parentsquare -- uvx --from "psquare-mcp[pdf] @ git+https://github.com/thehesiod/psquare-mcp" parentsquare-mcp
+```
+
+### That's It
+
+No further configuration needed. The server **auto-discovers** your schools, students, and user ID from ParentSquare on first use. Authentication is handled automatically via 1Password CLI — when the session expires, the server loads your credentials from 1Password and re-authenticates (including MFA if needed).
+
+## How It Works
+
+The server uses `requests` + `BeautifulSoup` to scrape ParentSquare's server-rendered HTML pages. Each tool follows the pattern:
+
+1. **Fetch** the HTML page via `PSClient.get_page()` or JSON via `PSClient.get_json()` (auto-relogins on session expiry)
+2. **Parse** with a dedicated parser in `parsers/` that extracts structured data into dataclasses
+3. **Return** results as either structured JSON dicts (for data-lookup tools) or markdown text (for content-rich tools)
+
+Data-lookup tools (`list_schools`, `get_directory`, `get_calendar_events`, `get_student_dashboard`, `get_staff_member`) return structured JSON for easy programmatic access. Content tools (`get_post`, `get_feeds`, `get_conversation`) return markdown.
+
+On first use, the server auto-discovers your schools, students, and user ID from ParentSquare (no config file needed).
+
+For `get_post`, image attachments are downloaded and returned as MCP `Image` objects (so Claude can see them), and PDF attachments have their text extracted via pymupdf. `get_staff_member` also returns inline profile photos.
+
+Groups use a GraphQL endpoint (`/graphql`) instead of HTML scraping. The directory and staff details use the internal `/api/v2/` JSON:API.
+
+## Dependencies
+
+| Package | Purpose | License |
+|---------|---------|---------|
+| `mcp` | Model Context Protocol SDK | MIT |
+| `requests` | HTTP client | Apache 2.0 |
+| `beautifulsoup4` | HTML parsing | MIT |
+| `icalendar` | ICS calendar parsing | BSD |
+| `pymupdf` | PDF text extraction (optional) | AGPL-3.0 |
+
+## License
+
+MIT — see [LICENSE](LICENSE). Note: the optional `pymupdf` dependency is AGPL-3.0 licensed.
+
+<!-- mcp-name: io.github.thehesiod/psquare -->

parentsquare_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[project]
+name = "parentsquare-mcp"
+version = "0.1.0"
+description = "MCP server for ParentSquare school communication platform"
+license = "MIT"
+requires-python = ">=3.12"
+dependencies = [
+    "mcp>=1.26.0",
+    "requests>=2.32.0",
+    "beautifulsoup4>=4.13.0",
+    "icalendar>=6.0.0",
+]
+
+[project.optional-dependencies]
+pdf = ["pymupdf>=1.27.0"]
+
+[project.scripts]
+parentsquare-mcp = "parentsquare_mcp.server:main"
+parentsquare-export-cookies = "parentsquare_mcp.export_cookies:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

parentsquare_mcp-0.1.0/src/parentsquare_mcp/auth.py

@@ -0,0 +1,273 @@
+from __future__ import annotations
+
+import json
+import logging
+import os
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from urllib.parse import parse_qs, urlparse
+
+import requests
+from bs4 import BeautifulSoup
+
+from parentsquare_mcp.config import BASE_URL
+
+logger = logging.getLogger(__name__)
+
+COOKIE_FILE = Path(os.environ.get("PS_COOKIE_FILE", "~/.parentsquare_cookies.json")).expanduser()
+MFA_STATE_FILE = COOKIE_FILE.with_name(".parentsquare_mfa_state.json")
+
+
+@dataclass
+class MFAState:
+    """Stores state needed to complete MFA verification."""
+
+    contact_value: str  # masked email/phone from redirect
+    contact_method: str  # "email" or "phone"
+    email: str  # the actual email used to login
+    csrf_token: str = ""  # CSRF token from the MFA page — required for /mfa/submit
+
+    def save(self) -> None:
+        """Persist MFA state to disk so it survives server restarts."""
+        MFA_STATE_FILE.parent.mkdir(parents=True, exist_ok=True)
+        MFA_STATE_FILE.write_text(json.dumps({
+            "contact_value": self.contact_value,
+            "contact_method": self.contact_method,
+            "email": self.email,
+            "csrf_token": self.csrf_token,
+        }))
+        logger.info(f"Saved MFA state to {MFA_STATE_FILE}")
+
+    @classmethod
+    def load(cls) -> MFAState | None:
+        """Load persisted MFA state from disk. Returns None if not found."""
+        if not MFA_STATE_FILE.exists():
+            return None
+        try:
+            data = json.loads(MFA_STATE_FILE.read_text())
+            return cls(
+                contact_value=data["contact_value"],
+                contact_method=data["contact_method"],
+                email=data["email"],
+                csrf_token=data.get("csrf_token", ""),
+            )
+        except (json.JSONDecodeError, KeyError) as e:
+            logger.warning(f"Failed to load MFA state: {e}")
+            return None
+
+    @staticmethod
+    def clear() -> None:
+        """Remove persisted MFA state file."""
+        if MFA_STATE_FILE.exists():
+            MFA_STATE_FILE.unlink()
+            logger.info("Cleared MFA state file")
+
+
+class MFARequiredError(Exception):
+    """Raised when login succeeds but MFA verification is needed."""
+
+    def __init__(self, mfa_state: MFAState):
+        self.mfa_state = mfa_state
+        masked = mfa_state.contact_value
+        method = mfa_state.contact_method
+        super().__init__(
+            f"MFA verification required. A 6-digit code was sent to your {method} ({masked}). "
+            f"Use the submit_mfa_code tool to provide the code."
+        )
+
+
+def load_credentials_from_1password() -> tuple[str, str]:
+    """Load ParentSquare credentials from 1Password via CLI."""
+    result = subprocess.run(
+        ["op", "item", "get", "Parentsquare", "--fields", "label=username,label=password", "--format", "json"],
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    fields = json.loads(result.stdout)
+    creds: dict[str, str] = {}
+    for field_obj in fields:
+        label = field_obj.get("label", "")
+        value = field_obj.get("value", "")
+        if label in ("username", "password"):
+            creds[label] = value
+    if "username" not in creds or "password" not in creds:
+        raise RuntimeError(f"Could not find username/password in 1Password. Got fields: {list(creds.keys())}")
+    return creds["username"], creds["password"]
+
+
+def save_cookies(session: requests.Session) -> None:
+    """Persist session cookies to disk for reuse across server restarts."""
+    cookies = {}
+    for cookie in session.cookies:
+        cookies[cookie.name] = {
+            "value": cookie.value,
+            "domain": cookie.domain,
+            "path": cookie.path,
+            "secure": cookie.secure,
+        }
+    COOKIE_FILE.write_text(json.dumps(cookies, indent=2))
+    logger.info(f"Saved {len(cookies)} cookies to {COOKIE_FILE}")
+
+
+def load_cookies(session: requests.Session) -> bool:
+    """Load previously saved cookies. Returns True if cookies were loaded."""
+    if not COOKIE_FILE.exists():
+        return False
+    try:
+        cookies = json.loads(COOKIE_FILE.read_text())
+        for name, data in cookies.items():
+            session.cookies.set(
+                name,
+                data["value"],
+                domain=data.get("domain", ".parentsquare.com"),
+                path=data.get("path", "/"),
+            )
+        logger.info(f"Loaded {len(cookies)} cookies from {COOKIE_FILE}")
+        return True
+    except (json.JSONDecodeError, KeyError) as e:
+        logger.warning(f"Failed to load cookies: {e}")
+        return False
+
+
+def extract_csrf_token(session: requests.Session) -> str:
+    """GET /signin and extract CSRF token from <meta name='csrf-token'> tag."""
+    resp = session.get(f"{BASE_URL}/signin")
+    resp.raise_for_status()
+    soup = BeautifulSoup(resp.text, "html.parser")
+    meta = soup.find("meta", attrs={"name": "csrf-token"})
+    if not meta or not meta.get("content"):
+        raise RuntimeError("Could not find CSRF token on signin page")
+    return meta["content"]
+
+
+def login(session: requests.Session, email: str, password: str) -> None:
+    """Perform full login flow: extract CSRF, POST credentials, verify success.
+
+    If 2FA is required, raises MFARequiredError with state needed to complete
+    verification via submit_mfa_code().
+    """
+    logger.info("Logging in to ParentSquare...")
+    csrf = extract_csrf_token(session)
+    resp = session.post(
+        f"{BASE_URL}/sessions",
+        data={
+            "utf8": "✓",
+            "authenticity_token": csrf,
+            "session[email]": email,
+            "session[password]": password,
+            "commit": "Sign In",
+        },
+        headers={
+            "Content-Type": "application/x-www-form-urlencoded",
+            "Referer": f"{BASE_URL}/signin",
+        },
+        allow_redirects=True,
+    )
+
+    # After successful login, should redirect away from /signin
+    if "mfa_required" in resp.url:
+        # Parse MFA redirect params: /signin?mfa_required=true&contact_value=...&contact_method=email
+        parsed = urlparse(resp.url)
+        params = parse_qs(parsed.query)
+        contact_value = params.get("contact_value", [""])[0]
+        contact_method = params.get("contact_method", ["email"])[0]
+        logger.info(f"MFA required — code sent to {contact_method}: {contact_value}")
+
+        # Extract CSRF token from the MFA page — Rails requires this for /mfa/submit
+        mfa_soup = BeautifulSoup(resp.text, "html.parser")
+        csrf_meta = mfa_soup.find("meta", attrs={"name": "csrf-token"})
+        csrf_token = csrf_meta["content"] if csrf_meta and csrf_meta.get("content") else ""
+        if csrf_token:
+            logger.info("Captured CSRF token from MFA page")
+        else:
+            logger.warning("No CSRF token found on MFA page")
+
+        # Save cookies from login attempt — needed for /mfa/submit
+        save_cookies(session)
+
+        mfa_state = MFAState(
+            contact_value=contact_value,
+            contact_method=contact_method,
+            email=email,
+            csrf_token=csrf_token,
+        )
+        # Persist MFA state so it survives server restarts
+        mfa_state.save()
+        raise MFARequiredError(mfa_state)
+
+    if "/signin" in resp.url:
+        raise RuntimeError("Login failed — redirected back to signin. Check credentials.")
+
+    logger.info("Successfully logged in to ParentSquare")
+    save_cookies(session)
+
+
+def submit_mfa(session: requests.Session, mfa_state: MFAState, code: str) -> None:
+    """Submit a 6-digit MFA verification code to complete login.
+
+    Args:
+        session: The requests session (must already have cookies from login attempt)
+        mfa_state: MFA state from the login redirect
+        code: The 6-digit verification code from email/phone
+    """
+    logger.info("Submitting MFA verification code...")
+    payload: dict[str, str] = {
+        "data_value": mfa_state.contact_value,
+        "code": code,
+    }
+    if mfa_state.contact_method == "email":
+        payload["email"] = mfa_state.email
+    else:
+        payload["phone"] = mfa_state.contact_value
+
+    headers = {
+        "Content-Type": "application/json",
+        "Accept": "application/json",
+        "X-Requested-With": "XMLHttpRequest",
+        "Referer": f"{BASE_URL}/signin",
+    }
+    if mfa_state.csrf_token:
+        headers["X-CSRF-Token"] = mfa_state.csrf_token
+
+    resp = session.post(
+        f"{BASE_URL}/mfa/submit",
+        json=payload,
+        headers=headers,
+    )
+
+    if resp.status_code == 401:
+        raise RuntimeError(
+            "MFA verification failed — invalid or expired code. "
+            "Check your email for the latest code and try submit_mfa_code again."
+        )
+    resp.raise_for_status()
+
+    data = resp.json()
+    redirect_url = data.get("redirect_url", "")
+    if redirect_url:
+        # Follow the redirect to establish the full session
+        if redirect_url.startswith("/"):
+            redirect_url = f"{BASE_URL}{redirect_url}"
+        session.get(redirect_url)
+
+    logger.info("MFA verification successful")
+    save_cookies(session)
+    MFAState.clear()
+
+
+def is_session_valid(session: requests.Session) -> bool:
+    """Quick check: does a request to the root page redirect to /signin?"""
+    resp = session.get(f"{BASE_URL}/", allow_redirects=False)
+    if resp.status_code == 302:
+        location = resp.headers.get("Location", "")
+        return "/signin" not in location
+    return resp.status_code == 200
+
+
+def ensure_session(session: requests.Session, email: str, password: str) -> None:
+    """Re-login if session has expired."""
+    if not is_session_valid(session):
+        logger.info("Session expired, re-authenticating...")
+        login(session, email, password)