MCP Server開発記 — 82ツールのWeb検査を16コマンドに凝縮した設計判断

はじめに — 82個のツールを「AIの顧客」に届ける

ZERONOVA LABには82個の無料オンラインツールがあります。OGPチェッカー、リンク切れチェッカー、ページ速度チェッカー。すべてブラウザで動く、人間向けのツールです。82個のツールを10日で作った経緯は「Claude Codeで10日間に82個の無料ツールを量産した開発プロセス」に書きました。

しかし2026年の開発現場では、Claude CodeやCursorなどのAIエージェントが当たり前のように使われています。AIエージェントはブラウザを開いてフォームに入力することができません。82個のツールが「人間にしか使えない」のはもったいない。

ここから「B2A（Business to Agent）」——AIエージェントを「顧客」として捉えるMCP Server開発が始まりました。

82ツールから16ツールへの絞り込み

MCP Serverを企画したとき、最初の判断は「82ツール全部をMCP化しない」ことでした。

AI は文字数カウント、Base64変換、JSON整形を自力でできる。これらを MCP 化しても「AI にとって不要なものが大半」になり、信頼性が落ちる

2月16日の開発日記にこう書きました。AIが自分でできることをわざわざMCPツールとして提供しても、使い勝手が悪いだけです。フィルタの基準は「AIエージェントが自力でできるか？」。この問いを82ツールに当てはめると、残ったのは16ツールでした。

残ったのは、外部URLにアクセスしてHTMLを解析する系のツール——OGPチェッカー、リンク切れチェッカー、ページ速度チェッカー、alt属性チェッカー、見出し抽出、X Cardバリデーション。AIエージェントが自力では実行できない「外部リソースへのアクセスと分析」に特化しています。

Tier設計 — 「Workflow as a Tool」の発見

16ツールはTier 1からTier 2の2層に分類しました。

Tier 1（個別検査ツール: 7つ）: OGPチェック、alt属性チェック、リンク切れチェック、ページ速度チェック、見出し抽出、X Cardバリデーション、サイト設定チェック（robots.txt/sitemap）。既存のAPI routeのラッパーです。

Tier 2（ワークフローツール: 3つ）: run_seo_audit、run_web_launch_audit、run_freelance_delivery_audit。ここが最大の差別化ポイントです。

PM-AI 対話: ワークフローの設計転換

最初のTier 2設計はチェックリストデータを返すだけでした。v2で大きく方針転換します。

Zeronova

v1のTier 2は「チェックリストのデータを返す → AIが個別ツールを順次呼び出す」だった。でもこれだとAIに6回以上のツール呼び出しを要求することになる。「SEOチェックして」と言われたら、1回で結果が返ってほしい。

Zeronova

それだ。ワークフローと個別ツールは共存させよう。ワークフローは便利なショートカット、個別ツールは粒度の細かい分析に使い分ける。

「Workflow as a Tool」という設計パターン: 個別ツールの寄せ集めではなく、ワークフロー全体を1つのツールとして提供する。ほとんどの MCP Server がやっていない差別化要素

この設計転換が、MCP Serverの核心的な価値になりました。

TypeScript型との格闘 — ServerNotificationのcontravariance

技術的に最も苦労したのは、MCP SDKのTypeScript型定義です。

Tier 2のワークフローツールは実行に10-30秒かかるため、進捗通知が必要です。MCP SDKの sendNotification() は ServerNotification というdiscriminated union型を受け取ります。

問題は、method フィールドがリテラル型（"notifications/progress" as const）でなければ型が通らないことでした。関数パラメータはcontravariant（反変）なので、string に広げると型エラーになります。

TypeScript の discriminated union と contravariance: 関数パラメータは contravariant。discriminated union の method フィールドを string に広げると型が合わなくなる

3回のアプローチ変更を経て、最終的にはツールハンドラー内でインラインコールバックを構築し、as const でリテラル型を維持する方式に落ち着きました。

情報パリティ問題 — v0.2.0のデモで気づいた

Phase 2を完成させてデモを実行したとき、違和感に気づきました。run_seo_audit の出力が、サイト側のツール（/tools/ogp-checker 等）より情報量が明らかに少ないのです。

調査すると、45フィールド中64%が欠落していました。OGPの実際のタイトル文、description文、画像URL。PageSpeed Insightsの6メトリクス。alt欠落画像のURL。すべてが省略されていました。

「情報パリティ」というチェック観点: MCP Server（B2A）経由の出力が、ブラウザ（B2C）経由の出力と同等の情報量を持つべき

PM-AI 対話: 情報パリティの修正方針

Zeronova

45フィールド中64%が欠落している。全部追加すると出力が巨大になりすぎないか？AIが処理しきれない量のデータを返しても意味がない。

Zeronova

方針は「個別ツールと同等の情報量をワークフローでも返す」にしよう。サマリーのフォーマットは使いやすさを優先して調整する。

ワークフローは「5ツール連鎖実行の便利ショートカット」であるべきなのに、個別ツールより情報量が劣るなら存在意義が薄れます。v0.2.1でこの情報パリティを修正し、mcp-dev-checklist.md に「情報パリティ」を新しいチェック観点として追加しました。

bot-blockedの区別 — X/Twitterの403問題

もう一つデモで発見した問題があります。リンク切れチェックでX/Twitterへのリンクが「リンク切れ」と判定されていました。

X/TwitterはBotからのアクセスに403を返す仕様です。これは「リンク切れ」ではなく「Botがブロックされた」だけ。サイト側のAPIはすでにwarningフィールドで区別していたので、MCP Server側もそれに合わせて、bot-blockedの403をwarn扱い、真の404のみfailとする判定に修正しました。

npm公開 — v0.1.0からv0.2.2まで

MCP Serverは zeronova-lab-mcp としてnpmに公開しました。公開フローの詳細は「個人開発者がnpmパッケージを公開するまでの全手順」を参照してください。

npx zeronova-lab-mcp で即座に利用可能。Claude Codeなら claude mcp add で登録するだけです。

チェックリスト駆動の品質保証

MCP Serverの品質保証で重要だったのは mcp-dev-checklist.md です。無料ツール用の tools-dev-guidelines.md とは別に、MCP Server固有の観点をカバーするチェックリストを整備しました。

「配布形態の変化 = セキュリティモデルの変化」: Web アプリからnpm パッケージへの配布形態変更は、攻撃面・ライセンス義務・障害影響範囲の全てが変わる

特にPhase 2の事後レビューでは、このチェックリストから4件の改善点を発見しました。スコア計算の「未評価」扱い、ワークフロータイムアウトの強化、進捗通知の実装、エッジケーステストの追加。チェックリストなしでは見逃していた可能性が高いものです。

学んだこと

MCP Server開発を通じて学んだことをまとめます。

「厳選」が信頼を生む: 82ツール全部をMCP化するより、16ツールに絞った方が「分かっている人が作ったMCP Server」という信頼感が生まれます。

Workflow as a Toolは強力な差別化: ほとんどのMCP Serverは個別ツールの寄せ集めです。ワークフローを1ツールとして提供するパターンは、ユーザー体験を劇的に変えます。

情報パリティは意識しないと劣化する: MCP Serverの出力がサイト版と同等の情報量を持つべきという原則。「便利だけど情報が足りない」は本末転倒です。

チェックリストのフィードバックループ: 問題を発見 → 修正 → チェックリストに反映 → 今後の開発で予防。教訓セクションが蓄積されるほどチェックリストの価値が上がります。

自分がユーザーになれる強み: KDP原稿のEPUB化やサイトのSEO監査など、実際の業務で使えるユースケースが先にあるから、説得力のある設計ができました。