アーキテクチャ¶
このサーバーは、NovelAI HTTP クライアントの上に載る薄いコンポジションルートです。 このページでは各レイヤーと、それらがどのように組み合わさるのかを順に説明します。
レイヤー¶
graph TD
A[Agent / MCP host] -->|JSON-RPC over stdio / HTTP| B[FastMCP]
B -->|middleware| M[ToolCallLoggingMiddleware]
B -->|optional bearer auth| N[mcp_auth.build_auth]
B -->|lifespan| C[AppContext: NovelAIClient + NovelAISettings]
C -->|Depends DI| D[tools/* · resources.py · prompts.py]
D -->|calls| E[NovelAIClient nai/]
E -->|httpx.AsyncClient| F[NovelAI API]
D -->|saves| G[output.py → outputs/]
D -->|ImageContent| A
D -->|structured output| A
FastMCP コンポジションルート¶
novelai_image_mcp.server がコンポジションルートです。これは
次のことを行います:
MCP の
lifespanが所有する単一の共有httpx.AsyncClient(コネクションプール) を構築します。設定と httpx クライアントから
NovelAIClientを構築します。両者を
AppContextとして yield し、依存性プロバイダーがそれをすべての ツール、リソース、プロンプトに公開します。シャットダウン時に両者を破棄します (まず
NovelAIClientを閉じ、次に基盤の httpx セッションを閉じます — クライアントのクローズが例外を送出しても、 ソケットのリークを避けるため httpx セッションは必ず解放されます)。
インスタンス自体はインポート時に一度だけ設定されます:
mcp = FastMCP(
name="novelai-image",
version=__version__, # serves the package version, not the framework version
instructions=INSTRUCTIONS, # how an agent should use the server
lifespan=lifespan,
auth=build_auth(get_mcp_settings()), # None unless MCP_AUTH_TOKEN is set
mask_error_details=True, # only ToolError messages reach the client
middleware=[ToolCallLoggingMiddleware()],
)
from . import prompts, resources, tools # decorators attach to `mcp`
ツール、リソース、プロンプトはモジュールレベルのデコレーターでアタッチされるため、
呼び出すべき register(mcp) 関数はありません: tools/ (または resources.py、
prompts.py) をインポートすることが登録手順そのものであり、それは mcp が
存在した後に実行されます。
@asynccontextmanager
async def lifespan(_server: FastMCP) -> AsyncIterator[AppContext]:
settings = get_novelai_settings()
if not settings.has_credentials():
raise RuntimeError("NovelAI credentials are not configured...")
http_client = create_http_client(timeout=settings.timeout)
client = create_novelai_client(settings, http_client=http_client)
try:
yield AppContext(client=client, settings=settings)
finally:
try:
await client.aclose()
finally:
if not http_client.is_closed:
await http_client.aclose()
すべてのコンポーネントは自身が必要とするものを宣言し、FastMCP がリクエストごとに それを解決して、依存関係を入力スキーマから除外します:
@mcp.tool(title=..., tags={...}, annotations=IMAGE_WRITE_ANNOTATIONS)
@translate_errors
async def generate_image(
prompt: str,
model: Model | None = None,
app: AppContext = Depends(get_app_context), # hidden from the schema
) -> list[Any]: ...
deps.py がプロバイダー (get_app_context、get_client) を所有し、
tools/_errors.py が NovelAIError/ValueError → ToolError の変換を所有します。
この変換はツール本体の内部で行う必要があります: ミドルウェアのフックが呼び出しを
見るころには、FastMCP がすでに例外をマスクしているためです。
NovelAIClient (nai/ サブパッケージ)¶
nai/ サブパッケージは NovelAI HTTP クライアントです。MCP とは 無関係 で —
任意の非同期 Python コードから単体で利用できます。
モジュール |
責務 |
|---|---|
|
Argon2id によるアクセスキーの導出、リクエスト追跡ヘッダー。 |
|
|
|
Enum: |
|
ドメイン例外: |
|
Pydantic モデル: |
|
|
|
|
|
|
ツールレイヤー¶
novelai_image_mcp.tools は、fastmcp の FastMCP ツールデコレーターと
NovelAIClient の間の薄いアダプターです。各ツールは次のことを行います:
Depends(get_app_context)パラメーター (deps.py) を通じてAppContextを 受け取るため、入力スキーマには現れません。ツールのパラメーターから
GenerationRequest(または同等のもの) を構築します。対応する
NovelAIClientのメソッドを呼び出します。output.save_imageで結果を永続化します。MCP コンテンツブロックのリスト
[Image, text_path]を返します。
ツールは意図的にビジネスロジックを避けています — 検証とパラメーターの
マーシャリングは nai/ に置かれているため、同じコードパスが MCP サーバー、
CLI、クライアントの直接利用に共通して使われます。Enum 型のパラメーター
(Model、Sampler、DirectorTool、…) はツール本体の内部で変換されるため、
Python から直接呼び出す場合は素の文字列を渡せますが、MCP の呼び出し側は
スキーマ検証を受けます。
ツールに加えて、サーバーは読み取り専用のコンテキストを公開します:
コンポーネント |
場所 |
目的 |
|---|---|---|
|
|
機能フラグ付きのモデル ID。 |
|
|
サンプラー / ノイズスケジュール / UC プリセットの語彙。 |
|
|
現在有効な生成デフォルト (認証情報なし)。 |
|
|
生成された PNG を読み戻します (名前は出力ディレクトリに対して検証されます)。 |
|
|
ハウススタイルのプロンプト作成とツールの順序付け。 |
CLI¶
novelai_image_mcp.cli は typer アプリで、MCP ツールの一部を直接のサブコマンド
(generate、upscale、director、annotate、info、serve) として公開します。
呼び出しごとに短命な httpx.AsyncClient + NovelAIClient を構築します —
共有セッションはありません。長期間にわたって複数のツールを使う場合は、
MCP サーバー (lifespan 経由でプールされたセッションを所有します) を推奨します。
設定¶
novelai_image_mcp.settings は 2 つの pydantic-settings モデルを定義します:
NovelAISettings— 認証情報、エンドポイント、生成デフォルト (NOVELAI_*環境変数)。MCPServerSettings— トランスポートの選択 (MCP_*環境変数)。
どちらもプロセス環境 + (カレントディレクトリの) .env から読み込まれ、UTF-8、
大文字小文字を区別せず、不明なキーは無視されます。NovelAISettings は構造的に
NovelAIConfigLike を満たすため、クライアントファクトリーはそれをそのまま
利用します。
出力¶
novelai_image_mcp.output.save_image は PNG を NOVELAI_OUTPUT_DIR に書き込み、
パスを返します。ディレクトリは必要に応じて作成されます。ファイル名にはツール名 +
ISO タイムスタンプ + サンプルインデックスが含まれます
(generate-20260725-133702-001.png)。
トランスポート¶
サーバーは stdio (既定) と HTTP をサポートし、起動時に MCP_TRANSPORT で選択します
(http が正規で、streamable-http は受け付けられる別名です)。どちらも同じ lifespan、
同じツール、同じ NovelAIClient を共有し — 異なるのはフレーミングだけです。
MCP_AUTH_TOKEN (または MCP_ROUTE_TOKENS) を設定すると、HTTP トランスポートは
ベアラートークンを要求します。stdio は影響を受けません。
トランスポート を参照してください。
コンテナ化¶
apps/server/Dockerfile
はマルチステージビルドです:
ビルダーステージ: uv をインストールし、ランタイム依存関係 (dev グループを除く) をエクスポートし、wheel をビルドします。
プロジェクトビルドステージ:
uv buildでプロジェクトの wheel をビルドします。ランタイムステージ: スリムな Python 3.13、非 root の
appユーザー、 ビルド済み wheel のみをインストール — ランタイムイメージにコンパイラー ツールチェーンは含まれません。
スモークテスト (apps/server/docker/smoke-test.py) は別のイメージに組み込まれ
(SMOKE_TEST=true ビルド引数経由)、次のことを検証します:
パッケージがクリーンにインポートされる。
設定が環境変数からインスタンス化される (
NOVELAI_TOKEN=pst-smoke-testを使用)。すべてのツールが記録用の FastMCP スタブに登録される。
typer CLI がランタイムエラーなく構築される。