piazza-mcp

piazza-mcp es un servidor MCP local y de solo lectura para buscar y leer discusiones de Piazza configuradas.

El servidor utiliza el paquete piazza-api creado por la comunidad y los endpoints internos no publicados de Piazza. No es una integración oficial de Piazza y puede dejar de funcionar cuando Piazza cambie su sitio web. Mantén límites de solicitudes conservadores y confirma que este método de acceso sea aceptable para tu cuenta e institución.

Requisitos

• Python 3.10 a 3.14.

• uv para la gestión de dependencias y del entorno.

• MCP Python SDK 1.x. El servidor utiliza la API de decorador Server de bajo nivel v1 y declara mcp>=1.28.1,<2.

Herramientas

• list-piazza-courses: lista los cursos configurados accesibles para la cuenta.

• list-piazza-posts: devuelve resúmenes recientes y acotados de publicaciones de un curso.

• get-piazza-post: devuelve un hilo normalizado y acotado.

• search-piazza-posts: busca en un curso configurado y devuelve resúmenes acotados.

Todas las herramientas son de solo lectura. Las llamadas específicas de un curso se restringen a los IDs en PIAZZA_COURSES. El texto de las publicaciones devuelto es texto plano acotado y se etiqueta como contenido generado por el usuario no confiable. El servidor no publica, responde, edita, descarga archivos adjuntos, expone listas de alumnos ni realiza operaciones de instructor.

list-piazza-posts acepta un limit de 1 a 25 y un offset de 0 a 500. Solicita otra página solo cuando la respuesta anterior indique truncated: true. Las búsquedas aceptan una consulta de como máximo 200 caracteres y devuelven como máximo 25 resultados. Las respuestas se almacenan en caché en memoria durante 60 segundos; es posible que se devuelvan datos de caché obsoletos después de un error de actualización.

Configuración

Copia la plantilla redactada y mantén privado el archivo resultante:

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 asigna IDs de cursos de Piazza a nombres para mostrar. Un ID de curso es el valor después de /class/ en una URL de curso de Piazza. Las variables de entorno del proceso tienen prioridad sobre .env. Cuando se ejecuta una rueda instalada fuera de este checkout, proporciona las variables a través del entorno del proceso.

Nunca confirmes .env, pegues credenciales en prompts ni incluyas credenciales, cookies, IDs de cursos o contenidos de publicaciones en los registros. Las cuentas que requieren SSO exclusivo de la institución pueden no admitir el flujo de correo electrónico/contraseña utilizado por el paquete no oficial.

Ejecutar y registrar

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

Registra el checkout con Codex:

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

El .env local del checkout se carga de forma diferida cuando se llama a la primera herramienta de Piazza. Puedes actualizar el registro con:

./scripts/update_mcp_server.sh

Reinicia el cliente MCP después de cambiar el catálogo de herramientas.

Estructura del proyecto

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/

Desarrollo

El inspector seguro para la privacidad carga como máximo cinco resúmenes y un hilo completo, y luego imprime recuentos agregados de claves, tipos y anidación sin imprimir valores de publicaciones:

uv run --frozen python scripts/inspect_piazza_shapes.py

Aún así realiza solicitudes en vivo. Ejecútalo solo cuando tengas la intención explícita de acceder a la cuenta de Piazza configurada.

Ejecuta la suite de verificación sin conexión:

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

Depura el servidor con MCP Inspector:

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