pp-goodreads

Goodreads — Printing Press CLI

前提条件：CLI のインストール

このスキルは goodreads-pp-cli バイナリを使用します。このスキルのコマンドを実行する前に、CLI がインストールされていることを必ず確認してください。 見つからない場合は、先にインストールしてください。

1. Printing Press インストーラーを使ってインストールします。バイナリの保存先は、macOS/Linux では $HOME/.local/bin、Windows では %LOCALAPPDATA%\Programs\PrintingPress\bin がデフォルトです。

   npx -y @mvanhorn/printing-press-library install goodreads --cli-only
   

2. 次のコマンドで確認します：goodreads-pp-cli --version
3. 表示されたインストールディレクトリが、このスキルを実行するエージェント／ランタイムの $PATH に含まれていることを確認します。

npx でのインストールに失敗する場合（Node がない、オフラインなど）は、Go を使って直接インストールしてください（Go 1.26.6 以降が必要です）。

go install github.com/mvanhorn/printing-press-library/library/media-and-entertainment/goodreads/cmd/goodreads-pp-cli@latest

インストール後に --version が「command not found」と表示される場合、ランタイムからバイナリディレクトリを $PATH 経由で参照できていません。確認が成功するまで、スキルのコマンドを実行しないでください。

HTTP トランスポート

この CLI は、ブラウザー向けエンドポイントに Chrome 互換の HTTP トランスポートを使用し、設定済みの Goodreads セッションを _session_id2 Cookie として送信します。通常の API 呼び出しに、常駐するブラウザープロセスは必要ありません。

MCP インターフェース

MCP バイナリはデフォルトで stdio を使用し、ホスト型エージェント向けにストリーミング可能な HTTP を提供できます。

goodreads-pp-mcp
goodreads-pp-mcp --transport http --addr :7777

デフォルトの MCP 登録では、全ルートマップ向けの goodreads_search と goodreads_execute に加え、ローカルの search、sql、context が公開されます。未加工のエンドポイントミラーツールを有効にするには、GOODREADS_MCP_ENDPOINT_MIRRORS=1 を設定します。変更を伴うルートは、明示的な承認後に GOODREADS_PP_ALLOW_WRITES=1 を設定しない限りブロックされます。

コマンドリファレンス

amazon-purchases — Amazon の購入を管理します

• goodreads-pp-cli amazon-purchases — Amazon の購入インポート／確認ページです。

book — 書籍を管理します

• goodreads-pp-cli book <book_slug> — 書籍の詳細ページです。現在のページは Next.js ベースです。

comment — コメントを管理します

• goodreads-pp-cli comment <user_slug> — ユーザーのコメント／最近の投稿ページです。

feed — ホームの更新フィード（友達のアクティビティ）を読み込みます

• goodreads-pp-cli feed list — ホームの更新フィード（友達のアクティビティ）を読み込みます。古いアクティビティをたどるには --page <n> を使用します。/home/load_more_updates への読み取り専用 POST です。

friend — Goodreads の友達や友達申請を確認します

• goodreads-pp-cli friend list — 友達一覧ページです。
• goodreads-pp-cli friend list-requests — 友達申請ページです。

genres — Goodreads のジャンルや本棚の探索ページを閲覧します

• goodreads-pp-cli genres get — ジャンルのランディングページです。
• goodreads-pp-cli genres list — ジャンル一覧ページです。
• goodreads-pp-cli genres list-list — ジャンル別本棚のアルファベット順一覧です。
• goodreads-pp-cli genres list-search — ジャンル検索ルートです。

giveaway — Goodreads Giveaways を閲覧して応募します

• goodreads-pp-cli giveaway list — Goodreads Giveaways の一覧を閲覧します（--format、--genre）。
• goodreads-pp-cli giveaway show <giveaway_id> — 1 件の Giveaway 詳細ページを表示します。
• goodreads-pp-cli giveaway enter <giveaway_id> — Giveaway に応募します。まだ利用できません：応募 POST の形式は取得されていません。実行は拒否され、--dry-run では既知の情報に基づく最適なリクエストをプレビューします。

goodreads-web-undocumented-search — Goodreads の非公開 Web 検索を管理します

• goodreads-pp-cli goodreads-web-undocumented-search — OpenSearch 記述子に基づく正規の書籍検索ルートです。

list — リストを管理します

• goodreads-pp-cli list <list_id> — 公開 Listopia リストページです。

message — Goodreads のメッセージフォルダー操作を確認し、計画します

• goodreads-pp-cli message create — メッセージフォルダー／既読状態の一括操作です。
• goodreads-pp-cli message get — ユーザーのメッセージフォルダーページです。
• goodreads-pp-cli message get-show — メッセージ詳細ページです。
• goodreads-pp-cli message list — ユーザーのメッセージ受信トレイです。
• goodreads-pp-cli message list-markallasread — 受信トレイで表示中のメッセージをすべて既読にします。

notes — Kindle のメモ／ハイライトを読み込み、操作を計画します

• goodreads-pp-cli notes get — ユーザーの Kindle Notes & Highlights 一覧です。

• goodreads-pp-cli notes get-bookslug — 1 冊の書籍とユーザーに関するメモ／ハイライトの詳細ページです。 notifications — Goodreads の通知とトラッキング呼び出しを確認します

• goodreads-pp-cli notifications create — UI から送信される通知トラッキング呼び出しです。

• goodreads-pp-cli notifications list — ユーザー通知ページです。

opensearch-xml — OpenSearch XML を管理します

• goodreads-pp-cli opensearch-xml — Goodreads の書籍検索用 OpenSearch 記述子です。

quotes — Goodreads の引用と引用ウィジェットを読み取ります

• goodreads-pp-cli quotes get — ユーザーの引用ウィジェットスクリプトです。
• goodreads-pp-cli quotes list — 現在のユーザーの引用一覧です。

rating — 書籍の星評価を設定または削除します（GraphQL）

評価は従来のフォームではなく、最新の Goodreads AWS AppSync GraphQL API（RateBook／UnrateBook）経由で書き込まれます。この操作には、セッション Cookie とは別の認証情報である、バインド済みの AppSync JWT が必要です。GOODREADS_GRAPHQL_TOKEN を使って設定してください（Auth Setup を参照）。書き込みには制限があります。プレビューするには --dry-run を、承認後に実行するには GOODREADS_PP_ALLOW_WRITES=1 を指定します。

• goodreads-pp-cli rating set <book_id> --stars <1-5> — 書籍を評価します（RateBook GraphQL ミューテーション）。
• goodreads-pp-cli rating clear <book_id> — 評価を削除します（UnrateBook GraphQL ミューテーション）。

recommendations — Goodreads のおすすめページを確認します

• goodreads-pp-cli recommendations list — パーソナライズされたおすすめページです。
• goodreads-pp-cli recommendations list-tome — 友達のおすすめページです。

review — レビューの読み取りと書き込み、および本棚／レビュー表の操作を計画します

• goodreads-pp-cli review create <book_id> — 書籍のレビューを作成／更新します（--review、--spoiler、--publicize、--add-to-blog、--shelf、--notes）。従来の /review/update/:book_id フォーム（フォーム URL エンコード形式）を送信します。Rails CSRF トークンは、GOODREADS_AUTHENTICITY_TOKEN 環境変数または標準入力から取得します（--authenticity-token フラグは非推奨です。シェル履歴や ps aux に漏れるためです）。星評価は GraphQL でのみ設定できます。rating set を使用してください。
• goodreads-pp-cli review create-update <book_id> --stdin — 1 冊の書籍のレビュー／日付／メモ欄をインラインで更新します。Rails レビューフォームのフィールドを含む JSON オブジェクト（例：{"review[review]":"..."}）をパイプで渡します。/review/update/:book_id にフォーム URL エンコード形式で送信されます。CSRF トークンには GOODREADS_AUTHENTICITY_TOKEN を使用します。
• goodreads-pp-cli review create-updatelist — ユーザーの本棚表で選択したレビュー／書籍を一括更新します。
• goodreads-pp-cli review get — ユーザーの本棚一覧です。必要に応じて本棚で絞り込めます。
• goodreads-pp-cli review get-listrss — この公開 XML ルートは、本棚のエクスポートに使える現在最も簡潔な読み取り API です。
• goodreads-pp-cli review get-stats — 読書統計ページです。
• goodreads-pp-cli review list — レビューの下書きページです。
• goodreads-pp-cli review list-duplicates — 重複書籍ツールです。
• goodreads-pp-cli review list-import — インポート／エクスポートページです。

shelf — Goodreads の本棚操作を確認し、計画します

• goodreads-pp-cli shelf create — 本棚選択ヘルパーを使用して、1 冊の書籍を本棚に追加または本棚から削除します。
• goodreads-pp-cli shelf create-movebatch — 書籍／本棚を一括で並べ替えます。
• goodreads-pp-cli shelf create-movebatch-2 — ユーザーの本棚表の位置変更を保存します。
• goodreads-pp-cli shelf create-movetoposition — 本棚／書籍の行を指定した位置に移動します。
• goodreads-pp-cli shelf create-removebook — ボタンヘルパーから本棚の書籍を 1 冊削除します。
• goodreads-pp-cli shelf create-update — 本棚の表示設定を更新します。
• goodreads-pp-cli shelf get — 公開本棚のランディングページです。
• goodreads-pp-cli shelf list — 公開本棚のトップインデックスです。

tooltips — ツールチップを管理します

• goodreads-pp-cli tooltips — 本棚／一覧ページに表示される書籍 ID のツールチップメタデータを一括取得します。

topic — トピックを管理します

• goodreads-pp-cli topic — グループで絞り込めるディスカッションページです。

user — Goodreads のプロフィールと人物ページを確認します

• goodreads-pp-cli user get — プロフィールの遅延読み込みセクションを取得します。
• goodreads-pp-cli user get-show — ユーザープロフィールページを取得します。
• goodreads-pp-cli user get-yearinbooks — 「Year in Books」ページを取得します。
• goodreads-pp-cli user list — 人気のレビュアーを探すユーザー検索ページを取得します。
• goodreads-pp-cli user list-topreaders — トップリーダーを探すユーザー検索ページを取得します。
• goodreads-pp-cli user list-topreviewers — トップレビュアーを探すユーザー検索ページを取得します。

user-following — Goodreads でフォロー数が最も多いユーザーを探します

• goodreads-pp-cli user-following — フォロー数が最も多いユーザーを探すユーザー検索ページを取得します。

user-shelves — Goodreads のカスタム本棚の作成を計画します

• goodreads-pp-cli user-shelves — カスタムのユーザー本棚を作成します。

適切なコマンドを探す

実行したいことは分かっていても、どのコマンドを使えばよいか分からない場合は、CLI に直接問い合わせてください。

goodreads-pp-cli which "<capability in your own words>"

which は自然言語による機能の問い合わせを、この CLI の厳選された機能インデックスから最適なコマンドに対応付けます。終了コード 0 は少なくとも 1 件の一致があることを示し、終了コード 2 は確度の高い一致がないことを示します。その場合は --help を使うか、検索語を絞り込んでください。

認証の設定

Goodreads では、新しい公開開発者 API キーを発行していません。goodreads-pp-cli auth setup を実行すると、Goodreads のブラウザーセッション Cookie を設定するための URL と手順が表示されます（Goodreads を開くには --launch を追加します）。その後、Goodreads の _session_id2 Cookie の値だけを設定してください。

export GOODREADS_GOODREADS_COOKIE_SESSION="<your-goodreads-session-cookie>"

または、~/.config/goodreads-web-undocumented-pp-cli/config.toml に保存してください。

Amazon、AWS、その他の無関係なブラウザー Cookie をまとめて貼り付けないでください。

goodreads-pp-cli doctor を実行して、設定を確認してください。

GraphQL トークン（評価の書き込みのみ）

rating set／rating clear コマンドは、最新の Goodreads AWS AppSync GraphQL API 経由で書き込みを行います。この API は、セッション Cookie とは別の認証情報である、紐付けられた JWT で認証します。トークンを取得する手順は次のとおりです。

1. ログインした状態で goodreads.com を開き、ブラウザーの DevTools → Network を開きます。
2. 任意の書籍ページで評価の星をクリックし、*.appsync-api.*.amazonaws.com/graphql へのリクエストを探します。
3. そのリクエストの Authorization ヘッダーの値をコピーします。
4. export GOODREADS_GRAPHQL_TOKEN='<that value>'

セッション Cookie だけでは GraphQL の認証を行えません。ライブキャプチャでは Cookie からトークンを発行するエンドポイントは確認されていないため、環境変数を使う方法が推奨されています。その他すべてのコマンド（読み取り、従来のレビュー用フォーム、本棚への書き込み）では、セッション Cookie のみを使用します。

Rails CSRF トークン（レビュー／本棚フォームへの書き込み）

従来のフォームへの書き込み（review create、review create-update、shelf create）では、該当する編集ページ（例：/review/edit/:book_id にある非表示の authenticity_token 入力）から Rails CSRF の authenticity_token を取得する必要があります。GOODREADS_AUTHENTICITY_TOKEN 環境変数（推奨）で指定するか、標準入力からパイプで渡してください。どちらの方法でも、シェル履歴やプロセステーブル（ps aux）にトークンが残りません。--authenticity-token フラグも引き続き使えますが、この理由から非推奨です。

エージェントモード

任意のコマンドに --agent を追加します。次のオプションに展開されます：--json --compact --no-input --no-color --yes。

• パイプ可能 — stdout には JSON、stderr にはエラーを出力します

• フィルター可能 — --select でフィールドを絞り込みます。ドット区切りのパスでネストされた構造をたどり、配列は要素ごとに走査します。詳細な API でコンテキストを小さく保つために重要です。

  goodreads-pp-cli amazon-purchases --agent --select id,name,status
  

• プレビュー可能 — --dry-run でリクエストを送信せずに表示します

• オフラインでも使いやすい — 同期／検索コマンドでは、利用可能な場合にローカルの SQLite ストアを使用できます

• 非対話型 — プロンプトを表示せず、すべての入力をフラグで指定します

• 再試行を明示 — すでに作成済みの場合に成功として扱うときに限り、--idempotent を使用します

レスポンスエンベロープ

ローカルストアまたは API から読み取るコマンドは、出力をプロベナンスエンベロープで包みます。

{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

データには .results を、ライブデータかローカルデータかの判別には .meta.source を解析してください。人が読める N results (live) の概要が stderr に出力されるのは、stdout が端末であり、かつ機械可読形式のフラグ（--json、--csv、--compact、--quiet、--plain、--select）が設定されていない場合のみです。パイプ経由やエージェントによる利用、および形式を明示した実行では、stdout に純粋な JSON が出力されます。

エージェントからのフィードバック

この CLI に問題があると気づいたら、あなた自身（またはエージェント）が、その内容を記録してください。

goodreads-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
goodreads-pp-cli feedback --stdin < notes.txt
goodreads-pp-cli feedback list --json --limit 10

エントリーはローカルの ~/.goodreads-pp-cli/feedback.jsonl に保存されます。GOODREADS_FEEDBACK_ENDPOINT が設定されており、かつ --send が指定されているか、GOODREADS_FEEDBACK_AUTO_SEND=true の場合を除き、POST されることはありません。デフォルトの動作はローカルのみに保存することです。

バグ報告ではなく、意外に感じたことを書いてください。具体的に短く、1 行で記述します。そこから積み重ねが生まれます。

出力の配信

すべてのコマンドで --deliver <sink> を指定できます。出力は標準出力に加えて（または標準出力の代わりに）指定したシンクに送られるため、エージェントはコマンド結果を手作業でパイプに渡さずにルーティングできます。次の 3 つのシンクに対応しています。

シンク	動作
stdout	デフォルト。標準出力のみに書き込みます
file:<path>	出力を <path> にアトミックに書き込みます（tmp + rename）
webhook:<url>	出力本文を URL に POST します（--compact の場合は application/json または application/x-ndjson）

未対応のスキームは、対応する選択肢を示す構造化エラーとともに拒否されます。Webhook の失敗時は、ゼロ以外の終了コードが返され、URL と HTTP ステータスが stderr に記録されます。

名前付きプロファイル

プロファイルは、呼び出しごとに再利用できる、フラグ値の保存済みセットです。スケジュールされたエージェントが毎回同じ設定で同じコマンドを呼び出す場合に使用してください。HeyGen の「Beacon」パターンがこれに当たります。

goodreads-pp-cli profile save briefing --json
goodreads-pp-cli --profile briefing amazon-purchases
goodreads-pp-cli profile list --json
goodreads-pp-cli profile show briefing
goodreads-pp-cli profile delete briefing --yes

明示的に指定したフラグは、常にプロファイル値より優先されます。プロファイル値はデフォルト値より優先されます。agent-context は、実行時に情報を調べるエージェントがプロファイルを検出できるよう、利用可能なすべてのプロファイルを available_profiles の下に一覧表示します。

終了コード

コード	意味
0	成功
2	使用エラー（引数が誤っています）
3	リソースが見つかりません
4	認証が必要です
5	API エラー（上流の問題）
7	レート制限中（待機してから再試行してください）
10	設定エラー

引数の解析

$ARGUMENTS を解析します。

1. 空、help、または --help → goodreads-pp-cli --help の出力を表示します
2. install で始まる場合 → mcp で終わる場合は MCP のインストール、それ以外の場合は上記の「前提条件」を参照します
3. それ以外 → 直接使用（--agent を付けて CLI コマンドとして実行します）

MCP サーバーのインストール

この CLI の公開ライブラリエントリーまたはビルド済みリリースから MCP バイナリをインストールし、登録します。

claude mcp add goodreads-pp-mcp -- goodreads-pp-mcp

確認します：claude mcp list

直接使用

1. インストールされているか確認します：which goodreads-pp-cli 見つからない場合は、インストールを提案します（このスキルの冒頭にある「前提条件」を参照してください）。
2. ユーザーの問い合わせに最適なコマンドを、上記の「独自の機能」と「コマンドリファレンス」から選びます。
3. --agent フラグを付けて実行します。

   goodreads-pp-cli <command> [subcommand] [args] --agent
   

4. あいまいな場合は、サブコマンドのヘルプを確認します：goodreads-pp-cli <command> --help