NovelAI-Image-MCP: Instructions file for Codex

AGENTS.md

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

项目是什么

NovelAI Image MCP —— 一个基于 fastmcp 4 （fastmcp>=4.1.0,<5，底层运行在 MCP SDK v2 mcp>=2.3.0 上）的模型上下文协议 服务器，把 NovelAI 图像生成 API 暴露为 11 个 MCP 工具、2 个 prompt、3 个资源 + 1 个资源模板，供 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 工具（模块级 @mcp.tool 装饰器）
    resources.py # novelai://models / samplers / defaults / outputs/{name}
    prompts.py   # novelai_prompt_writer / novelai_image_workflow
    middleware.py# 工具调用日志 + 分路审计 + 实验性工具双闸门控
    mcp_auth.py  # 可选 HTTP Bearer Token（MCP_AUTH_TOKEN / MCP_ROUTE_TOKENS）
    deps.py      # AppContext + Depends 依赖提供者（含 insiders / routing providers）
    insiders.py  # X-MCP-Insiders 头解析（纯逻辑，无 I/O）
    features.py  # INSIDERS_FEATURES 特性注册表 + resolve_features
    routing.py   # 声明头 → RoutingContext（route 白名单 + 头脱敏）
    audit.py     # append-only JSONL 审计（单次 os.write + O_APPEND）
    schemas.py   # 结构化输出模型（AnlasEstimate / TagSuggestion）
    server.py    # FastMCP 实例 + lifespan + 组件导入
    cli.py       # typer CLI（同步入口）
  tests/
  mcp_server.py  # fastmcp run/dev 入口（绕开相对导入问题）
  pyproject.toml # 版本号唯一权威源 + ruff/pyright/pytest 配置
fastmcp.json (根或 member) → fastmcp run 的声明式配置（source 指向 mcp_server.py）
apps/docs/    → Sphinx 文档站（Furo + MyST）
.github/      → workflows (ci/release/docs) + detect-changes 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 服务器
uv run fastmcp run fastmcp.json                      # 标准 FastMCP 入口（仓库根）
uv run --directory apps/server poe inspect           # 组件/版本一览（fastmcp inspect）
uv run --directory apps/server poe dev               # MCP Inspector（交互调试）
pnpm docs:serve                                      # sphinx-autobuild 实时预览