piazza-mcp

piazza-mcp は、設定された Piazza ディスカッションを検索・閲覧するためのローカルな読み取り専用 MCP サーバーです。

このサーバーは、コミュニティ製の piazza-api パッケージと、Piazza の非公開の内部エンドポイントを使用しています。これは公式の Piazza 統合ではなく、Piazza がウェブサイトを変更すると動作しなくなる可能性があります。リクエスト制限は控えめに保ち、このアクセス方法が自分のアカウントと所属機関で許容されることを確認してください。

Requirements

• Python 3.10 から 3.14 まで。

• 依存関係と環境管理のための uv。

• MCP Python SDK 1.x。サーバーは v1 の低レベル Server デコレータ API を使用し、mcp>=1.28.1,<2 を宣言しています。

Tools

• list-piazza-courses: アカウントがアクセスできる設定済みコースを一覧表示します。

• list-piazza-posts: 1つのコースの直近の投稿概要を制限付きで返します。

• get-piazza-post: 制限付きの正規化されたスレッドを1つ返します。

• search-piazza-posts: 設定済みの1つのコースを検索し、制限付きの概要を返します。

すべてのツールは読み取り専用です。コース単位の呼び出しは PIAZZA_COURSES 内の ID に制限されます。返される投稿テキストは制限付きのプレーンテキストであり、信頼できないユーザー生成コンテンツとしてラベル付けされます。サーバーは投稿、回答、編集、添付ファイルのダウンロード、名簿の公開、インストラクター操作は行いません。

list-piazza-posts は limit を 1 から 25 まで、offset を 0 から 500 まで受け付けます。前のレスポンスが truncated: true を報告した場合にのみ、次のページをリクエストしてください。検索は最大 200 文字のクエリを受け付け、最大 25 件の結果を返します。レスポンスは 60 秒間メモリにキャッシュされます。更新に失敗した後は、古いキャッシュデータが返される可能性があります。

Configuration

編集済みテンプレートをコピーし、生成されたファイルを非公開に保ってください:

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 が必要なアカウントは、非公式パッケージが使用するメール/パスワードフローをサポートしていない場合があります。

Run and Register

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 クライアントを再起動してください。

Project Layout

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/

Development

プライバシーに配慮したインスペクタは、最大 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