はじめに
2026年2月16日にv0.1.0をnpm公開してから、わずか6日間で5つのバージョンをリリースした。ZERONOVA LAB MCP Serverは、サイトの89個の無料ツールをAIエージェントから呼び出せるようにするMCP（Model Context Protocol）Serverだ。
v0.1.0（6ツール）→ v0.2.1（9ツール + 情報パリティ修正）→ v0.2.2（SEO自動検証強化）→ v0.3.0（アクセシビリティ・セキュリティ拡張）→ v0.4.0/v0.4.1（設定ファイル生成5ツール + パッチ）→ v0.5.0（SEO検査拡張4ツール）。
6日間で7回のnpm publishを経験し、いくつかの設計原則が見えてきた。この記事ではその原則と、もっと早く気づいていれば避けられた「後悔」を記録する。
MCP Server開発の全体像についてはMCP Server開発記で詳しく書いている。この記事では、5バージョンのリリースを通じて得た「設計の学び」に焦点を当てる。
原則1: 薄いラッパーから始める
v0.1.0のTier 1ツール（6個）は、本体サイトのAPIルートをHTTP呼び出しするだけの薄いラッパーだった。
2月16日の開発日記にはこう書いている。
Phase 1 は「薄いラッパー」が正解: Tier 1 の各ツールハンドラーは 5-10 行程度。ロジックは全て本体 API に委譲し、MCP Server はバリデーション + レート制限 + エラーハンドリングに徹する
最初から複雑なロジックをMCP Server側に実装していたら、本体APIとの二重管理が発生し、メンテナンスコストが跳ね上がっていただろう。「まず動くものを出して、後から改善する」というアプローチが正しかった。
ただし「薄いラッパー」には落とし穴がある。それが次の原則で述べる「情報パリティ」の問題だ。
原則2: 情報パリティを最初から意識する
v0.2.0でTier 2ワークフローツール（run_seo_audit 等）をリリースした直後、重大な問題に気づいた。ワークフローの出力が、サイト側ツールの出力よりも情報量が少ない。
サイト側ツール（
/tools/ogp-checker等）が返すフィールド数と、MCP Server のbuildToolResultSummary()が返すフィールド数を比較。45フィールド中 64% が欠落していた
OGPチェックの結果に実際のタイトルテキストや画像URLが含まれていない、速度チェックの結果に改善提案が含まれていない——「件数」だけ返して「中身」を返していなかった。
Zeronovarun_seo_audit の出力を見て愕然とした。OGPチェックの結果に「pass」としか出ない。実際のタイトルや画像URLが欲しいのに。サイト側ツールでは全部見えるのに、MCP経由だと情報が劣化している。buildToolResultSummary() で各ツールの全フィールドを含めるよう修正しましょう。OGPは実テキスト・画像URL・type・siteName、速度は6メトリクス+改善提案5件、alt属性は欠落画像のURL・context情報を返すようにします。Zeronovaこの修正をv0.2.1として即日パッチリリースした。教訓として mcp-dev-checklist.md に「情報パリティ」セクションを追加し、以降の全バージョンで「サイト側ツールと同等の情報量を返しているか」をチェック項目に組み込んだ。
原則3: Workflow as a Tool — 連鎖実行を1ツールに
v0.1.0の企画時点では、Tier 2は「チェックリストデータを返却し、AIが個別ツールを順次呼び出す」設計だった。
Zeronovarun_seo_audit(url) 1回の呼び出しで、MCP Server内部がTier 1ツール5つを連鎖実行し、スコア付き統合レポートを返す設計です。ユーザーは「SEOチェックして」の一言で完了します。部分失敗時はエラー項目を "error" ステータスで返し、成功分のみでスコアを算出すれば正確性も保てます。Zeronova企画書のv1からv2への改訂で、「Workflow as a Tool」パターンに進化させた。
v1 の Tier 2 の課題: 「チェックリストデータを返却 → AI が個別ツールを順次呼び出し」の設計では、AI エージェントに6回以上のツール呼び出しを要求する
v2では run_seo_audit(url) 1回の呼び出しで、MCP Server内部がTier 1ツール5つを連鎖実行し、スコア付き統合レポートを返す。ユーザーは「SEOチェックして」の一言で完了する。
「Workflow as a Tool」という設計パターン: 個別ツールの寄せ集めではなく、ワークフロー（複数ツールの連鎖実行）を1つのツールとして提供するパターン
このパターンは多くのMCP Serverがまだ実装していない差別化要素になった。
部分失敗への対応
ワークフローで5つのAPIを順次呼び出すと、一部が失敗する可能性がある。初期実装では失敗した項目もスコア計算に含めていたが、これでは「APIが一時的にタイムアウトしただけ」でスコアが不当に低下する。
エラー項目を maxScore から除外し「未評価」として扱う（成功分のみでスコア計算）
「成功した項目のうち何割が合格か」——これが正しいスコアの意味だ。未評価の項目は "error" ステータスで返し、AIエージェントに「再試行してください」と伝える設計にした。
原則4: 手動項目ゼロを目指す
v0.2.0の時点で、SEO監査ワークフローには手動確認項目が残っていた。canonical URL、JSON-LD、robots.txt、サイトマップの4項目だ。
「URLを渡すだけで全チェック完了」の訴求ポイントが「結局自分で確認する項目がある」では弱い。Phase 2.5（v0.2.2）で4項目を自動化し、SEO監査の手動項目をゼロにした。この自動化の詳細なプロセスはSEO監査の手動チェック項目をゼロにした話で書いている。
SEO監査: 手動0項目達成（全16項目自動検証）
2月17日の開発日記にはこう書いている。
手動→自動化の段階的アプローチ: Phase 2（v0.2.0）で「手動項目あり」のままリリースし、Phase 2.5で自動化を追加するのは正しい段階的アプローチ。最初から完璧を目指すとリリースが遅れる
この「まず手動ありでリリースし、段階的に自動化する」パターンは、Phase 2.7（v0.3.0）でも適用した。Web公開前チェックの手動項目を4件→1件に削減した。
原則5: チェックリスト駆動の品質保証
v0.1.0のリリース前に mcp-dev-checklist.md を作成していた。npm配布・AIエージェント入力・ファイルシステムアクセスという、Webツールとは異なるリスク領域をカバーするチェックリストだ。
このチェックリストが効いたのはPhase 2以降だ。
mcp-dev-checklist.md に基づく事後レビューで4件の改善点を発見。特にスコア計算の「未評価」扱いとワークフロータイムアウトの強化は、チェックリストなしでは見逃していた可能性が高い
Phase 3（v0.4.0）のTier 3設定ファイル生成ツールでは、.htaccessのインジェクション防止やJSON-LDのXSS防止など、セキュリティ観点のチェックが特に有効だった。
セキュリティレビューとテストが表裏一体: .htaccess のインジェクション防止は「攻撃パターンをテストケースに変換する」プロセスそのもの
テスト数はv0.1.0の9件からv0.5.0の199件まで増えた。チェックリストが「何をテストすべきか」のガイドになっている。
後悔: もっと早く気づいていれば
情報パリティは設計時に組み込むべきだった
v0.2.0で情報劣化に気づいたのは「デモ実行したから」だ。もしデモせずにリリースしていたら、ユーザーに劣化した出力を返し続けていただろう。チェックリストに最初から「情報パリティ」の項目を入れるべきだった。
npm 2FAトークンの種類を事前に確認すべきだった
v0.1.0の公開時、2FAバイパス付きトークンが必要であることを知らず、通常のGranular Access Tokenで npm publish して403エラーに遭遇した。
最初の Granular Access Token で
npm publishすると403 Forbidden - Two-factor authentication or granular access token with bypass 2fa enabled is requiredエラー
この問題は mcp-npm-publish-guide.md に手順として記録し、v0.2.1以降では迷わず対応できるようになった。しかし初回で手間取った時間は痛かった。
speed-checkerのタイムアウトは本番データで検証すべきだった
v0.4.0でspeed-checkerのタイムアウト（15秒）が短すぎる問題が発覚し、v0.4.1でパッチリリースした。
PageSpeed Insights API の実際のレスポンス時間: 重いページの検査では API レスポンスに 15〜25秒かかるケースがある
開発環境の軽いページでは15秒で十分だったが、本番環境の重いページでは不足した。「本番に近いデータでテストする」という基本を怠った結果だ。
5バージョンのリリースサマリー
| バージョン | 日付 | 主な変更 | ツール数 | テスト数 |
|---|---|---|---|---|
| v0.1.0 | 02-16 | Phase 1: Tier 1 個別検査 | 6 | 9 |
| v0.2.1 | 02-16 | Phase 2: Tier 2 ワークフロー + 情報パリティ修正 | 9 | 50 |
| v0.2.2 | 02-17 | Phase 2.5: SEO自動検証、手動項目ゼロ化 | 10 | 50 |
| v0.3.0 | 02-18 | Phase 2.7: セキュリティヘッダー、a11y検証 | 11 | 56 |
| v0.4.0/4.1 | 02-18 | Phase 3: Tier 3 設定ファイル生成 + パッチ | 16 | 167 |
| v0.5.0 | 02-22 | Phase 3.5: SEO検査拡張 | 20 | 199 |
6日間で6ツール→20ツール、9テスト→199テスト。段階的リリースの仕組み（チェックリスト + 公開手順ガイド）が定着した結果、リリース作業自体が高速化した。
学んだこと
「薄いラッパー」で始めて「厚い価値」を段階的に追加する
v0.1.0は5-10行のハンドラーだけ。ここにワークフロー、自動化、設定ファイル生成と段階的に価値を追加していく。最初から完璧を目指すよりも、各フェーズで「このバージョンの価値は何か」を明確にして出す方が学びが多い。
チェックリストは「教訓」セクションで育てる
mcp-dev-checklist.md はPhase 1で空の「教訓」セクションを持っていた。Phase 2以降、実際に遭遇した問題（情報パリティ、タイムアウト、npm 2FA）を教訓として追記し続けることで、チェックリスト自体が進化していく。
ドッグフーディングが最強のQA
Story Logにはこう書いている。
自分で作った ZERONOVA LAB MCP Server で、自分のサイトをチェックして改善するという体験ができた。すべて Claude Code 内で完結できるので、MCP Server との相性がとても良いと感じた。
v0.2.0の情報パリティ問題も、v0.4.1のタイムアウト問題も、自分で使ったから気づけた。ユーザーからの報告を待っていたら、もっと長い間劣化した状態で提供し続けていただろう。ドッグフーディングで発見した具体的な改善事例は自作MCP Serverで自サイトを診断して即日改善した話にまとめている。
Zeronova（ゼロノバ）
Product Manager / AI-Native Builder
Web/IT業界19年以上・20以上のWebサービスを担当したPdM。東証プライム上場企業の子会社代表として事業経営を経験。現在はAIを駆使して企画から実装まで完結させる個人開発を実践中。