piazza-mcp

piazza-mcp는 구성된 Piazza 토론을 검색하고 읽기 위한 로컬, 읽기 전용 MCP 서버입니다.

이 서버는 커뮤니티에서 만든 piazza-api 패키지와 Piazza의 비공개 내부 엔드포인트를 사용합니다. 공식 Piazza 통합이 아니며, Piazza가 웹사이트를 변경하면 작동이 중단될 수 있습니다. 요청 한도를 보수적으로 유지하고 이 접근 방식이 본인의 계정과 기관에서 허용되는지 확인하세요.

요구 사항

• Python 3.10 ~ 3.14.

• uv — 의존성 및 환경 관리용.

• MCP Python SDK 1.x. 서버는 v1 저수준 Server 데코레이터 API를 사용하며 mcp>=1.28.1,<2를 선언합니다.

도구

• list-piazza-courses: 계정에서 접근 가능한 구성된 강좌를 나열합니다.

• list-piazza-posts: 한 강좌의 최근 게시물 요약을 제한된 범위로 반환합니다.

• get-piazza-post: 하나의 제한된 정규화 스레드를 반환합니다.

• search-piazza-posts: 구성된 한 강좌를 검색하고 제한된 요약을 반환합니다.

모든 도구는 읽기 전용입니다. 강좌 범위 호출은 PIAZZA_COURSES의 ID로 제한됩니다. 반환되는 게시물 텍스트는 제한된 일반 텍스트이며 신뢰할 수 없는 사용자 생성 콘텐츠로 표시됩니다. 서버는 게시, 답변, 편집, 첨부 파일 다운로드, 명단 노출 또는 강사 작업을 수행하지 않습니다.

list-piazza-posts는 125 사이의 limit과 0500 사이의 offset을 허용합니다. 이전 응답이 truncated: true를 보고한 경우에만 다음 페이지를 요청하세요. 검색은 최대 200자의 쿼리를 허용하며 최대 25개의 결과를 반환합니다. 응답은 메모리에 60초 동안 캐시됩니다. 새로고침 실패 후에는 오래된 캐시 데이터가 반환될 수 있습니다.

구성

수정된 템플릿을 복사하고 결과 파일을 비공개로 유지하세요:

cp .env.example .env
chmod 600 .env

PIAZZA_EMAIL="student@example.edu"
PIAZZA_PASSWORD="replace-with-your-password"
PIAZZA_COURSES='{"abc123":"CMSC 132","xyz789":"CMSC 216"}'

PIAZZA_COURSES는 Piazza 강좌 ID를 표시 이름에 매핑합니다. 강좌 ID는 Piazza 강좌 URL에서 /class/ 뒤의 값입니다. 프로세스 환경 변수는 .env보다 우선합니다. 이 체크아웃 외부에서 설치된 wheel을 실행할 때는 프로세스 환경을 통해 변수를 제공하세요.

.env를 커밋하거나, 프롬프트에 자격 증명을 붙여넣거나, 로그에 자격 증명, 쿠키, 강좌 ID 또는 게시물 내용을 포함하지 마세요. 기관 전용 SSO가 필요한 계정은 비공식 패키지에서 사용하는 이메일/비밀번호 흐름을 지원하지 않을 수 있습니다.

실행 및 등록

uv sync --locked
uv run --frozen piazza-mcp

체크아웃을 Codex에 등록:

codex mcp add piazza-mcp \
  -- uv --directory /absolute/path/to/piazza_mcp run --frozen piazza-mcp

체크아웃 로컬 .env는 첫 번째 Piazza 도구가 호출될 때 지연 로드됩니다. 등록을 새로고침하려면:

./scripts/update_mcp_server.sh

도구 카탈로그를 변경한 후 MCP 클라이언트를 다시 시작하세요.

프로젝트 구조

src/piazza_mcp/
  server.py              MCP protocol boundary and dispatch
  config/
    env.py               lazy checkout-local .env loading
    piazza.py            credentials and course allowlist
  mcp_schemas/
    piazza.py            structured-output contracts
  mcp_tools/
    piazza.py            tool descriptions, inputs, and annotations
  models/
    piazza.py            bounded Piazza data structures
  services/piazza/
    client.py            timeout-bound unofficial API adapter
    normalizer.py        HTML cleanup and response normalization
    profiler.py          privacy-safe aggregate shape diagnostics
    service.py           allowlisting, limits, caching, and serialization
    factory.py           lazy configured service construction
tests/
  config/
  mcp_schemas/
  mcp_tools/
  server/
  services/piazza/

개발

개인정보 보호 검사기는 최대 5개의 요약과 1개의 전체 스레드를 로드한 다음 게시물 값을 출력하지 않고 집계 키, 유형 및 중첩 횟수를 출력합니다:

uv run --frozen python scripts/inspect_piazza_shapes.py

여전히 실시간 요청을 수행합니다. 구성된 Piazza 계정에 명시적으로 접근하려는 경우에만 실행하세요.

오프라인 검증 스위트를 실행:

uv lock --check
uv run --frozen pytest -q
uv run --frozen python -m compileall -q src/piazza_mcp tests scripts
uv build

MCP Inspector로 서버를 디버그:

npx @modelcontextprotocol/inspector \
  uv --directory /absolute/path/to/piazza_mcp run --frozen piazza-mcp