piazza-mcp

piazza-mcp — это локальный MCP-сервер только для чтения для поиска и чтения настроенных обсуждений Piazza.

Сервер использует пакет piazza-api, созданный сообществом, и неопубликованные внутренние конечные точки Piazza. Это не официальная интеграция Piazza, и она может перестать работать при изменении веб-сайта Piazza. Соблюдайте консервативные лимиты запросов и убедитесь, что этот метод доступа приемлем для вашей учетной записи и учебного заведения.

Требования

• Python 3.10–3.14.

• uv для управления зависимостями и окружением.

• MCP Python SDK 1.x. Сервер использует низкоуровневый API декоратора Server версии 1 и объявляет mcp>=1.28.1,<2.

Инструменты

• list-piazza-courses: перечисляет настроенные курсы, доступные для учетной записи.

• list-piazza-posts: возвращает ограниченные сводки последних сообщений для одного курса.

• get-piazza-post: возвращает одну ограниченную нормализованную ветку обсуждения.

• search-piazza-posts: выполняет поиск по одному настроенному курсу и возвращает ограниченные сводки.

Все инструменты доступны только для чтения. Вызовы, ограниченные курсом, ограничены идентификаторами в PIAZZA_COURSES. Возвращаемый текст сообщений — это ограниченный обычный текст, помеченный как недоверенный пользовательский контент. Сервер не публикует, не отвечает, не редактирует, не загружает вложения, не раскрывает списки участников и не выполняет операции преподавателя.

list-piazza-posts принимает limit от 1 до 25 и offset от 0 до 500. Запрашивайте следующую страницу только тогда, когда предыдущий ответ сообщает 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 с отображаемыми именами. Идентификатор курса — это значение после /class/ в URL-адресе курса Piazza. Переменные окружения процесса имеют приоритет над .env. При запуске установленного колеса вне этого репозитория укажите переменные через окружение процесса.

Никогда не коммитьте .env, не вставляйте учетные данные в подсказки и не включайте учетные данные, файлы cookie, идентификаторы курсов или содержимое сообщений в журналы. Учетные записи, требующие 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/

Разработка

Инспектор, безопасный для конфиденциальности, загружает не более пяти сводок и одну полную ветку, затем выводит агрегированные счетчики ключей, типов и уровней вложенности без вывода значений сообщений:

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