# 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.

**`get_post(post_number)`** — Full post content formatted as readable markdown: subject and body, instructor answer (if any), student answer (if any) with endorsement status, all follow-up discussions with replies (no truncation), folders, date.

### Agent Tool Descriptions

The docstrings on each tool are carefully written to guide the agent's behavior. Key points embedded in descriptions:
- `list_classes`: Agent should use context clues to pick the right class, ask user if ambiguous
- `set_class`: Agent must call this once before search/get_post; should check folder names carefully
- `search_posts`: Prefer folder filtering for assignment-specific content; keyword search doesn't search folder names; keyword search requires ALL keywords to match so keep queries to 1-2 words max
- `get_post`: Use post number from search results or user reference like '@142'

### State Management

From the agent's perspective, every conversation looks the same — it doesn't know if a class is already active. The server hides this state.

**Every conversation (agent's view is identical):**
```
list_classes() → sees enrolled classes (no active indicator)
→ set_class("abc123") for the right class (inferred or asked)
→ gets folders: ["hw1", "hw2", "hw3", "midterm", "logistics"]
→ search_posts(folder="hw3") or search_posts(query="late policy")
→ get_post(142) → reads full content
```

**What happens internally:**
- `set_class` creates a Network connection and fetches class metadata from `user.status`
- Subsequent `search_posts`/`get_post` calls use the stored Network object

## Content Formatting (`formatting.py`)

Uses `html2text` for HTML-to-markdown. All text fields go through entity decoding (`html.unescape`) — post subjects in both search results and full posts, snippets via `make_snippet()`, and body content via `html_to_markdown()`. The Piazza API returns only post content HTML (no page chrome), so html2text works well without a custom parser.

The module handles:
- Post body HTML → readable markdown (via html2text)
- HTML entity decoding on all text fields (subjects, snippets, content)
- Extracting nested answer/followup structure from raw API response (the `children` field in Piazza's JSON)
- Snippet generation: strip HTML tags, decode entities, collapse whitespace, truncate to ~150 chars
- Building formatted output for both search result summaries and full post views

## Verification Checklist

1. `uv run piazza-mcp` starts without errors
2. `list_classes()` returns only active enrolled courses (no active class indicator)
3. `set_class()` returns class name + folder list
4. `search_posts()` with no args returns recent feed
5. `search_posts(folder="hw1")` returns folder-filtered results with snippets
6. `search_posts(query="deadline")` returns keyword matches
7. `search_posts(query="extension", folder="hw1")` returns combined results
8. `get_post(N)` returns readable markdown with all answers and followups

## Distribution

Published to PyPI as `piazza-mcp`. Users install via `uvx piazza-mcp@latest` — no cloning needed.

**Release flow:**
1. Bump `version` in `pyproject.toml`
2. `rm -rf dist && uv build && uv publish`

The `@latest` suffix in user configs ensures they get new versions on MCP client restart. Without it, `uvx` caches the first-resolved version indefinitely.

The `[project.scripts]` entry point defines the `piazza-mcp` console command used by `uvx`.
