Codex Pets

Codex Pets

Codex 互換のアニメーション付きペットを紹介するコミュニティギャラリーです。ローカルアカウント、手動モデレーション、公開生成リクエスト、YDB を利用したアセットストレージ、承認済みおよび保留中のペットの公開詳細ページを備えています。

公開サイト：https://pets.ydb-qdrant.tech/。

スタック

• Next.js 16 App Router、React 19、TypeScript strict
• Gravity UI + SCSS/BEM
• ydb-sdk を介した local-ydb / YDB ネイティブ gRPC
• YDB にユーザーとセッションを保存する、アプリ独自のメールアドレス＋パスワード認証
• YDB にバイナリブロブとして保存されるペットのアセット
• 動的な robots.txt、sitemap.xml、llms.txt、llms-full.txt、OpenAPI JSON
• llms.txt / llm.txt、/llms-full.txt、/mcp、JSON ルート、主要なレジストリデータの TOON ミラーを通じた、エージェント向けの HTTP アクセス
• 対応ブラウザーランタイムで利用できる、読み取り専用のオプションのブラウザー WebMCP ツール
• ydb-qdrant-ui と同じカウンター（104844437）を使用する Yandex Metrika。オプションでサーバー側の集計 MCP メトリクスも利用可能
• パッケージ検証用の JSZip + Sharp

開発

nvm use 24
npm install
cp .env.example .env.local
npm run dev

http://localhost:3000 を開きます。

エージェントからのアクセス

Codex Pets は、コーディングエージェントが承認済みのペットパックを検索、確認、インストール、共有できるよう、公開読み取り専用の MCP サーバーを提供しています。

主な公開窓口：

• おすすめガイド：https://pets.ydb-qdrant.tech/guides/best-codex-pets-for-ai-coding-agents
• LLM 向け情報：https://pets.ydb-qdrant.tech/llms.txt
• MCP エンドポイント：https://pets.ydb-qdrant.tech/mcp
• 公開マニフェスト：https://pets.ydb-qdrant.tech/api/manifest
• CLI でのインストール：npx @astandrik/codex-pets install <slug>

Codex を接続する：

codex mcp add codexPets --url https://pets.ydb-qdrant.tech/mcp

公開ギャラリーにプロキシ接続する、ローカルの stdio MCP サーバーを実行します。

npx @astandrik/codex-pets mcp

利用可能な MCP ツール：

• search_pets — 候補を探している場合や、正確なスラッグがわからない場合に、承認済みのペットを検索します
• get_pet — 承認済みのスラッグがわかっている場合に、公開ペットカードを取得します
• get_install_instructions — メトリクスを増やさずに、インストールコマンドを取得します
• get_badge_code — 既知のスラッグの README バッジ用スニペットを生成します
• get_embed_code — 既知のスラッグの iframe 埋め込み用スニペットを生成します
• get_card_code — 既知のスラッグのアニメーション GIF 用スニペットを生成します。デフォルトはスプライトのみのモードです
• get_pet_request_info — 公開されている新しいペットのリクエストワークフローを案内します。非公開のリクエストを送信したり、確認したりすることはありません

HTTP フォールバックルートも公開されています：

• /openapi.json
• /api/openapi.json
• /llms-full.txt
• /guides/best-codex-pets-for-ai-coding-agents
• /guides/best-codex-pets-for-ai-coding-agents.md
• /api/manifest
• /api/manifest.toon
• /api/pets
• /api/pets.toon
• /api/pets/<slug>
• /api/pets/<slug>.toon
• /pets/<slug>/markdown
• /api/tags
• /api/tags.toon
• /api/pets/<slug>/share
• /badge/<slug>.svg
• /card/<slug>.gif
• /embed/<slug>

クロール可能な HTML ギャラリーは / にあります。ページ番号付きのページには /?page=2、/?page=3 などでアクセスできます。従来の /pets カタログ URL は、同等のホームページ URL に恒久的にリダイレクトされます。ペットの詳細は引き続き /pets/<slug> にあります。

/api/pets と /api/pets.toon では、page と pageSize のパラメーターを任意で指定できます。いずれかのパラメーターを指定すると、追加の pagination メタデータオブジェクトが有効になります。パラメーターを指定しないリクエストでは、従来のレスポンス形式が維持されます。ページネーションされたレスポンスでは、トップレベルの total は返されたペットの数を示し、pagination.totalItems はフィルター適用後の全件数を示します。

/codex-pets のようなサブパスの下にデプロイする場合は、次のように設定します。

NEXT_PUBLIC_BASE_PATH=/codex-pets
NEXT_PUBLIC_APP_URL=https://example.com/codex-pets

公開ギャラリーはシークレットなしで表示されます。アカウントへのログイン、投稿、モデレーション、メトリクスには、YDB_PETS_ENDPOINT、YDB_PETS_DATABASE、認証用環境変数が必要です。サーバー側で MCP メトリクスを任意で使用する場合は、YANDEX_METRIKA_MP_TOKEN と YANDEX_METRIKA_MP_CLIENT_ID も必要です。 INDEXNOW_KEY を設定すると、任意の IndexNow 通知が有効になります。アプリは /<key>.txt を提供し、管理者がペットを承認した後に IndexNow に通知します。

任意のセマンティック検索では、Yandex AI Studio のテキスト埋め込みと YDB での正確なコサイン順位付けを使用します。クエリモードのデフォルトは PET_SEARCH_MODE=lexical です。shadow は公開順序を変えずにセマンティック順位を計算し、hybrid は語彙順位とテキストセマンティック順位を組み合わせます。独立した PET_SEARCH_VISUAL_MODE=off|shadow|hybrid を設定すると、4 つの固定スプライトフレームからオフラインの視覚キャプション順位を追加できます。キャプションとその出所情報は内部に保持され、公開 JSON、TOON、ホームページ、MCP、WebMCP の形式は変わりません。 YANDEX_AI_STUDIO_FOLDER_ID、YANDEX_AI_STUDIO_API_KEY_FILE、PET_SEARCH_MODEL_REVISION=yandex-text-embeddings-v2-768-2026-07 を設定してください。v2 ランタイムは、768 次元のマネージド text-embeddings-v2-doc/query モデルを使用します。 互換性のある Qwen 視覚順位付けを使用するには、PET_SEARCH_VISUAL_MODEL_REVISION=yandex-text-embeddings-v2-768-pet-vision-qwen3.6-v1 を設定します。ロールバック用に、従来の 256 次元のリビジョンも登録されています。API キーはシークレットファイルの設定からのみ受け付けられます。プロバイダーの障害やタイムアウト時は語彙検索の結果にフォールバックします。視覚検索のみの障害では、テキストとハイブリッドの順位が維持されます。

生成したサンプルデータを使って、YDB なしで実行するには次のようにします。

CODEX_PETS_DATA_SOURCE=mock AUTH_MODE=single-user \
  [email protected] \
  NEXT_PUBLIC_APP_URL=http://localhost:3000 \
  npm run dev -- --port 3000

本番運用に関する注意事項

https://pets.example.com のような専用の公開サブドメインには、次を推奨します。

NEXT_PUBLIC_APP_URL=https://pets.example.com
NEXT_PUBLIC_BASE_PATH=

アプリのコンテナが Docker のホスト名（例：grpc://ydb-local:2136）で YDB と通信する場合は、YDB コンテナと同じ Docker ネットワーク上でアプリを実行してください。

docker run --network ydb-net ...

Telegram などのプレビュークローラーには、軽量なプレビュールートで対応します。

• /api/preview/site
• /api/preview/pets/[slug]

通常の App Router ページにプロキシする前に、リバースプロキシでプレビューボットからの / および /pets/<slug> へのリクエストを、これらのエンドポイントに書き換えてください。以下を参照してください。

• deploy/nginx-pets-subdomain.conf.example
• deploy/nginx-pets-edge-proxy.conf.example

ローカル YDB クイックスタート

ローカルでアプリを開発する場合は、/local にある通常の local-ydb ルートデータベースで十分です。CMS テナントや動的ノードは必要ありません。アプリはホスト上で動作するため、local-ydb コンテナでは gRPC を 127.0.0.1:2136 で公開する必要があります。

local-ydb MCP を使用する場合は、local_ydb_destroy_stack(confirm=true) と local_ydb_bootstrap_root_database(confirm=true) を実行して、クリーンなルートデータベースから開始してください。作成されたコンテナで 127.0.0.1:2136 が公開されていない場合は、同じボリュームを使い、ホストの gRPC ポートを指定してコンテナのみを再作成してください。

docker rm -f ydb-local
docker run -d --name ydb-local --no-healthcheck --network ydb-net \
  --restart unless-stopped \
  -p 127.0.0.1:2136:2136 \
  -p 127.0.0.1:8765:8765 \
  -v ydb-local-data:/ydb_data \
  -e GRPC_PORT=2136 \
  -e MON_PORT=8765 \
  -e GRPC_TLS_PORT= \
  -e YDB_GRPC_ENABLE_TLS=0 \
  -e YDB_ANONYMOUS_CREDENTIALS=1 \
  -e YDB_LOCAL_SURVIVE_RESTART=1 \
  ghcr.io/ydb-platform/local-ydb:26.1.1.6

ローカルアプリでは、次の環境変数を使用してください。

AUTH_MODE=single-user
AUTH_SINGLE_USER_ID=local-admin
[email protected]
AUTH_SINGLE_USER_NAME="Local Admin"
SESSION_COOKIE_SECRET=dev-cookie-secret
PASSWORD_PEPPER=dev-password-pepper
[email protected]

YDB_ANONYMOUS_CREDENTIALS=1
YDB_ENDPOINT=grpc://127.0.0.1:2136
YDB_PETS_ENDPOINT=grpc://127.0.0.1:2136
YDB_PETS_DATABASE=/local
NEXT_PUBLIC_APP_URL=http://localhost:3000

ホストから Docker へのローカル実行では YDB_ENDPOINT が必要です。指定しない場合、ydb-sdk は Docker コンテナのホスト名が含まれる可能性のあるディスカバリーエンドポイントを使用するためです。

スキーマを適用し、シードデータを投入して、アプリを起動します。

docker cp ydb/schema.yql ydb-local:/tmp/codex-pets-schema.yql
docker exec ydb-local /ydb -e grpc://localhost:2136 -d /local scripting yql -f /tmp/codex-pets-schema.yql
npm run db:migrate
npm run seed:dev:reset
npm run dev -- --port 3000

http://localhost:3000 を開きます。ローカル YDB のモニタリング UI は http://127.0.0.1:8765 です。

リモート環境またはテナントを利用するデプロイでは、アプリの接続先を到達可能なテナントエンドポイントに設定してください。例：

YDB_PETS_ENDPOINT=grpc://ydb-host:2137
YDB_PETS_DATABASE=/local/your-tenant
YDB_STATIC_CREDENTIALS_USER=appuser
YDB_STATIC_CREDENTIALS_PASSWORD_FILE=/run/secrets/app.password
YDB_STATIC_CREDENTIALS_AUTH_ENDPOINT=grpc://ydb-host:2136

完全なアカウントフローを使用せずにローカル開発する場合：

AUTH_MODE=single-user
AUTH_SINGLE_USER_ID=local-admin
SESSION_COOKIE_SECRET=dev-cookie-secret
PASSWORD_PEPPER=dev-password-pepper
[email protected]

通常の組み込みアカウントフローを使用する場合：

AUTH_MODE=app-session
SESSION_COOKIE_SECRET=change-me
PASSWORD_PEPPER=change-me-too
[email protected]

既存の local-ydb テナントにテーブルを手動で作成します。

ydb -e "$YDB_PETS_ENDPOINT" -d "$YDB_PETS_DATABASE" scripting yql -f ydb/schema.yql

既存のデータベースにマイグレーションを適用します。

npm run db:migrate

マイグレーション後に、承認済みペットのテキストとビジュアルのバックフィルをプレビューして適用します。

npm run search:backfill -- --dry-run
npm run search:backfill -- --apply
npm run search:backfill -- --apply --slug orbit-otter --force
npm run search:backfill-vision -- --dry-run
npm run search:backfill-vision -- --apply --slug orbit-otter
npm run search:backfill-vision -- --apply
npm run search:eval:calibrate
npm run search:eval:holdout

どちらのバックフィルにも、明示的な --dry-run または --apply が必要です。ビジュアルの --force は --apply と併用する場合のみ有効です。ドキュメントのテキスト、キャプション、画像、埋め込み、プロンプト、シークレットが出力されることはありません。ドライランではスプライトシートの読み取りとハッシュ計算は行われますが、いずれの AI プロバイダーも呼び出さず、YDB への書き込みも行いません。安全なロールアウトの手順は、ベースを lexical、ビジュアルを off に設定 → 追加マイグレーション → バックフィル → ビジュアルを shadow に設定 → キャリブレーション → 未使用のホールドアウト → 統合された sexy の上位 5 件を人がレビュー → 両方のモードを hybrid に設定、です。

適用したテキストまたはビジュアルのバックフィルによってベクトルが変更されると、必要な関連ペットスナップショットの後続処理が出力されます。スナップショットのランキングが古いままにならないよう、埋め込みのメンテナンス完了後に V24 の派生データ処理をすべて実行してください。

npm run related:backfill-description-query -- --dry-run
npm run related:backfill-description-query -- --apply
npm run related:backfill-description-document -- --dry-run
npm run related:backfill-description-document -- --apply
npm run related:backfill-annotations -- --dry-run
npm run related:backfill-annotations -- --apply
npm run related:backfill-annotation-query -- --dry-run
npm run related:backfill-annotation-query -- --apply
npm run related:backfill-annotation-document -- --dry-run
npm run related:backfill-annotation-document -- --apply
npm run related:rebuild -- --dry-run
npm run related:rebuild -- --apply
npm run related:verify:v24

関連ペットの説明文の類似度では、同じ正規化済みの name + kind + description テキストから、クエリ用とドキュメント用の別々のリビジョンを作成します。タグはどちらの埋め込み入力にも含めません。クエリ用リビジョンではクエリロールを、ドキュメント用リビジョンでは同じ768次元モデルのドキュメントロールを使用します。AI Studioのレート制限枠を共有できるよう、モデルのバックフィルは順番に実行してください。V24では、説明文の類似度に、管理されたエンティティ、フランチャイズ、コレクション、アーキタイプのアノテーションを組み合わせます。ビジュアル類似度は、条件を満たす階層内の順位付けと、トピック数および種類による順位付け後の、共通トピックを持つスパースフォールバック候補の順位付けに寄与します。ビジュアル情報だけで一致条件を満たしたり、一致を救済したりすることはできません。関係ポリシーでは、検証済みの親ファミリーと既知の番号付きシリーズのルートを追加しますが、エンティティ／フランチャイズ識別子や保存済みのアノテーションは置き換えません。明示的なファミリーフィールドによる上書きも保持します。レジストリを変更する場合は、新しいアノテーション埋め込みではなく、新しい関係ポリシーのリビジョンと世代が必要です。現在のランキングリビジョンでは、承認済みのペットごとに順序付けられた8つのスラッグが保存されます。ペット詳細ページでは8つすべてを即時に表示します（デスクトップでは4列、タブレットでは3列、モバイルでは2列）。非公開のMarkdown版では意図的に先頭の4つのみを保持します。保存されたリビジョンは不変であり、アクティブな世代を現在の実装と正確に照合できます。

テキストとビジュアルのバックフィルでは、アクティブなリビジョンとは独立して埋め込みプロバイダーを解決します。テキストとビジュアルのリビジョンで互換性のない埋め込みモデルが使われている場合、ビジュアルランキングは安全に無効化されます。

管理者の承認では、通常の検索ドキュメント、説明文のクエリ／ドキュメントベクトル、管理されたアノテーションと両方のアノテーションベクトルロール、さらにビジュアル入力を更新するアトミックな準備処理をキューに追加できます。すべての入力が最新である場合に限り、1つのトランザクション内でペット、レビュー、準備済み世代を公開します。失敗した場合、ペットは保留状態のままとなり、以前の世代がアクティブな状態を維持します。PET_RELATED_PREAPPROVAL_ENABLED が厳密に true でない場合、最新のV24入力を用意せずにペットを公開することを防ぐため、承認はフェイルクローズします。アトミックな世代の有効化では、関連候補とサイトマップのキャッシュキーもローテーションされるため、スタンドアロンワーカーはNextのリクエストコンテキストに依存しません。npm run related:verify:v24 は読み取り専用です。AI Studioを呼び出さずに、保存済み入力からV24を再計算し、カバレッジ、整合性、アクティブなリビジョン、順序付きスナップショットの完全一致を確認します。

最初のロールバック手段は PET_SEARCH_VISUAL_MODE=off です。テキストのセマンティックコンターも無効にするには、PET_SEARCH_MODE=lexical を使用してください。追加されたキャプションテーブルと埋め込みテーブルは残してもかまいません。 チェックイン済みの評価用クエリは src/lib/pets/search-eval-fixtures.json にあり、calibration と holdout の分割は固定されています。キャリブレーションでは、観測されたすべてのビジュアルスコアを重み 0.25、0.50、0.75、1.00 で評価します。ホールドアウトコマンドには、コミット済みでリビジョンに紐付いたプロファイルが必要であり、チューニングには使用しないでください。ライブ評価には、設定済みのYDBとAI Studioへのアクセスが必要です。集計結果に加えて、最終的な sexy レビューリストに含まれる公開スラッグが出力されます。

スキーマの作成後、ローカル開発データをシードします。

npm run seed:dev

固定の dev_* シードレコードのみを置き換えるには、npm run seed:dev:reset を使用してください。

現在の動作

• 一般ユーザーはギャラリーを閲覧し、/pets/[slug] を開けます。
• 一般ユーザーはログインせずに、ファイルと任意の連絡先メールアドレスを指定してペットを投稿できます。
• 一般ユーザーはログインせずに、連絡先メールアドレス、テキストの概要、任意の参照画像を指定して、生成するペットをリクエストできます。
• ログインユーザーは、/my-pets で自分のペットのみを確認できます。
• ログインユーザーは、/my-requests で自分のペット生成リクエストを確認できます。
• 管理者は INITIAL_ADMIN_EMAILS に基づいて決定されます。
• 管理者は /admin/submissions から保留中のペットを承認、却下、削除できます。
• 管理者は /admin/requests から生成リクエストを確認し、既存のペットにリンクできます。
• オーナーは /my-pets から自分のペットを削除できます。
• 管理者はペットの詳細ページから、任意のペットを削除できます。
• 削除されたペットは、オーナーのリスト、公開リスト、sitemap.xml に表示されなくなります。

SEO、エージェント、アナリティクス

• robots.txt は src/app/robots.ts から配信されます。
• sitemap.xml は動的に生成され、現在承認されているすべてのペットが含まれます。
• llms.txt は動的に生成され、ギャラリー、マニフェスト、承認済みペットのページをまとめた、AI が読み取れる厳選マップを提供します。単数形のファイル名を要求するフェッチャー向けに、/llm.txt からもプレーンテキストで直接アクセスできます。
• llms-full.txt は動的に生成され、API リファレンスへのリンク、認証に関する注記、例、ウェブフックのステータスを含む、AI が読み取れる詳細なドキュメントを提供します。
• /openapi.json は、公開エージェント／開発者向け契約の範囲を対象とする、正式な OpenAPI 3.1 仕様です。公開されているメトリクス変更ルートとダウンロードリダイレクトルートは意図的に含めていません。予測可能な API パスを調査するスキャナー向けに、/api/openapi.json からもアクセスできます。
• /developers と /docs/api は、API、OpenAPI、MCP、認証、ウェブフックを見つけやすくするための、インデックス登録可能な開発者向けリソースページです。
• /mcp は、コーディングエージェント向けの公開読み取り専用 Streamable HTTP MCP サーバーです。Codex は次のコマンドで接続できます。 codex mcp add codexPets --url https://pets.ydb-qdrant.tech/mcp。
• 公式 MCP Registry 名： tech.ydb-qdrant.pets/codex-pets-ydb-qdrant。
• server.json と /.well-known/mcp/server.json は、公開リモートサーバーの MCP Registry メタデータを公開します。
• /.well-known/mcp-registry-auth は、mcp-publisher が使用する公開 HTTP ドメインの認証レコードを公開します。
• HTTP エージェントアクセスは、公開されている主要なマシン向け契約です。
  • /mcp — 読み取り専用ツールを備えた Streamable HTTP MCP エンドポイント： search_pets、get_pet、get_install_instructions、get_badge_code、 get_embed_code、get_card_code、get_pet_request_info
  • /openapi.json と /api/openapi.json — OpenAPI 3.1 の公開エージェント／開発者向け契約の範囲
  • /llms-full.txt — API、認証、MCP、パッケージ、ウェブフックに関する詳細な LLM 向けドキュメント
  • /developers と /docs/api — 開発者ポータルと API ドキュメントのページ
  • /server.json と /.well-known/mcp/server.json — 公開 Streamable HTTP リモートサーバーを示す MCP Registry メタデータ
  • /.well-known/mcp-registry-auth — 公開 MCP Registry HTTP 認証レコード
  • /api/manifest — ページ URL、インストールコマンド、アセット URL を含む承認済みペット一覧
  • /api/manifest.toon — LLM が取得しやすい形式にした、公開マニフェストの TOON ミラー
  • /api/pets?q=<query>&kind=all|creature|object|character — 非公開の連絡先メールアドレスを含まない、承認済みペットの一覧／検索 JSON
  • /api/pets.toon?q=<query>&kind=all|creature|object|character — 非公開の連絡先メールアドレスを含まない、承認済みペットの一覧／検索結果の TOON ミラー
  • /api/pets/<slug> — 非公開の連絡先メールアドレスを含まない、承認済みペット 1 件の公開詳細 JSON
  • /api/pets/<slug>.toon — 非公開の連絡先メールアドレスを含まない、公開詳細データの TOON ミラー
  • /api/tags — 承認済みペットの現在のタグ件数
  • /api/tags.toon — 現在のタグ件数の TOON ミラー
  • /api/pets/<slug>/share — サニタイズ済みのインストール、バッジ、埋め込み用スニペット
  • /api/pets/<slug>/install — メトリクスを変更しない読み取り専用のインストール手順
  • /badge/<slug>.svg — README バッジ SVG
  • /card/<slug>.gif — アニメーション GIF の共有画面。mode=sprite|card、state、scale をサポートします。デフォルトの共有出力はスプライトのみです。
  • /embed/<slug> — iframe 埋め込みページ。mode=sprite|card、state、scale、theme、compact、表示切り替えをサポートします。
  • npx @astandrik/codex-pets install <slug> — CLI インストールコマンドの形式
• ブラウザー WebMCP は、読み取り専用のプログレッシブエンハンスメントです。navigator.modelContext を公開するブラウザーランタイムでのみ動作します。通常の HTTP クローラーや ChatGPT のブラウジングセッションでは、上記のエンドポイントを使用してください。サポートされているブラウザー WebMCP ツール：
  • search_codex_pets — /api/pets を通じて承認済みペットを検索します
  • get_codex_pet — /api/pets/[slug] を通じて承認済みペット 1 件を取得します
  • get_codex_pets_manifest — /api/manifest を取得します
  • get_current_codex_pet — 現在のタブで開いている承認済みペットを確認します
• WebMCP では、送信、いいね、ダウンロード／インストールのカウンター、認証、管理者機能、モデレーション、削除の操作を意図的に公開していません。
• サイトマップはモデレーションの変更後に自動更新されます。新たに承認されたペットを掲載するために、cron や手動での再ビルドは必要ありません。
• Yandex Metrika は本番環境でのみ読み込まれ、以下を追跡します。
  • アカウント登録／ログインの成功とエラー
  • ペットの送信の成功とエラー
  • ペット生成リクエストの成功とエラー
  • モデレーションによる承認／却下／削除
  • 関連ペットが表示領域に 50％ 入ったときのインプレッションと、詳細ページへの移動クリック。参照元の slug、対象の slug、1 始まりの位置も記録します。
  • 関連ペットのインストールコマンドのコピーとダウンロード。カード上で直接行われた操作と、30 分間のブラウザーセッション内での、対応する詳細ページ上の操作の両方が対象です。
• サーバー側の MCP 集計メトリクスは任意です。YANDEX_METRIKA_MP_TOKEN と YANDEX_METRIKA_MP_CLIENT_ID が設定されている場合にのみ有効になります。MCP メトリクスでは、専用の技術用 Metrika ClientID を使用し、mcp_tool_call ゴールイベントの前に合成 /mcp ページビューを送信します。ペイロードには、ツール名、ステータス、安全な slug、種類、結果数、上限などの集計されたツール情報のみが含まれます。MCP の生の検索テキスト、IP アドレス、user-agent、origin ヘッダー、連絡先メールアドレス、所有者のメールアドレス、所有者 ID は含まれません。
• IndexNow は任意です。実行時環境に INDEXNOW_KEY を設定すると、公開鍵ファイルと、ギャラリー、新しいペット詳細ページ、sitemap.xml、llms.txt、/api/manifest の承認時通知が有効になります。

主なルート

• / — 公開ギャラリー
• /request — 公開ペット生成リクエストフロー
• /submit — 公開投稿フロー
• /login、/register、/logout — ローカルアカウントフロー
• /my-pets — オーナー向けビュー
• /my-requests — ログインユーザー向けペット生成リクエストビュー
• /admin/submissions — 管理者向けモデレーションキュー
• /admin/requests — 管理者向けペット生成リクエストキュー
• /pets/[slug] — ペット詳細ページ
• /agents — エージェントと MCP 接続ガイド
• /developers — Codex Pets 開発者ポータル
• /docs/api — Codex Pets API ドキュメント
• /guides/best-codex-pets-for-ai-coding-agents — Codex のペット選択に関するカテゴリーガイド
• /guides/codex-pets-vs-vscode-pets — エディタでのペット利用ケースの比較ガイド
• /mcp — 公開読み取り専用 Streamable HTTP MCP エンドポイント
• /openapi.json、/api/openapi.json — 公開 OpenAPI 仕様
• /server.json、/.well-known/mcp/server.json — MCP Registry メタデータ
• /api/manifest — 公開エージェント／CLI マニフェスト
• /api/manifest.toon — 公開マニフェストの TOON ミラー
• /api/pets — 公開承認済みペット一覧／検索 JSON
• /api/pets.toon — 承認済みペット一覧／検索の TOON ミラー
• /api/pets/[slug] — 公開承認済みペット詳細 JSON
• /api/pets/[slug].toon — 公開ペット詳細データの TOON ミラー
• /api/tags、/api/pets/[slug]/share、/api/pets/[slug]/install — 読み取り専用エージェント／共有 JSON
• /api/tags.toon — 承認済みタグ件数の TOON ミラー
• /badge/[slug].svg、/card/[slug].gif、/embed/[slug] — 共有用ページ
• /robots.txt、/sitemap.xml、/llms.txt、/llm.txt、/llms-full.txt — SEO および AI 可読形式の出力

エージェント向けチェック

ローカル YDB を使わずにエージェント向けルートをスモークテストするには、CODEX_PETS_DATA_SOURCE=mock npm run dev -- --port 3000 を使用します。想定される公開エンドポイント：

curl -I http://localhost:3000/
curl -I http://localhost:3000/api/pets
curl -I http://localhost:3000/api/pets.toon
curl -I http://localhost:3000/api/manifest
curl -I http://localhost:3000/api/manifest.toon
curl -I http://localhost:3000/openapi.json
curl -I http://localhost:3000/api/openapi.json
curl -I http://localhost:3000/api/tags
curl -I http://localhost:3000/api/tags.toon
curl -I http://localhost:3000/llms.txt
curl -I http://localhost:3000/llm.txt
curl -I http://localhost:3000/llms-full.txt
curl -I http://localhost:3000/developers
curl -I http://localhost:3000/docs/api
curl -I http://localhost:3000/guides/best-codex-pets-for-ai-coding-agents
curl -I http://localhost:3000/guides/codex-pets-vs-vscode-pets
curl -i http://localhost:3000/mcp

JSON レスポンスの MCP スモークテストには、次を使用します。

curl -s http://localhost:3000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

WebMCP 自体については、WebMCP 対応の Chrome またはラボ用ブラウザーを使い、navigator.modelContext から上記の読み取り専用ツールが公開されていることを確認します。WebMCP に対応していない通常のブラウザーでは、クライアントレジストラーは何もしません。これは想定どおりの動作であり、HTTP エージェントコントラクトには影響しません。

非公開デプロイに関するメモ

ホストごとの具体的な手順、ローカルパス、運用メモは、Git の追跡対象外である private/ ディレクトリ以下に置いてください。このリポジトリの公開ドキュメントは、汎用的で安全にコミットできる内容にしてください。

Pet Package

各ペットは次のファイルで配布されます。

• pet.json
• spritesheet.webp または spritesheet.png
• ルートに両方のファイルを含むダウンロード可能な ZIP

レジストリでは、192x208 セルを使用する 2 つの Codex アトラスバージョンを受け付けます。

• v1：spriteVersionNumber を省略するか、1 に設定します。1536x1872 の 8x9 アトラスを使用します。
• v2：spriteVersionNumber を 2 に設定します。1536x2288 の 8x11 アトラスを使用し、9 行目と 10 行目に時計回りの 16 個の視線方向を含めます。

CLI によるインストール

承認済みのギャラリーペットは、npm から Codex にインストールできます。

npx @astandrik/codex-pets install zero-two-2

CLI はデフォルトで https://pets.ydb-qdrant.tech から /api/manifest を読み込み、${CODEX_HOME:-~/.codex}/pets/<slug>/ に書き込みます。既存のローカルペットフォルダーを置き換えるには --force を使用します。また、別のデプロイ先を指定するには CODEX_PETS_URL または --url を使用します。Codex がすでに起動している場合は、Settings -> Appearance -> Pets で新しいペットを選択する前に再起動してください。