xserver-mcp CLAUDE.md

xserver-mcp

Xserver 公式の サーバーパネル REST API (https://api.xserver.ne.jp) をラップする MCP サーバー。

運用ルール (.claude/rules/)

リポジトリ運用の詳細ルールは .claude/rules/ 以下に分割している。各ファイルは CLAUDE.md と同様にセッション開始時のコンテキストへ読み込まれる。

• tdd-workflow.md — TDD 必須ポリシーとエージェント (tdd-developer / test-writer / implementer / reviewer) の使い分け基準。src/ / tests/ のコード変更は原則これらに委譲する。
• github-flow.md — ブランチ命名・マージ戦略・禁止事項。
• commit-messages.md — Conventional Commits の type/scope と本プロジェクトの既定フッタ。
• pull-requests.md — PR テンプレート・セルフレビュー観点・マージ条件。セルフレビューは read-only の reviewer エージェント (.claude/agents/reviewer.md) に委譲し、IDN 正規化・runApi・registry 登録・破壊的操作ガードなどの固有観点を Blocker/Major/Minor/Nit の verdict で機械的に受け取るのが既定運用。

Xserver API の癖

• 日本語ドメイン (IDN) は MCP が自動変換: 全ツールの domain 入力と mail_address の domain 部は src/tools/domain.ts の toPunycodeDomain / normalizeMailAddress で ASCII (Punycode) に正規化してから XServer に送る。ユーザーや上位エージェントは 日本.jp / user@日本.jp をそのまま渡してよい。書き込み系ツールのレスポンスには resolved_domain (および resolved_mail_address) が含まれ、実際に送信された ASCII 値を確認できる。DNS レコードの host / content はラベル・任意文字列なので変換しない。
• 公式エラーレスポンス形式: XServer は { "error": { "code", "message", "errors": [...] } } を返す。src/client/errors.ts の errorFromResponse がこれをパースし、旧 { "message": "..." } 形式にもフォールバック対応する。抽出された code / errors[] は XserverApiError.code / XserverApiError.errors に格納され、ツール応答の code / detail.errors として LLM に届く。
• HTTP ステータス → エラークラス / code 正規化: マッピングの真の情報源は src/client/errors.ts の STATUS_TO_CODE / STATUS_CLASS。TXT 認証失敗など 409 の特別扱いが必要な場合は err instanceof XserverOperationError で判定する (createMailAccountWithVerification.ts 参照)。それ以外のステータス分岐は err.code で行うこと (派生クラスを増やさない)。
• レート制限ヘッダ: httpClient はレスポンスから X-RateLimit-Limit / -Remaining / -Reset / -Concurrent-Limit / -Concurrent-Remaining と Retry-After を抽出 (src/client/rateLimit.ts)。429 発生時は XserverRateLimitError.rateLimit と .retryAfterSeconds に格納され、ツール応答の detail.rate_limit / detail.retry_after_seconds として LLM に届く。成功時のヘッダは破棄している (MVP)。
• 429 の自動リトライ: httpClient は 429 のうち「Retry-After が XSERVER_HTTP_RETRY_MAX_WAIT_SEC 以下」かつ「X-RateLimit-Concurrent-Remaining !== 0」のケースのみ、XSERVER_HTTP_RETRY_MAX_ATTEMPTS 回まで自動待機 & 再送する。同時接続由来の 429 は他の in-flight が捌けるまで解消しないのでリトライ対象外。それ以外の status はリトライせず LLM に即返す。無効化は XSERVER_HTTP_RETRY_MAX_ATTEMPTS=1。
• 同時接続セマフォ: createHttpClient は config.concurrency (既定 3) の軽量セマフォで fetch を直列化する。XServer プラン別上限 (スタンダード 5 / プレミアム 10 / ビジネス 20) に対して保守的に振る舞う。無効化したい場合は XSERVER_HTTP_CONCURRENCY=100 などで十分大きな値を与える。
• 422 バリデーション: err.errors[] に詳細メッセージが配列で入る。ツール出力では detail.errors として LLM に渡す。
• 204 No Content: DELETE などで返る場合あり。httpClient は null を返す。
• mail_address の URL エンコード: @ を含むため必ず encodeMailAccount (= encodeURIComponent) を通すこと (IDN 正規化後に適用)。
• ドメイン所有権確認 (TXT): POST /mail は毎回 _xserver-verify.{domain} TXT レコードで所有権検証を行う。サーバーパネル経由で作成済みのドメインは TXT 未登録のことが多く、初回 API 作成は 409 OPERATION_ERROR「TXTレコードによるドメイン認証に失敗しました。」 になる。create_mail_account_with_verification はこれを内部で吸収する (API 内部リゾルバへの TXT 反映は 30–90 秒遅延)。