NovelAI-Image-MCP: Instructions file for Codex

AGENTS.md

面向 AI agent 的仓库级上下文索引。完整开发者文档见 CONTRIBUTING.md 与 docs 站。 本文件只沉淀"约束 + 指针"，避免与 docs 站重复。

项目是什么

NovelAI Image MCP —— 一个基于 fastmcp 4 （fastmcp==4.0.0b3，底层运行在 MCP SDK v2 mcp>=2.0.0 上）的模型上下文协议 服务器，把 NovelAI 图像生成 API 暴露为 11 个 MCP 工具， 供 Claude Desktop / Cline / 自研 agent 调用。Python 3.13，MIT 协议。

仓库布局（uv + pnpm monorepo，Turbo 编排）

apps/server/  → 可安装的 MCP 服务器包（PyPI: novelai-image-mcp）
  src/novelai_image_mcp/
    nai/         # NovelAI HTTP 客户端（必须走 create_http_client()）
    tools/       # 11 个 MCP 工具的注册函数
    server.py    # FastMCP 实例 + lifespan AppContext
    cli.py       # typer CLI（同步入口）
  tests/
  dev_server.py  # mcp dev 入口（绕开相对导入问题）
  pyproject.toml # 版本号唯一权威源 + ruff/pyright/pytest 配置
apps/docs/    → Sphinx 文档站（Furo + MyST）
.github/      → workflows (ci/release/docs) + sync-version composite action
pyproject.toml (根) → uv workspace 虚拟根（不可安装）
uv.lock       → 全仓库唯一锁文件

常用命令

uv sync                                              # 同步 Python workspace
uv run --directory apps/server poe check             # format-check + lint + typecheck + test
uv run reuse lint                                    # REUSE 合规
uv run --directory apps/server poe serve             # 启动 stdio 服务器
uv run --directory apps/server poe serve-http        # 启动 HTTP 服务器
mcp dev apps/server/dev_server.py                    # MCP Inspector（交互调试）
pnpm docs:serve                                      # sphinx-autobuild 实时预览

硬约束（不要触碰）

1. 版本号唯一源 = apps/server/pyproject.toml 的 version 字段。 不要手改 package.json / apps/server/package.json / apps/docs/package.json 的版本号——release workflow 的 .github/actions/sync-version 会自动同步并回写 commit。
2. NovelAI HTTP 客户端必须通过 nai/http.py 的 create_http_client() 构造。不要直接 httpx.AsyncClient()——image.novelai.net 后的 Cloudflare WAF 会按 JA3/JA4 TLS 指纹识别非浏览器客户端并静默重置连接。自 2026 年起 NovelAI 已将大部分第三方 API 访问收口到 image.novelai.net：它承载 /ai/generate-image、/ai/generate-image-stream、/ai/augment-image、 /ai/encode-vibe、/ai/generate-image/suggest-tags 以及 /user/*（账户 / 订阅 / 数据）端点。例外：/ai/upscale 与 /ai/annotate-image 未迁移， 仍在 Primary API api.novelai.net 上——api.novelai.net/docs/ 明确指出 第三方用户可使用其 /ai/ 路由。NovelAISettings.legacy_image_base_url （默认 https://api.novelai.net）专门服务这两个端点，upscale() 与 annotate() 必须使用它。create_http_client() 用 httpx_curl_cffi.AsyncCurlTransport(impersonate="chrome") 复刻 Chrome 的 BoringSSL 指纹 + 完整 Chrome 150 请求头块（BROWSER_HEADERS）。
3. MCP 工具返回图像时返回 fastmcp 的 Image 辅助类（from .._mcp import Image），由 fastmcp 自动转为 ImageContent。tools/generate.py 与 tools/enhance.py 的 _save_and_return 已封装此逻辑：直接 return [Image(data=..., format="png"), "saved ..."]，fastmcp 在返回 list 时会自动转换。不要手动拼 ImageContent，也不要返回裸 bytes。
4. mcp dev 用 apps/server/dev_server.py 作为入口，不要直接指向 server.py——mcp dev 直接加载会破坏 from ._mcp import FastMCP 相对导入。
5. 提交消息必须 gitmoji + Conventional Commits，例： 🐛 fix(generate): handle zero-seed randomization。commit-msg hook 自动追加 Signed-off-by 实现 DCO。不要 --no-verify 提交 PR。
6. 不要在 releases/* 分支推送前忘记 uv lock。release workflow 的 build job 用 uv build --package novelai-image-mcp，lock 与 pyproject 不一致会触发警告。
7. 不要在 PyPI 重发同版本——PyPI 不允许覆盖。失败的发布用 yank + patch 版本（0.1.x → 0.1.x+1）补救。
8. i18n 翻译页面放在 apps/docs/source/<lang-code>/（如 source/zh/、 source/ja/）。英文留在 source/ 根。每个语言独立构建，共享同一份 conf.py。按语言的 toctree 只能引用该语言目录下实际存在的页面 —— 不要在 source/zh/index.md 的 toctree 里链接未翻译的 tools/ 或 tutorials/ 章节。未翻译的章节用户切换到英文查看即可。新增语言时同步 更新 conf.py 的 AVAILABLE_LANGUAGES 与 docs.yml 的 matrix。