codex-pets

# 代码宠物 [](https://glama.ai/mcp/servers/astandrik/codex-pets) 社区画廊，展示兼容 Codex 的动画宠物，支持本地账号、手动审核、公开生成请求、YDB 支持的资产存储和公开的宠物详情页面。 公开网站：https://pets.ydb-qdrant.tech/ ## 技术栈 - Next.js 16 应用路由，React 19，TypeScript 严格模式 - Gravity UI + SCSS/BEM - local-ydb / YDB 原生 gRPC via `ydb-sdk` - 应用自有邮箱+密码认证，YDB 支持的用户和会话 - 宠物资产存储在 YDB 中为二进制大文件 - 动态 `robots.txt`，`sitemap.xml`，`llms.txt`，`llms-full.txt` 和 OpenAPI JSON - 代理面向 HTTP 访问，通过 `llms.txt` / `llm.txt`，`/llms-full.txt`，`/mcp`，JSON 路由和 TOON 镜像核心注册数据 - 可选的浏览器 WebMCP 工具，支持的浏览器运行时 - Yandex Metrika 使用与 `ydb-qdrant-ui` 相同的计数器 (`104844437`)，可选服务器端聚合 MCP 指标 - JSZip + Sharp 用于包验证 ## 开发 ```bash nvm use 24 npm install cp .env.example .env.local npm run dev ``` 打开 `http://localhost:3000`。 ## 代理访问 代码宠物公开了一个公开的只读 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： ```bash codex mcp add codexPets --url https://pets.ydb-qdrant.tech/mcp ``` 运行一个本地的 stdio MCP 服务器，代理公开的画廊： ```bash npx @astandrik/codex-pets mcp ``` 可用 MCP 工具： - `search_pets` — 发现已批准的宠物，当您需要候选或缺乏确切的 slug - `get_pet` — 获取一个公开的宠物卡，当您已经拥有已批准的 slug - `get_install_instructions` — 获取安装命令而不增加指标 - `get_badge_code` — 为已知 slug 生成 README 徽章代码段 - `get_embed_code` — 为已知 slug 生成 iframe 嵌入代码段 - `get_card_code` — 为已知 slug 生成动画 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>` 如果您在子路径下部署，例如 `/codex-pets`，请设置： ```bash 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 通知由 `INDEXNOW_KEY` 启用；应用提供 `/<key>.txt` 并在管理员批准宠物后 ping IndexNow。 ## 生产环境说明 对于专用公开子域，例如 `https://pets.example.com`，优先使用： ```bash NEXT_PUBLIC_APP_URL=https://pets.example.com NEXT_PUBLIC_BASE_PATH= ``` 如果应用容器通过 Docker 主机名与 YDB 通信，例如 `grpc://ydb-local:2136`，请在与 YDB 容器相同的 Docker 网络上运行应用： ```bash docker run --network ydb-net ... ``` ## 本地 YDB 快速入门 对于本地应用开发，一个简单的本地 ydb 根数据库在 `/local` 就足够了；您不需要 CMS 租户或动态节点。应用在主机上运行，因此本地 ydb 容器必须在 `127.0.0.1:2136` 上发布 gRPC。 如果您使用 `local-ydb` MCP，请从一个干净的根数据库开始，使用 `local_ydb_destroy_stack(confirm=true)` 和 `local_ydb_bootstrap_root_database(confirm=true)`。如果生成的容器没有发布 `127.0.0.1:2136`，请仅使用相同卷重建容器，并使用主机 gRPC 端口： ```bash 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 ``` 使用这些本地应用环境变量： ```bash AUTH_MODE=single-user AUTH_SINGLE_USER_ID=local-admin AUTH_SINGLE_USER_EMAIL=local-admin@example.com AUTH_SINGLE_USER_NAME="本地管理员" SESSION_COOKIE_SECRET=dev-cookie-secret PASSWORD_PEPPER=dev-password-pepper INITIAL_ADMIN_EMAILS=local-admin@example.com 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 ``` 应用架构、种子数据并启动应用： ```bash 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 监控界面是 `http://127.0.0.1:8765`。 ## 当前行为 - 公众用户可以浏览画廊并打开 `/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 可读地图。 - `/openapi.json` 是公共代理/开发者合约子集的规范。 - `/developers` 和 `/docs/api` 是 API、OpenAPI、MCP、身份验证和 Webhook 的索引开发者资源页面。 - `/mcp` 是编码代理的公开只读 Streamable HTTP MCP 服务器。 - 官方 MCP 注册表名称：`tech.ydb-qdrant.pets/codex-pets-ydb-qdrant`。 - `server.json` 和 `/.well-known/mcp/server.json` 公开 MCP 注册表元数据，供公共远程服务器使用。 - `/.well-known/mcp-registry-auth` 公开 `mcp-publisher` 使用的公共 HTTP 域身份验证记录。 ## 主要路由 - `/` — 公共画廊 - `/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 注册表元数据 - `/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 可读输出 ## 代理面对检查 使用 `CODEX_PETS_DATA_SOURCE=mock npm run dev -- --port 3000` 在没有本地 YDB 的情况下检查代理面对路由。预期公共端点： ```bash 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 烟雾测试： ```bash 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"}' ``` ## 私有部署说明 每台主机的具体指令、本地路径和操作说明应位于一个 gitignored 的 `private/` 目录下。存储库中的公共文档应保持通用和安全，以提交。 ## 宠物包 每个宠物都以以下格式分发： - `pet.json` - `spritesheet.webp` 或 `spritesheet.png` - 可下载的 ZIP 文件，包含两个文件在根目录 v1 验证器期望在 `1536x1872` 的 8x9 图集中，每个单元格为 `192x208`。 ## CLI 安装 已批准的画廊宠物可以通过 npm 安装到 Codex： ```bash 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 已经运行，请在设置中选择新的宠物之前重启它。