piazza-mcp: Instructions file for Claude Code

Piazza MCP Server — Project Context

What This Is

An MCP server that lets AI agents browse a user's Piazza course forum — searching posts, reading questions/answers, and discovering relevant course content to assist with coursework.

Architecture

src/ layout with uv for dev and running. Two source files:

• server.py — FastMCP server with 4 tools, startup auth, class state management, tool descriptions
• formatting.py — html2text wrapper, snippet generation, post/answer/followup formatting

Authentication

Env vars: PIAZZA_EMAIL, PIAZZA_PASSWORD. Server calls Piazza.user_login() once on startup.

Design Decisions

Tool Design (4 tools)

list_classes() — Returns only active enrolled classes: name, term, course number, network ID. Filters out old/inactive classes via the status field from Piazza's user.status API. Does not show which class is currently active in the server — the agent always treats it as a fresh start and must select a class. This ensures the agent always follows the same predictable flow: list → select → search.

set_class(network_id) — Sets the active class and returns class name/term (confirmation) plus list of all available folders/tags. Called once at the start of a session before any searching. The agent doesn't know whether a class is already active, so it always calls this — which is the desired behavior.

Folder names matter because naming isn't predictable — "assignment 1" might be "hw1", "a1", or "problem_set_1". The agent needs to see the actual folder names to map user intent to the right filter.

search_posts(query, folder, limit) — Unified search/browse tool. Three modes:

• No args: recent posts (feed/browse mode)
• query only: keyword search across all posts
• folder only: all posts in a specific folder
• both: keyword search filtered to a folder (search API → client-side folder filter)

Returns per result: post number (@123), subject, snippet (~150 chars), folders/tags, answer status (instructor/student/unanswered), type, date.