io.github.thehesiod/psquare

Create a new class (section) at a school. Requires PS_ENABLE_WRITES. New classes are created **hidden** — they are not visible to staff, parents, or students until you call set_class_visibility. Assign teachers afterwards with add_class_staff. Args: school_id: School ID name: Class name (e.g. "Ms. Smith's Class") grade_ids: One or more grade IDs the class belongs to (from list_grades)

Assign teachers, assistants, or room parents to a class. Requires PS_ENABLE_WRITES. SAFETY: Never call this tool or remove_class_staff in parallel, even for different sections. ParentSquare replaces the full staff list, and concurrent writes have caused unrelated associations to disappear. The server serializes calls within this process; still use one call at a time and verify with a fresh get_class read before the next class-staff write. The class's existing staff are read first and preserved — only the listed people are added, all in a single update. Anyone already holding the role is skipped; anyone on the class under a different role is moved to this one. Room parents are ordinary guardians: get their user_id from list_parents. Teachers and assistants come from list_staff. Args: section_id: Class/section ID (from list_classes) user_ids: One or more user IDs (list_staff for staff, list_parents for room parents) role: One of TEACHER, ASSISTANT, ROOM_PARENT — applied to everyone in user_ids class_title: Optional label shown on the class (defaults to the role name)

Enroll students in a class. Requires PS_ENABLE_WRITES. SAFETY: Never call this tool or another class-staff/student-enrollment write in parallel. The server serializes section-membership writes within this process; still use one call at a time and verify with a fresh read. Adds everyone listed in a single call without disturbing the students already in the class or their other classes. Students already enrolled are skipped, so re-running is safe. To assign a whole grade at the start of the year, call this once per classroom with that classroom's students — list_students(grade=...) gives the ids. Args: section_id: Class/section ID (from list_classes) student_ids: One or more student IDs (from list_students)

Create a guardian/parent and link them to a student. Requires PS_ENABLE_WRITES. A parent is always created attached to at least one student. The new user id is not returned — call list_students or the parent roster afterward. Args: school_id: School ID student_id: Student ID to attach the guardian to (from list_students) first_name: Guardian first name last_name: Guardian last name email: Guardian email (optional) phone: Guardian phone (optional)

Add a teacher or other staff member to a school. Requires PS_ENABLE_WRITES. ParentSquare emails the new account an address-verification/registration invite. Passing section_ids assigns them to those classes right away (as class_role, default TEACHER) — verified live, because ParentSquare's own "invited classes" field does not create the assignment until the person registers, so this tool makes the assignment itself. Args: school_id: School ID first_name: Staff member's first name last_name: Staff member's last name email: Email address (optional but needed for them to register) phone: Phone number (optional) title: Title shown at the school, e.g. "3rd Grade Teacher" (optional) staff_id: The school's own staff/external ID (optional) is_admin: True to grant school Admin rather than Staff access section_ids: Class/section IDs to assign them to (from list_classes) class_role: Role for those classes — TEACHER (default) or ASSISTANT

Create a new student on a school's roster. Requires PS_ENABLE_WRITES. Use list_grades(school_id) to find the grade_id. The new student's id is not returned by ParentSquare — call list_students afterward to retrieve it. The roster is read back after the write, so the result says whether the student actually exists. If ParentSquare ever returns a 5xx here, do not retry on the status code alone: its error page is rendered after the record is saved, so the student may well have been created, and there is no API route to delete a duplicate. Args: school_id: School ID first_name: Student first name last_name: Student last name grade_id: Grade ID (from list_grades) student_sis_id: Optional SIS/external student ID

Send registration invitations to multiple guardians at once. Requires PS_ENABLE_WRITES. ParentSquare sends each unregistered guardian an email/text invite and automatically skips any that are already registered (the returned message reports how many of the selected users were actually notified). Get user_ids from list_parents(school_id) — typically those with registered=false. To "invite all", pass every unregistered user_id from list_parents. Args: school_id: School ID user_ids: Guardian user IDs to invite (from list_parents)

Download a photo, video, or file to local disk from a ParentSquare URL. Returns the local file path where the file was saved. Use URLs from list_photos, list_files, or get_post attachment results. Args: url: The file URL (from list_photos, list_files, or get_post results) filename: Optional custom filename. If not provided, uses the original filename from the URL.

Rename a class or change its room code / grades. Requires PS_ENABLE_WRITES. Only provided fields change — current values are read back from the class first and resent, because the underlying endpoint replaces what it is given. Staff are not affected; use add_class_staff / remove_class_staff for those. Args: section_id: Class/section ID (from list_classes) school_id: School ID the class belongs to name: New class name (optional) room: New room code / external ID, e.g. "Room 5" (optional) grade_ids: New list of grade IDs (optional; replaces the current grades)

Update a guardian's name, email, or phone. Requires PS_ENABLE_WRITES. Only provided fields change; existing student links are preserved. Get the user_id from list_parents(school_id). Args: school_id: School ID user_id: Guardian's user ID (from list_parents) first_name: New first name (optional) last_name: New last name (optional) email: New email (optional) phone: New phone (optional)

Update a staff member's name, email, phone, title, or staff ID. Requires PS_ENABLE_WRITES. Only provided fields change; everything else — including their class assignments and STAFF/ADMIN access level — is left untouched. Get the user_id from list_staff(school_id). To change which classes they teach, use add_class_staff / remove_class_staff instead. Guardians are rejected: use edit_parent for those. Args: school_id: School ID user_id: Staff member's user ID (from list_staff) first_name: New first name (optional) last_name: New last name (optional) email: New email (optional) phone: New phone (optional) title: New title shown at the school, e.g. "3rd Grade Teacher" (optional) staff_id: The school's own staff/external ID (optional)

Update an existing student. Only provided fields change. Requires PS_ENABLE_WRITES. Current values (name, SIS id, grade) are read from the edit form and preserved for any field you don't pass. Class enrollment is never touched — use add_class_students / remove_class_students / move_student_to_class. Args: school_id: School ID student_id: Student ID (from list_students) first_name: New first name (optional) last_name: New last name (optional) student_sis_id: New SIS/external ID (optional) grade_id: New grade ID (optional; from list_grades)

Get calendar events for a school using the ICS calendar export. Returns JSON array of events with title, start/end times, location, and description. Note: Some schools post monthly calendars as images or PDFs in the feed instead of using the ICS calendar. If this returns no events, use get_feeds to browse recent posts — look for posts with "calendar" in the title or image/PDF attachments. Use get_post to view them (images are returned inline so you can read them). Args: school_id: School ID

Get one class with its full staff list (teachers, assistants, room parents). Each staff entry includes the `user_id` (the person) and `assoc_id` (their link to this class). Use this before changing staff to see the current state. Args: section_id: Class/section ID (from list_classes)

Read a specific message conversation thread with all messages. IMPORTANT: Both school_id and chat_id are required. Args: school_id: School ID (same school_id used in list_conversations) chat_id: Conversation/chat ID (from list_conversations results)

List school contact info and staff directory with names, roles, and phone numbers. Returns JSON with school details (phone, address) and staff records. Use get_staff_member(school_id, user_id) for full staff details including email, photo, and office hours. Args: school_id: School ID

Get recent posts from a school's feed with titles, authors, dates, and summaries. Returns a paginated list of posts. Use get_post with the feed_id to see full details. Args: school_id: School ID page: Page number for pagination (default: 1)

Get posts from a specific group's feed. IMPORTANT: Both school_id and group_id are required. Args: school_id: School ID (same school_id used in list_groups) group_id: Group ID (from list_groups results)

Get full details of a specific post including body text, comments, and attachments. Image attachments are returned inline so you can see their contents directly. PDF attachments have their text extracted and included inline. Args: feed_id: Post/feed ID (shown as feed_id in get_feeds results)

Get detailed info for a specific staff member including email, photo, and office hours. Use get_directory first to find the user_id, then call this for full details. Returns structured data plus an inline profile photo when available. Args: school_id: School ID user_id: Staff member's user ID (from get_directory results)

Get admin detail for one student (name, grade, SIS id, linked guardians, classes). Args: student_id: Student ID (the `id` from list_students; == roster id)

Get student dashboard information including school, grade, classes, and teachers. Args: student_id: Student ID (use list_schools to see available students)

Send (or resend) a ParentSquare registration invitation to one guardian. Requires PS_ENABLE_WRITES. ParentSquare emails the guardian an invite to activate their account. The same endpoint is used to resend to an already-invited (but not yet registered) guardian. Get the user_id from list_parents(school_id); only guardians with registered=false need inviting. Args: school_id: School ID user_id: Guardian's user ID (from list_parents)

Link an existing guardian to an additional student. Requires PS_ENABLE_WRITES. Existing guardian-student links are left untouched. (Unlinking is a destructive op deferred to the ParentSquare website in v1.) Args: school_id: School ID user_id: Guardian's user ID (from list_parents) student_id: Student ID to link (from list_students)

List the students enrolled in one class. Args: section_id: Class/section ID (from list_classes)

List a school's classes (sections) with grades, teachers, and room-parent counts. Returns every class in one call. Use the `section_id` from results with get_class, edit_class, add_class_staff, remove_class_staff, and set_class_visibility. Args: school_id: School ID (from list_schools) name_contains: Optional case-insensitive substring filter on class name grade: Optional case-insensitive filter on grade name (e.g. "Kindergarten")

List message conversations for a school. Returns conversation IDs, participants, and previews. To read a full conversation, call get_conversation with BOTH the same school_id used here AND the chat_id shown in the results. Args: school_id: School ID (use list_schools to find available IDs)

List files and documents posted for a school. Returns file URLs for download_file. Args: school_id: School ID

List available forms and permission slips for a school. Shows form titles, authors, and dates. These are signable forms that may require parent signatures (e.g. field trip permission, driver forms). Use get_post with the feed_id to see the full form content. Args: school_id: School ID

List a school's grades with their grade_id values (needed for add_student). Grades are per-school and discovered at runtime. Use the returned `grade_id` with add_student / edit_student. Args: school_id: School ID (from list_schools)

List groups at a school with active post counts and descriptions. To view a group's posts, call get_group_feed with BOTH the same school_id used here AND the group_id shown in the results. Args: school_id: School ID (use list_schools to find available IDs)

List quick-access links for a school (calendars, menus, forms, etc.). Returns link names and URLs (typically Google Drive or external sites). Args: school_id: School ID

List alerts and notices for a school (urgent alerts, secure documents, consent forms). Args: school_id: School ID

List guardians/parents on a school's admin roster (user_id, name, email, phone, linked students). Returns the full parent roster in one call. Use the `user_id` from results in edit_parent and link_guardian_to_student. Args: school_id: School ID (from list_schools) name_contains: Optional case-insensitive substring filter on guardian name student_name_contains: Optional case-insensitive substring filter on the guardian's linked student names

List payment items for a school with summary stats and item prices. Shows upcoming/paid counts, total amount paid, and each payment post with its available items and prices. Args: school_id: School ID

List photos posted for a school. Returns photo URLs that can be used with download_file. Args: school_id: School ID page: Page number (default: 1)

List polls for a school with questions, options, and vote counts. Shows each poll's question, answer options with vote totals, and which option is winning. Args: school_id: School ID

List features available for a specific school by parsing its sidebar navigation. Returns a list of available sections (Feed, Messages, Calendar, Photos, etc.). Different schools may have different features enabled. Args: school_id: School ID (use list_schools to find available IDs)

List available schools and students in your ParentSquare account. Returns JSON with schools, students, and your user ID. Use the school_id and student_id values from this output in other tools. For school contact info (phone, address), use get_directory(school_id).

List sign-up and RSVP posts for a school (item donations, volunteer slots, event RSVPs). Shows each signup post with its title, progress (e.g. "53/103 Items"), and author. Use get_post with the feed_id to see full signup details including individual items. Args: school_id: School ID page: Page number for pagination (default: 1)

List a school's staff and admins (user_id, name, email, phone, role/title). Use the returned `user_id` with add_class_staff to assign a teacher to a class. Args: school_id: School ID (from list_schools) name_contains: Optional case-insensitive substring filter on staff name

List students on a school's admin roster (id, name, grade, SIS id, guardians). Returns the full roster in one call. Use the `id` from results as `student_id` in get_student, edit_student, add_parent, and link_guardian_to_student. Args: school_id: School ID (from list_schools) grade: Optional case-insensitive filter on grade name (e.g. "2nd Grade") name_contains: Optional case-insensitive substring filter on student name

List your logged volunteer hours for a school. Shows each logged entry with month, activity type, notes, and hours. Args: school_id: School ID

Switch a student from one class to another. Requires PS_ENABLE_WRITES. SAFETY: Never call this tool or another class-staff/student-enrollment write in parallel. The student's full class list is replaced, so the server holds one global lock across the read, computation, and PUT within this process. Applies both halves of the switch in a single request. The student's other classes are preserved. Omit from_section_id to add the new class while keeping every current one. Args: school_id: School ID the classes belong to student_id: Student ID (from list_students) to_section_id: Class to move the student into (from list_classes) from_section_id: Class to move them out of (optional)

Remove staff or room parents from a class. Requires PS_ENABLE_WRITES. SAFETY: Never call this tool or add_class_staff in parallel, even for different sections. ParentSquare replaces the full staff list, and concurrent writes have caused unrelated associations to disappear. The server serializes calls within this process; still use one call at a time and verify with a fresh get_class read before the next class-staff write. Pass user_ids to remove specific people, role to remove everyone holding that role on the class (e.g. role="ROOM_PARENT" clears that class's room parents), or both to remove only those people who hold that role. Everyone else on the class is preserved. To clear room parents school-wide, call list_classes and repeat this for each class with room_parent_count > 0. Args: section_id: Class/section ID (from list_classes) user_ids: One or more people to remove (optional if role is given) role: Remove all holders of this role: TEACHER, ASSISTANT, or ROOM_PARENT

Remove specific students from a class. Requires PS_ENABLE_WRITES. SAFETY: Never call this tool or another class-staff/student-enrollment write in parallel. The server serializes the complete school-map read and all resulting student writes within this process. Each student's other classes are read first and preserved — only this class is dropped. student_ids is required: this tool will not empty a class. Args: school_id: School ID the class belongs to section_id: Class/section ID (from list_classes) student_ids: The students to remove (from list_class_students)

Show or hide classes for staff, parents, and students. Requires PS_ENABLE_WRITES. Newly created classes start hidden, so a class made with add_class needs this before anyone can see or post to it. Hidden classes are not visible to staff, parents, or students. Args: school_id: School ID section_ids: Class/section IDs to update (from list_classes) visible: True to make the classes visible, False to hide them date: Optional YYYY-MM-DD date the change takes effect; defaults to today

Submit a 6-digit MFA verification code to complete ParentSquare login. When a ParentSquare tool returns an MFA error, a verification code is sent to your email. Check your email for the code and use this tool to complete authentication. Args: code: The 6-digit verification code from your email